/* resource.h -- generic resource handling
 *
 * Copyright (C) 2010,2011,2014 Olaf Bergmann <bergmann@tzi.org>
 *
 * This file is part of the CoAP library libcoap. Please see
 * README for terms of use.
 */

/**
 * @file resource.h
 * @brief generic resource handling
 */

#ifndef _COAP_RESOURCE_H_
#define _COAP_RESOURCE_H_

#include "coap_config.h"
#include "t_list.h"

# include <assert.h>

#ifndef COAP_RESOURCE_CHECK_TIME
/** The interval in seconds to check if resources have changed. */
#define COAP_RESOURCE_CHECK_TIME 2
#endif /* COAP_RESOURCE_CHECK_TIME */

#  ifdef COAP_RESOURCES_NOHASH
#    include "utlist.h"
#  else
#    include "uthash.h"
#  endif
#include "hashkey.h"
#include "async.h"
#include "str.h"
#include "pdu.h"
#include "coap_net.h"
#include "subscribe.h"

/** Definition of message handler function (@sa coap_resource_t). */
typedef void (*coap_method_handler_t)
(coap_context_t *, struct coap_resource_t *, coap_address_t *, coap_pdu_t *,
 str * /* token */, coap_pdu_t * /* response */);

#define COAP_ATTR_FLAGS_RELEASE_NAME  0x1
#define COAP_ATTR_FLAGS_RELEASE_VALUE 0x2

typedef struct coap_attr_t {
    struct coap_attr_t *next;
    str name;
    str value;
    int flags;
} coap_attr_t;

#define COAP_RESOURCE_FLAGS_RELEASE_URI 0x1

typedef struct coap_resource_t {
    unsigned int dirty: 1;	     /**< set to 1 if resource has changed */
    unsigned int partiallydirty: 1; /**< set to 1 if some subscribers have not yet been notified of the last change */
    unsigned int observable: 1; /**< can be observed */
    unsigned int cacheable: 1;  /**< can be cached */

    /**
     * Used to store handlers for the four coap methods @c GET, @c POST,
     * @c PUT, and @c DELETE. coap_dispatch() will pass incoming
     * requests to the handler that corresponds to its request method or
     * generate a 4.05 response if no handler is available.
     */
    coap_method_handler_t handler[4];

    coap_key_t key;	/**< the actual key bytes for this resource */

#ifdef COAP_RESOURCES_NOHASH
    struct coap_resource_t *next;
#else
    UT_hash_handle hh;
#endif

    coap_attr_t *link_attr; /**< attributes to be included with the link format */
    LIST_STRUCT(subscribers); /**< list of observers for this resource */


    /**
     * Request URI for this resource. This field will point into the
     * static memory. */
    str uri;
    int flags;
    int err_no;
    void *notify_priv;
    void *register_priv;
} coap_resource_t;

/**
 * Creates a new resource object and initializes the link field to the
 * string of length @p len.  This function returns the
 * new coap_resource_t object.
 *
 * @param uri    The URI path of the new resource.
 * @param len    The length of @p uri.
 * @param flags  Flags for memory management (in particular release of memory)
 *
 * @return A pointer to the new object or @c NULL on error.
 */
coap_resource_t *coap_resource_init(const unsigned char *uri, size_t len, int flags);

/**
 * Registers the given @p resource for @p context. The resource must
 * have been created by coap_resource_init(), the storage allocated
 * for the resource will be released by coap_delete_resource().
 *
 * @param context  The context to use.
 * @param resource The resource to store.
 */
void coap_add_resource(coap_context_t *context, coap_resource_t *resource);

/**
 * Deletes a resource identified by @p key. The storage allocated for
 * that resource is freed.
 *
 * @param context  The context where the resources are stored.
 * @param key      The unique key for the resource to delete.
 *
 * @return @c 1 if the resource was found (and destroyed), @c 0 otherwise.
 */
int coap_delete_resource(coap_context_t *context, coap_key_t key);

/**
 * Registers a new attribute with the given @p resource. As the
 * attributes str fields will point to @p name and @p val the
 * caller must ensure that these pointers are valid during the
 * attribute's lifetime.
 *
 * @param resource  The resource to register the attribute with.
 * @param name      The attribute's name.
 * @param nlen      Length of @p name.
 * @param val       The attribute's value or @c NULL if none.
 * @param vlen      Length of @p val if specified.
 * @param flags     Flags for memory management (in particular release of memory)
 *
 * @return A pointer to the new attribute or @c NULL on error.
 */
coap_attr_t *coap_add_attr(coap_resource_t *resource,
                           const unsigned char *name, size_t nlen,
                           const unsigned char *val, size_t vlen,
                           int flags);

/**
 * Returns @p resource's coap_attr_t object with given @p name if
 * found, @c NULL otherwise.
 *
 * @param resource  The resource to search for attribute @p name.
 * @param name      Name of the requested attribute.
 * @param nlen      Actual length of @p name.
 * @return The first attribute with specified @p name or @c NULL if
 *         none was found.
 */
coap_attr_t *coap_find_attr(coap_resource_t *resource,
                            const unsigned char *name, size_t nlen);

/**
 * Deletes an attribute
 *
 * @param attr  Pointer to a previously created attribute
 *
 */
void coap_delete_attr(coap_attr_t *attr);

