io.h File Reference

#include <anjay/core.h>

Go to the source code of this file.

Macros
#define	ANJAY_EXECUTE_GET_ARG_END   1
#define	ANJAY_BUFFER_TOO_SHORT   1

Typedefs
typedef struct anjay_dm_list_ctx_struct	anjay_dm_list_ctx_t
typedef struct anjay_dm_resource_list_ctx_struct	anjay_dm_resource_list_ctx_t
typedef struct anjay_output_ctx_struct	anjay_output_ctx_t
typedef struct anjay_ret_bytes_ctx_struct	anjay_ret_bytes_ctx_t
typedef struct anjay_input_ctx_struct	anjay_input_ctx_t
typedef struct anjay_execute_ctx_struct	anjay_execute_ctx_t

Enumerations
enum	anjay_dm_resource_kind_t {   ANJAY_DM_RES_R , ANJAY_DM_RES_W , ANJAY_DM_RES_RW , ANJAY_DM_RES_RM ,   ANJAY_DM_RES_WM , ANJAY_DM_RES_RWM , ANJAY_DM_RES_E , ANJAY_DM_RES_BS_RW }
enum	anjay_dm_resource_presence_t { ANJAY_DM_RES_ABSENT = 0 , ANJAY_DM_RES_PRESENT = 1 }

Functions
void	anjay_dm_emit (anjay_dm_list_ctx_t *ctx, uint16_t id)
void	anjay_dm_emit_res (anjay_dm_resource_list_ctx_t *ctx, anjay_rid_t rid, anjay_dm_resource_kind_t kind, anjay_dm_resource_presence_t presence)
anjay_ret_bytes_ctx_t *	anjay_ret_bytes_begin (anjay_output_ctx_t *ctx, size_t length)
int	anjay_ret_bytes_append (anjay_ret_bytes_ctx_t *ctx, const void *data, size_t length)
int	anjay_ret_bytes (anjay_output_ctx_t *ctx, const void *data, size_t length)
int	anjay_ret_string (anjay_output_ctx_t *ctx, const char *value)
int	anjay_ret_i64 (anjay_output_ctx_t *ctx, int64_t value)
static int	anjay_ret_i32 (anjay_output_ctx_t *ctx, int32_t value)
int	anjay_ret_u64 (anjay_output_ctx_t *ctx, uint64_t value)
static int	anjay_ret_u32 (anjay_output_ctx_t *ctx, uint32_t value)
int	anjay_ret_double (anjay_output_ctx_t *ctx, double value)
static int	anjay_ret_float (anjay_output_ctx_t *ctx, float value)
int	anjay_ret_bool (anjay_output_ctx_t *ctx, bool value)
int	anjay_ret_objlnk (anjay_output_ctx_t *ctx, anjay_oid_t oid, anjay_iid_t iid)
int	anjay_ret_certificate_chain_info (anjay_output_ctx_t *ctx, avs_crypto_certificate_chain_info_t certificate_chain_info)
int	anjay_ret_private_key_info (anjay_output_ctx_t *ctx, avs_crypto_private_key_info_t private_key_info)
int	anjay_ret_psk_identity_info (anjay_output_ctx_t *ctx, avs_crypto_psk_identity_info_t psk_identity_info)
int	anjay_ret_psk_key_info (anjay_output_ctx_t *ctx, avs_crypto_psk_key_info_t psk_key_info)
int	anjay_execute_get_next_arg (anjay_execute_ctx_t *ctx, int *out_arg, bool *out_has_value)
int	anjay_execute_get_arg_value (anjay_execute_ctx_t *ctx, size_t *out_bytes_read, char *out_buf, size_t buf_size)
int	anjay_get_bytes (anjay_input_ctx_t *ctx, size_t *out_bytes_read, bool *out_message_finished, void *out_buf, size_t buf_size)
int	anjay_get_string (anjay_input_ctx_t *ctx, char *out_buf, size_t buf_size)
int	anjay_get_i32 (anjay_input_ctx_t *ctx, int32_t *out)
int	anjay_get_i64 (anjay_input_ctx_t *ctx, int64_t *out)
int	anjay_get_u32 (anjay_input_ctx_t *ctx, uint32_t *out)
int	anjay_get_u64 (anjay_input_ctx_t *ctx, uint64_t *out)
int	anjay_get_float (anjay_input_ctx_t *ctx, float *out)
int	anjay_get_double (anjay_input_ctx_t *ctx, double *out)
int	anjay_get_bool (anjay_input_ctx_t *ctx, bool *out)
int	anjay_get_objlnk (anjay_input_ctx_t *ctx, anjay_oid_t *out_oid, anjay_iid_t *out_iid)

