NAME

rpc_mgmt_inq_server_princ_name-returns a server's principal name

SYNOPSIS

#include <dce/rpc.h>

void rpc_mgmt_inq_server_princ_name(
	rpc_binding_handle_t binding,
	unsigned32 authn_svc,
	unsigned_char_t **server_princ_name,
	unsigned32 *status);

PARAMETERS

Input

binding

Specifies a server binding handle for the server from which server_princ_name is returned. A server application can supply the value NULL to return its own principal name.

If the binding handle supplied refers to partially bound binding information and the binding information contains a nil object UUID, this routine fails with the rpc_s_binding_incomplete status code. Applications can avoid this situation by calling the rpc_ep_resolve_binding() routine to obtain a fully bound server binding handle.

authn_svc

Specifies the authentication service for which a principal name is returned. (See Authentication, Authorisation and Protection-level Arguments for possible values of this argument.)

Output

server_princ_name

Returns a principal name. This name is registered for the authentication service in the authn_svc argument by the server referenced in binding. If the server registered multiple principal names, only one of them is returned.

status

Returns the status code from this routine. The status code indicates whether the routine completed successfully, or if not, why not.

Possible status codes and their meanings include:

rpc_s_ok

Success.

rpc_s_binding_incomplete

Binding incomplete (no object ID and no endpoint).

rpc_s_comm_failure

Communications failure.

rpc_s_mgmt_op_disallowed

Management operation disallowed.

rpc_s_unknown_authn_service

Unknown authentication service.

In addition to the above values, status can return the value of status from an application-defined authorisation function. The prototype for such a function is defined in the authorization_fn argument description in tagmref_rpc_mgmt_set_authorization_fn .

DESCRIPTION

An application calls routine rpc_mgmt_inq_server_princ_name() to obtain the principal name of a server that is registered for a specified authentication service.

The RPC run-time system allocates memory for the string returned in the server_princ_name argument. The application should call the rpc_string_free() routine to deallocate that memory.

By default, the RPC run-time system allows all clients to call this routine remotely. To establish non-default authorisation for this or other management calls, a server application supplies an authorisation function by calling the rpc_mgmt_set_authorization_fn() routine.

RETURN VALUE

None.

SEE ALSO

rpc_binding_inq_object()
rpc_binding_set_auth_info()
rpc_ep_resolve_binding()
rpc_mgmt_set_authorization_fn()
rpc_server_register_auth_info()
rpc_string_free()
uuid_is_nil().

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.