legacy-libs/grpc/deps/grpc/include/grpc/impl/codegen/byte_buffer.h

   1 /*
   2  *
   3  * Copyright 2015 gRPC authors.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  */
  18
  19 #ifndef GRPC_IMPL_CODEGEN_BYTE_BUFFER_H
  20 #define GRPC_IMPL_CODEGEN_BYTE_BUFFER_H
  21
  22 #include <grpc/impl/codegen/port_platform.h>
  23
  24 #include <grpc/impl/codegen/grpc_types.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /** Returns a RAW byte buffer instance over the given slices (up to \a nslices).
  31  *
  32  * Increases the reference count for all \a slices processed. The user is
  33  * responsible for invoking grpc_byte_buffer_destroy on the returned instance.*/
  34 GRPCAPI grpc_byte_buffer* grpc_raw_byte_buffer_create(grpc_slice* slices,
  35                                                       size_t nslices);
  36
  37 /** Returns a *compressed* RAW byte buffer instance over the given slices (up to
  38  * \a nslices). The \a compression argument defines the compression algorithm
  39  * used to generate the data in \a slices.
  40  *
  41  * Increases the reference count for all \a slices processed. The user is
  42  * responsible for invoking grpc_byte_buffer_destroy on the returned instance.*/
  43 GRPCAPI grpc_byte_buffer* grpc_raw_compressed_byte_buffer_create(
  44     grpc_slice* slices, size_t nslices, grpc_compression_algorithm compression);
  45
  46 /** Copies input byte buffer \a bb.
  47  *
  48  * Increases the reference count of all the source slices. The user is
  49  * responsible for calling grpc_byte_buffer_destroy over the returned copy. */
  50 GRPCAPI grpc_byte_buffer* grpc_byte_buffer_copy(grpc_byte_buffer* bb);
  51
  52 /** Returns the size of the given byte buffer, in bytes. */
  53 GRPCAPI size_t grpc_byte_buffer_length(grpc_byte_buffer* bb);
  54
  55 /** Destroys \a byte_buffer deallocating all its memory. */
  56 GRPCAPI void grpc_byte_buffer_destroy(grpc_byte_buffer* byte_buffer);
  57
  58 /** Reader for byte buffers. Iterates over slices in the byte buffer */
  59 struct grpc_byte_buffer_reader;
  60 typedef struct grpc_byte_buffer_reader grpc_byte_buffer_reader;
  61
  62 /** Initialize \a reader to read over \a buffer.
  63  * Returns 1 upon success, 0 otherwise. */
  64 GRPCAPI int grpc_byte_buffer_reader_init(grpc_byte_buffer_reader* reader,
  65                                          grpc_byte_buffer* buffer);
  66
  67 /** Cleanup and destroy \a reader */
  68 GRPCAPI void grpc_byte_buffer_reader_destroy(grpc_byte_buffer_reader* reader);
  69
  70 /** Updates \a slice with the next piece of data from from \a reader and returns
  71  * 1. Returns 0 at the end of the stream. Caller is responsible for calling
  72  * grpc_slice_unref on the result. */
  73 GRPCAPI int grpc_byte_buffer_reader_next(grpc_byte_buffer_reader* reader,
  74                                          grpc_slice* slice);
  75
  76 /** EXPERIMENTAL API - This function may be removed and changed, in the future.
  77  *
  78  * Updates \a slice with the next piece of data from from \a reader and returns
  79  * 1. Returns 0 at the end of the stream. Caller is responsible for making sure
  80  * the slice pointer remains valid when accessed.
  81  *
  82  * NOTE: Do not use this function unless the caller can guarantee that the
  83  *       underlying grpc_byte_buffer outlasts the use of the slice. This is only
  84  *       safe when the underlying grpc_byte_buffer remains immutable while slice
  85  *       is being accessed. */
  86 GRPCAPI int grpc_byte_buffer_reader_peek(grpc_byte_buffer_reader* reader,
  87                                          grpc_slice** slice);
  88
  89 /** Merge all data from \a reader into single slice */
  90 GRPCAPI grpc_slice
  91 grpc_byte_buffer_reader_readall(grpc_byte_buffer_reader* reader);
  92
  93 /** Returns a RAW byte buffer instance from the output of \a reader. */
  94 GRPCAPI grpc_byte_buffer* grpc_raw_byte_buffer_from_reader(
  95     grpc_byte_buffer_reader* reader);
  96
  97 #ifdef __cplusplus
  98 }
  99 #endif
 100
 101 #endif /* GRPC_IMPL_CODEGEN_BYTE_BUFFER_H */