Macro Definition Documentation

ANJAY_BUFFER_TOO_SHORT

#define ANJAY_BUFFER_TOO_SHORT   1

ANJAY_EXECUTE_GET_ARG_END

#define ANJAY_EXECUTE_GET_ARG_END   1

Typedef Documentation

anjay_dm_list_ctx_t

typedef struct anjay_dm_list_ctx_struct anjay_dm_list_ctx_t

Type used to return Object Instance or Resource Instance lists.

anjay_dm_resource_list_ctx_t

typedef struct anjay_dm_resource_list_ctx_struct anjay_dm_resource_list_ctx_t

Type used to return Resource lists.

anjay_execute_ctx_t

typedef struct anjay_execute_ctx_struct anjay_execute_ctx_t

Type used to retrieve execute command.

anjay_input_ctx_t

typedef struct anjay_input_ctx_struct anjay_input_ctx_t

Type used to retrieve request content.

anjay_output_ctx_t

typedef struct anjay_output_ctx_struct anjay_output_ctx_t

Type used to return some content in response to a request from server.

anjay_ret_bytes_ctx_t

typedef struct anjay_ret_bytes_ctx_struct anjay_ret_bytes_ctx_t

Type used to return a chunked blob of data in response to a request from server. Useful in cases where the application needs to send more data than it can fit in the memory.

Enumeration Type Documentation

anjay_dm_resource_kind_t

enum anjay_dm_resource_kind_t

Kind of a Resource.

Enumerator
ANJAY_DM_RES_R	Read-only Single-Instance Resource. Bootstrap Server might attempt to write to it anyway.
ANJAY_DM_RES_W	Write-only Single-Instance Resource.
ANJAY_DM_RES_RW	Read/Write Single-Instance Resource.
ANJAY_DM_RES_RM	Read-only Multiple Instance Resource. Bootstrap Server might attempt to write to it anyway.
ANJAY_DM_RES_WM	Write-only Multiple Instance Resource.
ANJAY_DM_RES_RWM	Read/Write Multiple Instance Resource.
ANJAY_DM_RES_E	Executable Resource.
ANJAY_DM_RES_BS_RW	Resource that can be read/written only by Bootstrap server.

anjay_dm_resource_presence_t

enum anjay_dm_resource_presence_t

Resource presentness flag.

Enumerator
ANJAY_DM_RES_ABSENT	Resource that is absent (not yet instantiable, but might be instantiated e.g. using a Write operation).
ANJAY_DM_RES_PRESENT	Resource that is present.

Function Documentation

anjay_dm_emit()

void anjay_dm_emit	(	anjay_dm_list_ctx_t *	ctx,
		uint16_t	id
	)

Used to return entries from anjay_dm_list_instances_t or anjay_dm_list_resource_instances_t .

Parameters

ctx	Context passed to the iteration handler.
id	ID of the returned Object Instance or Resource Instance. MUST NOT be ANJAY_ID_INVALID / ANJAY_ID_INVALID (65535).

This function returns no value. Any errors that may occur are handled internally by the library after the calling handler returns.

anjay_dm_emit_res()

void anjay_dm_emit_res	(	anjay_dm_resource_list_ctx_t *	ctx,
		anjay_rid_t	rid,
		anjay_dm_resource_kind_t	kind,
		anjay_dm_resource_presence_t	presence
	)

Used to return Resource entries from anjay_dm_list_resources_t .

Parameters

ctx	Context passed to the iteration handler.
rid	ID of the returned Resource. MUST NOT be ANJAY_ID_INVALID (65535).
kind	Kind of the returned Resource.
presence	Flag that indicates whether the Resource is PRESENT.

