Wrapper API

High-level wrapper APIs providing convenience. More...

Collaboration diagram for Wrapper API:

Enumerations
enum	TLV_DATAARG_TYPE {   TLV_DATAARG_NAME_PTR, TLV_DATAARG_NAME_BUF, TLV_DATAARG_NAME_SEGNO_U64, TLV_DATAARG_CONTENTTYPE_U8,   TLV_DATAARG_FRESHNESSPERIOD_U64, TLV_DATAARG_FINALBLOCKID_PTR, TLV_DATAARG_FINALBLOCKID_BUF, TLV_DATAARG_FINALBLOCKID_U64,   TLV_DATAARG_CONTENT_BUF, TLV_DATAARG_CONTENT_SIZE, TLV_DATAARG_SIGTYPE_U8, TLV_DATAARG_IDENTITYNAME_PTR,   TLV_DATAARG_SIGKEY_PTR, TLV_DATAARG_SIGTIME_U64, TLV_DATAARG_VERIFY }
	The type of variant args of tlv_make_data and tlv_parse_data. More...
enum	TLV_INTARG_TYPE {   TLV_INTARG_NAME_PTR, TLV_INTARG_NAME_BUF, TLV_INTARG_NAME_SEGNO_U64, TLV_INTARG_CANBEPREFIX_BOOL,   TLV_INTARG_MUSTBEFRESH_BOOL, TLV_INTARG_LIFETIME_U64, TLV_INTARG_HOTLIMIT_U8, TLV_INTARG_PARAMS_BUF,   TLV_INTARG_PARAMS_SIZE, TLV_INTARG_SIGTYPE_U8, TLV_INTARG_IDENTITYNAME_PTR, TLV_INTARG_SIGKEY_PTR,   TLV_INTARG_VERIFY }
	The type of variant args of tlv_make_interest. More...

Functions
int	tlv_make_data (uint8_t *buf, size_t buflen, size_t *result_size, int argc,...)
	All-in-one function to generate a Data packet. More...
int	tlv_parse_data (uint8_t *buf, size_t buflen, int argc,...)
	All-in-one function to parse a Data packet. More...
int	tlv_make_interest (uint8_t *buf, size_t buflen, size_t *result_size, int argc,...)
	All-in-one function to generate an Interest packet. More...
int	tlv_parse_interest (uint8_t *buf, size_t buflen, int argc,...)
	All-in-one function to parse an Interest packet. More...
void	tlv_encode_segno (name_component_t *comp, uint64_t val)
	Encode a name component from a segment number. More...
uint64_t	tlv_decode_segno (name_component_t *comp)
	Decode a name component into a segment number. More...

Detailed Description

High-level wrapper APIs providing convenience.

Enumeration Type Documentation

TLV_DATAARG_TYPE

enum TLV_DATAARG_TYPE

The type of variant args of tlv_make_data and tlv_parse_data.

