A few parameters are common to many of the DCE RPC routines. These parameters are described fully here and again briefly on the specific routine reference pages.
1 – 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()
2 – 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.
3 – 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.
4 – 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.
5 – 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. For more information about the RPC status codes, see the OSF DCE Problem Determination Guide.
6 – 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.