This function returns no value. Any errors that may occur are handled internally by the library after the calling handler returns.

anjay_execute_get_arg_value()

int anjay_execute_get_arg_value	(	anjay_execute_ctx_t *	ctx,
		size_t *	out_bytes_read,
		char *	out_buf,
		size_t	buf_size
	)

Attempts to read currently processed argument's value (or part of it). Read data is written as null-terminated string into out_buf.

Returns ANJAY_ERR_BAD_REQUEST to indicate the message is malformed and user should forward this code as the return value of anjay_dm_resource_execute_t .

Function might return 0 when there is nothing more to read or because argument does not have associated value with it, or because the value has already been read / skipped entirely.

When the output buffer is not big enough to contain whole message content + terminating nullbyte, ANJAY_BUFFER_TOO_SHORT is returned, after which further calls can be made, to retrieve more data.

In case of an error following values are returned:

• -1 if buf_size < 2 or out_buf is NULL
• ANJAY_ERR_BAD_REQUEST in case of malformed message

In such cases all data read up to this point should be considered invalid.

Parameters

ctx	Execute context
out_bytes_read	Pointer to a variable that, on successful exit, will be set to the number of bytes read (not counting the terminating null-byte). May be NULL if not needed.
out_buf	Buffer where read bytes will be stored
buf_size	Size of the buffer

Returns

0 on success, a negative value in case of error, ANJAY_BUFFER_TOO_SHORT if the buffer is not big enough to contain whole message content + terminating nullbyte.

anjay_execute_get_next_arg()

int anjay_execute_get_next_arg	(	anjay_execute_ctx_t *	ctx,
		int *	out_arg,
		bool *	out_has_value
	)

Reads next argument from execute request content.

Returns ANJAY_ERR_BAD_REQUEST to indicate the message is malformed and user should forward this code as the return value of anjay_dm_resource_execute_t . Arguments are parsed sequentially so not necessarily the first call of this function will return an error. In case of an error all data read up to the point when an error occurs should be considered invalid.

User not interested in argument value (or interested in ignoring the value after reading some part of it), can safely call this function to skip tail of the value and get next argument or an EOF information.

Parameters

ctx	Execute context
out_arg	Obtained argument id
out_has_value	true if argument has a value, false otherwise

Returns

0 on success, ANJAY_ERR_BAD_REQUEST in case of malformed message, ANJAY_EXECUTE_GET_ARG_END in case of end of message (in which case out_arg is set to -1, and out_has_value to false)

anjay_get_bool()

int anjay_get_bool	(	anjay_input_ctx_t *	ctx,
		bool *	out
	)

Reads a boolean value from the request content.

Parameters

	ctx	Input context to operate on.
[out]	out	Returned value. If the call is not successful, it is guaranteed to be left untouched.

Returns

0 on success, a negative value in case of error.

anjay_get_bytes()

int anjay_get_bytes	(	anjay_input_ctx_t *	ctx,
		size_t *	out_bytes_read,
		bool *	out_message_finished,
		void *	out_buf,
		size_t	buf_size
	)

Reads a chunk of data blob from the request message.

Consecutive calls to this function will return successive chunks of the data blob. Reaching end of the data is signaled by setting the out_message_finished flag.

A call to this function will always attempt to read as much data as possible.

Example: writing a large data blob to file.

FILE *file;
// initialize file
 
bool finished;
size_t bytes_read;
char buf[1024];
 
do {
    if (anjay_get_bytes(ctx, &bytes_read, &finished, buf, sizeof(buf))
            || fwrite(buf, 1, bytes_read, file) < bytes_read) {
        // handle error
    }
} while (!finished);

Parameters

	ctx	Input context to operate on.
[out]	out_bytes_read	Number of bytes read.
[out]	out_message_finished	Set to true if there is no more data to read.
[out]	out_buf	Buffer to read data into.
	buf_size	Number of bytes available in out_buf .

Returns

0 on success, a negative value in case of error.

anjay_get_double()

int anjay_get_double	(	anjay_input_ctx_t *	ctx,
		double *	out
	)

Reads a floating-point value as a double from the request content.

