Systems Management: Event Management Service

Systems Management; Event Management Service (XEMS)
Copyright © 1997 The Open Group

Consumer Interface

The XEMS event consumer interface consists of two parts. One part is used by the consumer to set itself up as a consumer, and the other is used to register with XEMS.

All event consumers have to make calls to the XEMS event consumer setup routines before receiving XEMS events. These routines perform required setup, and are XEMS implementation dependent. The setup routines are designed to work with the register routines to save the state of a consumer environment so that the consumer can be restarted with a call to the ems_consumer_start() routine by passing the consumer uuid obtained from the initial call to ems_consumer_start().

The event consumer interface allows event consumers to register and unregister with XEMS. Once registered, consumers can add and delete event filters define what events they are interested in. When XEMS receives events from event suppliers, the event will be filtered using the event filter, and only the matching events will be forwarded on to the interested consumers. Systems Management: Event Management Service - ems_consumer_start

Previous section.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

NAME

ems_consumer_start - Consumer Start

SYNOPSIS

#include <xems.h>

void ems_consumer_start(
    ems_string_t         consumer,
    ems_ulong_int        flags,
    ems_handler_t        hfunc[],
    ems_uuid_t **        uuid,
    ems_handle_t *       handle[],
    ems_error_t *        status);

DESCRIPTION

This routine should be called at the beginning of each event consumer before making any register calls. It will create a ems_uuid_t to uniquely identify this event consumer and perform any local consumer initialization required. The routine can be called the first time a consumer starts, or when a consumer is restarting and wishes to reestablish the environment already established. If a new environment is being established, then the uuid parameter should contain NULL. When reestablishing an environment, then the uuid from the initial call should be passed in.

PARAMETERS

Input

consumer

specifies the consumer name. This parameter can be null if the uuid is specified.

flags

reserved for future use.

hfunc

null terminated array of event handler routines. All event handler routines that will be used in an ems_consumer_register() call must be in this array.

uuid

the unique consumer id returned from a previous call to ems_consumer_start().

Output

uuid

the unique consumer id for this consumer environment.

handle

returns an XEMS handle which can be used on subsequent calls to XEMS routines. This handle also represents a consumer filter_group/event handler association.

status

returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

RETURN VALUE

The possible ems status codes are:

ems_s_status_ok
ems_s_no_memory
ems_s_consumer_already_started

Systems Management: Event Management Service - ems_consumer_stop Previous section.

NAME

ems_consumer_stop - Consumer Stop

SYNOPSIS

#include <xems.h>

void ems_consumer_stop(
    ems_error_t *       status);

DESCRIPTION

This routine should be called at the end of each event consumer. It will perform any consumer cleanup required.

PARAMETERS

Output

status

returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

RETURN VALUE

The possible XEMS status codes are:

ems_s_status_ok
ems_s_consumer_not_started

Systems Management: Event Management Service - ems_push_consumer_register Previous section.

NAME

ems_push_consumer_register - Push Consumer Register

SYNOPSIS

#include <xems.h>

void ems_push_consumer_register(
    ems_netname_t *             hostname,
    ems_filtername_list_t *     filter_group,
    int                         hfunc_index,
    ems_handle_t *              handle,
    void *                      arg,
    ems_error_t *               status);

DESCRIPTION

This routine is used by XEMS event consumers to register as a push consumer with XEMS. This routine contacts an event service, and registers this filter group/handler association with that event service. This routine may be called multiple times per consumer with different hostnames, filter_groups, and handler functions. The handler function specified is started up the in the consumer process. ems_consumer_start() has to have been called before this routine (to establish the consumer name and uuid).

PARAMETERS

Input

hostname

is the name of the host machine where the Event Service is running. If the hostname is NULL, then the local host is assumed.

filter_group

is a list of event filter names which will define this consumers initial event filter group. If filter_group is empty, no filter group is specified, and XEMS will not forward any events to this consumers until the consumer makes a call to ems_add_event_to_group().

hfunc_index

the index into the event handler array of the event handler function to call if an event passes the filter group and is sent to the consumer. The event handler array is the hfunc[] parameter to the ems_consumer_start() routine.

Output

handle

returns an XEMS handle which can be used on subsequent calls to XEMS routines. This handle also represents a consumer filter_group/event handler association.

status

returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

RETURN VALUE

The possible status codes are:

ems_s_status_ok
ems_s_no_memory
ems_s_already_registered

Systems Management: Event Management Service - ems_pull_consumer_register Previous section.

NAME

ems_pull_consumer_register - Pull Consumer Register

SYNOPSIS

#include <xems.h>

void ems_pull_consumer_register(
    ems_netname_t *               hostname,
    ems_filtername_list_t *       filter_group,
    ems_handle_t *                handle,
    ems_error_t *                 status);

DESCRIPTION

This routine is used by XEMS event consumers to register as a pull consumer with XEMS. This routine should be called once for each host that this consumer wants to receive events from.

PARAMETERS

Input

hostname

is the name of the host machine where the Event Service is running. If the hostname is NULL, then the local host is assumed.

filter_group

is a list of event filter names which will define this consumers initial event filter group. If filter_group is empty, no filter group is specified, and XEMS will not forward any events to this consumers until the consumer makes a call to ems_add_event_to_group().

Output

handle

returns an XEMS handle which can be used on subsequent calls to XEMS routines.

status

returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

RETURN VALUE

The possible status codes are:

ems_s_status_ok
ems_s_no_memory
ems_s_already_registered

