CoQueryClientBlanket

[This is preliminary documentation and subject to change.]

Called by the server to find out about the client that invoked the method executing on the current thread.

HRESULT CoQueryClientBlanket(
  DWORD* pAuthnSvc, //Pointer to the current authentication service
  DWORD* pAuthzSvc, //Pointer to the current authorization service
  OLECHAR ** pServerPrincName,
                    //Pointer to the current principal name
  DWORD * pAuthnLevel,
                    //Pointer to the current authentication level
  DWORD * pImpLevel,
                    //Reserved for future use; must be NULL
  RPC_AUTHZ_HANDLE * pPrivs,
                    //Pointer to handle to privilege information
  DWORD ** pCapabilities
                    //Pointer to flags indicating further 
                    // capabilities of the proxy
);
 

Parameters

pAuthnSvc

[out] Pointer to a DWORD value defining the current authentication service. This will be a single value taken from the list of RPC_C_AUTHN_xxx constants. May be NULL, in which case the current authentication service is not returned.

pAuthzSvc

[out] Pointer to a DWORD value defining the current authorization service. This will be a single value taken from the list of RPC_C_AUTHZ_xxx constants. May be NULL, in which case the current authorization service is not returned.

pServerPrincName

[out] Pointer to the current principal name. The string will be allocated by the callee using CoTaskMemAlloc and must be freed by the caller using CoTaskMemFree when they are done with it. May be NULL, in which case the principal name is not returned. By default, SSL principal names will be in the msstd form. The fullsic form will be returned if EOAC_MAKE_FULLSIC is specified in the pCapabilities parameter. For more information on msstd and fullsic, see the SSL section of COM and Security Packages.

pAuthnLevel

[out] Pointer to a DWORD value defining the current authentication level. This will be a single value taken from the list of RPC_C_AUTHN_LEVEL_xxx constants. May be NULL, in which case the current authentication level is not returned.

pImpLevel

[out] Must be NULL. This parameter is reserved for future use.

pPrivs

[out] Pointer to a handle that indicates the privilege information for the client application. The format of the structure that the handle refers to depends on the authentication service. The application should not write or free the memory. The information is only valid for the duration of the current call. NULL may be returned, in which case the privilege information is not returned. For NTLMSSP, Kerberos, and SSL, this is the client's principal name.

pCapabilities

[in, out] Pointer to return flags indicating capabilities of the call. May be NULL, in which case the flags indicating capabilities are not returned. To request a fullsic SSL principal name, set the EOAC_MAKE_FULLSIC bit in the *pCapabilities. Notice that since this parameter was previously only an [out] parameter, you may have to clear the EOAC_MAKE_FULLSIC bit in *pCapabilities to get the msstd form. For more information on msstd and fullsic, see the SSL section of COM and Security Packages.

Return Values

S_OK

Success.

E_INVALIDARG

One or more arguments are invalid.

E_OUTOFMEMORY

Insufficient memory to create the pServerPrincName out-parameter.

Remarks

CoQueryClientBlanket is called by the server to get security information about the client that invoked the method executing on the current thread. This function encapsulates the following sequence of common calls (error handling excluded):

CoGetCallContext(IID_IServerSecurity, (void**)&pss);
    pss->QueryBlanket(pAuthnSvc, pAuthzSvc, pServerPrincName, 
                pAuthnLevel, pImpLevel, pPrivs, pCapabilities);
    pss->Release();
 

QuickInfo

  Windows NT: Use version 4.0 or later.
  Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in objbase.h.
  Import Library: Included as a resource in ole32.dll.

See Also

IServerSecurity::QueryBlanket, Security in COM