Parameters

	ctx	Input context to operate on.
[out]	out	Returned value. If the call is not successful, it is guaranteed to be left untouched.

Returns

0 on success, a negative value in case of error.

anjay_get_float()

int anjay_get_float	(	anjay_input_ctx_t *	ctx,
		float *	out
	)

Reads a floating-point value as a float from the request content.

Parameters

	ctx	Input context to operate on.
[out]	out	Returned value. If the call is not successful, it is guaranteed to be left untouched.

Returns

0 on success, a negative value in case of error.

anjay_get_i32()

int anjay_get_i32	(	anjay_input_ctx_t *	ctx,
		int32_t *	out
	)

Reads an integer as a 32-bit signed value from the request content.

Parameters

	ctx	Input context to operate on.
[out]	out	Returned value. If the call is not successful, it is guaranteed to be left untouched.

Returns

0 on success, a negative value in case of error.

anjay_get_i64()

int anjay_get_i64	(	anjay_input_ctx_t *	ctx,
		int64_t *	out
	)

Reads an integer as a 64-bit signed value from the request content.

Parameters

	ctx	Input context to operate on.
[out]	out	Returned value. If the call is not successful, it is guaranteed to be left untouched.

Returns

0 on success, a negative value in case of error.

anjay_get_objlnk()

int anjay_get_objlnk	(	anjay_input_ctx_t *	ctx,
		anjay_oid_t *	out_oid,
		anjay_iid_t *	out_iid
	)

Reads an object link (Object ID/Object Instance ID pair) from the request content.

Parameters

	ctx	Input context to operate on.
[out]	out_oid	Object ID part of the returned value.
[out]	out_iid	Object Instance ID part of the returned value.

Returns

0 on success, a negative value in case of error.

In case of error, out_oid and out_iid are guaranteed to be left untouched.

anjay_get_string()

int anjay_get_string	(	anjay_input_ctx_t *	ctx,
		char *	out_buf,
		size_t	buf_size
	)

Reads a null-terminated string from the request content. On success or even when ANJAY_BUFFER_TOO_SHORT is returned, the content inside out_buf is always null-terminated. On failure, the contents of out_buf are undefined.

When the input buffer is not big enough to contain whole message content + terminating nullbyte, ANJAY_BUFFER_TOO_SHORT is returned, after which further calls can be made, to retrieve more data.

Parameters

	ctx	Input context to operate on.
[out]	out_buf	Buffer to read data into.
	buf_size	Number of bytes available in out_buf . Must be at least 1.

Returns

0 on success, a negative value in case of error, ANJAY_BUFFER_TOO_SHORT if the buffer is not big enough to contain whole message content + terminating nullbyte.

anjay_get_u32()

int anjay_get_u32	(	anjay_input_ctx_t *	ctx,
		uint32_t *	out
	)

Reads an unsigned integer as a 32-bit unsigned value from the request content.

Parameters

	ctx	Input context to operate on.
[out]	out	Returned value. If the call is not successful, it is guaranteed to be left untouched.

Returns

0 on success, a negative value in case of error.

anjay_get_u64()

int anjay_get_u64	(	anjay_input_ctx_t *	ctx,
		uint64_t *	out
	)

Reads an unsigned integer as a 64-bit unsigned value from the request content.

Parameters

	ctx	Input context to operate on.
[out]	out	Returned value. If the call is not successful, it is guaranteed to be left untouched.

Returns

0 on success, a negative value in case of error.

anjay_ret_bool()

int anjay_ret_bool	(	anjay_output_ctx_t *	ctx,
		bool	value
	)

Returns a boolean value from the data model handler.

Parameters

ctx	Output context to operate on.
value	The value to return.

Returns

0 on success, a negative value in case of error.

anjay_ret_bytes()

int anjay_ret_bytes	(	anjay_output_ctx_t *	ctx,
		const void *	data,
		size_t	length
	)

Returns a blob of data from the data model handler.

Note: this should be used only for small, self-contained chunks of data. See anjay_ret_bytes_begin documentation for a recommended method of returning large data blobs.

Parameters

