domo-iot/lib/include/restd_server.h

/*!
 * restd_server.h
 *
 * Copyright (c) 2015-2019, NADAL Jean-Baptiste. All rights reserved.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 * MA 02110-1301 USA
 * 
 * @Author:  NADAL Jean-Baptiste
 * @Date: 23/12/2019
 *
 */

#ifndef _RESTD_SERVER_H
#define _RESTD_SERVER_H

/*------------------------------- INCLUDES ----------------------------------*/

#include <pthread.h>

#include <qlibc/qlibc.h>

/*------------------------------- TYPEDEFS ----------------------------------*/

typedef struct restd_server_s restd_server_t;
typedef struct restd_conn_s restd_conn_t;

/*------------------------------- DEFINE ----------------------------------*/

/*
 * Return values of user callback.
 */
#define RESTD_OK (0)       /*!< I'm done with this request. Escalate to other hooks. */
#define RESTD_TAKEOVER (1) /*!< I'll handle the buffer directly this time, skip next hook */
#define RESTD_DONE (2)     /*!< We're done with this request but keep the connection open. */
#define RESTD_CLOSE (3)    /*!< We're done with this request. Close as soon as we sent all data out. */

#define RESTD_ERROR_METHOD_NOT_ALLOWED (1)
#define RESTD_ERROR_PATH_NOT_FOUND (2)

/*
 * These flags are used for ad_log_level();
 */
enum restd_log_e
{
    RESTD_LOG_DISABLE = 0,
    RESTD_LOG_ERROR,
    RESTD_LOG_WARN,
    RESTD_LOG_INFO,
    RESTD_LOG_DEBUG,
    RESTD_LOG_DEBUG2,
};

/*---------------------------------------------------------------------------*\
|                               USER-CALLBACK                                 |
\*---------------------------------------------------------------------------*/

/**
 * User callback(hook) prototype.
 */
typedef int (*restd_call_hook_cb)(short event, restd_conn_t *conn);
typedef int (*restd_callback)(short event, restd_conn_t *conn, void *userdata);
typedef void (*restd_userdata_free_cb)(restd_conn_t *conn, void *userdata);

/**
 * Event types
 */
#define RESTD_EVENT_INIT (1)          /*!< Call once upon new connection. */
#define RESTD_EVENT_READ (1 << 1)     /*!< Call on read */
#define RESTD_EVENT_WRITE (1 << 2)    /*!< Call on write. */
#define RESTD_EVENT_CLOSE (1 << 3)    /*!< Call before closing. */
#define RESTD_EVENT_TIMEOUT (1 << 4)  /*!< Timeout indicator, this flag will be set with AD_EVENT_CLOSE. */
#define RESTD_EVENT_SHUTDOWN (1 << 5) /*!< Shutdown indicator, this flag will be set with AD_EVENT_CLOSE. */

/**
 * Defaults
 */
#define RESTD_NUM_USERDATA (2) /*!< Number of userdata. Currently 0 is for userdata, 1 is for extra. */

/*---------------------------------------------------------------------------*\
|                            DATA STRUCTURES                                  |
\*---------------------------------------------------------------------------*/

/**
 * Server info container.
 */
struct restd_server_s
{
    int errcode;       /*!< exit status. 0 for normal exit, non zero for error. */
    pthread_t *thread; /*!< thread object. not null if server runs as a thread */

    qhashtbl_t *options;             /*!< server options */
    qhashtbl_t *stats;               /*!< internal statistics */
    qlist_t *hooks;                  /*!< list of registered hooks */
    struct evconnlistener *listener; /*!< listener */
    struct event_base *evbase;       /*!< event base */

    struct bufferevent *notify_buffer; /*!< internal notification channel */

    restd_call_hook_cb call_hooks;
    restd_callback request_handler;
    restd_callback error_handler;
};

/**
 * Connection structure.
 */
struct restd_conn_s
{
    restd_server_t *server;     /*!< reference pointer to server */
    struct bufferevent *buffer; /*!< reference pointer to buffer */
    struct evbuffer *in;        /*!< in buffer */
    struct evbuffer *out;       /*!< out buffer */
    int status;                 /*!< hook status such as AD_OK */

    void *userdata[2];                          /*!< userdata[0] for end user, userdata[1] for extra */
    restd_userdata_free_cb userdata_free_cb[2]; /*!< callback to release user data */
    char *method;                               /*!< request method. set by protocol handler */
    int id;
};

/*
 * User callback hook container.
 */
typedef struct restd_hook_s restd_hook_t;
struct restd_hook_s
{
    char *method;
    char *path;
    restd_callback cb;
    void *userdata;
};

/*----------------------------------------------------------------------------*\
|                             PUBLIC FUNCTIONS                                 |
\*----------------------------------------------------------------------------*/
enum restd_log_e restd_log_level(enum restd_log_e log_level);

extern restd_server_t *restd_server_new(void);
extern void restd_server_free(restd_server_t *server);
extern int restd_server_start(restd_server_t *server);
extern int restd_server_attach_event_loop(restd_server_t *server, struct event_base *ev_base);


extern void restd_server_set_option(restd_server_t *server, const char *key, const char *value);
extern char *restd_server_get_option(restd_server_t *server, const char *key);
extern int restd_server_get_option_int(restd_server_t *server, const char *key);

extern void restd_server_register_request_handler(restd_server_t *server, restd_callback cb);
extern void restd_server_register_error_handler(restd_server_t *server, restd_callback cb);
extern void restd_server_register_call_hooks_handler(restd_server_t *server, restd_call_hook_cb cb);

extern void restd_server_register_hook(restd_server_t *server, restd_callback cb, void *userdata);
extern void restd_server_register_hook_on_method(restd_server_t *server, const char *method,
                                                 restd_callback cb, void *userdata);

extern void restd_server_register_hook_on_path(restd_server_t *server, const char *method, const char *path,
                                               restd_callback cb, void *userdata);

extern void *restd_conn_set_extra(restd_conn_t *conn, const void *extra, restd_userdata_free_cb free_cb);
extern void *restd_conn_get_extra(restd_conn_t *conn);
extern void restd_conn_set_method(restd_conn_t *conn, char *method);

#endif /* _RESTD_SERVER_H */