From 12af18dd9a731a816e7b074bbecaa5549bfdba31 Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Sun, 24 Oct 2010 19:57:32 -0700 Subject: SMlib.xml: Tag function names, parameters, constant values, etc. Includes correcting tags on things that aren't functions as some stylesheets may add () after tagged items so we shouldn't use them for constants, variables, filenames, etc. Signed-off-by: Alan Coopersmith --- doc/SMlib.xml | 598 ++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 328 insertions(+), 270 deletions(-) diff --git a/doc/SMlib.xml b/doc/SMlib.xml index d49983c..a82f209 100644 --- a/doc/SMlib.xml +++ b/doc/SMlib.xml @@ -131,12 +131,12 @@ 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 +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 +client-ID should be saved as part of the SmRestartCommand so that the client will retain the same ID after it is restarted. @@ -224,16 +224,17 @@ standard. Applications (both session managers and clients) should include the -header file <X11/SM/SMlib.h>. This -header file defines all of the SMlib data structures and function -prototypes. SMlib.h includes the header file -<X11/SM/SM.h>, which defines all of -the SMlib constants. +header file <X11/SM/SMlib.h>. +This header file defines all of the SMlib data structures and function +prototypes. SMlib.h includes the +header file <X11/SM/SM.h>, +which defines all of the SMlib constants. Because SMlib is dependent on ICE, applications should link against -SMlib and ICElib by using -lSM -lICE +SMlib and ICElib by using + . @@ -288,8 +289,9 @@ use SmcOpenConnection context -A pointer to an opaque object or NULL. Used to determine if an ICE -connection can be shared (see below). +A pointer to an opaque object or NULL. Used to determine +if an ICE connection can be shared +(see below). @@ -302,7 +304,7 @@ The highest major version of the XSMP the application supports. xsmp_minor_rev The highest minor version of the XSMP the application supports (for -the specified xsmp_major_rev). +the specified xsmp_major_rev). @@ -326,22 +328,23 @@ messages from the session manager. error_length - Length of the error_string_ret argument passed in. + Length of the error_string_ret argument passed in. 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 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 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: @@ -379,22 +382,24 @@ an attempt will be made using the second network ID, and so on. After the connection is established, SmcOpenConnection 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 previous -session. If the client is first joining the session, previous_id -should be set to NULL. If previous_id is specified but is determined +restarted from a previous session, previous_id +should contain a null terminated string representing the client ID from the +previous session. If the client is first joining the session, +previous_id should be set to NULL. +If previous_id is specified but is determined to be invalid by the session manager, SMlib will re-register the -client with previous_id set to NULL. +client with previous_id set to NULL. If SmcOpenConnection 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 NULL, and the -reason for failure is returned in error_string_ret. +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 +NULL, and the reason for failure is returned in +error_string_ret. @@ -406,10 +411,11 @@ connection to be used for session management. 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. +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. @@ -435,13 +441,14 @@ backwards compatibility in future versions of the library. -The following values may be ORed together to obtain a mask value: +The following values may be ORed together to obtain a +mask value: -SmcSaveYourselfProcMask -SmcDieProcMask -SmcSaveCompleteProcMask -SmcShutdownCancelledProcMask +SmcSaveYourselfProcMask +SmcDieProcMask +SmcSaveCompleteProcMask +SmcShutdownCancelledProcMask @@ -534,11 +541,14 @@ been set, the client calls SmcSaveYourselfDone -If interact_style is SmInteractStyleNone the -client must not interact with the user while saving state. If -interact_style is SmInteractStyleErrors the +If interact_style is +SmInteractStyleNone the +client must not interact with the user while saving state. +If interact_style is +SmInteractStyleErrors the client may interact with the user only if an error condition arises. -If interact_style is SmInteractStyleAny then the +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 @@ -551,13 +561,14 @@ calls SmcSaveYourselfDone -If save_type is SmSaveLocal the client must -update the properties to reflect its current state. Specifically, it -should save enough information to restore the state as seen by the -user of this client. It should not affect the state as seen by other -users. If save_type is SmSaveGlobal the user -wants the client to commit all of its data to permanent, globally -accessible storage. If save_type is SmSaveBoth +If save_type is SmSaveLocal the +client must update the properties to reflect its current state. Specifically, +it should save enough information to restore the state as seen by the +user of this client. It should not affect the state as seen by other users. +If save_type is SmSaveGlobal +the user wants the client to commit all of its data to permanent, globally +accessible storage. +If save_type is SmSaveBoth the client should do both of these (it should first commit the data to permanent storage before updating its properties). @@ -568,30 +579,32 @@ Some examples are as follows: If a word processor were sent a “Save Yourself” with a -type of SmSaveLocal it could create a temporary +type of SmSaveLocal it could create a temporary file that included the current contents of the file, the location of the cursor, and other aspects of the current editing session. It -would then update its SmRestartCommand property with enough -information to find this temporary file. +would then update its SmRestartCommand property with +enough information to find this temporary file. If a word processor were sent a “Save Yourself” with a -type of SmSaveGlobal it would simply save the +type of SmSaveGlobal it would simply save the currently edited file. If a word processor were sent a “Save Yourself” with a -type of SmSaveBoth it would first save the +type of SmSaveBoth it would first save the currently edited file. It would then create a temporary file with information such as the current position of the cursor and what file -is being edited. Finally, it would update its SmRestartCommand -property with enough information to find the temporary file. +is being edited. Finally, it would update its +SmRestartCommand property with enough information +to find the temporary file. -The shutdown argument specifies whether the system is being shut down. +The shutdown argument specifies whether the +system is being shut down. The interaction is different depending on whether or not shutdown is set. If not shutting down, the client should save its state and wait for a “Save Complete” message. If shutting down, the @@ -600,9 +613,10 @@ either a “Die” or a “Shutdown Cancelled.” -The fast argument specifies that the client should save its state as -quickly as possible. For example, if the session manager knows that -power is about to fail, it would set fast to True +The fast argument specifies that the client +should save its state as quickly as possible. For example, if the +session manager knows that power is about to fail, it would +set fast to True. @@ -705,9 +719,10 @@ when the user cancelled the shutdown during an interaction 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 -with the success argument set to False or it can +with the success argument set to False or it can continue with the save and then call SmcSaveYourselfDone -with the success argument set to reflect the outcome of the save. +with the success argument set to reflect the outcome +of the save. @@ -743,11 +758,11 @@ use SmcCloseConnection -The reason_msgs argument will most likely be NULL if resignation is -expected by the client. Otherwise, it contains a list of -null-terminated Compound Text strings representing the reason for -termination. The session manager should display these reason messages -to the user. +The reason_msgs argument will most likely be +NULL if resignation is expected by the client. +Otherwise, it contains a list of null-terminated Compound Text strings +representing the reason for termination. The session manager should +display these reason messages to the user. @@ -772,11 +787,11 @@ from the list of active descriptors to call select on -SmcClosedNow - the ICE connection was closed at +SmcClosedNow - the ICE connection was closed at this time, the watch procedures were invoked, and the connection was freed. -SmcClosedASAP - an IO error had occurred on the +SmcClosedASAP - an IO error had occurred on the connection, but SmcCloseConnection is being called within a nested IceProcessMessages The watch procedures have been invoked at this time, but the connection @@ -785,7 +800,7 @@ and IceProcessMessages returns a status of IceProcessMessagesConnectionClosed -SmcConnectionInUse - the connection was not closed at +SmcConnectionInUse - the connection was not closed at this time, because it is being used by other active protocols. @@ -825,14 +840,14 @@ use SmcModifyCallbacks -When specifying a value for the mask argument, the following values -may be ORed together: +When specifying a value for the mask argument, +the following values may be ORed together: -SmcSaveYourselfProcMask -SmcDieProcMask -SmcSaveCompleteProcMask -SmcShutdownCancelledProcMask +SmcSaveYourselfProcMask +SmcDieProcMask +SmcSaveCompleteProcMask +SmcShutdownCancelledProcMask @@ -860,7 +875,7 @@ use SmcSetProperties The session management connection object. - num_proprs + num_props The number of properties. @@ -881,7 +896,7 @@ the session manager as a database for storing application specific state. For a description of session management properties and -the SmProp structure, +the SmProp structure, see section 7, “Session Management Properties.” @@ -906,7 +921,7 @@ use SmcDeleteProperties The session management connection object. - num_proprs + num_props The number of properties. @@ -997,8 +1012,9 @@ use free After receiving a “Save Yourself” message with an -interact_style of SmInteractStyleErrors -or SmInteractStyleAny the client may choose to +interact_style of +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 and wait for an “Interact” message from the session manager. @@ -1043,9 +1059,9 @@ for failure and a positive value for success. -The dialog_type argument specifies -either SmDialogError indicating that the client -wants to start an error dialog, or SmDialogNormal +The dialog_type argument specifies +either SmDialogError indicating that the client +wants to start an error dialog, or SmDialogNormal meaning that the client wishes to start a nonerror dialog. @@ -1101,15 +1117,16 @@ message), you should call SmcInteractDone cancel_shutdown - If True, indicates that the user requests that the entire shutdown be cancelled. + If True, indicates that the user requests that the entire shutdown be cancelled. -The cancel_shutdown argument may only be True if -the corresponding “Save Yourself” -specified True for shutdown -and SmInteractStyleErrors -or SmInteractStyleAny for the interact_style. +The cancel_shutdown argument may only be +True if the corresponding “Save Yourself” +specified True for shutdown +and SmInteractStyleErrors +or SmInteractStyleAny for +the interact_style. @@ -1153,7 +1170,7 @@ use SmcRequestSaveYourself fast - If True the client should save its state as quickly as possible. + If True the client should save its state as quickly as possible. global @@ -1162,14 +1179,16 @@ use SmcRequestSaveYourself -The save_type, shutdown, interact_style, and fast arguments are discussed -in more detail in section 5.1.1, +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 +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 @@ -1177,7 +1196,7 @@ if the power is about to be lost. -If global is set to False then the “Save +If global is set to False then the “Save Yourself” should only be sent to the client that requested it. @@ -1251,7 +1270,7 @@ message, you should call SmcSaveYourselfDone success - If True the “Save Yourself” operation was completed successfully. + If True the “Save Yourself” operation was completed successfully. @@ -1292,7 +1311,7 @@ the session management protocol associated with this session. - char *SmcVendor + char *SmcVendor SmcConn smc_conn @@ -1305,7 +1324,7 @@ be freed with a call to free - char *SmcRelease + char *SmcRelease SmcConn smc_conn @@ -1318,7 +1337,7 @@ with a call to free - char *SmcClientID + char *SmcClientID SmcConn smc_conn @@ -1360,7 +1379,7 @@ standard. If the client receives an unexpected protocol error from the session 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 +to stderr and exits if the severity of the error is fatal. The client can change this error handler by calling the SmcSetErrorHandler function. @@ -1373,7 +1392,8 @@ the SmcSetErrorHandler function. -The error handler. You should pass NULL to restore the default handler. +The error handler. You should pass NULL to +restore the default handler. @@ -1421,7 +1441,10 @@ The SmcErrorHandler has the following type: severity - IceCanContinueIceFatalToProtocol or IceFatalToConnection + IceCanContinue, + IceFatalToProtocol, or + IceFatalToConnection + values @@ -1510,11 +1533,15 @@ time a new client connects to the session manager. error_length - Length of the error_string_ret argument passed in. + Length of the error_string_ret argument passed in. 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. + +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. + @@ -1581,32 +1608,33 @@ the different messages that the client might send. If a failure occurs, the SmsNewClientProc should return a zero status as well as allocate and return a failure reason -string in failure_reason_ret. +string in failure_reason_ret. SMlib will be responsible for freeing this memory. The session manager must register a set of callbacks to respond to -client events. The mask_ret argument specifies which callbacks are -set. All of the callbacks specified in this version of SMlib are -mandatory. The mask_ret argument is necessary in order to maintain -backwards compatibility in future versions of the library. +client events. The mask_ret argument specifies +which callbacks are set. All of the callbacks specified in this version of +SMlib are mandatory. The mask_ret argument is +necessary in order to maintain backwards compatibility in future versions +of the library. The following values may be ORed together to obtain a mask value: -SmsRegisterClientProcMask -SmsInteractRequestProcMask -SmsInteractDoneProcMask -SmsSaveYourselfRequestProcMask -SmsSaveYourselfP2RequestProcMask -SmsSaveYourselfDoneProcMask -SmsCloseConnectionProcMask -SmsSetPropertiesProcMask -SmsDeletePropertiesProcMask -SmsGetPropertiesProcMask +SmsRegisterClientProcMask +SmsInteractRequestProcMask +SmsInteractDoneProcMask +SmsSaveYourselfRequestProcMask +SmsSaveYourselfP2RequestProcMask +SmsSaveYourselfDoneProcMask +SmsCloseConnectionProcMask +SmsSetPropertiesProcMask +SmsDeletePropertiesProcMask +SmsGetPropertiesProcMask @@ -1710,18 +1738,19 @@ must be registered with the session manager. -If the client is being restarted from a previous session, previous_id -will contain a null-terminated string representing the client ID from -the previous session. Call free on the -previous_id pointer when it is no longer needed. If the client is -first joining the session, previous_id will be NULL. +If the client is being restarted from a previous session, +previous_id will contain a null-terminated string +representing the client ID from the previous session. +Call free on the previous_id +pointer when it is no longer needed. If the client is first joining the +session, previous_id will be NULL. -If previous_id is invalid, the session manager should not register the -client at this time. This callback should return a status of zero, -which will cause an error message to be sent to the client. The -client should re-register with previous_id set to NULL. +If previous_id is invalid, the session manager should +not register the client at this time. This callback should return a status +of zero, which will cause an error message to be sent to the client. The +client should re-register with previous_id set to NULL. @@ -1767,8 +1796,9 @@ type SmsInteractRequestProc When a client receives a “Save Yourself” message with an -interact_style of SmInteractStyleErrors -or SmInteractStyleAny the client may choose to +interact_style of +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 request to interact with the user. The session manager should keep a queue of all clients wishing to @@ -1778,9 +1808,9 @@ before continuing with the next client. -The dialog_type argument specifies -either SmDialogError indicating that the client -wants to start an error dialog, or SmDialogNormal +The dialog_type argument specifies +either SmDialogError indicating that the client +wants to start an error dialog, or SmDialogNormal meaning that the client wishes to start a nonerror dialog. @@ -1827,9 +1857,10 @@ the SmsInteractDoneProc callback will be invoked. Note that the shutdown can be cancelled only if the corresponding -“Save Yourself” specified True for -shutdown and SmInteractStyleErrors -or SmInteractStyleAny for the interact_style. +“Save Yourself” specified True for +shutdown and SmInteractStyleErrors +or SmInteractStyleAny for the +interact_style. @@ -1878,7 +1909,7 @@ type SmsSaveYourselfRequestProc fast - If True the client should save its state as quickly as possible. + If True the client should save its state as quickly as possible. global @@ -1888,17 +1919,18 @@ type SmsSaveYourselfRequestProc 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, +checkpoint or shutdown. For information on the +save_type, shutdown, +interact_style, and fast +arguments, see section 6.3, “Sending a Save Yourself Message.” -If global is set to True then the resulting -“Save Yourself” should be sent to all applications. If -global is set to False then the “Save -Yourself” should only be sent to the client that requested it. +If global is set to True then the +resulting “Save Yourself” should be sent to all applications. +If global is set to False then the +“Save Yourself” should only be sent to the client that requested it. @@ -1906,7 +1938,8 @@ Yourself” should only be sent to the client that requested it. The Save Yourself Phase 2 Request Callback -The Save Yourself Phase 2 Request callback is of type SmsSaveYourselfPhase2RequestProc +The Save Yourself Phase 2 Request callback is of +type SmsSaveYourselfPhase2RequestProc @@ -1965,7 +1998,7 @@ the SmsSaveYourselfDoneProc will be invoked. success - If True the Save Yourself operation was completed successfully. + If True the Save Yourself operation was completed successfully. @@ -1981,7 +2014,7 @@ the session manager. If the client properly terminates (that is, it -calls SmcCloseConnection +calls SmcCloseConnection, the SmsCloseConnectionProc callback is invoked. @@ -2015,7 +2048,8 @@ the SmsCloseConnectionProc callback is invoked. -The reason_msgs argument will most likely be NULL and the count +The reason_msgs argument will most likely +be NULL and the count argument zero (0) if resignation is expected by the user. Otherwise, it contains a list of null-terminated Compound Text strings representing the reason for termination. The session manager should @@ -2069,7 +2103,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, +the SmProp structure, see section 7, “Session Management Properties.” @@ -2128,7 +2162,7 @@ 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, +the SmProp structure, see section 7, “Session Management Properties.” @@ -2205,15 +2239,19 @@ it's own internal needs. -If a non-NULL previous_id was specified when the client registered -itself, client_id should be identical to previous_id. +If a non-NULL previous_id was +specified when the client registered itself, client_id +should be identical to previous_id. -Otherwise, client_id should be a unique ID freshly generated by the -session manager. In addition, the session manager should send a -“Save Yourself” message with type = Local, -shutdown = False, interact-style = None, and fast = False +Otherwise, client_id should be a unique ID freshly +generated by the session manager. In addition, the session manager should +send a “Save Yourself” message with +type = Local, +shutdown = False, +interact-style = None, +and fast = False immediately after registering the client. @@ -2235,7 +2273,7 @@ to generate a globally unique client ID. - char *SmsGenerateClientID + char *SmsGenerateClientID SmsConn sms_conn @@ -2249,7 +2287,7 @@ to generate a globally unique client ID. -NULL will be returned if the ID could not be generated. +NULL will be returned if the ID could not be generated. Otherwise, the return value of the function is the client ID. It should be freed with a call to free when no longer needed. @@ -2294,7 +2332,7 @@ use SmsSaveYourself. fast - If True the client should save its state as quickly as possible. + If True the client should save its state as quickly as possible. @@ -2309,11 +2347,14 @@ sends a “Save Yourself Done” message. -If interact_style is SmInteractStyleNone the -client must not interact with the user while saving state. If -interact_style is SmInteractStyleErrors the +If interact_style +is SmInteractStyleNone the +client must not interact with the user while saving state. +If interact_style +is SmInteractStyleErrors the client may interact with the user only if an error condition arises. -If interact_style is SmInteractStyleAny then the +If interact_style +is SmInteractStyleAny then the client may interact with the user for any purpose. The client must send an “Interact Request” message and wait for an “Interact” message from the session manager before it can @@ -2325,20 +2366,22 @@ Done.” -If save_type is SmSaveLocal the client must -update the properties to reflect its current state. Specifically, it -should save enough information to restore the state as seen by the -user of this client. It should not affect the state as seen by other -users. If save_type is SmSaveGlobal the user -wants the client to commit all of its data to permanent, globally -accessible storage. If save_type is SmSaveBoth +If save_type is SmSaveLocal +the client must update the properties to reflect its current state. +Specifically, it should save enough information to restore the state as +seen by the user of this client. It should not affect the state as seen +by other users. +If save_type is SmSaveGlobal +the user wants the client to commit all of its data to permanent, globally +accessible storage. +If save_type is SmSaveBoth the client should do both of these (it should first commit the data to permanent storage before updating its properties). -The shutdown argument specifies whether the session is being shut -down. The interaction is different depending on whether or not +The shutdown argument specifies whether the session +is being shut down. The interaction is different depending on whether or not shutdown is set. If not shutting down, then the client can save and resume normal operation. If shutting down, the client must save and then must prevent interaction until it receives either a @@ -2347,10 +2390,10 @@ anything the user does after the save will be lost. -The fast argument specifies that the client should save its state as -quickly as possible. For example, if the session manager knows that -power is about to fail, it should set fast -to True +The fast argument specifies that the client should +save its state as quickly as possible. For example, if the session manager +knows that power is about to fail, it should set fast +to True. @@ -2496,9 +2539,10 @@ To cancel a shutdown, use SmsShutdownCancelled. The client can now continue as if the shutdown had never happened. If the client has not sent a “Save Yourself Done” message yet, it can either abort the save and send a “Save Yourself -Done” with the success argument set to False +Done” with the success argument set to False or it can continue with the save and send a “Save Yourself Done” -with the success argument set to reflect the outcome of the save. +with the success argument set to reflect the outcome +of the save. @@ -2538,7 +2582,7 @@ 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, +the SmProp structure, see section 7, “Session Management Properties.” @@ -2665,7 +2709,7 @@ the session management protocol associated with this session. - char *SmsClientID + char *SmsClientID SmsConn sms_conn @@ -2686,7 +2730,7 @@ This host name will be needed to restart the client. - char *SmsClientHostName + char *SmsClientHostName SmsConn sms_conn @@ -2739,7 +2783,8 @@ calling SmsSetErrorHandler. -The error handler. You should pass NULL to restore the default handler. +The error handler. You should pass NULL +to restore the default handler. @@ -2783,7 +2828,11 @@ The SmsErrorHandler has the following type: severity - IceCanContinueIceFatalToProtocol or IceFatalToConnection + + IceCanContinue, + IceFatalToProtocol, or + IceFatalToConnection + values @@ -2806,7 +2855,7 @@ standard. Session Management Properties -Each property is defined by the SmProp structure: +Each property is defined by the SmProp structure: typedef struct { @@ -2831,9 +2880,9 @@ which ones are required. Each property has a type associated with it. -A type of SmCARD8 indicates that there is a single 1-byte value. -A type of SmARRAY8 indicates that there is a single array of bytes. -A type of SmLISTofARRAY8 indicates that there is a list of array of +A type of SmCARD8 indicates that there is a single 1-byte value. +A type of SmARRAY8 indicates that there is a single array of bytes. +A type of SmLISTofARRAY8 indicates that there is a list of array of bytes. @@ -2853,69 +2902,69 @@ bytes. - SmCloneCommand + SmCloneCommand OS-specific - SmLISTofARRAY8 + SmLISTofARRAY8 Yes - SmCurrentDirectory + SmCurrentDirectory OS-specific - SmARRAY8 + SmARRAY8 No - SmDiscardCommand + SmDiscardCommand OS-specific - SmLISTofARRAY8 + SmLISTofARRAY8 No* - SmEnvironment + SmEnvironment OS-specific - SmLISTofARRAY8 + SmLISTofARRAY8 No - SmProcessID + SmProcessID OS-specific - SmARRAY8 + SmARRAY8 No - SmProgram + SmProgram OS-specific - SmARRAY8 + SmARRAY8 Yes - SmRestartCommand + SmRestartCommand OS-specific - SmLISTofARRAY8 + SmLISTofARRAY8 Yes - SmResignCommand + SmResignCommand OS-specific - SmLISTofARRAY8 + SmLISTofARRAY8 No - SmRestartStyleHint - SmCARD8 - SmCARD8 + SmRestartStyleHint + SmCARD8 + SmCARD8 No - SmShutdownCommand + SmShutdownCommand OS-specific - SmLISTofARRAY8 + SmLISTofARRAY8 No - SmUserID - SmARRAY8 - SmARRAY8 + SmUserID + SmARRAY8 + SmARRAY8 Yes @@ -2928,72 +2977,78 @@ example, state file). - SmCloneCommand + SmCloneCommand -This is like the SmRestartCommand, except it restarts a copy of the -application. The only difference is that the application does not -supply its client ID at register time. On POSIX systems, this should -be of type SmLISTofARRAY8. +This is like the SmRestartCommand, except it restarts a +copy of the application. The only difference is that the application does not +supply its client ID at register time. On POSIX systems, +this should be of type SmLISTofARRAY8. - SmCurrentDirectory + SmCurrentDirectory -On POSIX-based systems, this specifies the value of the current -directory that needs to be set up prior to starting the SmProgram and -should of type SmARRAY8. +On POSIX-based systems, this specifies the value of the +current directory that needs to be set up prior to starting the +SmProgram and should of type SmARRAY8. - SmDiscardCommand + SmDiscardCommand The discard command contains a command that when delivered to the host that the client is running on (determined from the connection), will cause it to discard any information about the current state. If this command is not specified, the Session Manager will assume that all of -the client's state is encoded in the SmRestartCommand. On POSIX -systems, the type should be SmLISTofARRAY8. +the client's state is encoded in the SmRestartCommand. +On POSIX systems, the type should be +SmLISTofARRAY8. - SmEnvironment + SmEnvironment -On POSIX based systems, this will be of type SmLISTofARRAY8, where the -ARRAY8s alternate between environment variable name and environment -variable value. +On POSIX based systems, this will be of type +SmLISTofARRAY8, where the ARRAY8s alternate between +environment variable name and environment variable value. - SmProcessID + SmProcessID This specifies an OS-specific identifier for the process. -On POSIX systems, this should contain the return value +On POSIX systems, this should contain the return value of getpid turned into a Latin-1 (decimal) string. - SmProgram + SmProgram -This is the name of the program that is running. On POSIX systems, -this should be first parameter passed to execve -and should be of type SmARRAY8. +This is the name of the program that is running. On POSIX +systems, this should be first parameter passed to execve +and should be of type SmARRAY8. - SmRestartCommand + SmRestartCommand The restart command contains a command that, when delivered to the host that the client is running on (determined from the connection), -will cause the client to restart in its current state. On POSIX-based -systems, this is of type SmLISTofARRAY8, and each of the elements in -the array represents an element in the argv +will cause the client to restart in its current state. +On POSIX-based systems, this is of +type SmLISTofARRAY8, and each of the elements in +the array represents an element in the argv array. This restart command should ensure that the client restarts with the specified client-ID. - SmResignCommand + SmResignCommand -A client that sets the SmRestartStyleHint to SmRestartAnway uses this -property to specify a command that undoes the effect of the client and -removes any saved state. As an example, consider a user that -runs xmodmap which registers with the Session -Manager, sets SmRestartStyleHint to SmRestartAnyway, and then +A client that sets the SmRestartStyleHint +to SmRestartAnyway uses this property to specify a +command that undoes the effect of the client and removes any saved state. +As an example, consider a user that runs xmodmap which +registers with the Session Manager, +sets SmRestartStyleHint +to SmRestartAnyway, and then terminates. To allow the Session Manager (at the user's request) to -undo this, xmodmap would register a -SmResignCommand that undoes the effects of the xmodmap. +undo this, xmodmap would register a +SmResignCommand that undoes the effects of +the xmodmap. - SmRestartStyleHint + SmRestartStyleHint -If the RestartStyleHint property is present, it will contain the style -of restarting the client prefers. If this style is not specified, -SmRestartIfRunning is assumed. The possible values are as follows: +If the SmRestartStyleHint is present, it will contain the +style of restarting the client prefers. If this style is not specified, +SmRestartIfRunning is assumed. +The possible values are as follows: @@ -3007,19 +3062,19 @@ SmRestartIfRunning is assumed. The possible values are as follows: - SmRestartIfRunning + SmRestartIfRunning 0 - SmRestartAnyway + SmRestartAnyway 1 - SmRestartImmediately + SmRestartImmediately 2 - SmRestartNever + SmRestartNever 3 @@ -3028,23 +3083,23 @@ SmRestartIfRunning is assumed. The possible values are as follows: -The SmRestartIfRunning style is used in the usual case. +The SmRestartIfRunning style is used in the usual case. The client should be restarted in the next session if it was running at the end of the current session. -The SmRestartAnyway style is used to tell the Session Manager that the -application should be restarted in the next session even if it exits -before the current session is terminated. It should be noted that +The SmRestartAnyway style is used to tell the Session +Manager that the application should be restarted in the next session even if +it exits before the current session is terminated. It should be noted that this is only a hint and the Session Manager will follow the policies specified by its users in determining what applications to restart. -A client that uses SmRestartAnyway should also set the SmResignCommand -and SmShutdownCommand properties to commands that undo the state of -the client after it exits. +A client that uses SmRestartAnyway should also set the +SmResignCommand and SmShutdownCommand +properties to commands that undo the state of the client after it exits. @@ -3052,26 +3107,29 @@ The SmRestartImmediately style is like SmRestartAnyway, but, in addition, the cl -SmRestartNever style specifies that the client does not wish to be -restarted in the next session. +SmRestartNever style specifies that the client does not +wish to be restarted in the next session. - SmShutdownCommand + SmShutdownCommand This command is executed at shutdown time to clean up after a client that is no longer running but retained its state by setting -SmRestartStyleHint to SmRestartAnyway. The client must not remove any -saved state as the client is still part of the session. As an +SmRestartStyleHint to +SmRestartAnyway. The client must not remove any saved +state as the client is still part of the session. As an example, consider a client that turns on a camera at start up time. This client then exits. At session shutdown, the user wants the -camera turned off. This client would set the SmRestartStyleHint to -SmRestartAnyway and would register a SmShutdownCommand that would turn -off the camera. +camera turned off. This client would set the +SmRestartStyleHint to +SmRestartAnyway and would register +a SmShutdownCommand that would turn off the camera. - SmUserID + SmUserID -Specifies the user ID. On POSIX-based systems, this will contain the -user's name (the pw_name member of struct passwd). +Specifies the user ID. On POSIX-based systems, this will +contain the user's name (the pw_name member of +struct passwd). -- cgit v1.2.3