/*

 * object_monitor.c

 *

 * $Id$

 *

 * functions and data structures for cooperating code to monitor objects.

 *

 * WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!

 * WARNING!                                                       WARNING!

 * WARNING!                                                       WARNING!

 * WARNING!         This code is under active development         WARNING!

 * WARNING!         and is subject to change at any time.         WARNING!

 * WARNING!                                                       WARNING!

 * WARNING!                                                       WARNING!

 * WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!

 */

#include <net-snmp/net-snmp-config.h>

#include <net-snmp/net-snmp-includes.h>

#include <net-snmp/agent/net-snmp-agent-includes.h>

#include <net-snmp/library/container.h>

#include <net-snmp/library/snmp_assert.h>

#include "net-snmp/agent/object_monitor.h"

#if ! defined TRUE

#  define TRUE 1

#elsif TRUE != 1

error "TRUE != 1"

#endif

/**************************************************************************

 *

 * Private data structures

 *

 **************************************************************************/

    /*

     * individual callback info for an object

     */

    typedef struct monitor_info_s {

   /** priority for this callback */

    int             priority;

   /** handler that registred to watch this object */

    netsnmp_mib_handler *watcher;

   /** events that the watcher cares about */

    unsigned int    events;

   /** callback function */

    netsnmp_object_monitor_callback *cb;

   /** pointer to data from the watcher */

    void           *watcher_data;

    struct monitor_info_s *next;

} monitor_info;

/*

 * list of watchers for a given object

 */

typedef struct watcher_list_s {

   /** netsnmp_index must be first! */

    netsnmp_index  monitored_object;

    monitor_info   *head;

} watcher_list;

/*

 * temp holder for ordered list of callbacks

 */

typedef struct callback_placeholder_s {

    monitor_info   *mi;

    netsnmp_monitor_callback_header *cbh;

    struct callback_placeholder_s *next;

} callback_placeholder;

/**************************************************************************

 *

 * 

 *

 **************************************************************************/

/*

 * local statics

 */

static char     need_init = 1;

static netsnmp_container *monitored_objects = NULL;

static netsnmp_monitor_callback_header *callback_pending_list;

static callback_placeholder *callback_ready_list;

/*

 * local prototypes

 */

static watcher_list *find_watchers(oid * object, size_t oid_len);

static int      insert_watcher(oid *, size_t, monitor_info *);

static int      check_registered(unsigned int event, oid * o, int o_l,

                                 watcher_list ** pWl, monitor_info ** pMi);

static void     move_pending_to_ready(void);

/**************************************************************************

 *

 * Public functions

 *

 **************************************************************************/

/*

 * 

 */

void

netsnmp_monitor_init(void)

{

    if (!need_init)

        return;

    callback_pending_list = NULL;

    callback_ready_list = NULL;

    monitored_objects = netsnmp_container_get("object_monitor:binary_array");

    if (NULL != monitored_objects)

        need_init = 0;

    monitored_objects->compare = netsnmp_compare_netsnmp_index;

    monitored_objects->ncompare = netsnmp_ncompare_netsnmp_index;

    return;

}

/**************************************************************************

 *

 * Registration functions

 *

 **************************************************************************/

/**

 * Register a callback for the specified object.

 *

 * @param object  pointer to the OID of the object to monitor.

 * @param oid_len length of the OID pointed to by object.

 * @param priority the priority to associate with this callback. A

 *                 higher number indicates higher priority. This

 *                 allows multiple callbacks for the same object to

 *                 coordinate the order in which they are called. If

 *                 two callbacks register with the same priority, the

 *                 order is undefined.

 * @param events  the events which the callback is interested in.

 * @param watcher_data pointer to data that will be supplied to the

 *                     callback method when an event occurs.

 * @param cb pointer to the function to be called when an event occurs.

 *

 * NOTE: the combination of the object, priority and watcher_data must

 *       be unique, as they are the parameters for unregistering a

 *       callback.

 *

 * @return SNMPERR_NOERR registration was successful

 * @return SNMPERR_MALLOC memory allocation failed

 * @return SNMPERR_VALUE the combination of the object, priority and

 *                        watcher_data is not unique.

 */

