Systems Management: Event Management Service

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

Administration Interface

The XEMS Management interface provides a means to manage various aspects of the XEMS. Using this interface applications can manage event servers, event consumers, event filters, and undelivered events in the XEMS event log. Systems Management: Event Management Service - ems_mgmt_list_ems 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_mgmt_list_ems - List Event Service Hosts

SYNOPSIS

#include <xems.h>

void ems_mgmt_list_ems(
    ems_string_t **           host_list,
    ems_error_t *             status);

DESCRIPTION:

List hosts running the Event Service. These hosts can be used with calls to the .Fn ems_register, ems_push_supplier_register(), ems_pull_supplier_register(), ems_push_consumer_register() and ems_pull_consumer_register() routines.

PARAMETERS:

Output

host_list

contains the list of hosts running the Event Service. Use ems_mgmt_free_ems() to free this list.

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_mgmt_free_ems Previous section.

NAME

ems_mgmt_free_ems - Free Event Service Host List

SYNOPSIS

#include <xems.h>

void void ems_mgmt_free_ems(
    ems_string_t **           host_list,
    ems_error_t *             status);

DESCRIPTION

Free host_list structure obtained from a call to ems_mgmt_list_ems().

PARAMETERS

Input

host_list

list of hosts obtained from ems_mgmt_list_ems() to free.

Output

host_list

set 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

Systems Management: Event Management Service - ems_mgmt_list_attributes Previous section.

NAME

ems_mgmt_list_attributes - List Event Service Attributes

SYNOPSIS

#include <xems.h>

void ems_mgmt_list_attributes(
    ems_handle_t              h,
    ems_attrlist_t **         list,
    ems_error_t *             status);

DESCRIPTION

List Event Service attributes. These attributes are implementation defined

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_register() routine.

Output

list

contains the list of Event Service attributes

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_mgmt_free_attributes Previous section.

NAME

ems_mgmt_free_attributes - Free Event Service Attributes

SYNOPSIS

#include <xems.h>

void ems_mgmt_free_attributes(
    ems_attrlist_t **           list,
    ems_error_t *               status);

DESCRIPTION

Set an Event Service attribute. These attributes are implementation defined.

PARAMETERS

Input

list

contains the list of attributes to free.

Output

list

set 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

Systems Management: Event Management Service - ems_mgmt_list_consumers Previous section.

NAME

ems_mgmt_list_consumers - Management List Consumers

SYNOPSIS

#include <xems.h>

void ems_mgmt_list_consumers(
    ems_handle_t                     handle,
    ems_consumer_list_t **           list,
    ems_error_t *                    status);

DESCRIPTION

List consumers registered with XEMS.

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_register() routine.

Output

list

contains the list of consumers.

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_no_consumers

Systems Management: Event Management Service - ems_mgmt_free_consumers Previous section.

NAME

ems_mgmt_free_consumers - Management Free Consumers List

SYNOPSIS

#include <xems.h>

void ems_mgmt_free_consumers(
    ems_consumer_list_t **      list,
    ems_error_t *               status);

DESCRIPTION

Free the storage used by an ems_consumer_list_t structure obtained by a call to ems_mgmt_list_consumers().

PARAMETERS

Input

list

consumer list to free.

Output

list

set 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

Systems Management: Event Management Service - ems_mgmt_secedit Previous section.

NAME

ems_mgmt_secedit - Management Security Edit

SYNOPSIS

#include <xems.h>

void ems_mgmt_secedit(
    ems_handle_t          handle,
    ems_secobj_t          secobj,
    ems_secsubj_t         subject,
    ems_secperm_t         newperm,
    ems_secperm_t *       oldperm,
    ems_error_t *         status);

DESCRIPTION

Alters the permission attributes for a subject, that is, a principal or client with regard to an XEMS object. The effect of an edit operation may be to permit a subject to use an EMS object. The effect of an edit operation may be to revoke permission to use an EMS object. If the subject is not associated with the security object, then the addition of permissions will instantiate the subject for the security object. The removal of all permissions will remove the subject from the security object.

PARAMETERS

Input

handle

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

secobj

specifies the targeted security object.

subject

