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. 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 (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 109 of file clif.h.

◆ 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]attrpointer to the attribute to add. Must not be NULL, and must contain a key.
[out]bufbuffer to add the attribute to. Can be NULL
[in]maxlensize of buf
Note
  • If buf is NULL this will return the amount of bytes that would be needed.
  • If the lengths of the key or the value of the attribute are not defined a NULL-terminated string will be assumed, and it will be calculated.
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]bufbuffer to add the separator to. Can be NULL
[in]maxlensize 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]targetstring containing the path to the resource. Must not be NULL.
[out]bufbuffer to output the formatted path. Can be NULL
[in]maxlensize 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]typetype of the attribute
[out]strpointer 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]linklink to populate. Must not be NULL.
[out]attrsarray of attrs to populate
[in]attrs_lenlength of attrs
[in]bufstring to decode. Must not be NULL.
[in]maxlensize 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]linklink to encode.Must not be NULL.
[out]bufbuffer to output the encoded link. Can be NULL
[in]maxlensize 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]inputstring where to look for the attribute. It should only be ONE link. Must not be NULL.
[in]input_lenlength of input
[out]attrpointer 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]inputstring containing the attribute name. Must not be NULL.
[in]input_lenlength 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]inputstring where to look for the target. It should only be ONE link. Must not be NULL.
[in]input_lenlength of input.
[out]outputif 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]attrattribute to initialize
[in]typetype of the attribute
Returns
0 if successful
<0 otherwise
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.
clif_t::attrs_len
unsigned attrs_len
size of array of attributes
Definition: clif.h:151
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.
clif_attr_t
Link format attribute descriptor.
Definition: clif.h:137
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.
clif_t
Link format descriptor.
Definition: clif.h:147