Home | History | Annotate | Download | only in libcutils 
      1 /*
      2  * Copyright (C) 2007 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 /**
     18  * Byte buffer utilities.
     19  */
     20 
     21 #ifndef __BUFFER_H
     22 #define __BUFFER_H
     23 
     24 #ifdef __cplusplus
     25 extern "C" {
     26 #endif
     27 
     28 #include <stdlib.h>
     29 
     30 /**
     31  * Byte buffer of known size. Keeps track of how much data has been read
     32  * into or written out of the buffer.
     33  */
     34 typedef struct {
     35     /** Buffered data. */
     36     char* data;
     37 
     38     union {
     39         /** For reading. # of bytes we expect. */
     40         size_t expected;
     41 
     42         /** For writing. # of bytes to write. */
     43         size_t remaining;
     44     };
     45 
     46     /** Actual # of bytes in the buffer. */
     47     size_t size;
     48 
     49     /** Amount of memory allocated for this buffer. */
     50     size_t capacity;
     51 } Buffer;
     52 
     53 /**
     54  * Returns true if all data has been read into the buffer.
     55  */
     56 #define bufferReadComplete(buffer) (buffer->expected == buffer->size)
     57 
     58 /**
     59  * Returns true if the buffer has been completely written.
     60  */
     61 #define bufferWriteComplete(buffer) (buffer->remaining == 0)
     62 
     63 /**
     64  * Creates a new buffer with the given initial capacity.
     65  */
     66 Buffer* bufferCreate(size_t initialCapacity);
     67 
     68 /**
     69  * Wraps an existing byte array.
     70  */
     71 Buffer* bufferWrap(char* data, size_t capacity, size_t size);
     72 
     73 /**
     74  * Frees and its data.
     75  */
     76 void bufferFree(Buffer* buffer);
     77 
     78 /**
     79  * Prepares buffer to read 'expected' number of bytes. Expands capacity if
     80  * necessary. Returns 0 if successful or -1 if an error occurs allocating
     81  * memory.
     82  */
     83 int bufferPrepareForRead(Buffer* buffer, size_t expected);
     84 
     85 /**
     86  * Reads some data into a buffer. Returns -1 in case of an error and sets
     87  * errno (see read()). Returns 0 for EOF. Updates buffer->size and returns
     88  * the new size after a succesful read.
     89  *
     90  * Precondition: buffer->size < buffer->expected
     91  */
     92 ssize_t bufferRead(Buffer* buffer, int fd);
     93 
     94 /**
     95  * Prepares a buffer to be written out.
     96  */
     97 void bufferPrepareForWrite(Buffer* buffer);
     98 
     99 /**
    100  * Writes data from buffer to the given fd. Returns -1 and sets errno in case
    101  * of an error. Updates buffer->remaining and returns the number of remaining
    102  * bytes to be written after a successful write.
    103  *
    104  * Precondition: buffer->remaining > 0
    105  */
    106 ssize_t bufferWrite(Buffer* buffer, int fd);
    107 
    108 #ifdef __cplusplus
    109 }
    110 #endif
    111 
    112 #endif /* __BUFFER_H */
    113