specifies the subject involved in the edit operation.

newperm

specifies the permissions to be applied to the subject.

Output

oldperm

returns the permissions associated with the subject before the edit operation.

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_invalid_name
ems_s_insufficient_permission

Systems Management: Event Management Service - ems_mgmt_secread Previous section.

NAME

ems_mgmt_secread - Management Security Read

SYNOPSIS

#include <xems.h>

void ems_mgmt_secread(
    ems_handle_t          handle,
    ems_secobj_t          secobj,
    ems_secsubj_t         subject,
    ems_secperm_t *       oldperm,
    ems_error_t *         status);

DESCRIPTION

Retrieves the permission attributes for a subject, that is, a principal or client with regard to an XEMS.

PARAMETERS

Input

handle

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

secobj

specifies the targeted security object.

subject

specifies the subject involved in the edit operation.

Output

oldperm

returns the permissions associated with the subject.

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_invalid_name
ems_s_insufficient_permission

Systems Management: Event Management Service - ems_mgmt_secsubjadd Previous section.

NAME ems_mgmt_secsubjadd - Management Security Add Subject

SYNOPSIS

#include <xems.h>

void ems_mgmt_secsubjadd(
    ems_handle_t          handle,
    ems_secsubj_t         subject,
    ems_secprin_t         principal,
    ems_error_t *         status);

DESCRIPTION:

Identifies a principal as an XEMS subject.

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_register routine.

subject

specifies the subject involved in the edit operation.

principal

specifies an opaque identifier that represents the principal from the system perspective.

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
ems_s_invalid_name
ems_s_insufficient_permission

Systems Management: Event Management Service - ems_mgmt_secsubjdelete Previous section.

NAME

ems_mgmt_secsubjdelete - Management Security Delete Subject

SYNOPSIS

#include <xems.h>

void ems_mgmt_secsubjdelete(
    ems_handle_t          handle,
    ems_secsubj_t         subject,
    ems_error_t *         status);

DESCRIPTION

Identifies a principal as an XEMS subject.

PARAMETERS

Input

handle

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

subject

specifies the subject involved in the edit operation.

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
ems_s_invalid_name
not valid
ems_s_insufficient_permission

Systems Management: Event Management Service - ems_mgmt_secsubjget Previous section.

NAME

ems_mgmt_secsubjget - Management Security Get Subject

SYNOPSIS

#include <xems.h>

void ems_mgmt_secsubjget(
    ems_handle_t          handle,
    ems_secprin_t         principal,
    ems_secsubj_t *       subject,
    ems_error_t *         status);

DESCRIPTION

Identifies a principal as an XEMS subject.

PARAMETERS

Input

handle

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

principal

specifies an opaque identifier that represents the principal from the system perspective.

subject

returns the corresponding subject.

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
ems_s_invalid_name
ems_s_insufficient_permission

Systems Management: Event Management Service - ems_mgmt_delete_consumer Previous section.

NAME

ems_mgmt_delete_consumer - Management Delete Consumer

SYNOPSIS

#include <xems.h>

void ems_mgmt_delete_consumer(
    ems_handle_t          handle,
    ems_string_t          consumer,
    ems_uuid_t *          uuid,
    ems_error_t *         status);

DESCRIPTION

Deletes a consumer, that is, principal, from the XEMS consumer database. After this call, the specified consumer will not receive any events unless it reregisters with the Event Service. The principal may not be the same as a consumer, for example, the principal may be a group (dbadmin) and the consumer is a member of the group.
Implementations may provide an alternate mechanism, for example, command line or a global security mechanism, for removing principals. The alternate mechanism may be part of a global security scheme.

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_register() routine.

consumer

specifies the consumer, that is, principal, name to clear. This name is the name returned in the ems_consumer_list_t data structure after calling ems_mgmt_list_consumers() or the name used on the ems_consumer_start() routine.

uuid

specifies the consumer uuid which uniquely identifies the consumer to clear. If this parameter is NULL, then only one consumer can exist with the name consumer.

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
ems_s_invalid_name
ems_s_insufficient_permission

Systems Management: Event Management Service - ems_mgmt_delete_filter_from_group Previous section.