int

netsnmp_monitor_register(oid * object, size_t oid_len, int priority,

                         unsigned int events, void *watcher_data,

                         netsnmp_object_monitor_callback * cb)

{

    monitor_info   *mi;

    int             rc;

    netsnmp_assert(need_init == 0);

    mi = calloc(1, sizeof(monitor_info));

    if (NULL == mi)

        return SNMPERR_MALLOC;

    mi->priority = priority;

    mi->events = events;

    mi->watcher_data = watcher_data;

    mi->cb = cb;

    rc = insert_watcher(object, oid_len, mi);

    if (rc != SNMPERR_SUCCESS)

        free(mi);

    return rc;

}

/**

 * Unregister a callback for the specified object.

 *

 * @param object  pointer to the OID of the object to monitor.

 * @param oid_len length of the OID pointed to by object.

 * @param priority the priority to associate with this callback.

 * @param wd pointer to data that was supplied when the

 *                     callback was registered.

 * @param cb pointer to the function to be called when an event occurs.

 */

int

netsnmp_monitor_unregister(oid * object, size_t oid_len, int priority,

                           void *wd, netsnmp_object_monitor_callback * cb)

{

    monitor_info   *mi, *last;

    watcher_list   *wl = find_watchers(object, oid_len);

    if (NULL == wl)

        return SNMPERR_GENERR;

    last = NULL;

    mi = wl->head;

    while (mi) {

        if ((mi->cb == cb) && (mi->priority == priority) &&

            (mi->watcher_data == wd))

            break;

        last = mi;

        mi = mi->next;

    }

    if (NULL == mi)

        return SNMPERR_GENERR;

    if (NULL == last)

        wl->head = mi->next;

    else

        last->next = mi->next;

    if (NULL == wl->head) {

        CONTAINER_REMOVE(monitored_objects, wl);

        free(wl->monitored_object.oids);

        free(wl);

    }

    free(mi);

    return SNMPERR_SUCCESS;

}

/**************************************************************************

 *

 * object monitor functions

 *

 **************************************************************************/

/**

 * Notifies the object monitor of an event.

 *

 * The object monitor funtions will save the callback information

 * until all varbinds in the current PDU have been processed and

 * a response has been sent. At that time, the object monitor will

 * determine if there are any watchers monitoring for the event.

 *

 * NOTE: the actual type of the callback structure may vary. The

 *       object monitor functions require only that the start of

 *       the structure match the netsnmp_monitor_callback_header

 *       structure. It is up to the watcher and monitored objects

 *       to agree on the format of other data.

 *

 * @param cbh pointer to a callback header.

 */

void

netsnmp_notify_monitor(netsnmp_monitor_callback_header * cbh)

{

    netsnmp_assert(need_init == 0);

    /*

     * put processing of until response has been sent

     */

    cbh->private = callback_pending_list;

    callback_pending_list = cbh;

    return;

}

/**

 * check to see if a registration exists for an object/event combination

 *

 * @param event the event type to check for

 * @param o     the oid to check for

 * @param o_l   the length of the oid

 *

 * @returns TRUE(1) if a callback is registerd

 * @returns FALSE(0) if no callback is registered

 */

int

netsnmp_monitor_check_registered(int event, oid * o, int o_l)

{

    return check_registered(event, o, o_l, NULL, NULL);

}

/**

 * Process all pending callbacks

 *

 * NOTE: this method is not in the public header, as it should only be

 *       called in one place, in the agent.

 */

void

netsnmp_monitor_process_callbacks(void)

