/*
 * Portions of this file Copyright 1999-2005 University of Chicago
 * Portions of this file Copyright 1999-2005 The University of Southern California.
 *
 * This file or a portion of this file is licensed under the
 * terms of the Globus Toolkit Public License, found at
 * http://www.globus.org/toolkit/download/license.html.
 * If you redistribute this file, with or without
 * modifications, you must include this notice in the file.
 */

#ifndef GLOBUS_NOTIFICATION_CONSUMER_H
#define GLOBUS_NOTIFICATION_CONSUMER_H 1

#include "globus_common.h"
#include "globus_service_engine.h"

#include "wsnt_TopicExpressionType.h"
#include "wsa_EndpointReferenceType.h"
#include "xsd_anyType.h"

EXTERN_C_BEGIN

/**
 * @mainpage WSRF Notification Consumer
 *
 * This package implements the WSRF Notification Consumer portType and
 * provides a simple API for creating and deleting notification consumer
 * service resources.  The endpoint references for these resource can be
 * used as the ConsumerReference element of a Subscribe operation of a
 * client stub to cause a service which implements the
 * NotificationProducer portType to send topic change notifications to 
 * the client. The client will receive these notifications asyncronously as
 * callbacks.
 *
 * Applications which would use this API
 * must activate the <code>@ref GLOBUS_NOTIFICATION_CONSUMER_MODULE</code>
 * module before calling any of the 
 * @ref notification_consumer "API functions" described in this
 * document.
 */

/**
 * @defgroup notification_consumer Notification Consumer API
 *
 * The notification consumer API consists of the module descriptor,
 * functions to create and destroy notification consumers, and related
 * error types.
 */

extern globus_module_descriptor_t globus_i_notification_consumer_module;
/**
 * Module descriptor for the Notification Consumer API
 * @ingroup notification_consumer
 * @hideinitializer
 */
#define GLOBUS_NOTIFICATION_CONSUMER_MODULE \
        (&globus_i_notification_consumer_module)

/**
 * Error types
 * @ingroup notification_consumer
 * This API uses the globus_result_t method of generating error results.
 * The globus_error_generic API can be used to match error objects returned
 * from this API to the following types.
 */
enum
{
    /** Null parameter passed to API function */
    GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_NULL_PARAM = 1024,
    /**
     * Attempt to destroy a consumer resource which is unknown or already
     * destroyed.
     */
    GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_UNKNOWN_RESOURCE,
    /**
     * Unable to deserialize the topic notification message.
     */
    GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_DESERIALIZING_TOPIC,
    /**
     * Unable to create consumer.
     */
    GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_UNABLE_TO_CREATE_CONSUMER
};

/**
 * Notification Callback Type
 * @ingroup notification_consumer
 *
 * Applications register callbacks of this type when creating a new 
 * notification consumer. Whenever that consumer recieves a 
 * notification, this callback will be invoked. Applications which
 * would like to access to contents of the notification message after
 * their callback returns must make a copy of it.
 *
 * @param arg
 *     User-defined callback argument.
 * @param topic
 *     Topic expression associated with the notification message.
 * @param producer
 *     Endpoint reference to the resource which produced this topic
 *     notification.
 * @param message
 *     Notification message.
 */
typedef void (*globus_notification_consumer_func_t) (
        void *                          arg,
        wsnt_TopicExpressionType *      topic,
        wsa_EndpointReferenceType *     producer,
        xsd_anyType *                   message);

extern
globus_result_t
globus_notification_create_consumer(
    wsa_EndpointReferenceType *         consumer_reference,
    globus_service_engine_t             engine,
    globus_notification_consumer_func_t callback,
    void *                              callback_arg);

extern
globus_result_t
globus_notification_destroy_consumer(
    wsa_EndpointReferenceType *         consumer_reference);


EXTERN_C_END

#endif /* GLOBUS_NOTIFICATION_CONSUMER_H */
