struct PROFILE_INSTANCE

A structure defined by the Profile API for managing a profile-instance.

Profile API functions

Documentation

A structure defined by the Profile API for managing a profile-instance.

This structure is created by the wrapper each time a channel is opened, and is maintained by the wrapper code. (The wrapper also maintains a dual, the channel-instance structure.)

This structure contains function pointers for the "inner" callbacks invoked by the wrapper.

Profile API functions

Defines the function pointers for "inner" callbacks invoked by the wrapper.

void pro_start_indication(struct PROFILE_INSTANCE* pi, struct profile* po)

Indicates that a <start> element has been received for the specified profile-instance.

The profile should handle any start data and call bpc_start_response before returning.

To determine the servername to use, the callback should first invoke bp_server_name. If NULL, then consult pi->channel->inbound->server_name instead.

Parameters:

pi - A pointer to the newly-allocated profile-instance structure created by the wrapper.
po - A pointer to the profile structure, which is filled in with a parsed version of the <start> message received over channel 0. The contents of this structure should be considered read-only.

void pro_start_confirmation(void* client_data, struct PROFILE_INSTANCE* pi, struct profile* po)

Confirms that the given channel has been started successfully.

This is invoked after the start request callback has returned. If the <start> is refused by the remote peer via the return of an <error> element, then this callback is not made, and only the start request callback is called. On a channel started by the local peer, this is the first function invoked on the new profile-instance.

Parameters:

client_data - A user-supplied pointer from bp_start_request
pi - A pointer to the newly-allocated profile-instance structure created by the wrapper.
po - A pointer to the profile structure, which is filled in with a parsed version of the <profile> message received over channel 0. The contents of this structure should be considered read-only.

void pro_close_indication(struct PROFILE_INSTANCE* pi, struct diagnostic* status, char local_or_remote, char session_or_channel)

Indicates that a <close>element has been received for the specified profile-instance, or that the local peer is asking to close this channel or the entire session.

The profile should decide if it agrees (or not) and call bpc_close_response before returning.

Parameters:

pi - A pointer to the profile-instance structure.
status - A pointer to the diagnostic structure containing the reason for the request.
local_remote - Indicates which peer is making the request, one of:

• PRO_ACTION_LOCAL
• PRO_ACTION_REMOTE

session_channel - Indicates what is being requested to close, one of:

• PRO_ACTION_SESSION
• PRO_ACTION_CHANNEL
• PRO_ACTION_ABORT

Note that in the last case, this is a demand, not a request.

void pro_close_confirmation(struct PROFILE_INSTANCE* pi, char commit_or_rollback, struct diagnostic* error, char local_or_remote, char session_or_channel)

Confirms the final disposition of the close request.

This is invoked regardless of who asked to close the channel. (If invoked by the local peer, it's invoked after the close request callback has returned.) If the channel is now closed, the profile-instance structure is about to be deallocated, so the profile should release any instance-specific resources, e.g., referenced by user_ptr1 and user_ptr2.

Parameters:

pi - A pointer to the profile-instance structure.
commit_or_rollback - Whether the close actually occurred, one of:

• PRO_ACTION_SUCCESS
• PRO_ACTION_FAILURE

error - On rollback, a pointer to a diagnostic structure containing the reason.
local_remote - Indicates which peer made the request, one of:

• PRO_ACTION_LOCAL
• PRO_ACTION_REMOTE

session_channel - Indicates what was requested to close, one of:

• PRO_ACTION_SESSION
• PRO_ACTION_CHANNEL
• PRO_ACTION_ABORT

Note that in the last case, this is a demand, not a request.

void pro_tuning_reset_indication(struct PROFILE_INSTANCE* pi)

Indicates that a local profile is getting ready to perform a tuning reset, e.g., the TLS profile is getting ready to send the <ready> element.

This is a FYI for the profile-instance -- there isn't an opportunity to prevent the tuning reset from happening.

Parameters:

pi - A pointer to the profile-instance structure.

See Also:

bpc_tuning_reset_request

void pro_tuning_reset_confirmation(struct PROFILE_INSTANCE* pi, char commit_or_rollback)

Confirms the final disposition of a tuning reset.

If a tuning reset actually occurred, the profile-instance structure is about to be deallocated, so the profile should release any instance-specific resources, e.g., referenced by user_ptr1 and user_ptr2.

Parameters:

pi - A pointer to the profile-instance structure.
commit_or_rollback - Whether the tuning reset actually occurred, one of:

• PRO_ACTION_SUCCESS
• PRO_ACTION_FAILURE

See Also:

bpc_tuning_reset_complete

void pro_frame_available(struct PROFILE_INSTANCE* pi)

Announces that a frame has arrived and is ready to be read, if the profile is using the frame-oriented interface.

The profile should call bpc_query_frame or bpc_frame_read to fetch the frame, followed by bpc_frame_destroy.

Parameters:

pi - A pointer to the profile-instance structure.

void pro_message_available(struct PROFILE_INSTANCE* pi)

Announces that a message has arrived and is ready to be read, if the profile is using the message-oriented interface.

The profile should call bpc_query_message to fetch a linked-list of the frames making up the message, followed by bpc_frame_destroy. It may also be convenient to call bpc_frame_aggregate to collapse the data from the linked-list into a character buffer.

Parameters:

pi - A pointer to the profile-instance structure.

void pro_window_full(struct PROFILE_INSTANCE* pi)

Announces that the receive buffer for a profile has filled, but that a complete message has not yet been received.

The profile should do one of:

• Call bpc_query_frame or bpc_frame_read to fetch the frame, followed by bpc_frame_destroy.
• Call bpc_set_channel_window to increase the size of the receive buffer.
• Call bpc_error_allocate to generate an error, and then use bpc_send to send it, pre-emptively terminating the message and discarding any additional frames.

Parameters:

pi - A pointer to the profile-instance structure.

#define PRO_ACTION_LOCAL

The local peer requested the action

#define PRO_ACTION_REMOTE

The remote peer requested the action

#define PRO_ACTION_SESSION

The request is to close the session

#define PRO_ACTION_CHANNEL

The request is to close the channel

#define PRO_ACTION_ABORT

The demands is to close the session

#define PRO_ACTION_SUCCESS

The action occurred

#define PRO_ACTION_FAILURE

The action did not take place

Fields:

channel - A pointer to the associated channel-instance structure.
full_messages - Indicates whether the profile-instance is using the frame-oriented or the message-oriented interface. In the latter case, if the receive buffer fills up before a complete message is received, then pro_window_full being invoked.
user_ptr1 - A user-defined pointer.
user_ptr2 - A user-defined pointer.
user_long1 - A user-defined long-value.
user_long2 - A user-defined long-value.

Home Alphabetic index