CoRE Link Format

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.
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.
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.
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.
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.
ssize_t	clif_add_link_separator (char *buf, size_t maxlen)
	Adds the link separator character to a given buf, using link format.
ssize_t	clif_get_target (const char *input, size_t input_len, char **output)
	Looks for a the target URI of a given link.
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.
clif_attr_type_t	clif_get_attr_type (const char *input, size_t input_len)
	Returns the attribute type of a given string.
ssize_t	clif_attr_type_to_str (clif_attr_type_t type, const char **str)
	Returns a constant string of a given attribute type.
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.

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 109 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 118 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