Previous section.

Distributed Software Administration - DCE Interoperability (XDSA-DCE)

Distributed Software Administration - DCE Interoperability (XDSA-DCE)
Copyright © 1997 The Open Group

XDSA-DCE RPC Type Definitions

This chapter describes the DCE IDL for data types used in the XDSA-DCE RPC interface specification. These include types for:

Type Definition Interface

The XDSA-DCE type definition interface is defined as follows:

[uuid(59646C2C-B027-11CB-9302-080009199BEB), version(1.0)]
interface sdu_rpc_defs
{

	/* type definitions */

} /* sdu_rpc_defs */

Strings

Strings are passed either as RPC reference pointers or as RPC full pointers. Strings that are declared with the ptr attribute (that is, full) may be passed with a NULL value, but incur more overhead.

/*
 * String data type.  The full pointer version is used in cases
 * where the pointer may be NULL.
 */

typedef     [ref, string]   char    *sw_rpc_string_ref_t;
typedef     [ptr, string]   char    *sw_rpc_string_full_t;

Session Context Handles

A session handle is implemented as an RPC context handle, which enables the agent to associate RPCs with a given session. The context mechanism is also used by the agent to detect when the manager dies unexpectedly or communication with the manager is lost.

/*
 * The session context type.  This is implemented as an RPC context
 * handle so the agent can detect the death of the RPC client.
 */

typedef     [context_handle]   void    *sw_rpc_context_t;

Source and Target Specification

A target or source software collection is identified by the string binding to its host, combined with its absolute path in the host's filesystem. This string binding is the string form of the daemon_binding parameter used to initialize an agent via the sw_rpc_agent_init() function, not a copy of the agent_string_binding parameter returned from that function.

/*
 * Constructed type for software collection descriptor type.
 */

typedef struct
{

	sw_rpc_string_full_t  soc_binding; /* string binding to daemon */
	sw_rpc_string_full_t  soc_path;    /* absolute path on host */

} sw_rpc_soc_desc_t;

Host Information

Host information consists of uname() style attributes that are used to determine software compatibility.

/*
 * Constructed type for passing "uname" attributes.
 */

typedef struct
{
	sw_rpc_string_full_t	sysname;	/* uname sysname */
	sw_rpc_string_full_t	release;		/* uname release */
	sw_rpc_string_full_t	version;		/* uname version */
	sw_rpc_string_full_t	machine;	/* uname machine */
} sw_rpc_uname_attrs_t;

The host information also includes information listing the available distributions or installed software collections on the host.

/*
 * Constructed type for list of distributions or installed software collections.
 */

typedef struct
{

	unsigned32			max_depots;
	unsigned32			num_depots;
	[size_is(max_depots),
	    length_is(num_depots)]
		sw_rpc_string_full_t	depot_paths[];

} sw_rpc_depot_list_t;

Task Types

The task type determines what task the agent will perform on the software object collection during the course of the session (corresponds to the command that was invoked). This is also referred to as the session type.

/*
 * Type for the set of defined task types.
 */

typedef	unsigned32	sw_rpc_task_t;

Control Options

Control options affect a function's behavior, influencing the semantics of the task performed, the way certain events are interpreted, and the data that the function returns.

/*
 * Constructed type for passing control options.
 * Options are passed in "keyword=value" strings.
 */

typedef struct
{

	unsigned32			num_options;
	[size_is(num_options)]
		sw_rpc_string_ref_t	options_list[]; /* options */

} sw_rpc_options_t;

Result Status

The result status type is used in three instances:

  1. to indicate the overall result of a function upon its return

  2. to indicate the effect of each individual result that occurred during a function's execution

  3. to indicate the cumulative effect of the results that occurred during task analysis or execution for each individual selected software object.

Values for this type are composed by masking together the individual NOTE, WARNING, ERROR and SUSPEND effect values.

/*
 * Mask of the possible NOTE, WARNING, ERROR or SUSPEND 
 * effects of one or more results.
 */

typedef		unsigned32	sw_rpc_result_status_t;

Result Codes

The result code type is used to identify a result that occurred during a function's execution.

/*
 * Identifies a specific result.
 */

typedef		unsigned32	sw_rpc_result_code_t;

Function Results

The results of a function are returned as a structure containing an overall summary result status field, and an array of items indicating the code, effect, and auxiliary information identifying each specific result which occurred during the function's execution. The auxiliary information for each result is implemented as an integer whose meaning is specific to a the code, such as a count on the number of times the event occurred, or a media number needed in a tape change.

#define SW_MAX_RESULTS	256

/*
 * Constructed types for passing function results.  The value
 * assigned to max_results (by the caller) should be at least
 * SW_MAX_RESULTS.
 */

typedef struct
{

	sw_rpc_result_code_t	result_code;	/* which result */
	sw_rpc_result_status_t	result_status;	/* effect */
	unsigned32		result_info;	/* auxiliary info */

} sw_rpc_result_item_t;

typedef struct
{

	sw_rpc_result_status_t	summary_status;	/* summary of results */
	unsigned32		max_results;		/* max size of array */
	unsigned32		num_results;		/* cur size of array */
	[size_is(max_results),
	    length_is(num_results)]
		sw_rpc_result_item_t results_list[];	/* list of results */

} sw_rpc_results_t;

