struct PROFILE_REGISTRATION

A structure defined by the Profile API for registering a profile-module.

Profile API functions

Documentation

A structure defined by the Profile API for registering a profile-module.

Before the wrapper can invoke a profile-module's code, that profile-module must be registered with the connection structure. If a single profile-module implements multiple profiles (i.e., multiple URIs in the greeting), then multiple profile registrations must be registered by that profile-module.

This structure contains function pointers for all the callbacks invoked by the wrapper. After a connection structure is created but before it is started, all profiles available to the application must be registered with the connection structure. A compiled-in profile-module may use the link to chain together registrations at compile time. A dynamically-loaded profile-module must export a function that returns a pointer to its profile-registration structures.

Profile API functions

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

char* proreg_connection_init(struct PROFILE_REGISTRATION* pr, struct BP_CONNECTION* conn)

Invoked when the profile is registered with the wrapper.

Parameters:

pr - A pointer to the profile-registration structure.
conn - A pointer to the connection structure.

Returns:

NULL if successful, otherise a character pointer explaining the failure.

char* proreg_connection_fin(struct PROFILE_REGISTRATION* pr, struct BP_CONNECTION* conn)

Invoked when the wrapper is destroyed.

Parameters:

pr - A pointer to the profile-registration structure.
conn - A pointer to the connection structure.

Returns:

NULL if successful, otherise a character pointer explaining the failure.

char* proreg_session_init(struct PROFILE_REGISTRATION* pr, struct BP_CONNECTION* conn)

Invoked when a session is created (i.e., when a connection is established or a tuning reset completes).

Parameters:

pr - A pointer to the profile-registration structure.
conn - A pointer to the connection structure.

Returns:

NULL if successful, otherise a character pointer explaining the failure.

char* proreg_session_fin(struct PROFILE_REGISTRATION* pr, struct BP_CONNECTION* conn)

Invoked when a session is destroyed (i.e., when a connection is released or a tuning reset begins).

Parameters:

pr - A pointer to the profile-registration structure.
conn - A pointer to the connection structure.

Returns:

NULL if successful, otherise a character pointer explaining the failure.

void proreg_greeting_notification(struct PROFILE_REGISTRATION* pr, struct BP_CONNECTION* conn, char present_absent)

Invoked when a greeting is received.

Parameters:

pr - A pointer to the profile-registration structure.
conn - A pointer to the connection structure.
present_absent - Indicates whether a URI corresponding to the profile registration was present, one of:

• PROFILE_PRESENT
• PROFILE_ABSENT
• GREETING_ERROR

In the last case, an error was received instead of a greeting. Use bp_greeting_error to find out what was in the <error> element.

#define PROFILE_PRESENT

The profile's URI was present in the greeting

#define PROFILE_ABSENT

The profile's URI was absent from the greeting

#define GREETING_ERROR

The remote peer sent an <error> instead of a greeting

void (*proreg_start_indication)(struct PROFILE_INSTANCE* , struct profile* )

cf, pro_start_indication

void (*proreg_start_confirmation)(void* client_data, struct PROFILE_INSTANCE* , struct profile* )

cf, pro_start_confirmation

void (*proreg_close_indication)(struct PROFILE_INSTANCE* , struct diagnostic* , char, char)

cf, pro_close_indication

void (*proreg_close_confirmation)(struct PROFILE_INSTANCE* , char, struct diagnostic* , char, char)

cf, pro_close_confirmation

void (*proreg_tuning_reset_indication)(struct PROFILE_INSTANCE* )

cf, pro_tuning_reset_indication

void (*proreg_tuning_reset_confirmation)(struct PROFILE_INSTANCE* , char)

cf, pro_tuning_reset_confirmation

void (*proreg_tuning_reset_handshake)(struct PROFILE_INSTANCE* )

cf, pro_tuning_reset_handshake

void (*proreg_frame_available)(struct PROFILE_INSTANCE* )

cf, pro_frame_available

void (*proreg_message_available)(struct PROFILE_INSTANCE* )

cf, pro_message_available

void (*proreg_window_full)(struct PROFILE_INSTANCE* )

cf, pro_window_full

Fields:

uri - A pointer to the unique URI that identifies the profile being registered. This can be registered with IANA for standardized profiles. Note that each connection structure allows only one registration for each URI; that is, one cannot register multiple registrations with the same value for the URI. If both a client and server are implemented for the same URI, they must be implemented together.
next - A pointer to another profile_registration. This allows for convenient compiled-in registrations and convenient dynamic libraries implementing multiple profiles. All profiles can be registered with a single call by making a linked-list of profile-registration structures. Multiple calls to register profiles are equally acceptable, or any mixture of the two techniques.
initiator_modes - A pointer to a list of modes separated by commas in which this profile should have proreg_session_init called. Each value names one mode in which this profile will be initialized, but in which this profile URI will not be advertised in the greeting. Possible values are "plaintext" and "encrypted".
listener_modes - A pointer to a list of modes separated by commas in which this profile should have proreg_session_init called. Each value names one mode in which this profile will be initialized, and in which this profile URI will be advertised in the greeting. Possible values are "plaintext" and "encrypted".
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.
thread_per_channel - A flag indicating the threading behavior behavior that the profile expects. If true, the profile expects or needs a separate thread allocated for each channel started under this profile; otherwise, the profile does not expect its own thread and may be run in any work thread.
user_ptr - A user-defined pointer.

Home Alphabetic index