NAME

ems_mgmt_delete_filter_from_group - Management Delete Event Filter From Group

SYNOPSIS

#include <xems.h>

void ems_mgmt_delete_filter_from_group(
    ems_handle_t                handle,
    ems_string_t                consumer,
    ems_uuid_t *                uuid,
    int                         hfunc_index,
    ems_filtername_list_t *     filter_names,
    ems_error_t *               status);

DESCRIPTION

This routine deletes a specified event filter name(s) from a consumers event filter group.

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_register() routine.

consumer

specifies the consumer whose event filter group is getting updated.

uuid

specifies the consumer uuid which uniquely identifies the consumer to clear. If NULL is specified, then only one consumer can exist with the name consumer.

filter_name

name(s) of the filters to delete from the consumer's 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_mgmt_add_filter_to_group Previous section.

NAME

ems_mgmt_add_filter_to_group - Management Add Event Filter to Group

SYNOPSIS

#include <xems.h>

void ems_mgmt_add_filter_to_group(
    ems_handle_t                 handle,
    ems_string_t                 consumer,
    ems_uuid_t *                 uuid,
    int                          hfunc_index,
    ems_filtername_list_t *      filter_names,
    ems_error_t *                status);

DESCRIPTION

This routine adds event filter names to a consumers event filter group.

PARAMETERS

Input

handle

must contain a valid handle obtained from ems_register() routine.

consumer

specifies the consumer whose event filter group is getting updated.

uuid

specifies the consumer uuid which uniquely identifies the consumer to clear. If NULL is specified, then only one consumer can exist with the name consumer.

filter_name

specifies the list of event filter names to add.

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_mgmt_get_filter_group Previous section.

NAME

ems_mgmt_get_filter_group - Management Get Filter Group

SYNOPSIS

#include <xems.h>

void ems_mgmt_get_filter_group(
    ems_handle_t                  handle,
    ems_string_t                  consumer,
    ems_uuid_t *                  uuid,
    int                           hfunc_index,
    ems_filtername_list_t **      filter_names,
    ems_error_t *                 status);

DESCRIPTION

This routine returns a list of event filter names in a consumers event filter group.

PARAMETERS

Input

handle

must contain a valid consumer handle obtained from ems_register() routine.

consumer

specifies which consumers event filter group to return. The consumer name is the name given to the ems_start_consumer() routine, or the name returned in the ems_consumer_list_t data structure from the routine ems_mgmt_list_consumers().

uuid

specifies the consumer uuid which uniquely identifies the consumer to clear. If this parameter is NULL, then only one consumer can exist with the name consumer.

Output

filter_group

contains the list of event filter names in the specified consumers event 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_mgmt_list_suppliers Previous section.

NAME

ems_mgmt_list_suppliers - Management List Suppliers

SYNOPSIS

#include <xems.h>

void ems_mgmt_list_suppliers(
    ems_handle_t                handle,
    ems_supplier_list_t **      list,
    ems_error_t *               status);

DESCRIPTION

List suppliers registered with XEMS.

PARAMETERS

Input

handle

must contain a valid handle obtained from ems_register() routine.

Output

list

contains the list of suppliers.

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_no_suppliers

Systems Management: Event Management Service - ems_mgmt_free_suppliers Previous section.

NAME

ems_mgmt_free_suppliers - Management Free Suppliers List

SYNOPSIS

#include <xems.h>

void ems_mgmt_free_suppliers(
    ems_supplier_list_t **      list,
    ems_error_t *               status);

DESCRIPTION

Free the storage used by an ems_supplier_list_t structure obtained by a call to ems_mgmt_list_suppliers().

PARAMETERS

Input

list

supplier list to free.

Output

list

set 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

Systems Management: Event Management Service - ems_mgmt_delete_supplier Previous section.

NAME

ems_mgmt_delete_supplier - Management Delete Supplier

SYNOPSIS

#include <xems.h>

void ems_mgmt_delete_supplier(
    ems_handle_t          handle,
    ems_string_t          supplier,
    ems_uuid_t *          uuid,
    ems_error_t *         status);

DESCRIPTION

