5.4. Custom LwM2M objects

Note

This section describes in details the implementation of custom Objects in Anjay, either defined in OMA LwM2M Object and Resource Registry or designed by user.

Although most of the Object’s code can be generated using Anjay Object stub generator if you have Object’s definition in XML, it is recommended to read this section to have a clear understanding on what various parts of the LwM2M Object code are for.

LwM2M Objects are described using the anjay_dm_object_def_t struct, which holds:

Object ID,
a list of Resource IDs that the Object might contain,
a set of handlers used by the library to access and possibly modify the Object.

/** A struct containing pointers to Object handlers. */
typedef struct {
    /**
     * Get default Object attributes, @ref anjay_dm_object_read_default_attrs_t
     *
     * Required for handling *LwM2M Discover* and *LwM2M Observe* operations.
     *
     * Can be NULL if the *Attribute Storage* feature is enabled. Non-NULL
     * handler overrides *Attribute Storage* logic.
     */
    anjay_dm_object_read_default_attrs_t *object_read_default_attrs;

    /**
     * Set default Object attributes,
     * @ref anjay_dm_object_write_default_attrs_t
     *
     * Required for handling *LwM2M Write-Attributes* operation.
     *
     * Can be NULL when *Attribute Storage* feature is enabled. Non-NULL handler
     * overrides *Attribute Storage* logic.
     */
    anjay_dm_object_write_default_attrs_t *object_write_default_attrs;

    /**
     * Enumerate available Object Instances, @ref anjay_dm_list_instances_t
     *
     * Required for every LwM2M operation.
     *
     * **Must not be NULL.** @ref anjay_dm_list_instances_SINGLE can be used
     * here.
     */
    anjay_dm_list_instances_t *list_instances;

    /**
     * Resets an Object Instance, @ref anjay_dm_instance_reset_t
     *
     * Required for handling *LwM2M Write* operation in *replace mode*.
     *
     * Can be NULL if the object does not contain writable resources.
     */
    anjay_dm_instance_reset_t *instance_reset;

    /**
     * Create an Object Instance, @ref anjay_dm_instance_create_t
     *
     * Required for handling *LwM2M Create* operation.
     *
     * Can be NULL for single instance objects.
     */
    anjay_dm_instance_create_t *instance_create;

    /**
     * Delete an Object Instance, @ref anjay_dm_instance_remove_t
     *
     * Required for handling *LwM2M Delete* operation performed on Object
     * Instances.
     *
     * Can be NULL for single instance objects.
     */
    anjay_dm_instance_remove_t *instance_remove;

    /**
     * Get default Object Instance attributes,
     * @ref anjay_dm_instance_read_default_attrs_t
     *
     * Required for handling *LwM2M Discover* and *LwM2M Observe* operations.
     *
     * Can be NULL when *Attribute Storage* feature is enabled. Non-NULL handler
     * overrides *Attribute Storage* logic.
     */
    anjay_dm_instance_read_default_attrs_t *instance_read_default_attrs;

    /**
     * Set default Object Instance attributes,
     * @ref anjay_dm_instance_write_default_attrs_t
     *
     * Required for handling *LwM2M Write-Attributes* operation.
     *
     * Can be NULL when *Attribute Storage* feature is enabled. Non-NULL handler
     * overrides *Attribute Storage* logic.
     */
    anjay_dm_instance_write_default_attrs_t *instance_write_default_attrs;

    /**
     * Enumerate PRESENT Resources in a given Object Instance,
     * @ref anjay_dm_list_resources_t
     *
     * Required for every LwM2M operation.
     *
     * **Must not be NULL.**
     */
    anjay_dm_list_resources_t *list_resources;

    /**
     * Get Resource value, @ref anjay_dm_resource_read_t
     *
     * Required for *LwM2M Read* operation.
     *
     * Can be NULL if the object does not contain readable resources.
     */
    anjay_dm_resource_read_t *resource_read;

    /**
     * Set Resource value, @ref anjay_dm_resource_write_t
     *
     * Required for *LwM2M Write* operation.
     *
     * Can be NULL if the object does not contain writable resources.
     */
    anjay_dm_resource_write_t *resource_write;

    /**
     * Perform Execute action on a Resource, @ref anjay_dm_resource_execute_t
     *
     * Required for *LwM2M Execute* operation.
     *
     * Can be NULL if the object does not contain executable resources.
     */
    anjay_dm_resource_execute_t *resource_execute;

    /**
     * Remove all Resource Instances from a Multiple Resource,
     * @ref anjay_dm_resource_reset_t
     *
     * Required for *LwM2M Write* operation performed on multiple-instance
     * resources.
     *
     * Can be NULL if the object does not contain multiple writable resources.
     */
    anjay_dm_resource_reset_t *resource_reset;

    /**
     * Enumerate available Resource Instances,
     * @ref anjay_dm_list_resource_instances_t
     *
     * Required for *LwM2M Read*, *LwM2M Write* and *LwM2M Discover* operations
     * performed on multiple-instance resources..
     *
     * Can be NULL if the object does not contain multiple resources.
     */
    anjay_dm_list_resource_instances_t *list_resource_instances;

    /**
     * Get Resource attributes, @ref anjay_dm_resource_read_attrs_t
     *
     * Required for handling *LwM2M Discover* and *LwM2M Observe* operations.
     *
     * Can be NULL when *Attribute Storage* feature is enabled. Non-NULL handler
     * overrides *Attribute Storage* logic.
     */
    anjay_dm_resource_read_attrs_t *resource_read_attrs;

    /**
     * Set Resource attributes, @ref anjay_dm_resource_write_attrs_t
     *
     * Required for handling *LwM2M Write-Attributes* operation.
     *
     * Can be NULL when *Attribute Storage* feature is enabled. Non-NULL handler
     * overrides *Attribute Storage* logic.
     */
    anjay_dm_resource_write_attrs_t *resource_write_attrs;

    /**
     * Begin a transaction on this Object, @ref anjay_dm_transaction_begin_t
     *
     * Required for handling modifying operation: *LwM2M Write*, *LwM2M Create*
     * or *LwM2M Delete*.
     *
     * Can be NULL for read-only objects. @ref anjay_dm_transaction_NOOP can be
     * used here.
     */
    anjay_dm_transaction_begin_t *transaction_begin;

    /**
     * Validate whether a transaction on this Object can be cleanly committed.
     * See @ref anjay_dm_transaction_validate_t
     *
     * Required for handling modifying operation: *LwM2M Write*, *LwM2M Create*
     * or *LwM2M Delete*.
     *
     * Can be NULL for read-only objects. @ref anjay_dm_transaction_NOOP can be
     * used here.
     */
    anjay_dm_transaction_validate_t *transaction_validate;

    /**
     * Commit changes made in a transaction, @ref anjay_dm_transaction_commit_t
     *
     * Required for handling modifying operation: *LwM2M Write*, *LwM2M Create*
     * or *LwM2M Delete*.
     *
     * Can be NULL for read-only objects. @ref anjay_dm_transaction_NOOP can be
     * used here.
     */
    anjay_dm_transaction_commit_t *transaction_commit;

    /**
     * Rollback changes made in a transaction,
     * @ref anjay_dm_transaction_rollback_t
     *
     * Required for handling modifying operation: *LwM2M Write*, *LwM2M Create*
     * or *LwM2M Delete*.
     *
     * Can be NULL for read-only objects. @ref anjay_dm_transaction_NOOP can be
     * used here.
     */
    anjay_dm_transaction_rollback_t *transaction_rollback;

    /**
     * Get Resource Instance attributes, @ref
     * anjay_dm_resource_instance_read_attrs_t
     *
     * Required for handling *LwM2M Discover* and *LwM2M Observe* operations.
     *
     * Can be NULL if the object does not contain multiple resources, when
     * *Attribute Storage* feature is enabled, or when the application only
     * targets compliance with LwM2M TS 1.0. Non-NULL handler overrides
     * *Attribute Storage* logic.
     */
    anjay_dm_resource_instance_read_attrs_t *resource_instance_read_attrs;

    /**
     * Set Resource Instance attributes, @ref
     * anjay_dm_resource_instance_write_attrs_t
     *
     * Required for handling *LwM2M Write-Attributes* operation.
     *
     * Can be NULL if the object does not contain multiple resources, when
     * *Attribute Storage* feature is enabled, or when the application only
     * targets compliance with LwM2M TS 1.0. Non-NULL handler overrides
     * *Attribute Storage* logic.
     */
    anjay_dm_resource_instance_write_attrs_t *resource_instance_write_attrs;
} anjay_dm_handlers_t;

/** A struct defining a LwM2M Object. */
struct anjay_dm_object_def_struct {
    /** Object ID; MUST not be <c>ANJAY_ID_INVALID</c> (65535) */
    anjay_oid_t oid;

    /**
     * Object version: a string with static lifetime, containing two digits
     * separated by a dot (for example: "1.1").
     * If left NULL, client will not include the "ver=" attribute in Register
     * and Discover messages. This implies:
     * 1. Version 1.0 for Non-Core Objects.
     * 2. The version corresponding to the version in the LwM2M Enabler for Core
     * Objects.
     */
    const char *version;

    /** Handler callbacks for this object. */
    anjay_dm_handlers_t handlers;
};

See API docs for detailed information about each of those fields.

These structures themselves may seem intimidating at the first glance. In reality, most use cases will not require setting up all possible handlers - this tutorial will show multiple possible implementations, from the simplest cases to the most complex ones.