Enumerator
TLV_DATAARG_NAME_PTR	A pointer to a name. make_data: [in] ndn_name_t* At least one Name is necessary, otherwise NDN_INVALID_ARG is returned. If multiple names are specified by mistake, the last one is used. parse_data: [out] ndn_name_t*
TLV_DATAARG_NAME_BUF	A pointer to an encoded TLV name. make_data: [in] uint8_t* It will automaticaly detect the length. parse_data: [out] uint8_t** Output a pointer to where the name starts in buf.
TLV_DATAARG_NAME_SEGNO_U64	Segment number. make_data: [in] uint64_t It will be added after name. parse_data: [out] uint64_t* Output (uint64_t)-1 if the last component is not segment number.
TLV_DATAARG_CONTENTTYPE_U8	Content type. make_data: [in] uint8_t (promoted) parse_data: [out] uint8_t* Output 0xFF if not included in the packet.
TLV_DATAARG_FRESHNESSPERIOD_U64	Freshness period. make_data: [in] uint64_t parse_data: [out] uint64_t* Output 0 if not included in the packet.
TLV_DATAARG_FINALBLOCKID_PTR	A pointer to a final block id. make_data: [in] name_component_t* parse_data: [out] name_component_t* Output size=0 if not included.
TLV_DATAARG_FINALBLOCKID_BUF	A pointer to an encoded final block id. make_data: [in] uint8_t* It will automaticaly detect the length. parse_data: [out] uint8_t** Output a pointer to where the FinalBlockId starts in buf. NULL if not included.
TLV_DATAARG_FINALBLOCKID_U64	A pointer to a final block id, in form of segment number. make_data: [in] uint64_t parse_data: [out] uint64_t* If it fails, (uint64_t)-1 will be set.
TLV_DATAARG_CONTENT_BUF	Payload. make_data: [in, opt] uint8_t* parse_data: [out] uint8_t** Output a pointer to where the Content starts in buf. NULL if not included.
TLV_DATAARG_CONTENT_SIZE	The size of content. make_data: [in] size_t parse_data: [out] size_t*
TLV_DATAARG_SIGTYPE_U8	Signature type. make_data: [in] uint8_t (promoted) By default, NDN_SIG_TYPE_DIGEST_SHA256 is used. parse_data: [out] uint8_t*
TLV_DATAARG_IDENTITYNAME_PTR	A pointer to the name of identity. make_data: [in, opt] ndn_name_t* parse_data: N/A
TLV_DATAARG_SIGKEY_PTR	A pointer to the key. make_data: [in, opt] ndn_ecc_prv_t* or ndn_hmac_key_t* Not necessary for NDN_SIG_TYPE_DIGEST_SHA256. parse_data: [in, opt] ndn_ecc_pub_t* or ndn_hmac_key_t* Pass public key used by verification.
TLV_DATAARG_SIGTIME_U64	The signature timestamp. make_data: [in] uint64_t parse_data: [out] uint64_t* Output 0 if not included.
TLV_DATAARG_VERIFY	Verify the Data after decoding. make_data: N/A parse_data: [in] bool (promoted)

TLV_INTARG_TYPE

enum TLV_INTARG_TYPE

The type of variant args of tlv_make_interest.

Enumerator
TLV_INTARG_NAME_PTR	A pointer to a name. make_interest: [in] ndn_name_t* At least one Name is necessary, otherwise NDN_INVALID_ARG is returned. If multiple names are specified by mistake, the last one is used. parse_interest: [out] ndn_name_t*
TLV_INTARG_NAME_BUF	A pointer to an encoded TLV name. make_interest: [in] uint8_t* It will automaticaly detect the length. parse_interest: [out] uint8_t** Output a pointer to where the name starts in buf.
TLV_INTARG_NAME_SEGNO_U64	Segment number. make_interest: [in] uint64_t It will be added after name. parse_interest: [out] uint64_t* Output (uint64_t)-1 if the last component is not segment number.
TLV_INTARG_CANBEPREFIX_BOOL	CanBePrefix. make_interest: [in] bool (promoted) False by default. parse_interest: [out] bool*
TLV_INTARG_MUSTBEFRESH_BOOL	MustBeFresh. make_interest: [in] bool (promoted) False by default. parse_interest: [out] bool*
TLV_INTARG_LIFETIME_U64	Interest lifetime in milliseconds. make_interest: [in] uint64_t NDN_DEFAULT_INTEREST_LIFETIME by default. parse_interest: [out] uint64_t*
TLV_INTARG_HOTLIMIT_U8	Interest HopLimit. make_interest: [in] uint8_t (promoted) parse_interest: [out] uint8_t* (uint8_t)-1 by default.
TLV_INTARG_PARAMS_BUF	Interest parameters. make_interest: [in, opt] uint8_t* parse_interest: [out] uint8_t** Output a pointer to where the Interest parameters start in buf. NULL if not included.
TLV_INTARG_PARAMS_SIZE	The size of Interest parameters. make_interest: [in] size_t parse_interest: [out] size_t*
TLV_INTARG_SIGTYPE_U8	Signature type. make_interest: [in] uint8_t (promoted) By default, the Interest won't be signed. parse_interest: [out] uint8_t*
TLV_INTARG_IDENTITYNAME_PTR	A pointer to the name of identity. make_interest: [in, opt] ndn_name_t* parse_interest: N/A
TLV_INTARG_SIGKEY_PTR	A pointer to the key. make_interest: [in, opt] ndn_ecc_prv_t* or ndn_hmac_key_t* Not necessary for NDN_SIG_TYPE_DIGEST_SHA256. parse_interest: [in, opt] ndn_ecc_prv_t* or ndn_hmac_key_t* Pass public key used by verification.
TLV_INTARG_VERIFY	Verify the Interest after decoding. make_interest: N/A parse_interest: [in] bool (promoted)

