The XDSA-DCE RPC interface is defined in three DCE RPC interface definitions:
Each interface definition contains a UUID line identifying the interface and version of the interface, and interface body bgcolor="#FFFFFF" that contains the procedure and type definitions.
The XDSA-DCE daemon RPC interface is defined as follows:
[uuid(92F278D6-1723-11CC-9A0F-08000935358F), version(1.0)]
interface sdu_rpc_daemon
{
import "sdu_rpc_defs.idl";
/*
* The XDSA-DCE daemon interface defines the following procedures:
* sw_rpc_get_depots
* sw_rpc_register_depot
* sw_rpc_unregister_depot
* sw_rpc_is_registered_depot
* sw_rpc_agent_init
*/
/* procedure definitions */
} /* sdu_rpc_daemon */
[uuid(DD1933A0-B026-11CB-B03C-080009199BEB), version(1.0)]
interface sdu_rpc_agent
{
import "sdu_rpc_defs.idl";
/*
* The XDSA-DCE agent interface defines the following procedures:
* sw_rpc_begin_session
* sw_rpc_end_session
* sw_rpc_analyze_task
* sw_rpc_execute_task
* sw_rpc_abort_task
* sw_rpc_get_task_status_and_log
* sw_rpc_get_dsa_impact_data
* sw_rpc_get_dsa_volume_list
* sw_rpc_get_soc_file
*/
/* procedure definitions */
} /* sdu_rpc_agent */
The XDSA-DCE type definitions interface is defined in
sw_rpc_abort_task - abort task
void sw_rpc_abort_task ( [in] handle_t agent_binding, [in] sw_rpc_context_t session_context, [in] sw_rpc_options_t *control_options, [out] sw_rpc_session_phase_t *session_state, [in, out] sw_rpc_results_t *results );
This function aborts the execution of a task that has entered a suspended state. Task execution that has suspended may be aborted using this function, or resumed via the sw_rpc_execute_task() function.The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_agent_init - initialise agent
void sw_rpc_agent_init ( [in] handle_t daemon_binding, [in] sw_rpc_options_t *control_options, [in] sw_rpc_string_ref_t soc_path, [in] sw_rpc_task_t task_type, [out] sw_rpc_string_full_t *agent_string_binding, [in, out] sw_rpc_results_t *results ); } /* sdu_rpc_daemon */
Tell the XDSA daemon to schedule the XDSA agent, in preparation for performing a management task on a distribution or installed software collection. A string binding is returned in agent_string_binding, which is then used to bind to the newly-scheduled agent in thesw_rpc_begin_session() function.This call exists to support a process model in which the daemon exists as a separate process and schedules agents to do the actual tasks. For implementations that have the daemon and agent as the same process, this call is still required to initiate the agent sesssion within the daemon process.
An RPC binding handle is supplied in daemon_binding, which is used to establish the connection with the daemon.
The location of the software collection is supplied in soc_path. This is supplied as an absolute path with respect to the containing host's filesystem.
The task that is to be performed on the software collection is indicated by task_type.
The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_analyze_task - analyse task
void sw_rpc_analyze_task ( [in] handle_t agent_binding, [in] sw_rpc_context_t session_context, [in] sw_rpc_options_t *control_options, [in, out] sw_rpc_selections_t *software_selections, [out] sw_rpc_session_phase_t *session_state, [in, out] sw_rpc_results_t *results );
This function initiates the checks that are performed prior to the actual execution of a management task on a distribution or installed software collection. The caller must have previously established a management session for the software collection, which is identified by session_context. The nature of the analysis is determined by the given task, which was specified when the session was established.Software specifications may be specified at any level (bundles, products, subproducts, or filesets), and are passed in the software_selections parameter. In order to receive the most detailed result information when the call returns, the software_selections should be specified at the fileset level. Selection information is specified using a conformant array of software selection item structures, each of which contains the software specification string, the UUID, and the install or copy source of the selected software object. Additionally, each software selection item structure contains fields which are modified by the agent to indicate the expected action, error, and warning information that was collected during task analysis.
The expected actions determined during analysis for a given selected software object are listed in the section Analysis States.
The session_state output parameter controls whether the task can proceed to execution phase. If the value is SW_ANALYSIS_COMPLETED_PHASE, then one or more software selections passed analysis without errors, and they can be executed on. If no software passed analysis, then the state returned is SW_SELECTION_PHASE. In either case, the task can also repeat the analysis or end the session. See
Session Phase for all possible states.The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful for one or more software_selections, due to an occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_begin_session - begin session
void sw_rpc_begin_session ( [in] handle_t agent_binding, [in] sw_rpc_options_t *control_options, [in] sw_rpc_string_ref_t soc_path, [in] sw_rpc_task_t task_type, [out] sw_rpc_uname_attrs_t *uname_attrs, [out] sw_rpc_context_t *session_context, [out] sw_rpc_session_phase_t *session_state, [in, out] sw_rpc_results_t *results );
This function establishes a session context with the XDSA agent for the management of a software distribution or installed software collection.The location of the software collection is supplied in soc_path. This is supplied as an absolute path with respect to the containing host's filesystem.
The task that is to be performed on the software collection is indicated by task_type.
The session may be refused if the requesting manager does not have adequate authorization to manage the specified software collection, or if another conflicting management operation is already in progress on the software collection. If a session context is successfully established, a session handle is returned in session_context.
The session context is implemented using the DCE RPC context handle mechanism, enabling the XDSA agent to maintain the session's state across multiple RPCs. The context handle mechanism is also used by the agent to detect communication failure and/or the unexpected death of an XDSA manager.
The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_end_session - end session
void sw_rpc_end_session ( [in] handle_t agent_binding, [in, out] sw_rpc_context_t *session_context, [in] sw_rpc_options_t *control_options, [in, out] sw_rpc_results_t *results );
This function terminates a previously-established session for a distribution or installed software collection. The session to be terminated is indicated in session_context. When a session is terminated, the agent will release whatever resources and state were being maintained for it.The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_execute_task - execute task
void sw_rpc_execute_task ( [in] handle_t agent_binding, [in] sw_rpc_context_t session_context, [in] sw_rpc_options_t *control_options, [in, out] sw_rpc_selections_t *software_selections, [out] sw_rpc_session_phase_t *session_state, [in, out] sw_rpc_results_t *results );
This function initiates the actual execution of a management task on a distribution or installed software collection. This function is also used to resume the execution of a task that has entered a suspended state.The caller must have previously established a management session for the software collection, which is identified by session_context. The task that is to be performed was specified when the session was established.
Software specifications may be specified at any level (bundles, products, subproducts, or filesets), and are passed in the software_selections parameter. In order to receive the most detailed result information when the call returns, the software_selections should be specified at the fileset level. Selection information is specified using a conformant array of software selection item structures, each of which contains the software specification string, the UUID, and the install or copy source of the selected software object. Additionally, each software selection item structure contains fields which are modified by the agent to indicate the resulting action, error, and warning information that was collected during task execution.
The resultant actions taken during execution for a given selected software object are listed in the section Execution States.
The session_state output parameter controls whether the task can continue a suspended execution phase. If the value is SW_SUSPENDED_PHASE, then sw_rpc_execute_task can be called again to resume the execution. See
Session Phase for all possible states.The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful for one or more software_selections, due to an occurrence of one or more error events.
- SW_SUSPEND
Task execution was suspended due to the occurrence of a suspend event.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_get_depots - get list of existing distributions or installed software collections
void sw_rpc_get_depots ( [in] handle_t daemon_binding, [in] sw_rpc_options_t *control_option [in, out] sw_rpc_depot_list_t *depot_list, [in, out] sw_rpc_results_t *results );
The sw_rpc_get_depots() function returns a list of software distributions or installed software collections that are being served by a particular XDSA daemon. Whether the list contains distributions or installed software collections is determined by the value of the level control option. The list is returned via the depot_list parameter.The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_get_dsa_impact_data - get disk space analysis impact data
void sw_rpc_get_dsa_impact_data ( [in] handle_t agent_binding, [in] sw_rpc_context_t session_context, [in] sw_rpc_options_t *control_options, [in] sw_rpc_string_ref_t filesystem, [in, out] sw_rpc_fsvol_list_t *fsvol, [in, out] sw_rpc_results_t *results );
The second Disk Space Analysis step involves requesting data showing the impact that installing or removing the specified objects has on a given volume.This operation is task-specific, since to do the actual calculations, the agent needs to know if the software objects are being installed or removed, and whether or not the operation is being performed on a distribution or installation software collection.
The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_get_dsa_volume_list - get disk space analysis volume list
void sw_rpc_get_dsa_volume_list ( [in] handle_t agent_binding, [in] sw_rpc_context_t session_context, [in] sw_rpc_options_t *control_options, [in, out] sw_rpc_volumes_list_t *volumes, [in, out] sw_rpc_results_t *results );
The impact of an install or remove task is presented on a per-volume (that is, mounted filesystem) basis. Retrieving Disk Space Analysis information is therefore a two-step process. This call performs the first step, which is to retrieve the list of volumes that comprise the distribution or installation software collection (ideally, but would probably be easier to just list all of the volumes on the destination host).The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_get_soc_file - get software collection file
void sw_rpc_get_soc_file ( [in] handle_t agent_binding, [in] sw_rpc_context_t session_context, [in] sw_rpc_options_t *control_options, [in] uuid_t swobj_uuid, [in] sw_rpc_string_ref_t swobj_spec, [in] sw_rpc_string_ref_t file_path, [out] sw_rpc_bytepipe_t file_contents, [in, out] sw_rpc_results_t *results ); } /* interface sdu_rpc_agent */
The sw_rpc_get_soc_file() function returns the contents of a logical file contained in a distribution or installed software collection. The session_context parameter identifies the session in which the software collection is being managed. The swobj_uuid and swobj_spec parameters identify the software object within the software collection that contains the requested file. The file_path parameter is the relative pathname of the requested logical file.A logical file can be catalog information, a control file, or a product file that would exist in a software collection conforming to this standard. The file_path parameter is the path to the file relative to the directory where catalog, control, or product files for the software object indicated by swobj_uuid and swobj_spec would exist in a software collection conforming to this standard.
The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_get_task_status_and_log - get task status and log
void sw_rpc_get_task_status_and_log ( [in] handle_t agent_binding, [in] sw_rpc_context_t session_context, [in] sw_rpc_options_t *control_options, [out] sw_rpc_interim_status_t *interim_status, [out] sw_rpc_bytepipe_t log_data, [out] sw_rpc_session_phase_t *session_state, [in, out] sw_rpc_results_t *results );
This function retrieves interim status and log entries during task analysis or execution, enabling the caller to gauge progress as these long-duration operations are performed.The session for which status is retrieved is indicated by session_context.
The status data is returned in interim_status, which is a data structure containing fields which indicate:
- the current sub-task being performed
- the estimated time to completion
- the total number of kbytes that will be loaded/removed in the operation
- the current number of kbytes loaded/removed so far
- the current software object being operated on.
The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_is_registered_depot - check distribution or installed software collection root is registered
void sw_rpc_is_registered_depot ( [in] handle_t daemon_binding, [in] sw_rpc_options_t *control_options, [in] sw_rpc_string_ref_t depot_path, [in, out] sw_rpc_results_t *results );
The sw_rpc_is_registered_depot() function checks whether a software distribution or installed software collection is registered on the host (possibly under an alias). Whether the path to check is a depot or root is determined by the value of the level control option.The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_register_depot - register distribution or installed software collection
void sw_rpc_register_depot ( [in] handle_t daemon_binding, [in] sw_rpc_options_t *control_options, [in] sw_rpc_string_ref_t depot_path, [in, out] sw_rpc_results_t *results );
The sw_rpc_register_depot() function registers the software distributions or installed software collections located in the callee's file system at the path indicated by the depot_path parameter. Whether the path to register is a distribution or installed software collection is determined by the value of the level control option.The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
sw_rpc_unregister_depot - unregister distribution or installed software collection
void sw_rpc_unregister_depot ( [in] handle_t daemon_binding, [in] sw_rpc_options_t *control_options, [in] sw_rpc_string_ref_t depot_path, [in, out] sw_rpc_results_t *results );
The sw_rpc_unregister_depot() function deletes the software distribution or installed software collection located in the callee's file system at the path indicated by the depot_path parameter from the list of served distributions on the callee's system. Whether the path to unregister is a distribution or installed software collection is determined by the value of the level control option.The results of the function are returned via the results parameter, which is a structure of type sw_rpc_results_t. This structure contains a summary_status field which indicates the overall success of the function, and a results_list array which lists all error, warning, and informational events that occurred during execution of the function.
The value returned in the summary_status is a mask of the following possible values:
- SW_NOTE
The function was successful, but one or more informational events occurred.
- SW_WARNING
The function was successful, but one or more warning events occurred.
- SW_ERROR
The function was not successful, due to the occurrence of one or more error events.
The results_list field is a variable, conformant array of items which describe each event's result status (that is, error, warning, or note), its result code, and additional result information indicating number of occurrences, etc.
No return value (void).
Error, warning, and informational events are indicated via the results parameter. Refer to the Result Codes section for a description of the possible events.
| Contents | Next section | Index |