Simple encoding and decoding of CoRE Link Format (RFC 6690) strings. More...

Detailed Description

Simple encoding and decoding of CoRE Link Format (RFC 6690) strings.

See also: RFC 6690: https://tools.ietf.org/html/rfc6690

clif provides a high-level API for CoRE Link Format encoding and decoding of links, through the clif_encode_link and clif_decode_link respectively.

The high-level API is built on top of low-level functions provided by clif, such as clif_add_target, clif_add_attr, and clif_get_attr. Also, some convenience functions like clif_get_attr_type, clif_attr_type_to_str and clif_init_attr are provided, to facilitate the work with links.

Decoding

clif_decode_link takes a buffer which contains an encoded link and returns the information of it in a clif_t structure and each attribute in a clif_attr_t structure of a given array.

// A buffer 'input_buf' of length 'input_len' contains the links to decode
clif_attr_t out_attrs[ATTRS_NUM];
clif_t out_links[LINKS_NUM];
 
const char *pos = input_buf;
unsigned links_numof = 0;
unsigned attrs_numof = 0;
 
while (pos < &input_buf[input_len]) {
     ssize_t res = clif_decode_link(&out_links[links_numof],
                                    &out_attrs[attrs_numof],
                                    ATTRS_NUM - attrs_numof, pos,
                                    &input_buf[input_len]- pos);
     if (res < 0) {
         break;
     }
     pos += res;
     attrs_numof += out_links[links_numof].attrs_len;
     links_numof++;
}

Encoding

clif_encode_link encodes a given link into a buffer, it can be called with a NULL pointer, in that case it will only calculate the amount of bytes needed to encode the link. After every call to this function a separator needs to be added to the buffer.

// A 'links' array of clif_t, of length 'links_len' contains the links to encode
char out[OUT_SIZE];
ssize_t res;
size_t pos = 0;
 
for (unsigned i = 0; i < links_len; i++) {
     if (i) {
         res = clif_add_link_separator(&out[pos], OUT_SIZE - pos);
         if (res <= 0) {
             break;
         }
         pos += res;
     }
 
     res = clif_encode_link(&links[i], &out[pos], OUT_SIZE - pos);
     if (res <= 0) {
         break;
     }
     pos += res;
}

Note: 'attribute', in this module, extends to the term 'link-param' on the ABNF in section 2 of RFC 6690.

Files
file	clif_internal.h
	Internal definitions for CoRE Link format module.

file	clif.h
	CoRE Link Format encoding and decoding library public definitions.

Data Structures
struct	clif_attr_t
	Link format attribute descriptor. More...

struct	clif_t
	Link format descriptor. More...

Enumerations
enum	{ CLIF_OK = 0 , CLIF_NO_SPACE = -1 , CLIF_NOT_FOUND = -2 }
	Return types for the CoRE Link Format API. More...

enum	clif_attr_type_t { CLIF_ATTR_ANCHOR = 0 , CLIF_ATTR_REL = 1 , CLIF_ATTR_LANG = 2 , CLIF_ATTR_MEDIA = 3 , CLIF_ATTR_TITLE = 4 , CLIF_ATTR_TITLE_EXT = 5 , CLIF_ATTR_TYPE = 6 , CLIF_ATTR_RT = 7 , CLIF_ATTR_IF = 8 , CLIF_ATTR_SZ = 9 , CLIF_ATTR_CT = 10 , CLIF_ATTR_OBS = 11 , CLIF_ATTR_EXT = 12 }
	Types of link format attributes. More...

Functions
ssize_t	clif_encode_link (const clif_t link, char buf, size_t maxlen)
	Encodes a given link in link format into a given buffer. More...

ssize_t	clif_decode_link (clif_t link, clif_attr_t attrs, unsigned attrs_len, const char *buf, size_t maxlen)
	Decodes a string of link format. More...

ssize_t	clif_add_target_from_buffer (const char target, size_t target_len, char buf, size_t maxlen)
	Adds a given `target` to a given buffer `buf` using link format. More...

ssize_t	clif_add_target (const char target, char buf, size_t maxlen)
	Adds a given `target` to a given buffer `buf` using link format. More...