ctx	Context to operate on.
data	Data buffer.
length	Number of bytes available in the data buffer.

Returns

0 on success, a negative value in case of error.

anjay_ret_bytes_append()

int anjay_ret_bytes_append	(	anjay_ret_bytes_ctx_t *	ctx,
		const void *	data,
		size_t	length
	)

Appends a chunk of the data blob to the response message.

Note: total number of bytes returned by multiple consecutive successful calls to this function must be equal to the value passed as the length parameter to anjay_ret_bytes_begin that initialized the ctx, otherwise the behavior is undefined.

Parameters

ctx	Context to operate on.
data	Data buffer.
length	Number of bytes available in the data buffer.

Returns

0 on success, a negative value in case of error.

anjay_ret_bytes_begin()

anjay_ret_bytes_ctx_t* anjay_ret_bytes_begin	(	anjay_output_ctx_t *	ctx,
		size_t	length
	)

Marks the beginning of raw data returned from the data model handler. Used in conjunction with anjay_ret_bytes_append to return a large blob of data in multiple chunks.

Example: file content in the response.

FILE *file;
size_t filesize;
// initialize file and filesize
 
anjay_ret_bytes_ctx_t *bytes_ctx = anjay_ret_bytes_begin(ctx, filesize);
if (!bytes_ctx) {
    // handle error
}
 
size_t bytes_read;
char buffer[1024];
while ((bytes_read = fread(buffer, 1, sizeof(buffer), file)) > 0) {
    if (anjay_ret_bytes_append(bytes_ctx, buffer, bytes_read)) {
        // handle error
    }
}

If a zero-length value is to be returned, it is safe both not to call anjay_ret_bytes_append at all, or to call it any number of times with a length argument equal to zero.

Parameters

ctx	Output context to write data into.
length	Size of the data to be written.

Returns

Output context used to return the data or NULL in case of error.

anjay_ret_certificate_chain_info()

int anjay_ret_certificate_chain_info	(	anjay_output_ctx_t *	ctx,
		avs_crypto_certificate_chain_info_t	certificate_chain_info
	)

Returns information about a certificate chain from the data model handler.

NOTE: This function is ONLY intended to be used when handling the "Public Key or Identity" resource in custom implementations of the LwM2M Security object (i.e., when not using anjay_security_object_install). In this context, it may be used to pass client certificate configuration that is not representable through standard LwM2M format. In all other cases, anjay_ret_bytes family of functions SHOULD be used.

Parameters

ctx	Output context to operate on.
certificate_chain_info	Certificate chain information to return. A deep copy will immediately be created, so it is safe to invalidate any referenced buffers just after this call.

Returns

0 on success, a negative value in case of error.

anjay_ret_double()

int anjay_ret_double	(	anjay_output_ctx_t *	ctx,
		double	value
	)

Returns a 64-bit floating-point value from the data model handler.

Note: the value will be sent as a 32-bit floating-point value if it is exactly representable as such.

Parameters

ctx	Output context to operate on.
value	The value to return.

Returns

0 on success, a negative value in case of error.

anjay_ret_float()

static int anjay_ret_float ( anjay_output_ctx_t *  ctx, float  value  )

inlinestatic

Returns a 32-bit floating-point value from the data model handler.

Parameters

ctx	Output context to operate on.
value	The value to return.

Returns

0 on success, a negative value in case of error.

anjay_ret_i32()

static int anjay_ret_i32 ( anjay_output_ctx_t *  ctx, int32_t  value  )

inlinestatic

Returns a 32-bit signed integer from the data model handler.

Note: the only difference between anjay_ret_i32 and anjay_ret_i64 is the size of the value parameter. Actual number of bytes sent on the wire depends on the value.

Parameters

ctx	Output context to operate on.
value	The value to return.

Returns

0 on success, a negative value in case of error.

anjay_ret_i64()

int anjay_ret_i64	(	anjay_output_ctx_t *	ctx,
		int64_t	value
	)

Returns a 64-bit signed integer from the data model handler.

Note: the only difference between anjay_ret_i32 and anjay_ret_i64 is the size of the value parameter. Actual number of bytes sent on the wire depends on the value.

Parameters

