学习笔记_CCNx_20141204（1）

研究CCNx sample代码时的笔记，所有定义在源代码处都有更加详细解释。从头文件之间相互include可以看出最早是哪一个头文件最先定义的。

第一个：字节数组          

        /ccn/include/parc/algol/parc_ByteArray.h

#ifndef  #define:在编译阶段防止重复定义头文件

#include<stdlib.h>:添加c.c++系统库函数。

#include<stdbool.h>:添加对bool变量的支持、

#include<stdint.h>:添加对整型变量宏定义的支持。

struct parc_byte_array：自定义结构

typedef struct parc_byte_array PARCByteArray：结构别名

void parcByteArray_AssertValid(const PARCByteArray *instance)：验证某个PARCByteArray类型实例是否有效

PARCByteArray *parcByteArray_Allocate(const size_t capacity)：分配内存空间，记得最后要释放

PARCByteArray *parcByteArray_Wrap(size_t capacity, uint8_t array[capacity]):包裹

uint8_t *parcByteArray_Array(PARCByteArray *byteArray)：创建一个指针指向某个实例，实例的引用数没有增加。

PARCByteArray *parcByteArray_Acquire(PARCByteArray *instance)：增加该实例的一个引用数，释放后减少引用数。

void parcByteArray_Release(PARCByteArray **byteArrayPtr)：释放一个之前获取的引用，副作用是有指向这个实例的指针会变为NULL。

PARCByteArray *parcByteArray_PutByte(PARCByteArray *result, size_t index, uint8_t byte)：将一个uint_8类型的值放到字节数组中指定索引处。
uint8_t parcByteArray_GetByte(const PARCByteArray *result, size_t index)：获取给定字节数组中指定索引处的值。

int parcByteArray_Compare(const PARCByteArray *a, const PARCByteArray *b)：比较实例A与B以排序。返回负数、0或正数

PARCByteArray *parcByteArray_PutArray(PARCByteArray *result, size_t offset, size_t length, const uint8_t source[length])：将一个外部数组复制到PARCByteArray类型的数组中。

PARCByteArray *parcByteArray_GetArray(const PARCByteArray *source, size_t offset, size_t length, uint8_t destination[length])：效果与上一个函数相反。

PARCByteArray *parcByteArray_ArrayCopy(PARCByteArray *destination, size_t destOffset, PARCByteArray *source, size_t srcOffset, size_t length)：将一个实例的一部分内容复制到另一个数组里面。

size_t parcByteArray_Capacity(const PARCByteArray *byteArray)：获取数组容量（长度）.

PARCByteArray *parcByteArray_Copy(const PARCByteArray *original)：复制一个数组，完全新的。

bool parcByteArray_Equals(const PARCByteArray *a, const PARCByteArray *b)：比较两个数组实例是否相同。

uint32_t parcByteArray_HashCode(const PARCByteArray *array)：返回一个给定实例的hash值。

uint8_t *parcByteArray_AddressOfIndex(const PARCByteArray *array, size_t index)：返回给定索引值所指的数组中的位置的内存地址，是一个uint_8类型的指针。

void parcByteArray_Display(const PARCByteArray *array, int indentation)：打印出给定实例。

第二个文件：缓冲区

        /ccn/include/parc/algol/parc_Buffer.h

一个PARCBuffer是一个线性、确定的字节序列。主要的属性有内容、容量、限制、和位置。容量是指当前包含的字节数量。限制是指最大能够容纳的数量。位置是一个索引，指向下一个被读或写的字节。

通常用法是生成buffer——put操作插入数据——设定位置——读或取。

#include <parc/algol/parc_ByteArray.h>：将上一个头文件包含进来

struct parc_buffer：定义结构

typedef struct parc_buffer PARCBuffer：结构别名

void parcBuffer_AssertValid(const PARCBuffer *instance)：验证有效性

PARCBuffer *parcBuffer_Allocate(size_t capacity)：通过动态分配的方式生成一个buffer实例

