From 79c785adf86ef06f09910b68019bc8a1e6fcb122 Mon Sep 17 00:00:00 2001 From: Matt Dew Date: Tue, 4 Oct 2011 22:42:05 -0600 Subject: Cleanup IDs and links in doc 1 - fix the capitalization of the ID attributes to match either the or <funcdef> string it goes with. 2 - fix any <linkend>'s that were affected by 1. 3 - any <function> in the docs that has an actual funcdef, will become an olink. Signed-off-by: Matt Dew <marcoz@osource.org> --- doc/SMlib.xml | 551 +++++++++++++++++++++++++++++----------------------------- doc/xsmp.xml | 40 ++--- 2 files changed, 296 insertions(+), 295 deletions(-) diff --git a/doc/SMlib.xml b/doc/SMlib.xml index d3a5c8d..7577492 100644 --- a/doc/SMlib.xml +++ b/doc/SMlib.xml @@ -65,7 +65,7 @@ X Window System is a trademark of The Open Group. </bookinfo> -<chapter id="overview_of_session_management"> +<chapter id='Overview_of_Session_Management'> <title>Overview of Session Management @@ -97,7 +97,7 @@ displays at all. - + The Session Management Library @@ -150,7 +150,7 @@ chance to interact with the user and cancel the shutdown. - + Understanding SMlib's Dependence on ICE @@ -164,8 +164,8 @@ 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 +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 @@ -178,7 +178,7 @@ have some code that detects when there is data to read on an ICE connection. This can be done via a select call on the file descriptor for the ICE connection, but more typically, XtAppAddInput will be used to register -a callback that will invoke IceProcessMessages +a callback that will invoke IceProcessMessages each time there is data to read on the ICE connection. @@ -186,9 +186,9 @@ each time there is data to read on the ICE connection. To further complicate things, knowing which file descriptors to call select on requires an understanding of how ICE connections are created. On the client side, a call must be made -to SmcOpenConnection in order to open a connection -with a session manager. SmcOpenConnection will -internally makea call into IceOpenConnection +to in order to open a connection +with a session manager. will +internally makea call into IceOpenConnection which will, in turn, determine if an ICE connection already exists between the client and session manager. Most likely, a connection will not already exist and a new ICE connection will be created. The @@ -205,9 +205,9 @@ the list of descriptors to call select on. 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 +call IceListenForConnections in order to start listening for connections from clients. Once a connection attempt is -detected, IceAcceptConnection must be called, and +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. @@ -220,7 +220,7 @@ standard. - + Header Files and Library Name @@ -239,7 +239,7 @@ SMlib and ICElib by using - + Session Management Client (<acronym>Smc</acronym>) Functions @@ -258,15 +258,15 @@ SMlib and ICElib by using - - Connecting to the Session Manager + +Connecting to the Session Manager To open a connection with a session manager, -use SmcOpenConnection +use - + SmcConn SmcOpenConnection char *network_ids_list @@ -381,7 +381,7 @@ an attempt will be made using the second network ID, and so on. -After the connection is established, SmcOpenConnection +After the connection is established, registers the client with the session manager. If the client is being restarted from a previous session, previous_id should contain a null terminated string representing the client ID from the @@ -393,12 +393,12 @@ client with previous_id set to NULL. -If SmcOpenConnection succeeds, it returns an +If succeeds, it returns an opaque connection pointer of type SmcConn and the client_id_ret argument contains the client ID to be used for this session. The client_id_ret should be freed with a call to free when no longer needed. On -failure, SmcOpenConnection returns +failure, returns NULL, and the reason for failure is returned in error_string_ret. @@ -421,12 +421,12 @@ context associated with it. As previously discussed -(section 3, +(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 +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 @@ -486,14 +486,14 @@ typedef struct { } SmcCallbacks; - - The Save Yourself Callback + +The Save Yourself Callback The Save Yourself callback is of type SmcSaveYourselfProc - + typedef void (*SaveYourselfProc) SmcConn smc_conn @@ -536,9 +536,9 @@ The Save Yourself callback is of type SmcSaveYourselfProc The session manager sends a “Save Yourself” message to a client either to checkpoint it or just before termination so that it can save its state. The client responds with zero or more calls -to SmcSetProperties to update the properties +to to update the properties indicating how to restart the client. When all the properties have -been set, the client calls SmcSaveYourselfDone +been set, the client calls @@ -552,13 +552,13 @@ If interact_style is SmInteractStyleAny then the client may interact with the user for any purpose. Because only one client can interact with the user at a time, the client must -call SmcInteractRequest and wait for an +call and wait for an “Interact” message from the session manager. When the client is done interacting with the user, it -calls SmcInteractDone The client may only -call SmcInteractRequest after it receives a +calls The client may only +call after it receives a “Save Yourself” message and before it -calls SmcSaveYourselfDone +calls @@ -621,14 +621,14 @@ set fast to True. - - The Die Callback + +The Die Callback -The Die callback is of type SmcDieProc +The Die callback is of type - + typedef void (*SmcDieProc) SmcConn smc_conn @@ -651,20 +651,20 @@ The Die callback is of type SmcDieProc The session manager sends a “Die” message to a client when it wants it to die. The client should respond by calling -SmcCloseConnection. A session manager that +. A session manager that behaves properly will send a “Save Yourself” message before the “Die” message. - - The Save Complete Callback + +The Save Complete Callback -The Save Complete callback is of type SmcSaveCompleteProc +The Save Complete callback is of type - + typedef void (*SmcSaveCompleteProc) SmcConn smc_conn @@ -685,15 +685,15 @@ The Save Complete callback is of type SmcSaveCompleteProc - - The Shutdown Cancelled Callback + +The Shutdown Cancelled Callback The Shutdown Cancelled callback is of type -SmcShutdownCancelledProc + - + typedef void (*SmcShutdownCancelledProc) SmcConn smc_conn @@ -715,27 +715,28 @@ The Shutdown Cancelled callback is of type The session manager sends a “Shutdown Cancelled” message when the user cancelled the shutdown during an interaction -(see section 5.5, +(see section 5.5, “Interacting With the User”). The client can now continue as if the shutdown had never happened. If the client has not -called SmcSaveYourselfDone yet, it can either -abort the save and then call SmcSaveYourselfDone +called yet, it can either +abort the save and then call with the success argument set to False or it can -continue with the save and then call SmcSaveYourselfDone +continue with the save and then call with the success argument set to reflect the outcome of the save. - Closing the Connection + +Closing the Connection To close a connection with a session manager, -use SmcCloseConnection +use - + SmcCloseStatus SmcCloseConnection SmcConn smc_conn @@ -770,11 +771,11 @@ display these reason messages to the user. Note that SMlib used the ICE protocol to establish a connection with the session manager, and various protocols other than session management may be active on the ICE connection. -When SmcCloseConnection is called, the ICE +When is called, the ICE connection will be closed only if all protocols have been shutdown on the connection. Check the ICElib standard -for IceAddConnectionWatch -and IceRemoveConnectionWatch to learn how to set +for IceAddConnectionWatch +and IceRemoveConnectionWatch to learn how to set up a callback to be invoked each time an ICE connection is opened or closed. Typically this callback adds/removes the ICE file descriptor from the list of active descriptors to call select on @@ -784,7 +785,7 @@ from the list of active descriptors to call select on -SmcCloseConnection returns one of the following values: + returns one of the following values: @@ -793,11 +794,11 @@ this time, the watch procedures were invoked, and the connection was freed. SmcClosedASAP - an IO error had occurred on the -connection, but SmcCloseConnection is being -called within a nested IceProcessMessages The +connection, but is being +called within a nested IceProcessMessages The watch procedures have been invoked at this time, but the connection will be freed as soon as possible (when the nesting level reaches zero -and IceProcessMessages returns a status +and IceProcessMessages returns a status of IceProcessMessagesConnectionClosed @@ -809,15 +810,15 @@ this time, because it is being used by other active protocols. - - Modifying Callbacks + +Modifying Callbacks -To modify callbacks set up in SmcOpenConnection -use SmcModifyCallbacks +To modify callbacks set up in +use - + void SmcModifyCallbacks SmcConn smc_conn @@ -853,15 +854,15 @@ the following values may be ORed together: - - Setting, Deleting, and Retrieving Session Management Properties + +Setting, Deleting, and Retrieving Session Management Properties To set session management properties for this client, -use SmcSetProperties +use - + void SmcSetProperties SmcConn smc_conn @@ -889,7 +890,7 @@ use SmcSetProperties The properties are specified as an array of property pointers. Previously set property values may be over-written using -the SmcSetProperties function. Note that the +the function. Note that the session manager is not expected to restore property values when the session is restarted. Because of this, clients should not try to use the session manager as a database for storing application specific state. @@ -898,17 +899,17 @@ the session manager as a database for storing application specific state. For a description of session management properties and the SmProp structure, -see section 7, +see section 7, “Session Management Properties.” To delete properties previously set by the client, -use SmcDeleteProperties +use - + void SmcDeleteProperties SmcConn smc_conn @@ -933,10 +934,10 @@ use SmcDeleteProperties To get properties previously stored by the client, -use SmcGetProperties +use - + Status SmcGetProperties SmcConn smc_conn @@ -956,22 +957,22 @@ use SmcGetProperties client_data - This pointer to client data will be passed to the SmcPropReplyProc callback. + This pointer to client data will be passed to the callback. -The return value of SmcGetProperties is zero for +The return value of is zero for failure and a positive value for success. Note that the library does not block until the properties reply comes -back. Rather, a callback of type SmcPropReplyProc +back. Rather, a callback of type is invoked when the data is ready. - + typedef void (*SmcPropReplyProc) SmcConn smc_conn @@ -988,7 +989,7 @@ is invoked when the data is ready. client_data - This pointer to client data will be passed to the SmcPropReplyProc callback. + This pointer to client data will be passed to the callback. num_props @@ -1001,15 +1002,15 @@ is invoked when the data is ready. -To free each property, use SmFreeProperty -(see section 8, “Freeing +To free each property, use +(see section 8, “Freeing Data”). To free the actual array of pointers, use free - - Interacting With the User + +Interacting With the User After receiving a “Save Yourself” message with an @@ -1017,11 +1018,11 @@ After receiving a “Save Yourself” message with an SmInteractStyleErrors or SmInteractStyleAny the client may choose to interact with the user. Because only one client can interact with the -user at a time, the client must call SmcInteractRequest +user at a time, the client must call and wait for an “Interact” message from the session manager. - + Status SmcInteractRequest SmcConn smc_conn @@ -1048,14 +1049,14 @@ and wait for an “Interact” message from the session manager. client_data This pointer to client data will be passed to -the SmcInteractProc callback when the +the callback when the “Interact” message arrives. -The return value of SmcInteractRequest is zero +The return value of is zero for failure and a positive value for success. @@ -1075,11 +1076,11 @@ that have not interacted yet with the user will receive a -The SmcInteractProc callback will be invoked when +The callback will be invoked when the “Interact” message arrives from the session manager. - + typedef void (*SmcInteractProc) SmcConn smc_conn @@ -1100,10 +1101,10 @@ the “Interact” message arrives from the session manager. After interacting with the user (in response to an “Interact” -message), you should call SmcInteractDone +message), you should call - + void SmcInteractDone SmcConn smc_conn @@ -1131,15 +1132,15 @@ the interact_style. - - Requesting a Save Yourself + +Requesting a Save Yourself To request a checkpoint from the session manager, -use SmcRequestSaveYourself +use - + void SmcRequestSaveYourself SmcConn smc_conn @@ -1183,7 +1184,7 @@ use SmcRequestSaveYourself The save_type, shutdown, interact_style, and fast arguments are discussed in more detail in -section 5.1.1, +section 5.1.1, “The Save Yourself Callback.” @@ -1202,16 +1203,16 @@ Yourself” should only be sent to the client that requested it. - - Requesting a Save Yourself Phase 2 + +Requesting a Save Yourself Phase 2 In response to a “Save Yourself”, the client may request to be informed when all the other clients are quiescent so that it can save their -state. To do so, use SmcRequestSaveYourselfPhase2 +state. To do so, use - + Status SmcRequestSaveYourselfPhase2 SmcConn smc_conn @@ -1236,7 +1237,7 @@ state. To do so, use SmcRequestSaveYourselfPhase2 -The return value of SmcRequestSaveYourselfPhase2 +The return value of is zero for failure and a positive value for success. @@ -1248,15 +1249,15 @@ an idle state so that their state can be saved. - - Completing a Save Yourself + +Completing a Save Yourself After saving state in response to a “Save Yourself” -message, you should call SmcSaveYourselfDone +message, you should call - + void SmcSaveYourselfDone SmcConn smc_conn @@ -1276,16 +1277,16 @@ message, you should call SmcSaveYourselfDone -Before calling SmcSaveYourselfDone the client +Before calling the client must have set each required property at least once since the client registered with the session manager. - - Using Smc Informational Functions + +Using Smc Informational Functions - + int SmcProtocolVersion SmcConn smc_conn @@ -1293,12 +1294,12 @@ registered with the session manager. -SmcProtocolVersion returns the major version of + returns the major version of the session management protocol associated with this session. - + int SmcProtocolRevision SmcConn smc_conn @@ -1306,11 +1307,11 @@ the session management protocol associated with this session. -SmcProtocolRevision returns the minor version of + returns the minor version of the session management protocol associated with this session. - + char *SmcVendor SmcConn smc_conn @@ -1318,12 +1319,12 @@ the session management protocol associated with this session. -SmcVendor returns a string that provides some + returns a string that provides some identification of the owner of the session manager. The string should be freed with a call to free - + char *SmcRelease SmcConn smc_conn @@ -1331,12 +1332,12 @@ be freed with a call to free -SmcRelease returns a string that provides the + returns a string that provides the release number of the session manager. The string should be freed with a call to free - + char *SmcClientID SmcConn smc_conn @@ -1344,14 +1345,14 @@ with a call to free -SmcClientID returns a null-terminated string for + returns a null-terminated string for the client ID associated with this connection. This information was -also returned in SmcOpenConnection (it is +also returned in (it is provided here for convenience). Call free on this pointer when the client ID is no longer needed. - + IceConn SmcGetIceConnection SmcConn smc_conn @@ -1359,22 +1360,22 @@ this pointer when the client ID is no longer needed. -SmcGetIceConnection returns the ICE connection + 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, +IceLastSentSequenceNumber, IceLastReceivedSequenceNumber, -and IcePing. For further information, see +and IcePing. For further information, see the Inter-Client Exchange Library standard. - - Error Handling + +Error Handling If the client receives an unexpected protocol error from the session @@ -1382,10 +1383,10 @@ manager, an error handler is invoked by SMlib. A default error handler exists that simply prints the error message to stderr and exits if the severity of the error is fatal. The client can change this error handler by calling -the SmcSetErrorHandler function. +the function. - + SmcErrorHandler SmcSetErrorHandler SmcErrorHandler handler @@ -1399,14 +1400,14 @@ restore the default handler. -SmcSetErrorHandler returns the previous error handler. + returns the previous error handler. -The SmcErrorHandler has the following type: +The has the following type: - + typedef void (*SmcErrorHandler) SmcConn smc_conn @@ -1456,14 +1457,14 @@ The SmcErrorHandler has the following type: 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 +IceSetIOErrorHandler For further information, see the Inter-Client Exchange Library standard. - + Session Management Server (<acronym>Sms</acronym>) Functions @@ -1486,17 +1487,17 @@ This section discusses how Session Management servers: - - Initializing the Library + +Initializing the Library -SmsInitialize is the first SMlib function that + is the first SMlib function that should be called by a session manager. It provides information about the session manager and registers a callback that will be invoked each time a new client connects to the session manager. - + Status SmsInitialize char *vendor @@ -1526,7 +1527,7 @@ time a new client connects to the session manager. manager_data - When the SmsNewClientProc callback is invoked, this pointer to manager data will be passed. + When the callback is invoked, this pointer to manager data will be passed. host_based_auth_proc @@ -1547,15 +1548,15 @@ No more than error_length bytes are used. -After the SmsInitialize function is called, the -session manager should call the IceListenForConnections +After the 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 +call IceAcceptConnection -See section 9, +See section 9, “Authentication of Clients,” for more details on authentication (including host based authentication). Also see the Inter-Client Exchange @@ -1565,14 +1566,14 @@ accepting ICE connections. Each time a new client connects to the session manager, -the SmsNewClientProc callback is invoked. The +the 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. - + typedef Status (*SmsNewClientProc) SmsConn sms_conn @@ -1607,7 +1608,7 @@ the different messages that the client might send. -If a failure occurs, the SmsNewClientProc should +If a failure occurs, the should return a zero status as well as allocate and return a failure reason string in failure_reason_ret. SMlib will be responsible for freeing this memory. @@ -1700,16 +1701,16 @@ typedef struct { } SmsCallbacks; - - The Register Client Callback + +The Register Client Callback The Register Client callback is the first callback that will be invoked after the client connects to the session manager. Its type -is SmsRegisterClientProc +is - + typedef Status (*SmsRegisterClientProc) SmsConn sms_conn @@ -1756,22 +1757,22 @@ client should re-register with previous_id set to NULL. Otherwise, the session manager should register the client with a unique -client ID by calling the SmsRegisterClientReply +client ID by calling the function (to be discussed shortly), and the -SmsRegisterClientProc callback should return a + callback should return a status of one. - - The Interact Request Callback + +The Interact Request Callback The Interact Request callback is of -type SmsInteractRequestProc +type - + typedef void (*SmsInteractRequestProc) SmsConn sms_conn @@ -1824,15 +1825,15 @@ requested to interact. - - The Interact Done Callback + +The Interact Done Callback When the client is done interacting with the user, -the SmsInteractDoneProc callback will be invoked. +the callback will be invoked. - + typedef void (*SmsInteractDoneProc) SmsConn sms_conn @@ -1866,15 +1867,15 @@ or SmInteractStyleAny for the - - The Save Yourself Request Callback + +The Save Yourself Request Callback The Save Yourself Request callback is of type SmsSaveYourselfRequestProc - + typedef void (*SaveYourselfRequestProc) SmsConn sms_conn @@ -1923,7 +1924,7 @@ The Save Yourself Request prompts the session manager to initiate a checkpoint or shutdown. For information on the save_type, shutdown, interact_style, and fast -arguments, see section 6.3, +arguments, see section 6.3, “Sending a Save Yourself Message.” @@ -1935,15 +1936,15 @@ If global is set to False then the - - The Save Yourself Phase 2 Request Callback + +The Save Yourself Phase 2 Request Callback The Save Yourself Phase 2 Request callback is of -type SmsSaveYourselfPhase2RequestProc +type - + typedef void (*SmsSaveYourselfPhase2RequestProc) SmsConn sms_conn @@ -1970,8 +1971,8 @@ are in an idle state so that their state can be saved. - - The Save Yourself Done Callback + +The Save Yourself Done Callback When the client is done saving its state in response to a @@ -1979,7 +1980,7 @@ When the client is done saving its state in response to a the SmsSaveYourselfDoneProc will be invoked. - + typedef void (*SaveYourselfDoneProc) SmsConn sms_conn @@ -2010,16 +2011,16 @@ the session manager. - - The Connection Closed Callback + +The Connection Closed Callback If the client properly terminates (that is, it -calls SmcCloseConnection, -the SmsCloseConnectionProc callback is invoked. +calls , +the callback is invoked. - + typedef void (*SmsCloseConnectionProc) SmsConn sms_conn @@ -2058,21 +2059,21 @@ display these reason messages to the user. -Call SmFreeReasons to free the reason messages. +Call to free the reason messages. For further information, see -section 8, “Freeing Data” +section 8, “Freeing Data” - - The Set Properties Callback + +The Set Properties Callback When the client sets session management properties, -the SmsSetPropertiesProc callback will be invoked. +the callback will be invoked. - + typedef void (*SmsSetPropertiesProc) SmsConn sms_conn @@ -2105,7 +2106,7 @@ the SmsSetPropertiesProc callback will be invoked. The properties are specified as an array of property pointers. For a description of session management properties and the SmProp structure, -see section 7, +see section 7, “Session Management Properties.” @@ -2116,22 +2117,22 @@ nonpredefined properties. -To free each property, use SmFreeProperty. -For further information, see section 8, +To free each property, use . +For further information, see section 8, “Freeing Data” You should free the actual array of pointers with a call to free - - The Delete Properties Callback + +The Delete Properties Callback When the client deletes session management properties, -the SmsDeletePropertiesProc callback will be invoked. +the callback will be invoked. - + typedef void (*SmsDeletePropertiesProc) SmsConn sms_conn @@ -2164,20 +2165,20 @@ the SmsDeletePropertiesProc callback will be invoked. The properties are specified as an array of strings. For a description of session management properties and the SmProp structure, -see section 7, +see section 7, “Session Management Properties.” - - The Get Properties Callback + +The Get Properties Callback -The SmsGetPropertiesProc callback is invoked when +The callback is invoked when the client wants to retrieve properties it set. - + typedef void (*SmsGetPropertiesProc) SmsConn sms_conn @@ -2198,22 +2199,22 @@ the client wants to retrieve properties it set. The session manager should respond by -calling SmsReturnProperties. +calling . All of the properties set for this client should be returned. - - Registering the Client + +Registering the Client To register a client (in response to -a SmsRegisterClientProc callback), -use SmsRegisterClientReply. +a callback), +use . - + Status SmsRegisterClientReply SmsConn sms_conn @@ -2233,7 +2234,7 @@ use SmsRegisterClientReply. -The return value of SmsRegisterClientReply is +The return value of is zero for failure and a positive value for success. Failure will occur if SMlib can not allocate memory to hold a copy of the client ID for it's own internal needs. @@ -2268,11 +2269,11 @@ unique. -You should call the SmsGenerateClientID function +You should call the function to generate a globally unique client ID. - + char *SmsGenerateClientID SmsConn sms_conn @@ -2295,15 +2296,15 @@ no longer needed. - - Sending a Save Yourself Message + +Sending a Save Yourself Message To send a “Save Yourself” to a client, -use SmsSaveYourself. +use . - + void SmsSaveYourself SmsConn sms_conn @@ -2398,15 +2399,15 @@ to True. - - Sending a Save Yourself Phase 2 Message + +Sending a Save Yourself Phase 2 Message In order to send a “Save Yourself Phase 2” message to a -client, use SmsSaveYourselfPhase2 +client, use - + void SmsSaveYourselfPhase2 SmsConn sms_conn @@ -2428,15 +2429,15 @@ and this client can save state that is associated with other clients. - - Sending an Interact Message + +Sending an Interact Message To send an “Interact” message to a client, -use SmsInteract. +use . - + void SmsInteract SmsConn sms_conn @@ -2458,15 +2459,15 @@ session manager. - - Sending a Save Complete Message + +Sending a Save Complete Message To send a “Save Complete” message to a client, -use SmsSaveComplete. +use . - + void SmsSaveComplete SmsConn sms_conn @@ -2486,15 +2487,15 @@ checkpoint. The client is then free to change its state. - - Sending a Die Message + +Sending a Die Message To send a “Die” message to a client, -use SmsDie. +use . - + void SmsDie SmsConn sms_conn @@ -2515,14 +2516,14 @@ a “Die” message to, timing out appropriately. - - Cancelling a Shutdown + +Cancelling a Shutdown -To cancel a shutdown, use SmsShutdownCancelled. +To cancel a shutdown, use . - + void SmsShutdownCancelled SmsConn sms_conn @@ -2548,15 +2549,15 @@ of the save. - - Returning Properties + +Returning Properties In response to a “Get Properties” message, the session -manager should call SmsReturnProperties. +manager should call . - + void SmsReturnProperties SmsConn sms_conn @@ -2584,25 +2585,25 @@ manager should call SmsReturnProperties. The properties are returned as an array of property pointers. For a description of session management properties and the SmProp structure, -see section 7, +see section 7, “Session Management Properties.” - - Pinging a Client + +Pinging a Client To check that a client is still alive, you should use -the IcePing function provided by the ICE library. +the IcePing function provided by the ICE library. To do so, the ICE connection must be obtained using -the SmsGetIceConnection -(see section 6.12, +the +(see section 6.12, “Using Sms Informational Functions”). - + void IcePing IceConn ice_conn @@ -2622,19 +2623,19 @@ the SmsGetIceConnection client_data - This pointer will be passed to the IcePingReplyProc callback. + This pointer will be passed to the callback. When the Ping reply is ready (if ever), -the IcePingReplyProc callback will be invoked. A +the callback will be invoked. A session manager should have some sort of timeout period, after which it assumes the client has unexpectedly died. - + typedef void (*IcePingReplyProc) IceConn ice_conn @@ -2649,23 +2650,23 @@ it assumes the client has unexpectedly died. client_data - The client data specified in the call to IcePing + The client data specified in the call to IcePing - - Cleaning Up After a Client Disconnects + +Cleaning Up After a Client Disconnects When the session manager receives a “Connection Closed” message or otherwise detects that the client aborted the connection, -it should call the SmsCleanUp function in order +it should call the function in order to free up the connection object. - + void SmsCleanUp SmsConn sms_conn @@ -2681,10 +2682,10 @@ to free up the connection object. - - Using Sms Informational Functions + +Using Sms Informational Functions - + int SmsProtocolVersion SmsConn sms_conn @@ -2692,11 +2693,11 @@ to free up the connection object. -SmsProtocolVersion returns the major version of + returns the major version of the session management protocol associated with this session. - + int SmsProtocolRevision SmsConn sms_conn @@ -2704,11 +2705,11 @@ the session management protocol associated with this session. -SmsProtocolRevision returns the minor version of + returns the minor version of the session management protocol associated with this session. - + char *SmsClientID SmsConn sms_conn @@ -2716,7 +2717,7 @@ the session management protocol associated with this session. -SmsClientID returns a null-terminated string for + returns a null-terminated string for the client ID associated with this connection. You should call free on this pointer when the client ID is no longer needed. @@ -2725,11 +2726,11 @@ no longer needed. To obtain the host name of a client, -use SmsClientHostName. +use . This host name will be needed to restart the client. - + char *SmsClientHostName SmsConn sms_conn @@ -2745,7 +2746,7 @@ You should call free on the string returned when it is no longer needed. - + IceConn SmsGetIceConnection SmsConn sms_conn @@ -2753,7 +2754,7 @@ it is no longer needed. -SmsGetIceConnection returns the ICE connection + 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 @@ -2765,18 +2766,18 @@ standard. - - Error Handling + +Error Handling If the session manager receives an unexpected protocol error from a client, an error handler is invoked by SMlib. A default error handler exists which simply prints the error message (it does not exit). The session manager can change this error handler by -calling SmsSetErrorHandler. +calling . - + SmsErrorHandler SmsSetErrorHandler SmsErrorHandler handler @@ -2789,11 +2790,11 @@ to restore the default handler. -SmsSetErrorHandler returns the previous error handler. -The SmsErrorHandler has the following type: + returns the previous error handler. +The has the following type: - + typedef void (*SmsErrorHandler) SmsConn sms_conn @@ -2844,7 +2845,7 @@ The SmsErrorHandler has the following type: 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. +use IceSetIOErrorHandler. For further information, see the Inter-Client Exchange Library standard. @@ -2852,7 +2853,7 @@ standard. - + Session Management Properties @@ -3135,14 +3136,14 @@ contain the user's name (the pw_name member of - + Freeing Data -To free an individual property, use SmFreeProperty +To free an individual property, use - + void SmFreeProperty SmProp *prop @@ -3158,11 +3159,11 @@ To free an individual property, use SmFreeProperty To free the reason strings from -the SmsCloseConnectionProc callback, -use SmFreeReasons +the callback, +use - + void SmFreeReasons int count @@ -3182,7 +3183,7 @@ use SmFreeReasons - + Authentication of Clients @@ -3204,7 +3205,7 @@ standard. - + Working in a Multi-Threaded Environment @@ -3217,7 +3218,7 @@ standard. - + Acknowledgements diff --git a/doc/xsmp.xml b/doc/xsmp.xml index b42621e..139e035 100644 --- a/doc/xsmp.xml +++ b/doc/xsmp.xml @@ -75,7 +75,7 @@ top of the X.Org ICE protocol. - + Acknowledgments @@ -87,7 +87,7 @@ and Bob Scheifler. - + Definitions and Goals @@ -124,7 +124,7 @@ relies on the ICE protocol to handle connection management an - + Overview of the Protocol @@ -230,7 +230,7 @@ no properties set. - + Data Types @@ -307,7 +307,7 @@ the receiver of the message to the sender of the message. - + Protocol Setup and Message Format @@ -322,7 +322,7 @@ message this message contains. - + Client Identification String A client ID is a string of XPCS characters encoded in ISO Latin 1 (ISO @@ -400,7 +400,7 @@ any user, session manager, and machine will be different from any other. - + Protocol The protocol consists of a sequence of messages as described below. @@ -454,7 +454,7 @@ for this client. If the client had specified an ID in the specified ID. If previous-ID was null, client-ID will be a unique ID freshly generated by the SM. The client-ID format is specified in -section 6. +section 6. @@ -902,7 +902,7 @@ Sets the specified properties to the specified values. Existing properties not specified in the Set­Properties message are unaffected. Some properties have predefined semantics. -See section 11, +See section 11, “Predefined Properties.” @@ -947,7 +947,7 @@ message and includes the values of all the properties. - + Errors @@ -964,15 +964,15 @@ a BadState error message. - + State Diagrams These state diagrams are designed to cover all actions of both the client and the SM. - - Client State Diagram + +Client State Diagram @@ -1066,7 +1066,7 @@ client and the SM. client stops participating in session - + Session Manager State Diagram @@ -1164,10 +1164,10 @@ client and the SM. - + Protocol Encoding - - Types + +Types @@ -1363,8 +1363,8 @@ client and the SM. - - Messages + +Messages XSMP is a sub-protocol of ICE. The major opcode is assigned at run-time by ICE and is represented here @@ -1955,7 +1955,7 @@ manager. The session manager should supply this information in the - + Predefined Properties All property values are stored in a LISTofARRAY8. If the type of the -- cgit v1.2.1