{

    netsnmp_assert(need_init == 0);

    netsnmp_assert(NULL == callback_ready_list);

    if (NULL == callback_pending_list) {

        DEBUGMSGT(("object_monitor", "No callbacks to process"));

        return;

    }

    DEBUGMSG(("object_monitor", "Checking for registered " "callbacks."));

    /*

     * move an pending notification which has a registered watcher to the

     * ready list. Free any other notifications.

     */

    move_pending_to_ready();

    /*

     * call callbacks

     */

    while (callback_ready_list) {

        /*

         * pop off the first item

         */

        callback_placeholder *current_cbr;

        current_cbr = callback_ready_list;

        callback_ready_list = current_cbr->next;

        /*

         * setup, then call callback

         */

        current_cbr->cbh->watcher_data = current_cbr->mi->watcher_data;

        current_cbr->cbh->priority = current_cbr->mi->priority;

        (*current_cbr->mi->cb) (current_cbr->cbh);

        /*

         * release memory (don't free current_cbr->mi)

         */

        if (--(current_cbr->cbh->refs) == 0) {

            free(current_cbr->cbh->monitored_object.oids);

            free(current_cbr->cbh);

        }

        free(current_cbr);

        /*

         * check for any new pending notifications

         */

        move_pending_to_ready();

    }

    netsnmp_assert(callback_ready_list == NULL);

    netsnmp_assert(callback_pending_list = NULL);

    return;

}

/**************************************************************************

 *

 * COOPERATIVE helpers

 *

 **************************************************************************/

/**

 * Notifies the object monitor of a cooperative event.

 *

 * This convenience function will build a

 * ::netsnmp_monitor_callback_header and call

 * netsnmp_notify_monitor().

 *

 * @param event the event type

 * @param  o pointer to the oid of the object sending the event

 * @param o_len    the lenght of the oid

 * @param o_steal set to true if the function may keep the pointer

 *                  to the memory (and free it later). set to false

 *                  to make the function allocate and copy the oid.

 * @param object_info pointer to data supplied by the object for

 *                    the callback. This pointer must remain valid,

 *                    will be provided to each callback registered

 *                    for the object (i.e. it will not be copied or

 *                    freed).

 */

void

netsnmp_notify_cooperative(int event, oid * o, size_t o_len, char o_steal,

                           void *object_info)

{

    netsnmp_monitor_callback_cooperative *cbh;

    netsnmp_assert(need_init == 0);

    cbh = SNMP_MALLOC_TYPEDEF(netsnmp_monitor_callback_cooperative);

    if (NULL == cbh) {

        snmp_log(LOG_ERR, "could not allocate memory for "

                 "cooperative callback");

        return;

    }

    cbh->hdr.event = event;

    cbh->hdr.object_info = object_info;

    cbh->hdr.monitored_object.len = o_len;

    if (o_steal) {

        cbh->hdr.monitored_object.oids = o;

    } else {

        cbh->hdr.monitored_object.oids = snmp_duplicate_objid(o, o_len);

    }

    netsnmp_notify_monitor((netsnmp_monitor_callback_header *) cbh);

}

/** @cond */

/*************************************************************************

 *************************************************************************

 *************************************************************************

 * WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!

 * WARNING!                                                       WARNING!

 * WARNING!                                                       WARNING!

 * WARNING!         This code is under active development         WARNING!

 * WARNING!         and is subject to change at any time.         WARNING!

 * WARNING!                                                       WARNING!

 * WARNING!                                                       WARNING!

 * WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!

 *************************************************************************

 *************************************************************************

 *************************************************************************

 */

static watcher_list *

find_watchers(oid * object, size_t oid_len)