PARCBuffer *parcBuffer_Wrap(void *array, size_t arrayLength, size_t position, size_t limit)：通过实例化一个数组，静态分配方式，对任何一方的修改会影响另一个。返回指针。

PARCBuffer *parcBuffer_WrapByteArray(PARCByteArray *byteArray, size_t position, size_t limit)：通过对一个给定的PARCByteArray数组引用生成一个buffer实例。修改对双方是同步的。

PARCBuffer *parcBuffer_WrapCString(char *string)：生成一个C string 的buffer、

PARCBuffer *parcBuffer_AllocateCString(const char *string)：生成一个C string 的buffer，效果有不太大的差别？

PARCBuffer *parcBuffer_NewArray(PARCBuffer *buffer, size_t capacity)：将给定buffer中一定数量的内覆盖到新的buffer中。

PARCBuffer *parcBuffer_Acquire(const PARCBuffer *buffer)：增加给定buffer的引用

void parcBuffer_Release(PARCBuffer **bufferPtr)：释放buffer。

size_t parcBuffer_Capacity(const PARCBuffer *buffer)：返回buffer大小、

PARCBuffer *parcBuffer_Clear(PARCBuffer *buffer)：清除一个buffer，位置回到0.

bool parcBuffer_Equals(const PARCBuffer *x, const PARCBuffer *y)：判断两个buffer是否相同。

int parcBuffer_Compare(const PARCBuffer *a, const PARCBuffer *b)：比较，返回负数,0,正数。

PARCByteArray *parcBuffer_Array(const PARCBuffer *buffer)：返回一个数组的指针，该数组内容是buffer的内容

PARCBuffer *parcBuffer_Copy(const PARCBuffer *buffer)：生成一个独立的buffer，复制给定buffer的内容。

PARCBuffer *parcBuffer_PutUint8(PARCBuffer *buffer, uint8_t value)：在给定buffer当前位置插入一个uint_8类型的值，当前位置加1.

PARCBuffer *parcBuffer_PutUint16(PARCBuffer *buffer, uint16_t value)：16bit 值，当前位置加2

PARCBuffer *parcBuffer_PutUint32(PARCBuffer *buffer, uint32_t value)：32bit值，当前位置加4

PARCBuffer *parcBuffer_PutUint64(PARCBuffer *buffer, uint64_t value)：64bit值，当前位置加8

uint8_t parcBuffer_GetUint8(PARCBuffer *buffer)：读取buffer当前位置的8位的值。

uint16_t parcBuffer_GetUint16(PARCBuffer *buffer)：16bit 值

uint32_t parcBuffer_GetUint32(PARCBuffer *buffer)：32bit 值

uint64_t parcBuffer_GetUint64(PARCBuffer *buffer)：64bit 值

size_t parcBuffer_ArrayOffset(const PARCBuffer *buffer)：返回一个offset，指示buffer中第一个元素的位置。

PARCBuffer *parcBuffer_Rewind(PARCBuffer *buffer)：位置被设定到0处，标记也被无效化。

PARCBuffer *parcBuffer_Reset(PARCBuffer *buffer)：将给定buffer的位置重新设置到之前标记的位置，

size_t parcBuffer_Limit(const PARCBuffer *buffer)：返回给定buffer的limit（一般指buffer长度？）

PARCBuffer *parcBuffer_Mark(PARCBuffer *buffer)：在buffer当前位置设置一个标记。

PARCBuffer *parcBuffer_SetLimit(PARCBuffer *buffer, size_t newLimit)：设定buffer的limit。（有关mark内容，找源代码）

void *parcBuffer_Overlay(PARCBuffer *buffer, size_t length)：返回一个指向缓冲内存的指针，该指针可以cast到一个特定类型。

