rpc_ns_entry_inq_resolution(3rpc)
Resolves the cell namespace components of a name and returns partial results
Synopsis
#include <dce/rpc.h>
void rpc_ns_entry_inq_resolution(
unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
unsigned_char_t **resolved_name,
unsigned_char_t **unresolved_name,
unsigned32 *status
);
Parameters
Input
entry_name_syntax
An integer value that specifies the syntax of the argument entry_name.
To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX environment variable, supply a value of rpc_c_ns_syntax_default.
entry_name
The entry name on which the attempted name resolution is to be done. The name can be specified in either cell-relative or global from.
Input/Output
resolved_name
Returns a pointer to the resolved portion of the entry name. The resolved_name string returned will be null terminated and will not contain trailing
component separators (that is, no trailing "/'' (slash) characters).
If NULL is specified on input for this parameter, nothing will be returned.
unresolved_name
Returns a pointer to the unresolved portion of the entry name. The unresolved_name string returned will be a relative name, containing no leading
component separators (that is, it will contain no leading "/'' (slash) characters).
If NULL is specified on input for this parameter, nothing will be returned.
Output
status
Returns the status code from this routine. The status code indicates whether the routine completed successfully, or if not, why not.
Description
The rpc_ns_entry_inq_resolution( ) routine attempts to read an entry in the cell namespace. If the entire entry name as specified is successfully read, the
full resolution of the entry name (i.e., the originally-specified entry_name) is returned in resolved_name and the status is set to rpc_s_ok.
If the read was unsuccessful because the full entry was not found in the cell namespace, then the status code will be set to rpc_s_partial_results, and:
· The part of the name successfully read will be returned in resolved_name
· The remaining (unresolved) part of the name will be returned in unresolved_name
Thus, if the status code is rpc_s_partial_results and the (non-empty) return parameter resolved_name specifies a leaf (not a directory) entry, the contents of resolved_name can be used in subsequent calls to the NSI interface to obtain a binding handle for the server that exported to the entry. This behavior allows applications to implement namespace junctions to their own internally-implemented namespaces. Using this routine, clients can attempt to bind to overqualified name entries whose resolved_name part is the name of the server entry, and whose unresolved_name part is the path name (meaningful to the server) of some object managed by the application. Calling rpc_ns_entry_inq_resolution( ) with the full name allows the client to learn what part of the name denotes the server entry it must import bindings from; it can then bind to the server, passing the rest of the name, which the server interprets as appropriate. The sec_acl_bind(~) routine, for example, works this way.
The RPC runtime allocates memory for the returned resolved_name and unresolved_name parameters. The application is responsible for calling rpc_string_free( ) to free the allocated memory.
Permissions Required
The application requires read permission for the name entries that are resolved within the cell namespace.
Return Values
None.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
rpc_s_ok
Success.
rpc_s_partial_results
The entry name was only partially resolved within the cell namespace and the value of unresolved_name points to the residual of the name.
rpc_s_invalid_name_syntax
The requested name syntax is invalid.
rpc_s_unsupported_name_syntax
The requested name syntax is not supported.
Related Information
Functions: rpc_ns_binding_export(3rpc)
rpc_ns_binding_import_begin(3rpc)
rpc_ns_binding_import_done(3rpc)
rpc_ns_binding_import_next(3rpc)
rpc_ns_binding_inq_entry_name(3rpc)
rpc_ns_binding_lookup_begin(3rpc)
rpc_ns_binding_lookup_done(3rpc)
rpc_ns_binding_lookup_next(3rpc)