ctx	Output context to operate on.
value	The value to return.

Returns

0 on success, a negative value in case of error.

anjay_ret_objlnk()

int anjay_ret_objlnk	(	anjay_output_ctx_t *	ctx,
		anjay_oid_t	oid,
		anjay_iid_t	iid
	)

Returns a object link (Object ID/Instance ID pair) from the data model handler.

Parameters

ctx	Output context to operate on.
oid	Object ID part of the link.
iid	Object Instance ID part of the link.

Returns

0 on success, a negative value in case of error.

anjay_ret_private_key_info()

int anjay_ret_private_key_info	(	anjay_output_ctx_t *	ctx,
		avs_crypto_private_key_info_t	private_key_info
	)

Returns information about a private key from the data model handler.

NOTE: This function is ONLY intended to be used when handling the "Secret Key" resource in custom implementations of the LwM2M Security object (i.e., when not using anjay_security_object_install). In this context, it may be used to pass client certificate configuration that is not representable through standard LwM2M format. In all other cases, anjay_ret_bytes family of functions SHOULD be used.

Parameters

ctx	Output context to operate on.
private_key_info	Private key information to return. A deep copy will immediately be created, so it is safe to invalidate any referenced buffers just after this call.

Returns

0 on success, a negative value in case of error.

anjay_ret_psk_identity_info()

int anjay_ret_psk_identity_info	(	anjay_output_ctx_t *	ctx,
		avs_crypto_psk_identity_info_t	psk_identity_info
	)

Returns information about a PSK identity from the data model handler.

NOTE: This function is ONLY intended to be used when handling the "Public Key Or Identity" or "SMS Binding Key Parameters" resource in custom implementations of the LwM2M Security object (i.e., when not using anjay_security_object_install). In this context, it may be used to pass key configuration that is not representable through standard LwM2M format. In all other cases, anjay_ret_bytes family of functions SHOULD be used.

Parameters

ctx	Output context to operate on.
psk_identity_info	PSK identity information to return. A deep copy will immediately be created, so it is safe to invalidate any referenced buffers just after this call.

Returns

0 on success, a negative value in case of error.

anjay_ret_psk_key_info()

int anjay_ret_psk_key_info	(	anjay_output_ctx_t *	ctx,
		avs_crypto_psk_key_info_t	psk_key_info
	)

Returns information about a PSK key from the data model handler.

NOTE: This function is ONLY intended to be used when handling the "Secret Key" or "SMS Binding Secret Key(s)" resource in custom implementations of the LwM2M Security object (i.e., when not using anjay_security_object_install). In this context, it may be used to pass key configuration that is not representable through standard LwM2M format. In all other cases, anjay_ret_bytes family of functions SHOULD be used.

Parameters

ctx	Output context to operate on.
psk_key_info	PSK key information to return. A deep copy will immediately be created, so it is safe to invalidate any referenced buffers just after this call.

Returns

0 on success, a negative value in case of error.

anjay_ret_string()

int anjay_ret_string	(	anjay_output_ctx_t *	ctx,
		const char *	value
	)

Returns a null-terminated string from the data model handler.

Parameters

ctx	Output context to operate on.
value	Null-terminated string to return.

Returns

0 on success, a negative value in case of error.

anjay_ret_u32()

static int anjay_ret_u32 ( anjay_output_ctx_t *  ctx, uint32_t  value  )

inlinestatic

Returns a 32-bit unsigned integer from the data model handler.

Note: the only difference between anjay_ret_u32 and anjay_ret_u64 is the size of the value parameter. Actual number of bytes sent on the wire depends on the value.

Parameters

ctx	Output context to operate on.
value	The value to return.

Returns

0 on success, a negative value in case of error.

anjay_ret_u64()

int anjay_ret_u64	(	anjay_output_ctx_t *	ctx,
		uint64_t	value
	)

Returns a 64-bit unsigned integer from the data model handler.

Note: the only difference between anjay_ret_u32 and anjay_ret_u64 is the size of the value parameter. Actual number of bytes sent on the wire depends on the value.

Parameters

ctx	Output context to operate on.
value	The value to return.

Returns

0 on success, a negative value in case of error.