Group Services Programming Guide and Reference

ha_gs_send_message subroutine

Purpose

ha_gs_send_message - Called by a provider of a group to broadcast message data to all of the providers in the group

Library

GSAPI Thread-Safe Library (libha_gs_r.a)

GSAPI Library (not thread-safe) (libha_gs.a)

Syntax

#include <ha_gs.h>
 
ha_gs_rc_t
    ha_gs_send_message(
                ha_gs_token_t           provider_token,
        const   ha_gs_proposal_info_t   *proposal_info)
 

Parameters

provider_token

A token that identifies the caller as a provider of the group. This token was previously initialized when the provider joined the group using the ha_gs_join subroutine.

proposal_info

A pointer to a buffer that contains a proposal information block, which describes the proposed provider-broadcast message request.

Description

The ha_gs_send_message subroutine is used by a provider of a Group Services group to broadcast message data to all of the providers of the group.

If the request is specified as a one-phase protocol, and Group Services chooses to run this protocol, the group's providers are notified using normal protocol approval procedures.

If the request is specified as an n-phase protocol, and Group Services chooses to run this protocol, the group's providers are notified using normal n-phase voting procedures.

If the Group Services subsystem chooses not to run this protocol (because another protocol is already in progress), the HA_GS_COLLIDE error number is returned either synchronously or asynchronously, depending on when the error is detected. Asynchronous errors are delivered through the delayed error callback routine. Otherwise, the proposal will initiate a protocol within the group.

Information about the provider-broadcast message request is supplied through the provider-broadcast message request block, which is a type of proposal information block. On the ha_gs_send_message subroutine, specify the proposal information block as a provider-broadcast message request block. For the definition of the proposal information block, see the ha_gs_delayed_error_callback man page.

The provider-broadcast message request block has the following definition:

typedef struct {
    ha_gs_num_phases_t          gs_num_phases;
    ha_gs_time_limit_t          gs_time_limit;
    ha_gs_provider_message_t    *gs_message;
} ha_gs_message_request_t;

The gs_num_phases field specifies whether the provider-broadcast message protocols are to be n-phase protocols or one-phase protocols. It can take one of the following values:

HA_GS_1_PHASE

The protocols are to be one-phase protocols. One-phase protocols are automatically approved.

HA_GS_N_PHASE

The protocols are to be n-phase protocols, which put the group into multi-phase voting.

The gs_time_limit field contains the voting phase time limit, in seconds. This is the number of seconds within which each provider must register its vote for each phase of an n-phase protocol. If the field is set to a value of 0, no limit is enforced.

The gs_message field points to a buffer that contains the message that is to be broadcast to providers by a message-with-voting proposal. The provider-broadcast message has the following definition:

typedef  struct {
    int         gs_length;
    char        *gs_message;
} ha_gs_provider_message_t;

The gs_length field contains the length, in bytes, of the message to be broadcast to providers. It must be a value between 1 and 2048.

The gs_message field points to a buffer that contains the message. Provider-broadcast messages are defined by the application that is using the GSAPI and are controlled by the providers in a way that is meaningful to the application. Provider-broadcast messages are not interpreted by the Group Services subsystem.

Restrictions

The calling process must be a provider.

Return Values

If the ha_gs_send_message subroutine is successful, it returns a value of 0 (HA_GS_OK). Group Services has accepted the request and will asynchronously attempt to run the proposed protocol.

Error Values

If the ha_gs_send_message subroutine is unsuccessful, it returns an error number. If the error is detected immediately, an error is returned synchronously. If the error is detected after the call has been accepted, an error is returned asynchronously.

The GSAPI error numbers are defined in the ha_gs.h header file. For more information on GSAPI errors, see GSAPI errors (err_gsapi).

Synchronous Errors

The following errors may be returned synchronously by the ha_gs_send_message subroutine:

HA_GS_BAD_MEMBER_TOKEN

The given provider_token does not specify a valid provider joined to a group.

HA_GS_BAD_PARAMETER

The number of phases specified for the protocol is not allowable; it must be HA_GS_1_PHASE or HA_GS_N_PHASE.

HA_GS_NO_INIT

The GS client has not yet successfully initialized itself with Group Services by calling ha_gs_init().

HA_GS_COLLIDE

The provider's group is already running a protocol; or this provider has already submitted a protocol request.

HA_GS_NOT_A_MEMBER

The given provider_token does not specify a valid group.

HA_GS_NOT_OK

The connection to the GS daemon has been lost. The GS client needs to reinitialize (via ha_gs_init()).

Asynchronous Errors

The following errors may be returned asynchronously by the ha_gs_send_message subroutine:

HA_GS_NOT_A_MEMBER

The provider that is proposing the protocol is no longer a provider for the specified group.

HA_GS_BAD_PARAMETER

The specified parameter was not valid.

HA_GS_COLLIDE

Another protocol is already active for this group.

Files

ha_gs.h

Prerequisite Information

Understanding Group Services.

Related Information

Subroutines: ha_gs_init, ha_gs_join, ha_gs_change_state_value, ha_gs_leave, ha_gs_expel, ha_gs_subscribe, ha_gs_change_attributes, ha_gs_goodbye