COM
Expand Minimize

CoQueryProxyBlanket function

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_opt_  DWORD *pwAuthnSvc,
  _Out_opt_  DWORD *pAuthzSvc,
  _Out_opt_  OLECHAR **pServerPrincName,
  _Out_opt_  DWORD *pAuthnLevel,
  _Out_opt_  DWORD *pImpLevel,
  _Out_opt_  RPC_AUTH_IDENTITY_HANDLE *pAuthInfo,
  _Out_opt_  DWORD *pCapabilites
);

Parameters

pProxy [in]

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

pwAuthnSvc [out, optional]

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.

pAuthzSvc [out, optional]

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.

pServerPrincName [out, optional]

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.

pAuthnLevel [out, optional]

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.

pImpLevel [out, optional]

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.

pAuthInfo [out, optional]

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.

pCapabilites [out, optional]

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->QueryInterface(IID_IClientSecurity, (void**)&pcs);
pcs->QueryBlanket(
    pProxy, pAuthnSvc, pAuthzSvc, pServerPrincName, pAuthnLevel, pImpLevel, ppAuthInfo, pCapabilities
  );
pcs->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

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Objbase.h

Library

Ole32.lib

DLL

Ole32.dll

See also

CoQueryClientBlanket
CoSetProxyBlanket
IClientSecurity::QueryBlanket
Security in COM

 

 

Community Additions

ADD
Show:
© 2014 Microsoft