ssize_t	clif_add_attr (clif_attr_t attr, char buf, size_t maxlen)
	Adds a given `attr` to a given buffer `buf` using link format. More...

ssize_t	clif_add_link_separator (char *buf, size_t maxlen)
	Adds the link separator character to a given `buf`, using link format. More...

ssize_t	clif_get_target (const char input, size_t input_len, char *output)
	Looks for a the target URI of a given link. More...

ssize_t	clif_get_attr (const char input, size_t input_len, clif_attr_t attr)
	Looks for the first attribute in a given link. More...

clif_attr_type_t	clif_get_attr_type (const char *input, size_t input_len)
	Returns the attribute type of a given string. More...

ssize_t	clif_attr_type_to_str (clif_attr_type_t type, const char **str)
	Returns a constant string of a given attribute type. More...

int	clif_init_attr (clif_attr_t *attr, clif_attr_type_t type)
	Initializes the key of a given attribute according to a given type. More...

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Return types for the CoRE Link Format API.

Enumerator
CLIF_OK	success
CLIF_NO_SPACE	not enough space in the buffer
CLIF_NOT_FOUND	could not find a component in a buffer

Definition at line 108 of file clif.h.

◆ clif_attr_type_t

enum clif_attr_type_t

Types of link format attributes.

Enumerator
CLIF_ATTR_ANCHOR	anchor
CLIF_ATTR_REL	rel
CLIF_ATTR_LANG	hreflang
CLIF_ATTR_MEDIA	media
CLIF_ATTR_TITLE	title
CLIF_ATTR_TITLE_EXT	title*
CLIF_ATTR_TYPE	type
CLIF_ATTR_RT	rt
CLIF_ATTR_IF	if
CLIF_ATTR_SZ	sz
CLIF_ATTR_CT	ct
CLIF_ATTR_OBS	obs
CLIF_ATTR_EXT	extensions

Definition at line 117 of file clif.h.

Function Documentation

◆ clif_add_attr()

ssize_t clif_add_attr	(	clif_attr_t *	attr,
		char *	buf,
		size_t	maxlen
	)

Adds a given attr to a given buffer buf using link format.

Precondition: (attr != NULL) && (attr->key != NULL)

Parameters

[in]	attr	pointer to the attribute to add. Must not be NULL, and must contain a key.
[out]	buf	buffer to add the attribute to. Can be NULL
[in]	maxlen	size of `buf`

Note

If buf is NULL this will return the amount of bytes that would be needed.
The length of the key must be set in attr->key_len.

Returns: amount of bytes used from the buffer if successful; CLIF_NO_SPACE if there is not enough space in the buffer

◆ clif_add_link_separator()

ssize_t clif_add_link_separator	(	char *	buf,
		size_t	maxlen
	)

Adds the link separator character to a given buf, using link format.

Parameters

[out]	buf	buffer to add the separator to. Can be NULL
[in]	maxlen	size of `buf`

Note: If buf is NULL this will return the amount of bytes that would be needed

Returns: amount of bytes used from buffer if successful; CLIF_NO_SPACE if there is not enough space in the buffer

◆ clif_add_target()

ssize_t clif_add_target	(	const char *	target,
		char *	buf,
		size_t	maxlen
	)

Adds a given target to a given buffer buf using link format.

Precondition: target != NULL

Parameters

[in]	target	zero terminated string containing the path to the resource. Must not be NULL.
[out]	buf	buffer to output the formatted path. Can be NULL
[in]	maxlen	size of `buf`

Note: If buf is NULL this will return the amount of bytes that would be needed

Returns: in success the amount of bytes used in the buffer; CLIF_NO_SPACE if there is not enough space in the buffer

◆ clif_add_target_from_buffer()

ssize_t clif_add_target_from_buffer	(	const char *	target,
		size_t	target_len,
		char *	buf,
		size_t	maxlen
	)

Adds a given target to a given buffer buf using link format.

Precondition: target != NULL

Parameters

[in]	target	buffer containing the path to the resource. Must not be NULL.
[in]	target_len	size of `target`
[out]	buf	buffer to output the formatted path. Can be NULL
[in]	maxlen	size of `buf`