Systems Management: Event Management Service - ems_consumer_unregister Previous section.

NAME

ems_consumer_unregister - Consumer Unregister

SYNOPSIS

#include <xems.h>

void ems_consumer_unregister(
    ems_handle_t *          handle,
    ems_error_t *           status);

DESCRIPTION

This routine is used by XEMS event consumers to unregister with XEMS. This routine should be called once for each call to ems_push_consumer_register() or ems_pull_consumer_register(). The event consumer should call this routine before calling the ems_consumer_stop() routine.

PARAMETERS

Input

handle

a handle returned from a call to one of the consumer register routines.

Output

handle

this routine will free up memory used by handle, and set handle to NULL.

status

returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

RETURN VALUE

The possible status codes are:

ems_s_status_ok
ems_s_unknown_consumer

Systems Management: Event Management Service - ems_add_filter_to_group Previous section.

NAME

ems_add_filter_to_group - Add Event Filter to Group

SYNOPSIS

#include <xems.h>

void ems_add_filter_to_group(
    ems_handle_t                    handle,
    ems_filtername_list_t *         event_filters,
    ems_error_t *                   status);

DESCRIPTION

This routine is used by XEMS event consumers to add event filter names to a consumers event filter group. This routine can be called multiple times for each consumer.

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_push_consumer_register() or ems_pull_consumer_register().

event_filters

contains a list of one or more event filter names to add to this consumers event filter group. consumers can use the names of new event filters after building them with the ems_filter_add() routine, or existing filters which can be obtained by using the ems_filter_get_namelist() routine.

Output

status

Returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

RETURN VALUE

The possible status codes are:

ems_s_status_ok

Systems Management: Event Management Service - ems_delete_filter_from_group Previous section.

NAME

ems_delete_filter_from_group - Delete Event Filter From Group

SYNOPSIS

#include <xems.h>

void ems_delete_filter_from_group(
    ems_handle_t                    handle,
    ems_filtername_list_t *         filter_name,
    ems_error_t *                   status);

DESCRIPTION

This routine is used by XEMS event consumers to delete event filter names from consumer event filter groups.

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_push_consumer_register() or ems_pull_consumer_register().

filter_name

specifies the event filter name(s) to delete from the consumers event filter group.

Output

status

returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

RETURN VALUE

The possible status codes are:

ems_s_status_ok

Systems Management: Event Management Service - ems_get_filter_group Previous section.

NAME

ems_get_filter_group - Get Filter Group

SYNOPSIS

#include <xems.h>

void ems_get_filter_group(
    ems_handle_t                     handle,
    ems_filtername_list_t **         filter_group,
    ems_error_t *                    status);

DESCRIPTION

This routine returns a list of event filter names that comprise the consumers event filter group.

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_push_consumer_register() or ems_pull_consumer_register().

Output

filter_group

will contain the list of event filter names which are in the consumers event filter group. It is up to the requesting consumer to free the storage allocated for filter_group.

status

returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

RETURN VALUE

The possible status codes are:

ems_s_status_ok

Systems Management: Event Management Service - ems_consumer_get_registration Previous section.

NAME

ems_consumer_get_registration - Get Consumer Registration

SYNOPSIS

#include <xems.h>

void ems_consumer_get_registration(
    ems_handle_t                   handle,
    ems_netname_t **               hostname,
    ems_filtername_list_t **       filter_group,
    int*                           hfunc_index,
    ems_error_t *                  status);

DESCRIPTION

This routine returns the consumer registration information associated with a consumer handle.

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_push_consumer_register() or ems_pull_consumer_register().

Output

filter_group

will contain the list of event filter names which are in the event filter group which is associated with this consumer registration handle. It is up to the caller to free the storage allocated for filter_group.

hostname

will contain the hostname of the event service associated with this consumer registration handle. It is up to the caller to free the storage allocated for hostname.

hfunc_index

will contain the handler function index associated with this consumer registration handle. If the consumer is a pull consumer, then this value will be -1.

status

returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

RETURN VALUE

The possible status codes are:

ems_s_status_ok

Systems Management: Event Management Service - ems_consumer_pull Previous section.

NAME

ems_consumer_pull - Consumer Pull

SYNOPSIS

#include <xems.h>

void ems_consumer_pull(
    ems_handle_t            handle,
    ems_event_t *           event,
    ems_error_t *           status);

DESCRIPTION

This routine is called by pull consumers to get an event from the event service. The event has to pass through the filter group set up by the pull consumer in order to receive the event. This routine does not return until an event is available.

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_pull_consumer_register().

Output

event

will contain the event received from the pull operation from the event service.

status

returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

RETURN VALUE

The possible status codes are:

ems_s_status_ok

Systems Management: Event Management Service - ems_consumer_try_pull Previous section.

NAME

ems_consumer_try_pull - Consumer Try Pull

SYNOPSIS

#include <xems.h>

void ems_consumer_try_pull(
    ems_handle_t            handle,
    ems_event_t *           event,
    ems_error_t *           status);

DESCRIPTION

This routine is called by pull consumers to get an event from the event service. The event has to pass through the filter group set up by the pull consumer in order to receive the event. This routine returns with a status of ems_s_no_event() when no event is available.

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_pull_consumer_register().

Output

event

will contain the event received from the pull operation from the event service.

status

returns the status code from this routine which indicates whether the routine completed successfully or, if not, why not.

RETURN VALUE

The possible status codes are:

ems_s_status_ok
ems_s_no_event

Contents

Next section

Index