diff options
Diffstat (limited to 'libccnx-common/ccnx/common/codec/ccnxCodec_EncodingBuffer.h')
| -rw-r--r-- | libccnx-common/ccnx/common/codec/ccnxCodec_EncodingBuffer.h | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/libccnx-common/ccnx/common/codec/ccnxCodec_EncodingBuffer.h b/libccnx-common/ccnx/common/codec/ccnxCodec_EncodingBuffer.h new file mode 100644 index 00000000..05563762 --- /dev/null +++ b/libccnx-common/ccnx/common/codec/ccnxCodec_EncodingBuffer.h @@ -0,0 +1,300 @@ +/* + * Copyright (c) 2017 Cisco and/or its affiliates. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at: + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file ccnxCodec_EncodingBuffer + * @brief An encoding buffer is a zero-copy vectored I/O for PARCBuffers + * + * An Encoding Buffer is an ordered list of PARCBuffers that can be written by functions like + * writev(). You can append and append to the list and the buffers are stored only by reference. + * + * You can also append one encoding buffer to another. In this case, the buffers are moved from + * the previous list to the end of the new list. + * + * @code + * { + * PARCBuffer *name = parcBuffer_Wrap("marc", 4, 0, 4); + * PARCBuffer *space= parcBuffer_Wrap(" ", 1, 0 ,1); + * PARCBuffer *email= parcBuffer_Wrap("<marc@example.com>", 18, 0, 18); + * + * CCNxCodecEncodingBuffer *encodingBuffer = ccnxCodecEncodingBuffer_Create(); + * ccnxCodecEncodingBuffer_BufferInsertTail(encodingBuffer, name); + * ccnxCodecEncodingBuffer_BufferInsertTail(encodingBuffer, space); + * parcBuffer_Release(&space); + * parcBuffer_Release(&name); + * + * CCNxCodecEncodingBuffer *emailBuffer = ccnxCodecEncodingBuffer_Create(); + * ccnxCodecEncodingBuffer_BufferInsertTail(emailBuffer, email); + * parcBuffer_Release(&email); + * + * ccnxCodecEncodingBuffer_MoveToTail(encodingBuffer, emailBuffer); + * ccnxCodecEncodingBuffer_Release(&emailBuffer); + * + * CCNxCodecEncodingBufferIOVec *iov = ccnxCodecEncodingBuffer_CreateIOVec(encodingBuffer); + * writev(STDOUT_FILENO, iov->iov, iov->iovcnt); + * ccnxCodecEncodingBufferIOVec_Release(&iov); + * + * ccnxCodecEncodingBuffer_Release(&encodingBuffer); + * } + * @endcode + * + */ + +#ifndef libccnx_ccnxCodec_EncodingBuffer_h +#define libccnx_ccnxCodec_EncodingBuffer_h + +#include <sys/uio.h> +#include <parc/algol/parc_Buffer.h> + +struct ccnx_codec_encoding_buffer; +typedef struct ccnx_codec_encoding_buffer CCNxCodecEncodingBuffer; + +/** + * @typedef CCNxCodecEncodingBufferIOVec + * @abstract Used for writev() or similar functions + * @constant encodingBuffer A reference counted copy of the encoding Buffer + * @constant iov An allocated array of iovec entries + * @constant iovcnt The number of array entries + * @discussion <#Discussion#> + */ +typedef struct ccnx_tlv_encoding_buffer_iovec { + CCNxCodecEncodingBuffer *encodingBuffer; + int iovcnt; + struct iovec iov[]; +} CCNxCodecEncodingBufferIOVec; + +// ====================================================================================== + +/** + * Creates an empty encoding buffer + * + * <#Paragraphs Of Explanation#> + * + * @return non-null An allocated encoding buffer + * @return null An error + * + * Example: + * @code + * <#example#> + * @endcode + */ +CCNxCodecEncodingBuffer *ccnxCodecEncodingBuffer_Create(void); + +/** + * Returns a reference counted copy + * + * Caller must call ccnxCodecEncodingBuffer_Release() on all copies. + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return non-null A reference counted copy + * @return null An error + * + * Example: + * @code + * <#example#> + * @endcode + */ +CCNxCodecEncodingBuffer *ccnxCodecEncodingBuffer_Acquire(const CCNxCodecEncodingBuffer *encodingBuffer); + + +/** + * Release the encoding buffer and all internal references + * + * will release the list and release our reference to all enclosed PARCBuffers + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * Example: + * @code + * <#example#> + * @endcode + */ +void ccnxCodecEncodingBuffer_Release(CCNxCodecEncodingBuffer **listBufferPtr); + +/** + * Displays the structure of the encoding buffer to STDOUT + * + * <#Paragraphs Of Explanation#> + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * + * Example: + * @code + * <#example#> + * @endcode + */ +void ccnxCodecEncodingBuffer_Display(const CCNxCodecEncodingBuffer *encodingBuffer, int indentation); + +/** + * Appends a PARCBuffer to the encoding buffer + * + * Appends to the encoding buffer a reference count to the given buffer. + * The return value is the storage node used in the internal data structure. + * + * The buffer will be used from its position at the time of use (i.e. when + * ccnxCodecEncodingBuffer_CreateIOVec() is called). It is important that no other + * use of the PARCBuffer move the Position. + * + * @param [in] encodingBuffer The buffer to append to + * @param [in] bufferToInsert The PARCBuffer to insert at the tail of the encoding buffer. + * + * @return number The position in the encoding buffer list + * + * Example: + * @code + * <#example#> + * @endcode + */ +size_t ccnxCodecEncodingBuffer_AppendBuffer(CCNxCodecEncodingBuffer *encodingBuffer, PARCBuffer *bufferToInsert); + +/** + * Prepends a PARCBuffer to the encoding buffer + * + * Prepends to the encoding buffer a reference count to the given buffer. + * The return value is the storage node used in the internal data structure. + * + * The buffer will be used from its position at the time of use (i.e. when + * ccnxCodecEncodingBuffer_CreateIOVec() is called). It is important that no other + * use of the PARCBuffer move the Position. + * + * @param [in] encodingBuffer The buffer to prepend to + * @param [in] bufferToInsert The PARCBuffer to insert at the head of the encoding buffer. + * + * @return number The position in the encoding buffer list + * + * Example: + * @code + * <#example#> + * @endcode + */ +size_t ccnxCodecEncodingBuffer_PrependBuffer(CCNxCodecEncodingBuffer *encodingBuffer, PARCBuffer *bufferToPrepend); + +/** + * Puts the value in scratch memory + * + * <#Paragraphs Of Explanation#> + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * + * Example: + * @code + * <#example#> + * @endcode + */ +void ccnxTlvEncodingbuffer_AppendUint16(CCNxCodecEncodingBuffer *encodingBuffer, uint16_t value); + +/** + * The number of elements in the list + * + * <#Paragraphs Of Explanation#> + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * + * Example: + * @code + * <#example#> + * @endcode + */ +size_t ccnxCodecEncodingBuffer_Size(const CCNxCodecEncodingBuffer *encodingBuffer); + +/** + * The total number of bytes in the list + * + * This is calculated as the sum of all PARCBuffer Remaining lengths in + * the encoding buffer. + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * + * Example: + * @code + * <#example#> + * @endcode + */ +size_t ccnxCodecEncodingBuffer_Length(const CCNxCodecEncodingBuffer *encodingBuffer); + +// ====================================================================================== + +/** + * Constructs an iovec array based on the buffers in the list + * + * The elements of the iovec array will be in the list order. + * Each iovec entry will point to the backing array of each PARCBuffer + * based on that buffers current position. + * + * This object contains a reference counted copy to the encoding buffer, so + * the caller can release the encoding buffer and hold on to only this object + * until the writev (or similar function) is done. + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return non-null The allocated IOVec structure + * @return null An error + * + * Example: + * @code + * <#example#> + * @endcode + */ +CCNxCodecEncodingBufferIOVec *ccnxCodecEncodingBuffer_CreateIOVec(CCNxCodecEncodingBuffer *encodingBuffer); + +/** + * Constructs an iovec array based on the buffers in the list that cooresponds to offset and length + * + * The elements of the iovec array will be in the list order. + * Each iovec entry will point to the backing array of each PARCBuffer + * based on that buffers current position. + * + * This object contains a reference counted copy to the encoding buffer, so + * the caller can release the encoding buffer and hold on to only this object + * until the writev (or similar function) is done. + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return non-null The allocated IOVec structure + * @return null An error, or the specified offset/length is not contained in the extent + * + * Example: + * @code + * <#example#> + * @endcode + */ +CCNxCodecEncodingBuffer *ccnxCodecEncodingBuffer_Slice(CCNxCodecEncodingBuffer *encodingBuffer, size_t offset, size_t length); + +/** + * Release the iovec object. + * + * This will release the IOVec object and release its reference to the encoding + * buffer. If this was the last reference to the encoding buffer, all references to + * the underlying PARCBuffers will be released too. + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * Example: + * @code + * <#example#> + * @endcode + */ +void ccnxCodecEncodingBufferIOVec_Release(CCNxCodecEncodingBufferIOVec **iovecPtr); + +#endif // libccnx_ccnxCodec_EncodingBuffer_h |