Note: If buf is NULL this will return the amount of bytes that would be needed

Returns: in success the amount of bytes used in the buffer; CLIF_NO_SPACE if there is not enough space in the buffer

◆ clif_attr_type_to_str()

ssize_t clif_attr_type_to_str	(	clif_attr_type_t	type,
		const char **	str
	)

Returns a constant string of a given attribute type.

Parameters

[in]	type	type of the attribute
[out]	str	pointer to store the string pointer

Returns: length of the string; CLIF_NOT_FOUND if the type is an extension or unknown

◆ clif_decode_link()

ssize_t clif_decode_link	(	clif_t *	link,
		clif_attr_t *	attrs,
		unsigned	attrs_len,
		const char *	buf,
		size_t	maxlen
	)

Decodes a string of link format.

It decodes the first occurrence of a link.

Precondition: (link != NULL) && (buf != NULL)

Parameters

[out]	link	link to populate. Must not be NULL.
[out]	attrs	array of attrs to populate
[in]	attrs_len	length of `attrs`
[in]	buf	string to decode. Must not be NULL.
[in]	maxlen	size of `buf`

Returns: number of bytes parsed from buf in success; CLIF_NOT_FOUND if the string is malformed

◆ clif_encode_link()

ssize_t clif_encode_link	(	const clif_t *	link,
		char *	buf,
		size_t	maxlen
	)

Encodes a given link in link format into a given buffer.

Precondition: link != NULL

Parameters

[in]	link	link to encode.Must not be NULL.
[out]	buf	buffer to output the encoded link. Can be NULL
[in]	maxlen	size of `buf`

Note: If buf is NULL this will return the amount of bytes that would be needed

Returns: amount of bytes used from buf in success; CLIF_NO_SPACE if there is not enough space in the buffer

◆ clif_get_attr()

ssize_t clif_get_attr	(	const char *	input,
		size_t	input_len,
		clif_attr_t *	attr
	)

Looks for the first attribute in a given link.

Precondition: (input != NULL) && (attr != NULL)

Note: In order to consider that the string contains a valid attribute, input should start with the attribute separator character ';'.

Parameters

[in]	input	string where to look for the attribute. It should only be ONE link. Must not be NULL.
[in]	input_len	length of `input`
[out]	attr	pointer to store the found attribute information. Must not be NULL.

Returns: length of the attribute in the buffer if found; CLIF_NOT_FOUND if no valid attribute is found

◆ clif_get_attr_type()

clif_attr_type_t clif_get_attr_type	(	const char *	input,
		size_t	input_len
	)

Returns the attribute type of a given string.

Precondition: (input != NULL) && (input_len > 0)

Parameters

[in]	input	string containing the attribute name. Must not be NULL.
[in]	input_len	length of `input`. Must be greater than 0.

Returns: type of the attribute

◆ clif_get_target()

ssize_t clif_get_target	(	const char *	input,
		size_t	input_len,
		char **	output
	)

Looks for a the target URI of a given link.

Precondition: input != NULL

Parameters

[in]	input	string where to look for the target. It should only be ONE link. Must not be NULL.
[in]	input_len	length of `input`.
[out]	output	if a target is found this will point to the beginning of it

Returns: length of the target if found; CLIF_NOT_FOUND if no valid target is found

◆ clif_init_attr()

int clif_init_attr	(	clif_attr_t *	attr,
		clif_attr_type_t	type
	)

Initializes the key of a given attribute according to a given type.

Parameters

[out]	attr	attribute to initialize
[in]	type	type of the attribute

Returns: 0 if successful; <0 otherwise

Detailed Description

Decoding

Encoding

Files

Data Structures

Enumerations

Functions

Enumeration Type Documentation

◆ anonymous enum

◆ clif_attr_type_t

Function Documentation

◆ clif_add_attr()

◆ clif_add_link_separator()

◆ clif_add_target()

◆ clif_add_target_from_buffer()

◆ clif_attr_type_to_str()

◆ clif_decode_link()

◆ clif_encode_link()

◆ clif_get_attr()

◆ clif_get_attr_type()

◆ clif_get_target()

◆ clif_init_attr()