Notification Consumer API

The notification consumer API consists of the module descriptor, functions to create and destroy notification consumers, and related error types. More...

Defines

• #define GLOBUS_NOTIFICATION_CONSUMER_MODULE

Typedefs

• typedef void(* globus_notification_consumer_func_t )(void *arg, wsnt_TopicExpressionType *topic, wsa_EndpointReferenceType *producer, xsd_any *message)

Enumerations

• enum {
    GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_NULL_PARAM = 1024,
    GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_UNKNOWN_RESOURCE,
    GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_DESERIALIZING_TOPIC,
    GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_UNABLE_TO_CREATE_CONSUMER
  }

Functions

• 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)
• globus_result_t globus_notification_destroy_consumer (wsa_EndpointReferenceType *consumer_reference)

---

Detailed Description

The notification consumer API consists of the module descriptor, functions to create and destroy notification consumers, and related error types.

---

Define Documentation

#define GLOBUS_NOTIFICATION_CONSUMER_MODULE

Module descriptor for the Notification Consumer API.

---

Typedef Documentation

typedef void(* globus_notification_consumer_func_t)(void *arg, wsnt_TopicExpressionType *topic, wsa_EndpointReferenceType *producer, xsd_any *message)

Notification Callback Type

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.

Parameters:

	arg	User-defined callback argument.
	topic	Topic expression associated with the notification message.
	producer	Endpoint reference to the resource which produced this topic notification.
	message	Notification message.

---

Enumeration Type Documentation

anonymous enum

Error types

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.

Enumerator:

GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_NULL_PARAM	Null parameter passed to API function.
GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_UNKNOWN_RESOURCE	Attempt to destroy a consumer resource which is unknown or already destroyed.
GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_DESERIALIZING_TOPIC	Unable to deserialize the topic notification message.
GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_UNABLE_TO_CREATE_CONSUMER	Unable to create consumer.

---

Function Documentation

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
	)

Create a NotificationConsumerService resource.

Create a notification consumer resource, which binds an resource endpoint to a user-defined callback. The consumer_reference passed to this function will be modified to contain an EPR to this resource which can be used as the ConsumerReference element in a Subscribe operation call when using the client stubs for a service which implements the NotificationProducer API.

Parameters:

	consumer_reference	EPR to be populated to point to a new NotificationConsumer service resource instance.
	engine	Service engine which will be used to process requests for this new new service.
	callback	Pointer to the application callback to be called when a notification message is received for this resouce.
	callback_arg	Application-specific parameter to the callback function.

Return values:

	GLOBUS_SUCCESS	Consumer resource created successfully.
	GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_NULL_PARAM	Null parameter passed to this function.
	GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_UNABLE_TO_CREATE_CONSUMER	Unable to create consumer. Underlying cause will be chained to this error, but is typically an out-of-memory situation.

globus_result_t globus_notification_destroy_consumer

(

wsa_EndpointReferenceType *

consumer_reference

)

Destroy a consumer resource.

The resource associated with the EPR passed to this function will be destroyed. After this function returns, the callback associated with this resource will no longer be called.

Parameters:

consumer_reference

EPR of the resource to destroy.

Return values:

	GLOBUS_SUCCESS	Consumer resource destroyed successfully.
	GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_NULL_PARAM	Null parameter passed to this function.
	GLOBUS_NOTIFICATION_CONSUMER_ERROR_TYPE_UNKNOWN_RESOURCE	The EPR does not refer to a valid resource.