Clear all information stored in XEMS about the specified supplier. The principal may not be the same as a supplier, for example, the principal may be a group (dbadmin) and the supplier is a member of the group.
Implementations may provide an alternate mechanism, for example, command line or a global security mechanism, for adding principals. The alternate mechanism may be part of a global security scheme.

PARAMETERS

Input

handle

must contain a valid supplier handle obtained from ems_register() routine.

supplier

specifies the supplier name to clear. This name is the name returned in the ems_supplier_list_t data structure after calling ems_mgmt_list_suppliers().

uuid

specifies the supplier uuid which uniquely identifies the supplier to clear. If this parameter is NULL, then only one supplier can exist with the name supplier.

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_mgmt_get_undelivered_events Previous section.

NAME

ems_mgmt_get_undelivered_events - Management Get Undelivered Events

SYNOPSIS

#include <xems.h>

void ems_mgmt_get_undelivered_events(
    ems_handle_t              handle,
    ems_event_type_t          type,
    ems_event_list_t **       list,
    ems_error_t *             status);

DESCRIPTION

Get a list of events that have not been delivered to interested consumers.

PARAMETERS

Input

handle

must contain a valid handle obtained from ems_register() routine.

type

the event type to control the number of returned events.

Output

list

contains the list of undelivered events.

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_no_events

Systems Management: Event Management Service - ems_mgmt_free_undelivered_events Previous section.

NAME

ems_mgmt_free_undelivered_events - Management Free Undelivered Events

SYNOPSIS

#include <xems.h>

void ems_mgmt_free_undelivered_events(
    ems_event_list_t **    event,     /* undelivered events     */
    ems_error_t *          status);   /* event get status       */

DESCRIPTION

Free the undelivered events for the interested consumer.

PARAMETERS

Input

list

contains the list of undelivered events to free.

Output

list

set to free.

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_mgmt_delete_undelivered_event Previous section.

NAME

ems_mgmt_delete_undelivered_event - Management Delete Undelivered Event

SYNOPSIS

#include <xems.h>

void ems_mgmt_delete_undelivered_event(
    ems_handle_t          handle,
    ems_eventid_t *       event_id,
    ems_error_t *         status);

DESCRIPTION

Delete an undelivered event from the XEMS Event log.

PARAMETERS

Input

handle

must contain a valid handle obtained from ems_register() routine.

event_id

the event id of the event to delete.

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
ems_s_no_memory
ems_s_no_events

Systems Management: Event Management Service - ems_mgmt_forward Previous section.

NAME

ems_mgmt_forward - Management Forward Events

SYNOPSIS

#include <xems.h>

void ems_mgmt_forward(
    ems_handle_t                 handle,
    ems_filtername_list_t *      filter_group,
    ems_netname_t *              hostname,
    ems_string_t *               name,
    ems_uuid_t *                 uuid,
    ems_error_t *                status);

DESCRIPTION

This call tells the XEMS identified by ems_handle to forward all events that pass through the filter_group specified to the XEMS specified by hostname.
Once this call is made, then the event service identified as hostname will be treated like any other consumer, and the filter group can be manipulated by the XEMS management filter group routines.
Forwarding can be stopped by using the ems_mgmt_consumer_delete().

PARAMETERS

Input

handle

ems handle of the event service that is being asked to forward events. Handle must contain a valid consumer handle obtained from the ems_register() routine.

filter_group

is a list of event filter names which will define the event filter group that controls which events will be forwarded. If filter_group is empty, no filter group is specified, and XEMS will not forward any events to the specified event service until a call is make to ems_mgmt_add_filter_to_group().

hostname

is the name of the host machine where the Event Service is running that will receive the forwarded events. If the hostname is NULL, then the local host is assumed. This hostname cannot be the same as the host referred to in the handle.

Output

name

returns the consumer name associated with the event service that the events will be forwarded to. This name can be used in calls to the ems_mgmt_XXX_filter_group() routines so that the event service can be treated as any other consumer.

uuid

returns the consumer uuid which uniquely identifies the event service to forward to so that it can be treated like as any other event consumer.

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_forwarding_event_service_not_there
ems_s_forwarding_event_loop

Contents

Next section

Index