CoQueryProxyBlanket function (combaseapi.h)

Article
10/13/2021

Retrieves the authentication information the client uses to make calls on the specified proxy. This is a helper function for IClientSecurity::QueryBlanket.

Syntax

HRESULT CoQueryProxyBlanket(
  [in]            IUnknown                 *pProxy,
  [out, optional] DWORD                    *pwAuthnSvc,
  [out, optional] DWORD                    *pAuthzSvc,
  [out, optional] LPOLESTR                 *pServerPrincName,
  [out, optional] DWORD                    *pAuthnLevel,
  [out, optional] DWORD                    *pImpLevel,
  [out, optional] RPC_AUTH_IDENTITY_HANDLE *pAuthInfo,
  [out, optional] DWORD                    *pCapabilites
);

Parameters

[in] pProxy

A pointer indicating the proxy to query. This parameter cannot be NULL. For more information, see the Remarks section.

[out, optional] pwAuthnSvc

A pointer to a variable that receives the current authentication service. This will be a single value taken from the authentication service constants. This parameter cannot be NULL.

[out, optional] pAuthzSvc

A pointer to a variable that receives the current authorization service. This will be a single value taken from the authorization constants. If the caller specifies NULL, the current authorization service is not retrieved.

[out, optional] pServerPrincName

The current principal name. The string will be allocated by the callee using CoTaskMemAlloc, and must be freed by the caller using CoTaskMemFree. The EOAC_MAKE_FULLSIC flag is not accepted in the pCapabilities parameter. For more information about the msstd and fullsic forms, see Principal Names. If the caller specifies NULL, the current principal name is not retrieved.

[out, optional] pAuthnLevel

A pointer to a variable that receives the current authentication level. This will be a single value taken from the authentication level constants. If the caller specifies NULL, the current authentication level is not retrieved.

[out, optional] pImpLevel

A pointer to a variable that receives the current impersonation level. This will be a single value taken from the impersonation level constants. If the caller specifies NULL, the current impersonation level is not retrieved.

[out, optional] pAuthInfo

A pointer to a handle that receives the identity of the client that was passed to the last IClientSecurity::SetBlanket call (or the default value). Default values are only valid until the proxy is released. If the caller specifies NULL, the client identity is not retrieved. The format of the structure that the handle refers to depends on the authentication service. The application should not write or free the memory. For NTLMSSP and Kerberos, if the client specified a structure in the pAuthInfo parameter to CoInitializeSecurity, that value is returned. For Schannel, if a certificate for the client could be retrieved from the certificate manager, that value is returned here. Otherwise, NULL is returned. See RPC_AUTH_IDENTITY_HANDLE.

[out, optional] pCapabilites

A pointer to a variable that receives the capabilities of the proxy. If the caller specifies NULL, the current capability flags are not retrieved.

Return value

This function can return the standard return values E_INVALIDARG, E_OUTOFMEMORY, and S_OK.

Remarks

CoQueryProxyBlanket is called by the client to retrieve the authentication information COM will use on calls made from the specified proxy. This function encapsulates the following sequence of common calls (error handling excluded):

pProxy-&gt;QueryInterface(IID_IClientSecurity, (void**)&amp;pcs);
pcs-&gt;QueryBlanket(
    pProxy, pAuthnSvc, pAuthzSvc, pServerPrincName, pAuthnLevel, pImpLevel, ppAuthInfo, pCapabilities
  );
pcs-&gt;Release();

This sequence calls QueryInterface on the proxy to get a pointer to IClientSecurity, and with the resulting pointer, calls IClientSecurity::QueryBlanket and then releases the pointer.

In pProxy, you can pass any proxy, such as a proxy you get through a call to CoCreateInstance or CoUnmarshalInterface, or you can pass an interface pointer. It can be any interface. You cannot pass a pointer to something that is not a proxy. Therefore, you can't pass a pointer to an interface that has the local keyword in its interface definition because no proxy is created for such an interface. IUnknown is the exception to this rule.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	combaseapi.h (include Objbase.h)
Library	Ole32.lib
DLL	Ole32.dll