{

    netsnmp_index oah;

    oah.oids = object;

    oah.len = oid_len;

    return (watcher_list *)CONTAINER_FIND(monitored_objects, &oah;;

}

static int

insert_watcher(oid * object, size_t oid_len, monitor_info * mi)

{

    watcher_list   *wl = find_watchers(object, oid_len);

    int             rc = SNMPERR_SUCCESS;

    if (NULL != wl) {

        monitor_info   *last, *current;

        netsnmp_assert(wl->head != NULL);

        last = NULL;

        current = wl->head;

        while (current) {

            if (mi->priority == current->priority) {

                /*

                 * check for duplicate

                 */

                if (mi->watcher_data == current->watcher_data)

                    return SNMPERR_VALUE; /** duplicate! */

            } else if (mi->priority > current->priority) {

                break;

            }

            last = current;

            current = current->next;

        }

        if (NULL == last) {

            mi->next = wl->head;

            wl->head = mi;

        } else {

            mi->next = last->next;

            last->next = mi;

        }

    } else {

        /*

         * first watcher for this oid; set up list

         */

        wl = SNMP_MALLOC_TYPEDEF(watcher_list);

        if (NULL == wl)

            return SNMPERR_MALLOC;

        /*

         * copy index oid

         */

        wl->monitored_object.len = oid_len;

        wl->monitored_object.oids = malloc(sizeof(oid) * oid_len);

        if (NULL == wl->monitored_object.oids) {

            free(wl);

            return SNMPERR_MALLOC;

        }

        memcpy(wl->monitored_object.oids, object, sizeof(oid) * oid_len);

        /*

         * add watcher, and insert into array

         */

        wl->head = mi;

        mi->next = NULL;

        rc = CONTAINER_INSERT(monitored_objects, wl);

        if (rc) {

            free(wl->monitored_object.oids);

            free(wl);

            return rc;

        }

    }

    return rc;

}

/**

 * @internal

 * check to see if a registration exists for an object/event combination

 *

 * @param event the event type to check for

 * @param o     the oid to check for

 * @param o_l   the length of the oid

 * @param pWl   if a pointer to a watcher_list pointer is supplied,

 *              upon return the watcher list pointer will be set to

 *              the watcher list for the object, or NULL if there are

 *              no watchers for the object.

 * @param pMi   if a pointer to a monitor_info pointer is supplied,

 *              upon return the pointer will be set to the first

 *              monitor_info object for the specified event.

 *

 * @returns TRUE(1) if a callback is registerd

 * @returns FALSE(0) if no callback is registered

 */

static int

check_registered(unsigned int event, oid * o, int o_l,

                 watcher_list ** pWl, monitor_info ** pMi)

{

    watcher_list   *wl;

    monitor_info   *mi;

    netsnmp_assert(need_init == 0);

    /*

     * check to see if anyone has registered for callbacks

     * for the object.

     */

    wl = find_watchers(o, o_l);

    if (pWl)

        *pWl = wl;

    if (NULL == wl)

        return 0;

    /*

     * check if any watchers are watching for this specific event

     */

    for (mi = wl->head; mi; mi = mi->next) {

        if (mi->events & event) {

            if (pMi)

                *pMi = mi;

            return TRUE;

        }

    }

    return 0;

}

/**

 *@internal

 */

inline void

insert_ready(callback_placeholder * new_cbr)

{

    callback_placeholder *current_cbr, *last_cbr;

    /*

     * insert in callback ready list

     */

    last_cbr = NULL;

    current_cbr = callback_ready_list;

    while (current_cbr) {

        if (new_cbr->mi->priority > current_cbr->mi->priority)

            break;

        last_cbr = current_cbr;

        current_cbr = current_cbr->next;

    }

    if (NULL == last_cbr) {

        new_cbr->next = callback_ready_list;

        callback_ready_list = new_cbr;

    } else {

        new_cbr->next = last_cbr->next;

        last_cbr->next = new_cbr;

    }

}

/**

 *@internal

 *

 * move an pending notification which has a registered watcher to the

 * ready list. Free any other notifications.

 */

static void

move_pending_to_ready(void)

{

    /*

     * check to see if anyone has registered for callbacks

     * for each object.

     */

    while (callback_pending_list) {

        watcher_list   *wl;

        monitor_info   *mi;

        netsnmp_monitor_callback_header *cbp;

        /*

         * pop off first item

         */

        cbp = callback_pending_list;

        callback_pending_list = cbp->private; /** next */

        if (0 == check_registered(cbp->event, cbp->monitored_object.oids,

                                  cbp->monitored_object.len, &wl,

                                  &mi)) {

            /*

             * nobody watching, free memory

             */

            free(cbp);

            continue;

        }

        /*

         * Found at least one; check the rest of the list and

         * save callback for processing

         */

        for (; mi; mi = mi->next) {

            callback_placeholder *new_cbr;

            if (0 == (mi->events & cbp->event))

                continue;

            /*

             * create temprory placeholder.

             *

             * I hate to allocate memory here, as I'd like this code to

             * be fast and lean. But I don't have time to think of another

             * solution os this will have to do for now.

             *

             * I need a list of monitor_info (mi) objects for each

             * callback which has registered for the event, and want

             * that list sorted by the priority required by the watcher.

             */

            new_cbr = SNMP_MALLOC_TYPEDEF(callback_placeholder);

            if (NULL == new_cbr) {

                snmp_log(LOG_ERR, "malloc failed, callback dropped.");

                continue;

            }

            new_cbr->cbh = cbp;

            new_cbr->mi = mi;

            ++cbp->refs;

            /*

             * insert in callback ready list

             */

            insert_ready(new_cbr);

        } /** end mi loop */

    } /** end cbp loop */

    netsnmp_assert(callback_pending_list == NULL);

}

#if defined TESTING_OBJECT_MONITOR

/**************************************************************************

 *

 * (untested) TEST CODE

 *

 */

void

dummy_callback(netsnmp_monitor_callback_header * cbh)

{

    printf("Callback received.\n");

}

void

dump_watchers(netsnmp_index *oah, void *)

{

    watcher_list   *wl = (watcher_list *) oah;

    netsnmp_monitor_callback_header *cbh = wl->head;

    printf("Watcher List for OID ");

    print_objid(wl->hdr->oids, wl->hdr->len);

    printf("\n");

    while (cbh) {

        printf("Priority = %d;, Events = %d; Watcher Data = 0x%x\n",

               cbh->priority, cbh->events, cbh->watcher_data);

        cbh = cbh->private;

    }

}

void

main(int argc, char **argv)

{

    oid             object[3] = { 1, 3, 6 };

    int             object_len = 3;

    int             rc;

    /*

     * init

     */

    netsnmp_monitor_init();

    /*

     * insert an object

     */

    rc = netsnmp_monitor_register(object, object_len, 0,

                                  EVENT_ROW_ADD, (void *) 0xdeadbeef,

                                  dummy_callback);

    printf("insert an object: %d\n", rc);

    /*

     * insert same object, new priority

     */

    netsnmp_monitor_register(object, object_len, 10,

                             EVENT_ROW_ADD, (void *) 0xdeadbeef,

                             dummy_callback);

    printf("insert same object, new priority: %d\n", rc);

    /*

     * insert same object, same priority, new data

     */

    netsnmp_monitor_register(object, object_len, 10,

                             EVENT_ROW_ADD, (void *) 0xbeefdead,

                             dummy_callback);

    printf("insert same object, same priority, new data: %d\n", rc);

    /*

     * insert same object, same priority, same data

     */

    netsnmp_monitor_register(object, object_len, 10,

                             EVENT_ROW_ADD, (void *) 0xbeefdead,

                             dummy_callback);

    printf("insert same object, same priority, new data: %d\n", rc);

    /*

     * dump table

     */

    CONTAINER_FOR_EACH(monitored_objects, dump_watchers, NULL);

}

#endif /** defined TESTING_OBJECT_MONITOR */

/** @endcond */