Software State

This type is used to indicate the action that the agent will take (as a result of task analysis), or did take (as a result of task execution), for each selected software object.

It is passed back to the manager in the selections array when an analyze, execute or abort task function returns.

/*
 * Type for the possible predicted state, or resultant
 * state for each software object.
 */

typedef		unsigned32	sw_rpc_swobj_state_t;

Session Phase

This type is used to indicate the current phase of the session. A session's phase is modified (that is. "transitioned") via the analyze, execute, and abort task functions. Session phase also determines which functions may be called at a particular point in time.

During analysis and execution, the session phase indicates the current sub-phase being performed, which can be retrieved via the get status and log function.

/*
 * Type describing the current state of a session.
 */

typedef		unsigned32	sw_rpc_session_phase_t;

Selections

These types are used to indicate the software object selections that are passed to an analyze, execute, or abort task function, and to return result data for each software object. A software object is identified by its software specification, uuid, and the source where the software object may be found.

Software object selections are differentiated as either explicit, or due to a dependency relationship.

Result data consists of the predicted (analysis) or resultant (execution) state, and an indicator of the cumulative effect of the results that occurred during task analysis or execution, for each individual selected software object.

/*
 * Constructed types for passing software selections.  The
 * swobj_state and result_status are output fields set by
 * the agent after task analysis or execution has completed.
 */

typedef struct
{

	uuid_t			swobj_uuid;	/* uuid (not used) */
	sw_rpc_string_ref_t	swobj_spec;	/* software spec */
	sw_rpc_soc_desc_t	soc_desc;	/* source path */
	unsigned32		selection_type;	/* explicit vs dependency */
	sw_rpc_swobj_state_t	swobj_state;	/* swobj state */
	sw_rpc_result_status_t	result_status;	/* cumulative status */

} sw_rpc_selection_item_t;

typedef struct
{

	unsigned32				num_selections;
	[size_is(num_selections)]
		sw_rpc_selection_item_t		selections_list[];	/* selections */

} sw_rpc_selections_t;

Interim Status

This type is used to indicate the intermediate status of a task's execution.

Interim status is returned by the sw_rpc_get_task_status_and_log() function.

/*
 * Constructed type for retrieving interim status data.
 */
    
typedef struct
{

	sw_rpc_string_full_t	current_swobj;		/* current swobj */
	unsigned32		time_elapsed;		/* time elapsed thus far */
	unsigned32		time_to_completion;	/* estimated time */
	unsigned32		kbytes_done;		/* kbytes done so far */
	unsigned32		kbytes_total;		/* total kbytes estimated */
	unsigned32		files_done;		/* files done so far */
	unsigned32		files_total;		/* total files estimated */
	unsigned32		percent_done;		/* percentage to completion */

} sw_rpc_interim_status_t;

File Transfer

This type is used for the transfer of file contents, such as the files that comprise the software catalog, a software object's actual files, and the log file data for a session.

/*
 * General "pipe of bytes" typedef, used in transferring logfile
 * entries and file contents.
 */

typedef		pipe	byte	sw_rpc_bytepipe_t;

Disk Space Analysis

These types are used to transfer the data generated by performing disk space analysis. Data is gathered on a per-volume as well as a per-fileset basis.

/*
 * This is used for RPC transport of disk space analysis results
 * from the agent to the manager.
 */

typedef struct
{

	/* Volume attributes. */

	sw_rpc_string_full_t	filesystem;	/* filesystem */
	unsigned32		type;		/* type of file system */|| 
	long			minfree;		/* percent for this volume */
	long			blocks;		/* total 1K available */
	long			free_blocks;	/* 1K before operation */

	/* 
 	* Volume status.  
 	* All block sizes are normalized to 1024 bytes/block
 	*/

	unsigned32	state;		/* file system use */
	unsigned32	num_files;	/* number of files to load on this volume  */
	long		current_blocks;	/* current for all selected filesets */
	long		needed_blocks;	/* net for all selected filesets */
	long		till_full;		/* blocks available to absolute limit */
	long		till_warn;	/* blocks available to minfree threshold */

} sw_rpc_volume_t;

typedef struct
{

	unsigned32			max_volumes;	/* max size of array */
	unsigned32			num_volumes;	/* cur size of array */
	[size_is(max_volumes),
	    length_is(num_volumes)]
		sw_rpc_volume_t	volumes[];	/* list of volumes */

} sw_rpc_volumes_list_t;

/*
 * This is the per volume / per fileset information
 */

typedef struct
{

	sw_rpc_string_full_t	swobj_spec;		/* software spec */
	uuid_t			swobj_uuid;		/* uuid (not used) */
	unsigned32		fileset_index;		/* index (not used) */
	unsigned32		num_files;		/* Effect of fileset */
	unsigned32		current_blocks;
	unsigned32		needed_blocks;

} sw_rpc_fsvol_t;

typedef struct
{

	unsigned32		max_fsvol;	/* max size of array */
	unsigned32		num_fsvol;	/* cur size of array */
	[size_is(max_fsvol),
	    length_is(num_fsvol)]
		sw_rpc_fsvol_t	fsvol[];		/* list of fsvol entries */

} sw_rpc_fsvol_list_t;

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index