RpcMgmtSetAuthorizationFn

The RpcMgmtSetAuthorizationFn function establishes an authorization function for processing remote calls to a server's management routines.

This function is supported only by Windows NT.

#include <rpc.h>
RPC_STATUS RPC_ENTRY RpcMgmtSetAuthorizationFn( 
  RPC_MGMT_AUTHORIZATION_FN  AuthorizationFn  
);
 

Parameters

AuthorizationFn

Specifies an authorization function. The RPC server run-time library automatically calls this function whenever the server runtime receives a client request to execute one of the remote management routines. The server must implement this function. Applications specify NULL to unregister a previously registered authorization function. After such a call, default authorizations are used.

Remarks

Server applications call the RpcMgmtSetAuthorizationFn routine to establish an authorization function that controls access to the server's remote management routines. When a server has not called RpcMgmtSetAuthorizationFn, or calls with a NULL value for AuthorizationFn, the server run-time library uses the following default authorizations:

In the above table, "Enabled" indicates that all clients can execute the remote routine, and "Disabled" indicates that all clients are prevented from executing the remote routine.

The following example shows the prototype for authorization function that the server must implement:

typedef boolean32  (*RPC_MGMT_AUTHORIZATION_FN)
   (
   RPC_BINDING_HANDLE      ClientBinding               /* in */
   unsigned long           RequestedMgmtOperation      /* in */
   RPC_STATUS *            Status                      /* out */
   );
 

When a client requests one of the server's remote management functions, the server run-time library calls the authorization function with ClientBinding and RequestedMgmtOperation. The authorization function uses these parameters to determine whether the calling client can execute the requested management routine.

The value for RequestedMgmtOperation depends on the remote routine requested, as shown in the following:

The authorization function must handle all of these values.

The authorization function returns a Boolean value to indicate whether the calling client is allowed access to the requested management function. If the authorization function returns TRUE, the management routine can execute. If the authorization function returns FALSE, the management routine cannot execute. If this is the case, the routine returns a Status value to the client:

• If Status is either 0 (zero) or RPC_S_OK, the Status value RPC_S_ACCESS_DENIED is returned to the client by the remote management routine.
• If the authorization function returns any other value for Status, that Status value is returned to the client by the remote management routine.

Return Values

QuickInfo

  Windows NT: Yes
  Windows CE: Unsupported.
  Header: Declared in rpcdce.h.
  Import Library: Link with rpcrt4.lib.

See Also

RpcMgmtInqStats, RpcMgmtIsServerListening, RpcMgmtStopServerListening, RpcMgmtWaitServerListen