nf-bits2_5-ibackgroundcopyjobhttpoptions-getclientcertificate.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name
NF:bits2_5.IBackgroundCopyJobHttpOptions.GetClientCertificate	IBackgroundCopyJobHttpOptions::GetClientCertificate (bits2_5.h)	Retrieves the client certificate from the job.	GetClientCertificate GetClientCertificate method [BITS] GetClientCertificate method [BITS] IBackgroundCopyJobHttpOptions interface IBackgroundCopyJobHttpOptions interface [BITS] GetClientCertificate method IBackgroundCopyJobHttpOptions.GetClientCertificate IBackgroundCopyJobHttpOptions::GetClientCertificate bits.ibackgroundcopyjobhttpoptions_getclientcertificate bits2_5/IBackgroundCopyJobHttpOptions::GetClientCertificate	bits\ibackgroundcopyjobhttpoptions_getclientcertificate.htm	Bits	cd317bf9-1d4b-438e-beec-15ea7da90fc9	12/05/2018	GetClientCertificate, GetClientCertificate method [BITS], GetClientCertificate method [BITS],IBackgroundCopyJobHttpOptions interface, IBackgroundCopyJobHttpOptions interface [BITS],GetClientCertificate method, IBackgroundCopyJobHttpOptions.GetClientCertificate, IBackgroundCopyJobHttpOptions::GetClientCertificate, bits.ibackgroundcopyjobhttpoptions_getclientcertificate, bits2_5/IBackgroundCopyJobHttpOptions::GetClientCertificate	bits2_5.h	Bits.h	Windows	Windows Vista	Windows Server 2008					Bits2_5.idl					Bits.lib			Windows			19H1	IBackgroundCopyJobHttpOptions::GetClientCertificate bits2_5/IBackgroundCopyJobHttpOptions::GetClientCertificate	c++	APIRef kbSyntax	COM	Bits.lib Bits.dll	IBackgroundCopyJobHttpOptions.GetClientCertificate

IBackgroundCopyJobHttpOptions::GetClientCertificate

-description

Retrieves the client certificate from the job.

-parameters

-param pStoreLocation [out]

Identifies the location of a system store to use for looking up the certificate. For possible values, see the BG_CERT_STORE_LOCATION enumeration.

-param pStoreName [out]

Null-terminated string that contains the name of the certificate store. To free the string when done, call the CoTaskMemFree function.

-param ppCertHashBlob [out]

SHA1 hash that identifies the certificate. To free the blob when done, call the CoTaskMemFree function.

-param pSubjectName [out]

Null-terminated string that contains the simple subject name of the certificate. The RDNs in the subject name are in the reverse order from what the certificate displays. Subject name can be empty if the certificate does not contain a subject name. To free the string when done, call the CoTaskMemFree function.

-returns

The following table lists some of the possible return values.

Return code	Description
S_OK	Successfully retrieved the certificate.
RPC_X_BAD_STUB_DATA	The job does not specify a certificate or the user does not have permissions to the certificate.
RPC_X_NULL_REF_POINTER	One of the parameters is NULL.

-remarks

You use the IBackgroundCopyJobHttpOptions::SetClientCertificateByID or IBackgroundCopyJobHttpOptions::SetClientCertificateByName method to specify the certificate.

Examples

The following example shows how to retrieve information about the client certificate. The example assumes pJob points to a valid job.

#define THUMBPRINT_SIZE 20

  HRESULT hr = S_OK;
  IBackgroundCopyJob* pJob = NULL;
  IBackgroundCopyJobHttpOptions* pHttpOptions = NULL;
  GUID JobId;

  BG_CERT_STORE_LOCATION StoreLocation;
  LPWSTR pStoreName = NULL;
  BYTE* pThumbprint = NULL;
  LPWSTR pSubjectName = NULL;

  // Retrieve a pointer to the IBackgroundCopyJobHttpOptions interface.
  hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJobHttpOptions), (void**)&pHttpOptions);
  pJob->Release();
  if (FAILED(hr))
  {
    wprintf(L"pJob->QueryInterface failed with 0x%x.\n", hr);
    goto cleanup;
  }

  // Retrieve information about the client certificate set on the job. 
  hr = pHttpOptions->GetClientCertificate(&StoreLocation, &pStoreName, 
         &pThumbprint, &pSubjectName);
  if (S_OK == hr)
  {
    wprintf(L"\nLocation: %d\nStore name: %s\nSubject: %s\n", 
        StoreLocation, pStoreName, pSubjectName);

    wprintf(L"Thumbprint: ");
    for (DWORD i = 0; i < THUMBPRINT_SIZE; i++)
    {
      wprintf(L"%x ", pThumbprint[i]);
    }
    wprintf(L"\n");

    CoTaskMemFree(pStoreName);
    CoTaskMemFree(pThumbprint);
    CoTaskMemFree(pSubjectName);
  }
  else if (RPC_X_BAD_STUB_DATA == hr)
  {
    wprintf(L"The job does not specify a client certificate or\n"
            L"the user does not have permission to access the certificate.\n");
  }
  else
  {
    wprintf(L"pHttpOptions->GetClientCertificate failed with 0x%x.\n", hr);
    goto cleanup;
  }


cleanup:

  if (pHttpOptions)
  {
    hr = pHttpOptions->Release();
  }

-see-also

IBackgroundCopyJobHttpOptions

IBackgroundCopyJobHttpOptions::RemoveClientCertificate

IBackgroundCopyJobHttpOptions::SetClientCertificateByID

IBackgroundCopyJobHttpOptions::SetClientCertificateByName