Example:
 * @code
 * {
 *     char *expected = "Hello World";
 *     struct timeval theTime = { .tv_sec = 123, .tv_usec = 456};
 *
 *     PARCBuffer *buffer = parcBuffer_Allocate(sizeof(uint16_t) + strlen(expected) + sizeof(theTime));
 *
 *     parcBuffer_PutUint16(buffer, strlen(expected));
 *     parcBuffer_PutUint8(buffer, expected, strlen(expected));
 *     parcBuffer_PutUint8(buffer, &theTime, sizeof(theTime));
 *     parcBuffer_Flip();
 *
 *     uint16_t length = parcBuffer_GetUint16(buffer);
 *     char *actual = parcBuffer_Overlay(buffer, length);
 *     struct timeval *tm = parcBuffer_Overlay(buffer, sizeof(struct timeval));
 * }
 * @endcode

size_t parcBuffer_Position(const PARCBuffer *buffer)：返回buffer的位置，位置是指下一个将要被读或写的的元素的索引。

PARCBuffer *parcBuffer_SetPosition(PARCBuffer *buffer, size_t newPosition)：设定位置。

size_t parcBuffer_Remaining(const PARCBuffer *buffer)：返回当前位置到limit之间的元素数量，（buffer中剩下的元素数量）

bool parcBuffer_HasRemaining(const PARCBuffer *buffer)：判断是否还有剩余元素

PARCBuffer *parcBuffer_Slice(const PARCBuffer *original)：生成一个新的buffer，其内容与给定buffer 中给定一段一致，内容是给定buffer当前位置到limit的所有元素，修改对双方影响等同。要buffer的后一段

PARCBuffer *parcBuffer_Flip(PARCBuffer *buffer)：将limit设置到当前位置，当前位置重设为0.要buffer的前一段

uint8_t parcBuffer_GetAtIndex(const PARCBuffer *buffer, size_t index)：获取给定索引处的值

PARCBuffer *parcBuffer_GetArray(PARCBuffer *buffer, size_t length, uint8_t array[length])：从给定buffer中读取一段复制到给定数组中

PARCBuffer *parcBuffer_PutAtIndex(PARCBuffer *buffer, size_t index, uint8_t value)：在给定位置插入一个值，当前位置不变

PARCBuffer *parcBuffer_PutArray(PARCBuffer *buffer, size_t arrayLength, const uint8_t array[arrayLength])：从给定数组中复制给定长度的字节到buffer中。

PARCBuffer *parcBuffer_PutBuffer(PARCBuffer *buffer, const PARCBuffer *source)：将一个buffer中的值复制到另一个中

uint32_t parcBuffer_HashCode(const PARCBuffer *buffer)：返回给定实例的hash值

size_t parcBuffer_FindUint8(const PARCBuffer *buffer, uint8_t byte)：返回匹配到给定字节的首个位置。如果没有匹配就返回SIZE_MAX.

size_t parcBuffer_FindUint8(const PARCBuffer *buffer, uint8_t byte):输出给定实例的string表示形式

void parcBuffer_Display(const PARCBuffer *buffer, int indentation)：显示给定buffer的人类可读形式，indentation是缩进

char *parcBuffer_ToHexString(const PARCBuffer *buffer)：返回一个以空字符结束的字符串，其包含给定buffer的16进制形式显示

bool parcBuffer_SkipOver(PARCBuffer *buffer, size_t length, const uint8_t bytesToSkipOver[length])：将给定buffer的位置向前变动到首个没有包括在给定数组中字符的位置跳过给定字节数组指定的字符，返回1，buffer中位置改动，返回0位置到末尾

@code
 * {
 *     PARCBuffer *buffer = parcBuffer_WrapCString("Hello World");
 *     uint8_t skipOverBytes[] = { 'H', 0 };
 *
 *     bool actual = parcBuffer_SkipOver(buffer, 1, skipOverBytes);
 *     // the buffer position will now be 1, as it skipped over the 'H' byte in the array
 *     // actual will be true
 * }
 * @endcode

bool parcBuffer_SkipTo(PARCBuffer *buffer, size_t length, const uint8_t bytesToSkipTo[length])：将给定buffer的位置向前变动到首个包括在给定数组中字符的位置跳到给定字符的首个位置

uint8_t parcBuffer_PeekByte(const PARCBuffer *buffer)：返回当前位置的字节，同时位置不向前加1、