/**
 * Status word to encode the result of conditional print or copy
 * operations such as coap_print_link(). The lower 28 bits of
 * coap_print_status_t are used to encode the number of characters
 * that has actually been printed, bits 28 to 31 encode the status.
 * When COAP_PRINT_STATUS_ERROR is set, an error occurred during
 * output. In this case, the other bits are undefined.
 * COAP_PRINT_STATUS_TRUNC indicates that the output is truncated,
 * i.e. the printing would have exceeded the current buffer.
 */
typedef unsigned int coap_print_status_t;

#define COAP_PRINT_STATUS_MASK  0xF0000000u
#define COAP_PRINT_OUTPUT_LENGTH(v) ((v) & ~COAP_PRINT_STATUS_MASK)
#define COAP_PRINT_STATUS_ERROR 0x80000000u
#define COAP_PRINT_STATUS_TRUNC 0x40000000u

/**
 * Writes a description of this resource in link-format to given text
 * buffer. @p len must be initialized to the maximum length of @p buf
 * and will be set to the number of characters actually written if
 * successful.  This function returns @c 1 on success or @c 0 on
 * error.
 *
 * @param resource The resource to describe.
 * @param buf      The output buffer to write the description to.
 * @param len      Must be initialized to the length of @p buf and
 *                 will be set to the length of the printed link description.
 * @param offset   The offset within the resource description where to
 *                 start writing into @p buf. This is useful for dealing
 *                 with the Block2 option. @p offset is updated during
 *                 output as it is consumed.
 *
 * @return If COAP_PRINT_STATUS_ERROR is set, an error occured. Otherwise,
 *         the lower 28 bits will indicate the number of characters that
 *         have actually been output into @p buffer. The flag
 *         COAP_PRINT_STATUS_TRUNC indicates that the output has been
 *         truncated.
 */
coap_print_status_t coap_print_link(const coap_resource_t *resource,
                                    unsigned char *buf, size_t *len, size_t *offset);

/**
 * Registers the specified @p handler as message handler for the request type
 * @p method
 *
 * @param resource The resource for which the handler shall be registered.
 * @param method   The CoAP request method to handle.
 * @param handler  The handler to register with @p resource.
 */
static inline void
coap_register_handler(coap_resource_t *resource,
                      unsigned char method, coap_method_handler_t handler)
{
    assert(resource);
    assert(method > 0 && (size_t)(method - 1) < sizeof(resource->handler) / sizeof(coap_method_handler_t));
    resource->handler[method - 1] = handler;
}

/**
 * Returns the resource identified by the unique string @p key. If no
 * resource was found, this function returns @c NULL.
 *
 * @param context  The context to look for this resource.
 * @param key      The unique key of the resource.
 *
 * @return A pointer to the resource or @c NULL if not found.
 */
coap_resource_t *coap_get_resource_from_key(coap_context_t *context,
        coap_key_t key);
coap_resource_t *coap_get_resource_from_uri(coap_context_t *context,
        char *uri);
/**
 * Calculates the hash key for the resource requested by the
 * Uri-Options of @p request.  This function calls coap_hash() for
 * every path segment.
 *
 * @param request The requesting pdu.
 * @param key     The resulting hash is stored in @p key
 */
void coap_hash_request_uri(const coap_pdu_t *request, coap_key_t key);

/**
 * @addtogroup observe
 */

/**
 * Adds the specified peer as observer for @p resource. The
 * subscription is identified by the given @p token. This function
 * returns the registered subscription information if the @p observer
 * has been added, or @c NULL on error.
 *
 * @param resource The observed resource.
 * @param observer The remote peer that wants to received status updates.
 * @param token The token that identifies this subscription.
 * @param token_length The actual length of @p token. Must be @c 0 when
 *        @p token is @c NULL.
 * @return A pointer to the added/updated subscription information or
 *        @c NULL on error.
 */
coap_subscription_t *coap_add_observer(coap_resource_t *resource,
                                       const coap_address_t *observer,
                                       const str *token);

/**
 * Returns a subscription object for given @p peer.
 *
 * @param resource The observed resource.
 * @param peer The address to search for.
 * @param token The token that identifies this subscription or @c NULL for any
 *              token.
 * @return A valid subscription if exists or @c NULL otherwise.
 */
coap_subscription_t *coap_find_observer(coap_resource_t *resource,
                                        const coap_address_t *peer,
                                        const str *token);

/**
 * Marks an observer as alive.
 *
 * @param context  The CoAP context to use
 * @param observer The transport address of the observer
 * @param token    The corresponding token that has been used for
 *   the subscription
 */
void coap_touch_observer(coap_context_t *context,
                         const coap_address_t *observer,
                         const str *token);

/**
 * Removes any subscription for @p observer from @p resource and releases
 * the allocated storage. The result is @c 1 if an observation relationship
 * with @p observer and @p token existed, @c 0 otherwise.
 *
 * @param resource The observed resource.
 * @param observer The observer's address.
 * @param token    The token that identifies this subscription or @c NULL for any
 *                 token.
 * @return @c 1 if the observer has been deleted, @c 0 otherwise.
 */
int coap_delete_observer(coap_resource_t *resource,
                         const coap_address_t *observer,
                         const str *token);

/**
 * Checks for all known resources, if they are dirty and notifies
 * subscribed observers.
 */
void coap_check_notify(coap_context_t *context);


void coap_add_option_observer(coap_context_t  *ctx, struct coap_resource_t *resource,
                              coap_address_t *peer, coap_pdu_t *request, str *token, coap_pdu_t *response);


/** @} */

#endif /* _COAP_RESOURCE_H_ */