From 862e2b220bc928d6ab2f3bb6159bc4be03914979 Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Thu, 21 Oct 2010 23:43:49 -0700 Subject: SMlib.xml: misc markup cleanups Signed-off-by: Alan Coopersmith --- doc/SMlib.xml | 340 +++++++++++++++++++++++++++++----------------------------- 1 file changed, 170 insertions(+), 170 deletions(-) (limited to 'doc/SMlib.xml') diff --git a/doc/SMlib.xml b/doc/SMlib.xml index 66fedd2..90c3b15 100644 --- a/doc/SMlib.xml +++ b/doc/SMlib.xml @@ -42,16 +42,16 @@ Overview of Session Management -The purpose of the X Session Management Protocol (XSMP) is to provide a uniform mechanism for users to save and restore their sessions. A session is a group of clients, each of which has a particular state. The session is controlled by a network service called the session manager. The session manager issues commands to its clients on behalf of the user. These commands may cause clients to save their state or to terminate. It is expected that the client will save its state in such a way that the client can be restarted at a later time and resume its operation as if it had never been terminated. A client's state might include information about the file currently being edited, the current position of the insertion point within the file, or the start of an uncommitted transaction. The means by which clients are restarted is unspecified by this protocol. +The purpose of the X Session Management Protocol (XSMP) is to provide a uniform mechanism for users to save and restore their sessions. A session is a group of clients, each of which has a particular state. The session is controlled by a network service called the session manager. The session manager issues commands to its clients on behalf of the user. These commands may cause clients to save their state or to terminate. It is expected that the client will save its state in such a way that the client can be restarted at a later time and resume its operation as if it had never been terminated. A client's state might include information about the file currently being edited, the current position of the insertion point within the file, or the start of an uncommitted transaction. The means by which clients are restarted is unspecified by this protocol. -For purposes of this protocol, a client of the session manager is defined as a connection to the session manager. A client is typically, though not necessarily, a process running an application program connected to an X display. However, a client may be connected to more than one X display or not be connected to any X displays at all. +For purposes of this protocol, a client of the session manager is defined as a connection to the session manager. A client is typically, though not necessarily, a process running an application program connected to an X display. However, a client may be connected to more than one X display or not be connected to any X displays at all. The Session Management Library -The Session Management Library (SMlib) is a low-level "C" language interface to XSMP. It is expected that higher level toolkits, such as Xt, will hide many of the details of session management from clients. Higher level toolkits might also be developed for session managers to use, but no such effort is currently under way. +The Session Management Library (SMlib) is a low-level "C" language interface to XSMP. It is expected that higher level toolkits, such as Xt, will hide many of the details of session management from clients. Higher level toolkits might also be developed for session managers to use, but no such effort is currently under way. SMlib has two parts to it: @@ -60,9 +60,9 @@ One set of functions for session managers to call -Some applications will use both sets of functions and act as nested session managers. That is, they will be both a session manager and a client of another session. An example is a mail program that could start a text editor for editing the text of a mail message. The mail program is part of a regular session and, at the same time, is also acting as a session manager to the editor. +Some applications will use both sets of functions and act as nested session managers. That is, they will be both a session manager and a client of another session. An example is a mail program that could start a text editor for editing the text of a mail message. The mail program is part of a regular session and, at the same time, is also acting as a session manager to the editor. -Clients initialize by connecting to the session manager and obtaining a client-ID that uniquely identifies them in the session. The session manager maintains a list of properties for each client in the session. These properties describe the client's environment and, most importantly, describe how the client can be restarted (via an SmRestartCommand. Clients are expected to save their state in such a way as to allow multiple instantiations of themselves to be managed independently. For example, clients may use their client-ID as part of a filename in which to store the state for a particular instantiation. The client-ID should be saved as part of the SmRestartCommand so that the client will retain the same ID after it is restarted. +Clients initialize by connecting to the session manager and obtaining a client-ID that uniquely identifies them in the session. The session manager maintains a list of properties for each client in the session. These properties describe the client's environment and, most importantly, describe how the client can be restarted (via an SmRestartCommand. Clients are expected to save their state in such a way as to allow multiple instantiations of themselves to be managed independently. For example, clients may use their client-ID as part of a filename in which to store the state for a particular instantiation. The client-ID should be saved as part of the SmRestartCommand so that the client will retain the same ID after it is restarted. Once the client initializes itself with the session manager, it must be ready to respond to messages from the session manager. For example, it might be asked to save its state or to terminate. In the case of a shutdown, the session manager might give each client a chance to interact with the user and cancel the shutdown. @@ -70,7 +70,7 @@ Understanding SMlib's Dependence on ICE -The X Session Management Protocol is layered on top of the Inter-Client Exchange (ICE) Protocol. The ICE protocol is designed to multiplex several protocols over a single connection. As a result, working with SMlib requires a little knowledge of how the ICE library works. +The X Session Management Protocol is layered on top of the Inter-Client Exchange (ICE) Protocol. The ICE protocol is designed to multiplex several protocols over a single connection. As a result, working with SMlib requires a little knowledge of how the ICE library works. The ICE library utilizes callbacks to process messages. When a client detects that there is data to read on an ICE connection, it should call the IceProcessMessages function. IceProcessMessages will read the message header and look at the major opcode in order to determine which protocol the message was intended for. The appropriate protocol library will then be triggered to unpack the message and hand it off to the client via a callback. @@ -80,7 +80,7 @@ On the session manager side, things work a bit differently. The session manager has complete control over the creation of ICE connections. The session manager has to first call IceListenForConnections in order to start listening for connections from clients. Once a connection attempt is detected, IceAcceptConnection must be called, and the session manager can simply add the new ICE file descriptor to the list of descriptors to call select on. -For further information on the library functions related to ICE connections, see the Inter-Client Exchange Library standard. +For further information on the library functions related to ICE connections, see the Inter-Client Exchange Library standard. @@ -92,7 +92,7 @@ -Session Management Client (Smc) Functions +Session Management Client (<acronym>Smc</acronym>) Functions This section discusses how Session Management clients: @@ -134,45 +134,45 @@ - context + context A pointer to an opaque object or NULL. Used to determine if an ICE connection can be shared (see below). - xsmp_major_rev + xsmp_major_rev The highest major version of the XSMP the application supports. - xsmp_minor_rev + xsmp_minor_rev The highest minor version of the XSMP the application supports (for the specified xsmp_major_rev). - mask + mask A mask indicating which callbacks to register. - callbacks + callbacks The callbacks to register. These callbacks are used to respond to messages from the session manager. - previous_id + previous_id The client ID from the previous session. - client_id_ret + client_id_ret The client ID for the current session is returned. - error_length + error_length Length of the error_string_ret argument passed in. - error_string_ret + error_string_ret Returns a null-terminated error message, if any. The error_string_ret argument points to user supplied memory. No more than error_length bytes are used. -The network_ids_list argument is a null-terminated string containing a list of network IDs for the session manager, separated by commas. If network_ids_list is NULL, the value of the SESSION_MANAGER environment variable will be used. Each network ID has the following format: +The network_ids_list argument is a null-terminated string containing a list of network IDs for the session manager, separated by commas. If network_ids_list is NULL, the value of the SESSION_MANAGER environment variable will be used. Each network ID has the following format: @@ -182,17 +182,17 @@ - tcp/<hostname>:<portnumber> + tcp/<hostname>:<portnumber> or - decnet/<hostname>::<objname> + decnet/<hostname>::<objname> or - local/<hostname>:<path> + local/<hostname>:<path> @@ -209,7 +209,7 @@ The context argument indicates how willing the client is to share the ICE connection with other protocols. If context is NULL, then the caller is always willing to share the connection. If context is not NULL, then the caller is not willing to use a previously opened ICE connection that has a different non-NULL context associated with it. -As previously discussed (section 3, “Understanding SMlib's Dependence on ICE”), the client will have to keep track of when ICE connections are created or destroyed (using IceAddConnectionWatch and IceRemoveConnectionWatch and will have to call IceProcessMessages each time a select shows that there is data to read on an ICE connection. For further information, see the Inter-Client Exchange Library standard. +As previously discussed (section 3, “Understanding SMlib's Dependence on ICE”), the client will have to keep track of when ICE connections are created or destroyed (using IceAddConnectionWatch and IceRemoveConnectionWatch and will have to call IceProcessMessages each time a select shows that there is data to read on an ICE connection. For further information, see the Inter-Client Exchange Library standard. The callbacks argument contains a set of callbacks used to respond to session manager events. The mask argument specifies which callbacks are set. All of the callbacks specified in this version of SMlib are mandatory. The mask argument is necessary in order to maintain backwards compatibility in future versions of the library. @@ -270,28 +270,28 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - client_data + client_data Client data specified when the callback was registered. - save_type + save_type Specifies the type of information that should be saved. - shut_down + shut_down Specifies if a shutdown is taking place. - interact_style + interact_style The type of interaction allowed with the user. - fast - if True, then client should save its state as quickly as possible. + fast + if True, then client should save its state as quickly as possible. @@ -329,11 +329,11 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - client_data + client_data Client data specified when the callback was registered. @@ -357,11 +357,11 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - client_data + client_data Client data specified when the callback was registered. @@ -383,11 +383,11 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - client_data + client_data Client data specified when the callback was registered. @@ -410,15 +410,15 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - count + count The number of reasons for closing the connection. - reason_msgs + reason_msgs The reasons for closing the connection. @@ -454,15 +454,15 @@ typedef struct { The session management connection object. - smc_conn + smc_conn The session management connection object. - mask + mask A mask indicating which callbacks to modify. - callbacks + callbacks The new callbacks. @@ -493,15 +493,15 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - num_proprs + num_proprs The number of properties. - props + props The list of properties to set. @@ -524,15 +524,15 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - num_proprs + num_proprs The number of properties. - prop_names + prop_names The list of properties to set. @@ -550,15 +550,15 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - prop_reply_proc + prop_reply_proc The callback to be invoked when the properties reply comes back. - client_data + client_data This pointer to client data will be passed to the SmcPropReplyProc callback. @@ -579,19 +579,19 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - client_data + client_data This pointer to client data will be passed to the SmcPropReplyProc callback. - num_props + num_props The number of properties returned. - props + props The list of properties returned. @@ -616,19 +616,19 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - dialog_type + dialog_type The type of dialog the client wishes to present to the user. - interact_proc + interact_proc The callback to be invoked when the “Interact” message arrives from the session manager. - client_data + client_data This pointer to client data will be passed to the SmcInteractProc callback when the “Interact” message arrives. @@ -651,11 +651,11 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - client_data + client_data Client data specified when the callback was registered. @@ -672,11 +672,11 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - cancel_shutdown + cancel_shutdown If True, indicates that the user requests that the entire shutdown be cancelled. @@ -703,34 +703,34 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - save_type + save_type Specifies the type of information that should be saved. - shutdown + shutdown Specifies if a shutdown is taking place. - interact_style + interact_style The type of interaction allowed with the user. - fast + fast If True the client should save its state as quickly as possible. - global + global Controls who gets the “Save Yourself.” The save_type, shutdown, interact_style, and fast arguments are discussed in more detail in section 5.1.1, “The Save Yourself Callback.” -If global is set to True then the resulting “Save Yourself” should be sent to all clients in the session. For example, a vendor of a Uninterruptible Power Supply (UPS) might include a Session Management client that would monitor the status of the UPS and generate a fast shutdown if the power is about to be lost. +If global is set to True then the resulting “Save Yourself” should be sent to all clients in the session. For example, a vendor of a Uninterruptible Power Supply (UPS) might include a Session Management client that would monitor the status of the UPS and generate a fast shutdown if the power is about to be lost. If global is set to False then the “Save Yourself” should only be sent to the client that requested it. @@ -751,15 +751,15 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - save_type_phase2_proc + save_type_phase2_proc The callback to be invoked when the “Save Yourself Phase 2” message arrives from the session manager. - client_data + client_data This pointer to client data will be passed to the SmcSaveYourselfPhase2Proc callback when the “Save Yourself Phase 2” message arrives. @@ -784,11 +784,11 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - success + success If True the “Save Yourself” operation was completed successfully. @@ -852,7 +852,7 @@ typedef struct { -SmcGetIceConnection returns the ICE connection object associated with this session management connection object. The ICE connection object can be used to get some additional information about the connection. Some of the more useful functions which can be used on the IceConn are IceConnectionNumber IceConnectionString IceLastSentSequenceNumber IceLastReceivedSequenceNumber and IcePing For further information, see the Inter-Client Exchange Library standard. +SmcGetIceConnection returns the ICE connection object associated with this session management connection object. The ICE connection object can be used to get some additional information about the connection. Some of the more useful functions which can be used on the IceConn are IceConnectionNumber IceConnectionString IceLastSentSequenceNumber IceLastReceivedSequenceNumber and IcePing For further information, see the Inter-Client Exchange Library standard. @@ -888,41 +888,41 @@ typedef struct { - smc_conn + smc_conn The session management connection object. - swap + swap A flag that indicates if the specified values need byte swapping. - offending_minor_opcode + offending_minor_opcode The minor opcode of the offending message. - offending_sequence_num + offending_sequence_num The sequence number of the offending message. - error_class + error_class The error class of the offending message. - severity + severity IceCanContinueIceFatalToProtocol or IceFatalToConnection - values + values Any additional error values specific to the minor opcode and class. -Note that this error handler is invoked for protocol related errors. To install an error handler to be invoked when an IO error occurs, use IceSetIOErrorHandler For further information, see the Inter-Client Exchange Library standard. +Note that this error handler is invoked for protocol related errors. To install an error handler to be invoked when an IO error occurs, use IceSetIOErrorHandler For further information, see the Inter-Client Exchange Library standard. -Session Management Server (Sms) Functions +Session Management Server (<acronym>Sms</acronym>) Functions This section discusses how Session Management servers: @@ -964,38 +964,38 @@ typedef struct { - vendor + vendor A string specifying the session manager vendor. - release + release A string specifying the session manager release number. - new_client_proc + new_client_proc Callback to be invoked each time a new client connects to the session manager. - manager_data + manager_data When the SmsNewClientProc callback is invoked, this pointer to manager data will be passed. - host_based_auth_proc + host_based_auth_proc Host based authentication callback. - error_length + error_length Length of the error_string_ret argument passed in. - error_string_ret + error_string_ret Returns a null-terminated error message, if any. The error_string_ret points to user supplied memory. No more than error_length bytes are used. After the SmsInitialize function is called, the session manager should call the IceListenForConnections function to listen for new connections. Afterwards, each time a client connects, the session manager should call IceAcceptConnection -See section 9, “Authentication of Clients,” for more details on authentication (including host based authentication). Also see the Inter-Client Exchange Library standard for further details on listening for and accepting ICE connections. +See section 9, “Authentication of Clients,” for more details on authentication (including host based authentication). Also see the Inter-Client Exchange Library standard for further details on listening for and accepting ICE connections. Each time a new client connects to the session manager, the SmsNewClientProc callback is invoked. The session manager obtains a new opaque connection object that it should use for all future interaction with the client. At this time, the session manager must also register a set of callbacks to respond to the different messages that the client might send. @@ -1012,23 +1012,23 @@ typedef struct { - sms_conn + sms_conn A new opaque connection object. - manager_data + manager_data Manager data specified when the callback was registered. - mask_ret + mask_ret On return, indicates which callbacks were set by the session manager. - callbacks_ret + callbacks_ret On return, contains the callbacks registered by the session manager. - failure_reason_ret + failure_reason_ret Failure reason returned. @@ -1125,15 +1125,15 @@ typedef struct { - sms_conn + sms_conn The session management connection object. - manager_data + manager_data Manager data specified when the callback was registered. - previous_id + previous_id The client ID from the previous session. @@ -1164,15 +1164,15 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - manager_data + manager_data Manager data specified when the callback was registered. - dialog_type + dialog_type The type of dialog the client wishes to present to the user. @@ -1200,15 +1200,15 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - manager_data + manager_data Manager data specified when the callback was registered. - cancel_shutdown + cancel_shutdown Specifies if the user requests that the entire shutdown be cancelled. @@ -1239,31 +1239,31 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - manager_data + manager_data Manager data specified when the callback was registered. - save_type + save_type Specifies the type of information that should be saved. - shutdown + shutdown Specifies if a shutdown is taking place. - interact_style + interact_style The type of interaction allowed with the user. - fast + fast If True the client should save its state as quickly as possible. - global + global Controls who gets the “Save Yourself.” @@ -1288,11 +1288,11 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - manager_data + manager_data Manager data specified when the callback was registered. @@ -1316,15 +1316,15 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - manager_data + manager_data Manager data specified when the callback was registered. - success + success If True the Save Yourself operation was completed successfully. @@ -1348,19 +1348,19 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - manager_data + manager_data Manager data specified when the callback was registered. - count + count The number of reason messages. - reason_msgs + reason_msgs The reasons for closing the connection. @@ -1386,19 +1386,19 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - manager_data + manager_data Manager data specified when the callback was registered. - num_props + num_props The number of properties. - props + props The list of properties to set. @@ -1427,19 +1427,19 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - manager_data + manager_data Manager data specified when the callback was registered. - num_props + num_props The number of properties. - prop_names + prop_names The list of properties to delete. @@ -1462,11 +1462,11 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - manager_data + manager_data Manager data specified when the callback was registered. @@ -1489,11 +1489,11 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - client_id + client_id A null-terminated string representing a unique client ID. @@ -1517,7 +1517,7 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. @@ -1543,23 +1543,23 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - save_type + save_type Specifies the type of information that should be saved. - shutdown + shutdown Specifies if a shutdown is taking place. - interact_style + interact_style The type of interaction allowed with the user. - fast + fast If True the client should save its state as quickly as possible. @@ -1590,7 +1590,7 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. @@ -1612,7 +1612,7 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. @@ -1636,7 +1636,7 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. @@ -1658,7 +1658,7 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. @@ -1680,7 +1680,7 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. @@ -1705,15 +1705,15 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - num_props + num_props The number of properties. - props + props The list of properties to return to the client. @@ -1738,15 +1738,15 @@ If the client is first joining the session, previous_id will be NULL. - ice_conn + ice_conn A valid ICE connection object. - ping_reply_proc + ping_reply_proc The callback to invoke when the Ping reply arrives. - client_data + client_data This pointer will be passed to the IcePingReplyProc callback. @@ -1764,11 +1764,11 @@ If the client is first joining the session, previous_id will be NULL. - ice_conn + ice_conn A valid ICE connection object. - client_data + client_data The client data specified in the call to IcePing @@ -1788,7 +1788,7 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. @@ -1835,7 +1835,7 @@ If the client is first joining the session, previous_id will be NULL. -The string returned is of the form protocol/hostname, where protocol is one of {tcp, decnet, local}. You should call free on the string returned when it is no longer needed. +The string returned is of the form protocol/hostname, where protocol is one of {tcp, decnet, local}. You should call free on the string returned when it is no longer needed. @@ -1844,7 +1844,7 @@ If the client is first joining the session, previous_id will be NULL. -SmsGetIceConnection returns the ICE connection object associated with this session management connection object. The ICE connection object can be used to get some additional information about the connection. Some of the more useful functions which can be used on the IceConn are IceConnectionNumber and IceLastSequenceNumber For further information, see the Inter-Client Exchange Library standard. +SmsGetIceConnection returns the ICE connection object associated with this session management connection object. The ICE connection object can be used to get some additional information about the connection. Some of the more useful functions which can be used on the IceConn are IceConnectionNumber and IceLastSequenceNumber For further information, see the Inter-Client Exchange Library standard. @@ -1877,36 +1877,36 @@ If the client is first joining the session, previous_id will be NULL. - sms_conn + sms_conn The session management connection object. - swap + swap A flag which indicates if the specified values need byte swapping. - offending_minor_opcode + offending_minor_opcode The minor opcode of the offending message. - offending_sequence_num + offending_sequence_num The sequence number of the offending message. - error_class + error_class The error class of the offending message. - severity + severity IceCanContinueIceFatalToProtocol or IceFatalToConnection - values + values Any additional error values specific to the minor opcode and class. -Note that this error handler is invoked for protocol related errors. To install an error handler to be invoked when an IO error occurs, use IceSetIOErrorHandler For further information, see the Inter-Client Exchange Library standard. +Note that this error handler is invoked for protocol related errors. To install an error handler to be invoked when an IO error occurs, use IceSetIOErrorHandler For further information, see the Inter-Client Exchange Library standard. @@ -1943,7 +1943,7 @@ typedef struct { Name Type - POSIX Type + POSIX Type Required @@ -2091,7 +2091,7 @@ typedef struct { - prop + prop The property to free. @@ -2108,11 +2108,11 @@ typedef struct { - count + count The number of reason strings. - reasons + reasons The list of reason strings to free. @@ -2129,13 +2129,13 @@ typedef struct { The authentication methods that are available are implementation-dependent -(that is., dependent on the ICElib and SMlib implementations in use). For further information, see the Inter-Client Exchange Library standard. +(that is., dependent on the ICElib and SMlib implementations in use). For further information, see the Inter-Client Exchange Library standard. Working in a Multi-Threaded Environment -To declare that multiple threads in an application will be using SMlib (or any other library layered on top of ICElib), you should call IceInitThreads For further information, see the Inter-Client Exchange Library standard. +To declare that multiple threads in an application will be using SMlib (or any other library layered on top of ICElib), you should call IceInitThreads For further information, see the Inter-Client Exchange Library standard. -- cgit v1.2.3