Frequently Used Routine Parameters

binding
Used as an input or output parameter.

Returns a binding handle for making remote procedure calls to a server.

A client obtains a binding handle by calling one of the following routines:
rpc_binding_copy( )
rpc_binding_from_string_binding( )
rpc_ns_binding_import_next( )
rpc_ns_binding_select( )

Creating a binding handle establishes a relationship between a client and a server. However, the relationship does not involve any communications between the client and server. The communications occur when a client makes a remote procedure call.

As an input parameter to a remote procedure call, binding specifies a binding handle that refers to binding information. The client's RPC runtime uses this binding information to make a remote procedure call to a server.

Server manager routines can extract client information from a client binding handle by using the following routines:
rpc_binding_inq_auth_client( )
rpc_binding_inq_object( )
rpc_binding_to_string_binding( )
rpc_string_binding_parse( )

name
Used as an input/output parameter.

When used as an input parameter, the value of this parameter depends on the syntax selected in the name_syntax parameter. If it is allowed by the called routine, the value NULL specifies that the routine uses the name specified in the RPC_DEFAULT_ENTRY environment variable. Specifying NULL also has the called routine use the name syntax that the environment variable RPC_DEFAULT_ENTRY_SYNTAX specifies.

For a name_syntax value of rpc_c_ns_syntax_dce, use the DCE naming rules to specify parameter name.

As an output parameter, returns an entry in the name service database in the form of a character string that includes a terminating null character. The value of this parameter depends on the syntax selected in name_syntax.

For a name_syntax value of rpc_c_ns_syntax_dce, name is returned using the DCE naming syntax.

The DCE RPC runtime allocates memory for the returned string. The application is responsible for calling the rpc_string_free( ) routine to deallocate the string.

If an application does not want a returned name string, the application usually specifies NULL for this parameter. The one exception is routine rpc_ns_entry_expand_name( ); it always returns a name string.

name_syntax
Used as an input parameter, an integer value that specifies the syntax of an entry name. When allowed by the called routine, a value of rpc_c_ns_syntax_default specifies that the routine uses the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX environment variable. The following table lists the valid syntaxes that applications can use in DCE RPC for entries in the name service database.

Valid Name Syntaxes

Constant	Value	Description
rpc_c_ns_syntax_default	0	Default syntax
rpc_c_ns_syntax_dce	3	DCE

The name_syntax parameter tells routines how to parse the entry name specified in an input name parameter or specifies the syntax to use when returning an entry name as an output name parameter.

If the RPC_DEFAULT_ENTRY_SYNTAX environment variable is not defined, the RPC runtime uses the rpc_c_ns_syntax_dce name syntax.

string
Used as an input or output parameter.

Returns a character string, which always includes the terminating null character 0. The DCE RPC runtime allocates memory for the returned string. The application calls the rpc_string_free( ) routine to deallocate the memory occupied by the string.

If there is no data for the requested string, the routine returns the string \0. For example, if the string binding passed to routine rpc_string_binding_parse( ) does not contain an object UUID, the routine returns \0 as the value of the object UUID string. The application must call the rpc_string_free( ) routine to deallocate the memory occupied by this string.

If an application does not require a returned output string, the application specifies NULL for this parameter.

status
Each routine in the RPC API returns a DCE status code indicating whether the routine completed successfully or, if not, why not. A return value of rpc_s_ok indicates success. All other return values signify routine failure. The status codes listed for each RPC runtime routine are the most likely, but not necessarily all, the status codes that the routine can return.

The status code argument has a data type of unsigned32.

To translate a DCE status code to a text message, call the routine dce_error_inq_text( ).

Note that RPC exceptions are equivalent to RPC status codes. To identify the status code that corresponds to a given exception, replace the _x_ string of the exception with the string _s_; for example, the exception rpc_x_already_listening is equivalent to the status code rpc_s_already_listening.

uuid
Used as an input or output parameter.

When you need to specify a nil UUID to a uuid input parameter in any of the DCE RPC routines, you can supply the value NULL.