Function Documentation

tlv_decode_segno()

uint64_t tlv_decode_segno

(

name_component_t *

comp

)

Decode a name component into a segment number.

Parameters

[in]

comp

Target component.

Returns

The segment number. (uint64_t)-1 if fails.

tlv_encode_segno()

void tlv_encode_segno	(	name_component_t *	comp,
		uint64_t	val
	)

Encode a name component from a segment number.

Parameters

[out]	comp	Target component.
[in]	val	The segment number.

tlv_make_data()

int tlv_make_data	(	uint8_t *	buf,
		size_t	buflen,
		size_t *	result_size,
		int	argc,
			...
	)

All-in-one function to generate a Data packet.

This function uses variant args to input optional parameters. The value of each variant arg should be given after its type. See TLV_DATAARG_TYPE for all supported variant arg types. An example:

tlv_make_data(buf, sizeof(buf), &output_size, 6, // 6 args following
              TLV_DATAARG_NAME_PTR,            &name,
              TLV_DATAARG_NAME_SEGNO_U64,      (uint64_t)i
              TLV_DATAARG_FRESHNESSPERIOD_U64, (uint64_t)15000,
              TLV_DATAARG_FINALBLOCKID_U64,    (uint64_t)(seg_count - 1),
              TLV_DATAARG_CONTENT_BUF,         content,
              TLV_DATAARG_CONTENT_SIZE,        sizeof(content));
// Create a Data packet with its payload = content,
// name = name + i (segment number), freshness period = 15s.
// And the data have seg_count segments in total.

Parameters

[out]	buf	The buffer where Data is stored. result_size bytes are written.
[in]	buflen	The available size of buf.
[out]	result_size	[Optional] The encoded size of the Data packet.
[in]	argc	The number of variant args, without counting the type.

Returns

NDN_SUCCESS if the call succeeded. The error code otherwise.

Return values

NDN_INVALID_ARG	An unknown argument is given; or no name is given.
NDN_SEC_UNSUPPORT_SIGN_TYPE	Unsupported signature type.
NDN_INVALID_POINTER	A non-optional pointer argument is NULL. Notice that some arguments are allowed to be NULL.

Postcondition

result_size <= buflen

Remarks

Not fully tested yet. Besides, the ideal solution is to allow users pass NULL to buf to get result_size only, but this is not possible under current back end.

tlv_make_interest()

int tlv_make_interest	(	uint8_t *	buf,
		size_t	buflen,
		size_t *	result_size,
		int	argc,
			...
	)

All-in-one function to generate an Interest packet.

This function uses variant args to input optional parameters. The value of each variant arg should be given after its type. See TLV_INTARG_TYPE for all supported variant arg types. An example:

tlv_make_interest(buf, sizeof(buf), &output_size, 5, // 5 args following
                  TLV_INTARG_NAME_PTR,         &name,
                  TLV_INTARG_NAME_SEGNO_U64,   (uint64_t)13,
                  TLV_INTARG_CANBEPREFIX_BOOL, true,
                  TLV_INTARG_MUSTBEFRESH_BOOL, true,
                  TLV_INTARG_LIFETIME_U64,     (uint64_t)60000);
