Initial commit: ccnxlibs.

Change-Id: I1b376527a7dd01a6b9e083a6cb646955902f45c0
Signed-off-by: Luca Muscariello <lumuscar+fdio@cisco.com>

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