IClientSecurity::QueryBlanket

Retrieves authentication information the client uses to make calls on the specified proxy.

HRESULT QueryBlanket(
  IUnknown*  pProxy,    //Pointer to the interface whose proxy 
                        // will be queried
  DWORD*  pAuthnSvc,    //Location for the current authentication 
                        // service
  DWORD*  pAuthzSvc,    //Location for the current authorization 
                        // service
  OLECHAR**  pServerPrincName,
                        //Location for the current principal name
  DWORD* pAuthnLevel,   //Location for the current authentication 
                        // level
  DWORD* pImpLevel,     //Location for the current impersonation 
                        // level
  RPC_AUTH_IDENTITY_HANDLE*  pAuthInfo, 
                        //Location of a handle that indicates the 
                        // client identity 
  DWORD*  pCapabilities //Location for flags indicating further 
                        // capabilities of the proxy
);
 

Parameters

pProxy

[in] Pointer indicating the proxy to query. It may not be NULL. For more information, see the Remarks section.

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. If the caller specifies NULL, the current authentication service is not retrieved.

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. If the caller specifies NULL, the current authorization service is not retrieved.

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. Notice that the actual principal name is returned. The EOAC_MAKE_FULLSIC flag is not accepted to convert the prinicpal name. If the caller specifies NULL, the current principal name is not retrieved.

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. If the caller specifies NULL, the current authentication level is not retrieved.

pImpLevel

[out] Pointer to a DWORD value defining the current impersonation level. This will be a single value taken from the list of RPC_C_IMP_LEVEL_xxx constants. If the caller specifies NULL, the current impersonation level is not retrieved. When using NTLMSSP, this value could be RPC_IMP_LEVEL_IDENTIFY or RPC_IMP_LEVEL_IMPERSONATE. When using NTLMSSP on NT 5.0, cross-apartment or cross-process, this value can be RPC_IMP_LEVEL_DELEGATE. When using Kerberos, it can be RPC_IMP_LEVEL_IDENTIFY, RPC_IMP_LEVEL_IMPERSONATE, or RPC_C_IMP_LEVEL_DELEGATE.

pAuthInfo

[out] Pointer to a handle indicating 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 returned handle refers to depends on the authentication service. For NTLMSSP and Kerberos, if the client specified a structure in the pAuthInfo parameter to CoInitializeSecurity, that value is returned. Because this points to the value itself and is not a copy, it should not be manipulated or freed. For SSL, if DCOM could get a private certificate from the certificate manager for the client, that value is returned here. Otherwise, NULL is returned.

pCapabilities

[out] Pointer to a DWORD of flags indicating the capabilities of the proxy. May be NULL, in which case the flags are not retrieved. On NT 5, these may be EOAC_STATIC_CLOAKING, or EOAC_DYNAMIC_CLOAKING, or EOAC_ANY_AUTHORITY. If the caller specifies NULL, the current capability flags are not retrieved.

Return Values

S_OK

Success.

E_INVALIDARG

One or more arguments are invalid.

E_OUTOFMEMORY

Insufficient memory to create the pServerPrincName out-parameter.

Remarks

IClientSecurity::QueryBlanket is called by the client to retrieve the authentication information COM will use on calls made from the specified interface proxy. With a pointer to an interface on the proxy, the client would first call QueryInterface for a pointer to IClientSecurity; then, with this pointer, the client would call IClientSecurity::QueryBlanket, followed by releasing the pointer. This sequence of calls is encapsulated in the helper function CoQueryProxyBlanket.

In pProxy, you pass an interface pointer. However, you cannot pass a pointer to an interface that does not use a proxy. Thus you can't pass a pointer to an interface that has the local keyword in its interface definition since no proxy is created for such an interface. IUnknown is the exception to this rule.

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 objidl.h.

See Also

CoQueryProxyBlanket