Galaxy Communicator Documentation:

Controlling Hub Server and Session Properties from the Server

License / Documentation home / Help and feedback

The Hub maintains state information for all its sessions and service providers. This information can be updated in the Hub, but it can also be updated by the server.

Server properties

The Hub keeps track of a set of properties for each service provider. These properties are not necessarily known by the servers themselves, but the Hub can use them locally to help select the appropriate service provider given the current session and token states. It is possible for the server to modify the properties the Hub associates with it.

Gal_Frame GalIO_ServerProperties(GalIO_ServerStruct *server)
Returns the frame constituting the server properties as the server currently knows them locally. Not thread-safe; use only in
_GalSS_init_server.

void GalIO_AddServiceType(GalIO_ServerStruct *server, const char *stype)
Use in _GalSS_init_server to add a service type to the default type (which is identical to the server name).

Gal_Frame GalSS_EnvGetServerProperties(GalSS_Environment *env, char **keys)
Fetches the properties from the Hub which the Hub has associated with the current server. keys is a NULL-terminated array of strings. The return value contains a key-value pair for each key in keys that the Hub has a value for; the name of the returned frame is not interesting. This function ultimately calls the Builtin server function get_properties.

void GalSS_EnvSetServerProperties(GalSS_Environment *env, Gal_Frame properties)
Updates the properties the Hub associates with the current server with the key-value pairs in properties. The name of properties is ignored by the Hub. The local server properties are also updated; see GalIO_ServerModifyProperties. This function ultimately calls the Builtin server function modify_properties.

void GalSS_EnvDeleteServerProperties(GalSS_Environment *env, char **keys)
Deletes the properties in keys from the properties the Hub associates with the current server. keys is a NULL-terminated array of strings. The local server properties are also updated; see GalIO_ServerModifyProperties. This function ultimately calls the Builtin server function modify_properties.

void GalSS_EnvModifyServerProperties(GalSS_Environment *env, Gal_Frame properties_to_set, char **properties_to_delete)
A combination of GalSS_EnvDeleteServerProperties and GalSS_EnvSetServerProperties. The properties in properties_to_delete are deleted before the properties in properties_to_set are added. This function ultimately calls the Builtin server function modify_properties.

void GalIO_ServerModifyProperties(GalIO_ServerStruct *server, Gal_Frame new_properties, char **delete_properties)
Modifies the server properties locally. The name of the new_properties frame is ignored. The properties in delete_properties are deleted before the properties in new_properties are added. delete_properties is a NULL-terminated array of
strings. This function is called by GalSS_EnvModifyServerProperties, etc.

Session properties

The Hub also keeps track of a set of properties for each session. Some of these properties are preset, such as those associated with logging. However, the programmer can also control them from the server.

Gal_Frame GalSS_EnvGetSessionProperties(GalSS_Environment *env, char **keys)
Fetches the properties from the Hub which the Hub has associated with the current session. keys is a NULL-terminated array of strings. The return value contains a key-value pair for each key in keys that the Hub has a value for; the name of the returned frame is not interesting. This function ultimately calls the Builtin server function get_properties.

void GalSS_EnvSetSessionProperties(GalSS_Environment *env, Gal_Frame properties)
Updates the properties the Hub associates with the current session with the key-value pairs in properties. The name of properties is ignored by the Hub. This function ultimately calls the Builtin server function modify_properties.

void GalSS_EnvDeleteSessionProperties(GalSS_Environment *env, char **keys)
Deletes the properties in keys from the properties the Hub associates with the current session. keys is a NULL-terminated array of strings. This function ultimately calls the Builtin server function modify_properties.

void GalSS_EnvModifySessionProperties(GalSS_Environment *env, Gal_Frame properties_to_set, char **properties_to_delete)
A combination of GalSS_EnvDeleteSessionProperties and GalSS_EnvSetSessionProperties. The properties in properties_to_delete are deleted before the properties in properties_to_set are added. This function ultimately calls the Builtin server function modify_properties.

void GalSS_EnvSetSession(GalSS_Environment *env, const char *session_name, int lock_info)
Changes the session ID for the current environment and sends a Hub message which guarantees that the session will exist. This function calls the Builtin function set_session. The lock information should be a logical OR of the following flags:
 
flag description
GAL_SERVER_READS_ONLY_FROM_SESSION the Hub will not send any messages for any sessions other than this one to this server
GAL_SESSION_WRITES_ONLY_TO_SERVER  the Hub will ensure that any messages in this session which might be sent to this server will be
GAL_SERVER_WRITES_ONLY_TO_SESSION the Hub will assume that any message received from this server is assigned to this session
GAL_PERMANENT_LOCK the Hub will not free these locks except in response to another call to Builtin.set_session.

If lock_info is not -1, this function frees all previous locks; otherwise, it inherits the locks from the previous session, if possible.

License / Documentation home / Help and feedback
Last updated June 21, 2002