// Create a Interest packet with its name = name/%00%13
// lifetime = 60s, CanBePrefix and MustBeFresh.

Parameters

[out]	buf	The buffer where Interest is stored. result_size bytes are written.
[in]	buflen	The available size of buf.
[out]	result_size	[Optional] The encoded size of the Interest packet.
[in]	argc	The number of variant args, without counting the type.

Returns

NDN_SUCCESS if the call succeeded. The error code otherwise.

Return values

NDN_INVALID_ARG	An unknown argument is given; or no name is given.
NDN_SEC_UNSUPPORT_SIGN_TYPE	Unsupported signature type.
NDN_INVALID_POINTER	A non-optional pointer argument is NULL. Notice that some arguments are allowed to be NULL.

Postcondition

result_size <= buflen

Remarks

Not fully tested yet. Besides, the ideal solution is to allow users pass NULL to buf to get result_size only, but this is not possible under current back end.

tlv_parse_data()

int tlv_parse_data	(	uint8_t *	buf,
		size_t	buflen,
		int	argc,
			...
	)

All-in-one function to parse a Data packet.

This function uses variant args as input and output optional parameters. The value of each variant arg should be given after its type. See TLV_DATAARG_TYPE for all supported variant arg types. An example:

ndn_name_t name;
uint64_t segno, last_segno;
uint8_t *content;
size_t content_size;
tlv_parse_data(data_buf, data_size, 6,  // 6 args following
               TLV_DATAARG_NAME_PTR,         &name,
               TLV_DATAARG_NAME_SEGNO_U64,   &segno,
               TLV_DATAARG_FINALBLOCKID_U64, &last_segno,
               TLV_DATAARG_CONTENT_BUF,      &content,
               TLV_DATAARG_CONTENT_SIZE,     &content_size,
               TLV_DATAARG_VERIFY,           true);

Parameters

[in]	buf	The encoded TLV Data block.
[in]	buflen	The size of buf.
[in]	argc	The number of variant args, without counting the type.

Returns

NDN_SUCCESS if the call succeeded. The error code otherwise.

Return values

NDN_INVALID_ARG	An unknown argument is given.
NDN_UNSUPPORTED_FORMAT	Unsupported Data format.
NDN_SEC_UNSUPPORT_SIGN_TYPE	Unsupported signature type.
NDN_INVALID_POINTER	A non-optional pointer argument is NULL. Notice that some arguments are allowed to be NULL.

Remarks

Not fully tested yet.

tlv_parse_interest()

int tlv_parse_interest	(	uint8_t *	buf,
		size_t	buflen,
		int	argc,
			...
	)

All-in-one function to parse an Interest packet.

This function uses variant args as input and output optional parameters. The value of each variant arg should be given after its type. See TLV_INTARG_TYPE for all supported variant arg types. An example:

ndn_name_t name;
uint64_t segno;
tlv_parse_data(interest_buf, interest_size, 2,     // 2 args following
               TLV_INTARG_NAME_PTR,       &name,
               TLV_INTARG_NAME_SEGNO_U64, &segno);

Parameters

[in]	buf	The encoded TLV Interest block.
[in]	buflen	The size of buf.
[in]	argc	The number of variant args, without counting the type.

Returns

NDN_SUCCESS if the call succeeded. The error code otherwise.

Return values

NDN_INVALID_ARG	An unknown argument is given.
NDN_UNSUPPORTED_FORMAT	Unsupported Interest format.
NDN_SEC_UNSUPPORT_SIGN_TYPE	Unsupported signature type.
NDN_INVALID_POINTER	A non-optional pointer argument is NULL. Notice that some arguments are allowed to be NULL.

Remarks

Not fully tested yet.