NAME

   rpc_mgmt_inq_server_princ_name - Returns a server's principal name

   Used by client, server, or management applications.

 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 binding handle.  If a client application wants the
       princi pal name from a server application, supply a server
       binding handle for that server.  For a server application to
       receive a principal name of itself, supply the value NULL.

       If the binding handle you supply refers to partially bound
       binding information and the binding information contains a nil
       object UUID, this routine returns the rpc_s_binding_incomplete
       status code.  In this case the DCE Host Daemon does not know
       which server instance to select from the local endpoint map
       because the RPC runtime automatically registers the RPC
       management interface for all RPC servers.  You can avoid this
       situation by calling rpc_ep_resolve_binding() to obtain a fully
       bound server binding handle.

   authn_svc
       Specifies the authentication service for which a principal name
       is returned.  The rpc_binding_set_auth_info reference page, in
       its explanation of the authn_svc parameter, contains a list of
       supported authentication services.

   Output

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

   status
       Returns the status code from this routine.  This status code
       indicates whether the routine completed successfully or, if
       not, why not.  The possible status codes and their meanings
       are as follows:

       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.

       rpc_s_wrong_kind_of_binding
                     Wrong kind of binding for operation.

   In addition to the above values, status can return the value of
   parameter status from the application-defined authorization function
   (rpc_mgmt_authorization_fn_t).  The prototype for such a function is
   defined in the authorization_fn parameter in the reference page for
   rpc_mgmt_set_authorization_fn.

 DESCRIPTION

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

   A client (or management) application uses this routine when it wants
   to allow one-way authentication with the server specified by binding.
   This means that the client does not care which server principal
   receives the remote procedure call request.  However, the server
   verifies that the client is who the client claims to be.  For one-way
   authentication, a client calls this routine before calling
   rpc_binding_set_auth_info().

   A server application uses this routine to obtain the principal name
   it registered by calling rpc_server_register_auth_info().

   The RPC runtime allocates memory for the string returned in
   server_princ_name.  The application calls rpc_string_free() to
   deallocate that memory.

   By default, the RPC runtime allows all clients to call this routine
   remotely.  To restrict these calls, a server application supplies an
   authorization function by calling rpc_mgmt_set_authorization_fn().

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: 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