Background Intelligent Transfer Service

Version 1.0

Purpose

The Microsoft® Background Intelligent Transfer Service (BITS) provides the documentation and samples necessary to write client applications that transfer files between a client and server and to monitor jobs within the transfer queue.

Where Applicable

Use BITS for applications that need to transfer files asynchronously, in the foreground or background, and automatically resume file transfers after network disconnects and machine reboots.

Developer Audience

This documentation is written for C/C++ developers.

Run-time Requirements

Requires Whistler.

About BITS

General information about BITS.

BITS Reference

Reference information for the BITS interfaces.

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Tuesday, February 06, 2001.


Legal Information

Background Intelligent Transfer Service

This is a preliminary document and may be changed substantially prior to final commercial release. This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document. Information in this document, including URL and other Internet Web site references, is subject to change without notice. The entire risk of the use or the results of the use of this document remains with the user. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unpublished work. © 2001 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows NT, are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


About BITS

[This is preliminary documentation and subject to change.]

Use Background Intelligent Transfer Service (BITS) to request asynchronous file transfers between a client and server. File transfers automatically resume after network disconnects and machine reboots. To manage file transfers, BITS uses a queue where you can prioritize transfer requests and specify whether the files are transferred in the foreground or background. You use the BITS interfaces to create applications that transfer files and monitor jobs within the queue.


BITS Reference

The Background Intelligent Transfer Service (BITS) reference section contains detailed information about the enumeration types, interfaces, and structures that you use to create applications that transfer files between a client and a server.

BITS version 1.0 supports HTTP and HTTPS downloads and requires an HTTP 1.1 compliant server as a source.


BITS Enumeration Types

The Background Intelligent Transfer Service (BITS) interfaces use the following enumeration types.

Enumeration type | Purpose
BG_ERROR_CONTEXT | Defines the constant values for the different contexts in which errors can occur.
BG_JOB_PRIORITY | Defines the constant values for job priority levels that you specify.
BG_JOB_PROXY_USAGE | Defines the constant values that specify which proxy to use for file transfers.
BG_JOB_STATE | Defines the constant values for the states of a job.
BG_JOB_TYPE | Defines the constant values for the type of transfer job, such as HTTP download.


BG_ERROR_CONTEXT

The BG_ERROR_CONTEXT enumeration type defines the contexts in which errors can occur.

typedef enum
{
  BG_ERROR_CONTEXT_NONE = 0,
  BG_ERROR_CONTEXT_UNKNOWN = 1,
  BG_ERROR_CONTEXT_GENERAL_QUEUE_MANAGER = 2,
  BG_ERROR_CONTEXT_QUEUE_MANAGER_NOTIFICATION = 3,
  BG_ERROR_CONTEXT_LOCAL_FILE = 4,
  BG_ERROR_CONTEXT_REMOTE_FILE = 5,
  BG_ERROR_CONTEXT_GENERAL_TRANSPORT = 6
} BG_ERROR_CONTEXT;

Enumeration Values

BG_ERROR_CONTEXT_NONE
An error has not occurred.
BG_ERROR_CONTEXT_UNKNOWN
The error context is unknown.
BG_ERROR_CONTEXT_GENERAL_QUEUE_MANAGER
The transfer queue manager generated the error.
BG_ERROR_CONTEXT_QUEUE_MANAGER_NOTIFICATION
The error was generated while the queue manager was notifying the client of an event.
BG_ERROR_CONTEXT_LOCAL_FILE
The error was related to the specified local file. For example, permission was denied or the volume was unavailable.
BG_ERROR_CONTEXT_REMOTE_FILE
The error was related to the specified remote file. For example, the URL is not accessible.
BG_ERROR_CONTEXT_GENERAL_TRANSPORT
The transport layer (for example, HTTP or HTTPS) generated the error while transferring the file.

See Also

IBackgroundCopyError::GetError, IBackgroundCopyError::GetErrorContextDescription


BG_JOB_PRIORITY

The BG_JOB_PRIORITY enumeration type defines the job priority levels that you specify. The priority level determines when the job is processed relative to other jobs in the transfer queue. In general, a job with a higher priority will preempt all lower priority jobs; however, the service does not guarantee the order in which jobs are completed—a lower priority job could complete before a higher priority job.

typedef enum
{
  BG_JOB_PRIORITY_FOREGROUND,
  BG_JOB_PRIORITY_HIGH,
  BG_JOB_PRIORITY_NORMAL,
  BG_JOB_PRIORITY_LOW
} BG_JOB_PRIORITY;

Enumeration Values

BG_JOB_PRIORITY_FOREGROUND
Transfers the job in the foreground. Foreground transfers compete for network bandwidth with other applications, which can impede the user experience.
BG_JOB_PRIORITY_HIGH
Transfers the job in the background. Background transfers only transfer data when there is unused network bandwidth. This is the highest background priority level.
BG_JOB_PRIORITY_NORMAL
Transfers the job in the background. Background transfers only transfer data when there is unused network bandwidth. This is the default priority level.
BG_JOB_PRIORITY_LOW
Transfers the job in the background. Background transfers only transfer data when there is unused network bandwidth. This is the lowest background priority level.

See Also

IBackgroundCopyJob::GetPriority, IBackgroundCopyJob::SetPriority


BG_JOB_PROXY_USAGE

The BG_JOB_PROXY_USAGE enumeration type defines which proxy to use for file transfers. You can define the proxy settings for each job.

typedef enum
{
  BG_JOB_PROXY_USAGE_PRECONFIG,
  BG_JOB_PROXY_USAGE_NO_PROXY,
  BG_JOB_PROXY_USAGE_OVERRIDE
} BG_JOB_PROXY_USAGE;

Enumeration Values

BG_JOB_PROXY_USAGE_PRECONFIG
Use the proxy and proxy bypass list settings defined by each user to transfer files. Settings are user-defined from Control Panel, Internet Options, Connections, Local Area Network (LAN) settings or Dial-up settings, depending on the network connection.
BG_JOB_PROXY_USAGE_NO_PROXY
Do not use a proxy to transfer files. Use this option when you transfer files within a LAN.
BG_JOB_PROXY_USAGE_OVERRIDE
Use the application's proxy and proxy bypass list to transfer files. Use this option when you cannot trust that the system settings are correct, or when you want to use a special account to transfer files, such as LocalSystem, to which the system settings do not apply.

See Also

IBackgroundCopyJob::GetProxySettings, IBackgroundCopyJob::SetProxySettings


BG_JOB_STATE

The BG_JOB_STATE enumeration type defines the states of a job.

typedef enum
{
  BG_JOB_STATE_QUEUED,
  BG_JOB_STATE_CONNECTING,
  BG_JOB_STATE_TRANSFERRING,
  BG_JOB_STATE_SUSPENDED,
  BG_JOB_STATE_ERROR,
  BG_JOB_STATE_TRANSIENT_ERROR,
  BG_JOB_STATE_TRANSFERRED,
  BG_JOB_STATE_ACKNOWLEDGED,
  BG_JOB_STATE_CANCELLED
} BG_JOB_STATE;

Enumeration Values

BG_JOB_STATE_QUEUED
Specifies that the job is in the queue and waiting to run.
BG_JOB_STATE_CONNECTING
Specifies that BITS is trying to connect to the server. If the connection succeeds, the state of the job becomes BG_JOB_STATE_TRANSFERRING; otherwise, the state becomes BG_JOB_STATE_TRANSIENT_ERROR.
BG_JOB_STATE_TRANSFERRING
Specifies that BITS is transferring data for the job.
BG_JOB_STATE_SUSPENDED
Specifies that the job is paused. The job is paused if the IBackgroundCopyJob::Suspend method was called, or if the user who scheduled the job is not logged on. The job remains suspended until you call the IBackgroundCopyJob::Resume, IBackgroundCopyJob::Complete, or IBackgroundCopyJob::Cancel method.
BG_JOB_STATE_ERROR
Specifies that a non-recoverable error occurred (the service is unable to transfer the file). When the error can be corrected, such as an access-denied error, call the IBackgroundCopyJob::Resume method after the error is fixed. However, if the error cannot be corrected, call the IBackgroundCopyJob::Cancel method to cancel the job, or call the IBackgroundCopyJob::Complete method to accept the portion of the job that transferred successfully.
BG_JOB_STATE_TRANSIENT_ERROR
Specifies that a recoverable error occurred. The service tries to recover from the transient error until the retry time value that you specify using the IBackgroundCopyJob::SetNoProgressTimeout method expires. If the retry time expires, the job state changes to BG_JOB_STATE_ERROR.
BG_JOB_STATE_TRANSFERRED
Specifies that your job was successfully processed. You must call the IBackgroundCopyJob::Complete method to acknowledge completion of the job and to save the files to the client.
BG_JOB_STATE_ACKNOWLEDGED
Specifies that you called the IBackgroundCopyJob::Complete method to acknowledge that your job completed successfully.
BG_JOB_STATE_CANCELLED
Specifies that you called the IBackgroundCopyJob::Cancel method to cancel the job (remove the job from the transfer queue).

See Also

IBackgroundCopyJob::GetState


BG_JOB_TYPE

The BG_JOB_TYPE enumeration type defines the type of transfer job, such as download.

typedef enum
{
  BG_JOB_TYPE_DOWNLOAD
} BG_JOB_TYPE;

Enumeration Values

BG_JOB_TYPE_DOWNLOAD
Specifies that the job downloads files to the client.

See Also

IBackgroundCopyJob::GetType, IBackgroundCopyManager::CreateJob


BITS Interfaces

Use the following Background Intelligent Transfer Service (BITS) interfaces to transfer files and monitor jobs within the transfer queue.

Interface | Description
IBackgroundCopyManager | Use to create transfer jobs, retrieve an enumerator object of jobs in the queue, and to retrieve individual jobs from the queue.
IBackgroundCopyJob | Use to add files to the job, set the priority level of the job, determine the state of the job, and to start and stop the job.
IBackgroundCopyFile | Use to retrieve the local and remote file names of a file transfer request in the job and its progress.
IBackgroundCopyError | Use the information in this interface to resolve fatal errors.
IBackgroundCopyCallback | Clients implement the IBackgroundCopyCallback interface to receive notification that a job is complete, has been modified, or is in error.
IEnumBackgroundCopyJobs | Use to enumerate jobs in the transfer queue.
IEnumBackgroundCopyFiles | Use to enumerate files in the job.


IBackgroundCopyCallback

Implement the IBackgroundCopyCallback interface to receive notification that a job is complete, has been modified, or is in error. Clients use the IBackgroundCopyCallback interface as an option to polling for the state of the job.

To receive job event notifications, you can pass BITS an interface pointer using the IBackgroundCopyJob::SetNotifyInterface method, or pass a CLSID in either the IBackgroundCopyManger::CreateJob method or the IBackgroundCopyJob::SetNotifyClass method. If you specify a callback interface pointer and a callback CLSID, BITS will use the interface pointer as long as it is valid. If the interface pointer becomes invalid (for example, the client exits), BITS will use the CLSID for notification.

Use the callback CLSID if your client is not loaded but needs to receive events. The service creates a new instance, if necessary, using the CLSID.

You must implement all methods of the IBackgroundCopyCallback interface. At a minimum, the method must return S_OK.

The following table lists the methods in IBackgroundCopyCallback.

Method | Description
JobTransferred | Implement this method to receive notification when all of the file transfers for the job are complete.
JobError | Implement this method to receive notification when an error occurs.
JobModification | Implement this method to receive notification when a job is modified.

Example Code

The following example shows an IBackgroundCopyCallback implementation. For an example that calls this implementation, see the IBackgroundCopyJob::SetNotifyInterface method.

class CNotifyInterface : public IBackgroundCopyCallback
{
  LONG m_lRefCount;

public:

  //Constructor, Destructor
  CNotifyInterface() {m_lRefCount = 1;};
  ~CNotifyInterface() {};

  //IUnknown
  HRESULT __stdcall QueryInterface(REFIID riid, LPVOID *ppvObj);
  ULONG __stdcall AddRef();
  ULONG __stdcall Release();

  //IBackgroundCopyCallback methods
  HRESULT __stdcall JobTransferred(IBackgroundCopyJob *pJob);
  HRESULT __stdcall JobError(IBackgroundCopyJob *pJob, IBackgroundCopyError *pError);
  HRESULT __stdcall JobModification(IBackgroundCopyJob *pJob, DWORD dwReserved);

};

HRESULT CNotifyInterface::QueryInterface(REFIID riid, LPVOID *ppvObj)
{
  if( riid == IID_IUnknown || riid == IID_IBackgroundCopyCallback )
  {
    *ppvObj = this;
  }
  else
  {
    *ppvObj = NULL;
    return E_NOINTERFACE;
  }

  AddRef();
  return NOERROR;
}

ULONG CNotifyInterface::AddRef()
{
  return InterlockedIncrement(&m_lRefCount);
}

ULONG CNotifyInterface::Release()
{
  ULONG  ulCount = InterlockedDecrement(&m_lRefCount);

  if(0 == ulCount)
  {
    delete this;
  }

  return ulCount;
}

HRESULT CNotifyInterface::JobTransferred(IBackgroundCopyJob *pJob)
{
  WCHAR  *pszJobName;

  pJob->GetDisplayName(&pszJobName);
  MessageBox(HWND_DESKTOP, pszJobName, L"Job Transferred", MB_OK);
  CoTaskMemFree(pszJobName);

  return S_OK;
}

HRESULT CNotifyInterface::JobError(IBackgroundCopyJob *pJob, IBackgroundCopyError *pError)
{
  WCHAR  *pszJobName;
  WCHAR  *pszErrorDescription;
  WCHAR  *pszMessage;

  pJob->GetDisplayName(&pszJobName);
  pError->GetErrorDescription(MAKELANGID(LANG_ENGLISH, SUBLANG_ENGLISH_US),
                              &pszErrorDescription);

  pszMessage = (WCHAR *)_alloca(wcslen(pszJobName) + wcslen(pszErrorDescription + 2));
  wsprintf(pszMessage, L"%s\n%s", pszJobName, pszErrorDescription);
  MessageBox(HWND_DESKTOP, pszMessage, L"Job Error", MB_OK);

  CoTaskMemFree(pszJobName);
  CoTaskMemFree(pszErrorDescription);

  return S_OK;
}

HRESULT CNotifyInterface::JobModification(IBackgroundCopyJob *pJob)
{
  WCHAR  *pszJobName = NULL;
  WCHAR  *pszMessage = NULL;
  BG_JOB_PROGRESS  Progress;

  pJob->GetDisplayName(&pszJobName);
  pJob->GetProgress(&Progress);

  pszMessage = (WCHAR *)_alloca(wcslen(pszJobName) + 15);  //15 for bytes string
  wsprintf(pszMessage, L"%s\n%I64d", pszJobname, Progress.BytesTransferred);
  MessageBox(HWND_DESKTOP, pszMessage, L"Job Modified", MB_OK);

  CoTaskMemFree(pszJobName);

  return S_OK;
}

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob, IBackgroundCopyJob::SetNotifyClass, IBackgroundCopyJob::SetNotifyFlags, IBackgroundCopyJob::SetNotifyInterface, IBackgroundCopyManager::CreateJob


IBackgroundCopyCallback::JobTransferred

BITS calls the client's implementation of the JobTransferred method when all of the files in the job have been successfully transferred.

HRESULT JobTransferred(
  IBackgroundCopyJob* pJob
);

Parameters

pJob
[in] Contains job-related information, such as the time the job completed, the number of bytes transferred, and the number of files transferred. Do not release pJob; BITS releases the interface when the method returns.

Return Values

This method should return S_OK; otherwise, the service continues to call this method until S_OK is returned.

Remarks

You must call the pJob::Complete method to acknowledge that BITS successfully transferred the files and to make the files available to the client. If you do not call the pJob::Complete method or the pJob::Cancel method within 90 days (default JobInactivityTimeout policy), the service cancels the job.

Note that BITS calls the implementation until you either acknowledge the transfer of the files or the 90-day inactivity period expires. The interval at which the implementation is called is arbitrary.

BITS does not guarantee the integrity of the transferred files against third-party intrusions. Clients can implement integrity checks to validate transferred files after calling the pJob::Complete method.

Example Code

See the example code for the IBackgroundCopyCallback interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyCallback, IBackgroundCopyCallback::JobError, IBackgroundCopyJob, IBackgroundCopyJob::Complete, IBackgroundCopyJob::Cancel


IBackgroundCopyCallback::JobError

BITS calls the client's implementation of the JobError method when the state of the job changes to BG_JOB_STATE_ERROR.

HRESULT JobError(
  IBackgroundCopyJob* pJob,
  IBackgroundCopyError* pError
);

Parameters

pJob
[in] Contains job-related information, such as the number of bytes and files transferred before the error occurred. It also contains the methods to resume and cancel the job. Do not release pJob; BITS releases the interface when the method returns.
pError
[in] Contains error information, such as the file being processed at the time the fatal error occurred and a description of the error. Do not release pError; BITS releases the interface when the method returns.

Return Values

This method should return S_OK; otherwise, the service continues to call this method until you return S_OK.

Remarks

After you determine the cause of the error, perform one of the following options:

  • To cancel the job, call the pJob::Cancel method.
  • To accept the portion of the job that transferred successfully before the error occurred, call the pJob::Complete method.
  • To finish processing the job, fix the problem, and then call the pJob::Resume method.

If the job remains in an error state for 90 days (default JobInactivityTimeout policy), the service deletes the job and temporary files.

Transient errors do not generate a call to the JobError method.

Example Code

See the example code for the IBackgroundCopyCallback interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyCallback, IBackgroundCopyCallback::JobTransferred, IBackgroundCopyError, IBackgroundCopyJob, IBackgroundCopyJob::Cancel, IBackgroundCopyJob::Resume


IBackgroundCopyCallback::JobModification

BITS calls the client's implementation of the JobModification method when the job has been modified. The service generates this event when bytes are transferred, files have been added to the job, properties have been modified, or the state of the job has changed.

HRESULT JobModification(
  IBackgroundCopyJob* pJob,
  DWORD dwReserved
);

Parameters

pJob
[in] Contains the methods for accessing property, progress, and state information of the job. Do not release pJob; BITS releases the interface when the method returns.
dwReserved
[in] Reserved for future use.

Return Values

This method should return S_OK.

Remarks

Your implementation may not receive all modification events under maximum resource load conditions.

The default notification flags that are set when you call the IBackgroundCopyManager::CreateJob method and pass a callback CLSID exclude the JobModification callback. To receive the JobModification callback, call the IBackgroundCopyJob::SetNotifyFlags method and include the BG_NOTIFY_JOB_MODIFICATION flag.

Example Code

See the example code for the IBackgroundCopyCallback interface.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyCallback, IBackgroundCopyJob


IBackgroundCopyError

Use the information in the IBackgroundCopyError interface to determine the cause of the error and if the transfer process can proceed. BITS only generates an error object when the state of the job is BG_JOB_STATE_ERROR. The service does not create an error object when a call to an IBackgroundCopyXXXX interface method fails.

To get an IBackgroundCopyError object, call the IBackgroundCopyJob::GetError method. Note that the error interface is only available after an error occurs (BG_JOB_STATE_ERROR) and before BITS begins transferring data (BG_JOB_STATE_TRANSFERRING).

The following table lists the methods in IBackgroundCopyError.

Method | Description
GetError | Retrieves the error code.
GetErrorContextDescription | Retrieves a description of the context in which the error occurred.
GetErrorDescription | Retrieves a description of the error.
GetFile | Retrieves the file object associated with the error.
GetProtocol | Retrieves the protocol used to transfer the file.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

BG_JOB_STATE, IBackgroundCopyJob::GetError, IBackgroundCopyJob::GetState, IBackgroundCopyCallback::JobError, IBackgroundCopyManager::GetErrorDescription


IBackgroundCopyError::GetError

Use the GetError method to retrieve the error code and identify the context in which the error occurred.

HRESULT GetError(
  BG_ERROR_CONTEXT* pContext,
  HRESULT* pErrorCode
);

Parameters

pContext
[out] Context in which the error occurred. For a list of context values, see the BG_ERROR_CONTEXT enumeration type.
pErrorCode
[out] Error code generated by the error condition.

Return Values

This method always returns S_OK.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyError::GetErrorContextDescription, IBackgroundCopyError::GetErrorDescription, IBackgroundCopyError::GetFile


IBackgroundCopyError::GetErrorContextDescription

Use the GetErrorContextDescription method to retrieve the description of the context in which the error occurred.

HRESULT GetErrorContextDescription(
  DWORD LanguageId,
  LPWSTR* ppContextDescription
);

Parameters

LanguageId
[in] Identifies the locale to use to generate the description. To create the language identifier, use the MAKELANGID macro. For example, to specify US English, use the following code sample.
MAKELANGID(LANG_ENGLISH, SUBLANG_ENGLISH_US)
ppContextDescription
[out] Description of the context in which the error occurred. Use the CoTaskMemFree function to free ppContextDescription.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
E_OUTOFMEMORY | Not enough memory is available to complete the operation.
E_INVALIDARG | The LanguageId parameter cannot be 0.
BG_E_LANGUAGE_NOT_FOUND | No string is available for the locale.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyError::GetError, IBackgroundCopyError::GetErrorDescription, IBackgroundCopyError::GetFile


IBackgroundCopyError::GetErrorDescription

Use the GetErrorDescription method to retrieve the description of the error.

HRESULT GetErrorDescription(
  DWORD LanguageId,
  LPWSTR* ppErrorDescription
);

Parameters

LanguageId
[in] Identifies the locale to use to generate the description. To create the language identifier, use the MAKELANGID macro. For example, to specify US English, use the following code sample.
MAKELANGID(LANG_ENGLISH, SUBLANG_ENGLISH_US)
ppErrorDescription
[out] Description of the error. Use the CoTaskMemFree function to free ppErrorDescription.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
E_OUTOFMEMORY | Not enough memory is available to complete the operation.
E_INVALIDARG | The LanguageId parameter cannot be 0.
BG_E_LANGUAGE_NOT_FOUND | No string is available for the locale.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyError::GetError, IBackgroundCopyError::GetErrorContextDescription, IBackgroundCopyError::GetFile, IBackgroundCopyManager::GetErrorDescription


IBackgroundCopyError::GetFile

Use the GetFile method to retrieve the file object associated with the error.

HRESULT GetFile(
  IBackgroundCopyFile** ppFile
);

Parameters

ppFile
[out] File object associated with the error. The file object contains the local and remote file names and indicates the progress made before the error occurred. When done, release ppFile.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
BG_E_FILE_NOT_AVAILABLE | File object is not available.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyError::GetError, IBackgroundCopyError::GetErrorContextDescription, IBackgroundCopyError::GetErrorDescription


IBackgroundCopyError::GetProtocol

Use the GetProtocol method to retrieve the remote file protocol that caused the error.

HRESULT GetProtocol(
  LPWSTR* ppProtocol
);

Parameters

ppProtocol
[out] Protocol used to transfer the file. Use the CoTaskMemFree function to free ppProtocol.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
BG_E_PROTOCOL_NOT_AVAILABLE | Protocol associated with the remote file is not available.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyError


IBackgroundCopyFile

The IBackgroundCopyFile interface contains information about a file that is part of a job. To get an IBackgroundCopyFile interface pointer, call the IBackgroundCopyError::GetFile method or the IEnumBackgroundCopyFiles::Next method.

The following table lists the methods in IBackgroundCopyFile.

Method | Description
GetLocalName | Retrieves the local name of the file.
GetProgress | Retrieves information to determine the progress of the file transfer.
GetRemoteName | Retrieves the remote name of the file.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyError, IBackgroundCopyJob, IEnumBackgroundCopyFiles


IBackgroundCopyFile::GetLocalName

Use the GetLocalName method to retrieve the local name of the file.

HRESULT GetLocalName(
  LPWSTR* ppName
);

Parameters

ppName
[out] Name of the file on the client. The name is fully qualified. Use the CoTaskMemFree function to free ppName.

Return Values

This method always returns S_OK.

Remarks

The local file name is set when you call the AddFile or AddFileSet methods of the IBackgroundCopyJob interface.

Example Code

The following example shows how to retrieve the local and remote file names associated with the file being transferred. The example also shows how to retrieve progress-related information.

#define BYTES_COMPLETE_LEN 50

HRESULT LoadFileProps(HWND hdlg, IBackgroundCopyFile *pFile)
{
  HRESULT  hr = 0;
  WCHAR *pszFileName;
  WCHAR  szBytes[BYTES_COMPLETE_LEN];
  BG_FILE_PROGRESS  Progress;

  hr = pFile->GetLocalName(&pszFileName);
  SetWindowText(GetDlgItem(hdlg, IDC_LOCALNAME), pszFileName);
  CoTaskMemFree(pszFileName);

  hr = pFile->GetRemoteName(&pszFileName);
  SetWindowText(GetDlgItem(hdlg, IDC_REMOTENAME), pszFileName);
  CoTaskMemFree(pszFileName);

  hr = pFile->GetProgress(&Progress);
  SetWindowText(GetDlgItem(hdlg, IDC_COMPLETE),
                (Progress.Completed) ? L"Complete" : L"Not Complete");

  wsprintf(szBytes, L"%I64d of %s", Progress.BytesTransferred,
           (Progress.BytesTotal == BG_SIZE_UNKNOWN) ? L"Unknown" : _ui64tow(Progress.BytesTotal, szTemp, 10));

  SetWindowText(GetDlgItem(hdlg, IDC_BYTESCOMPLETE), szBytes);

  return hr;
}

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyFile, IBackgroundCopyFile::GetRemoteName, IBackgroundCopyJob::AddFile, IBackgroundCopyJob::AddFileSet


IBackgroundCopyFile::GetProgress

Use the GetProgress method to retrieve information on the progress of the file transfer.

HRESULT GetProgress(
  BG_FILE_PROGRESS* pProgress
);

Parameters

pProgress
[out] Structure whose members indicate the progress of a file being transferred to the client. For details on the type of progress information available, see the BG_FILE_PROGRESS structure. The progress is snapshot in time.

Return Values

This method always returns S_OK.

Example Code

See the example code for the IBackgroundCopyFile::GetLocalName method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

BG_FILE_PROGRESS, IBackgroundCopyFile, IBackgroundCopyJob::GetProgress


IBackgroundCopyFile::GetRemoteName

Use the GetRemoteName method to retrieve the remote file name of the file.

HRESULT GetRemoteName(
  LPWSTR* ppName
);

Parameters

ppName
[out] Remote name of the file to transfer to the client. The name is fully qualified. Use the CoTaskMemFree function to free ppName.

Return Values

This method always returns S_OK.

Remarks

The remote file name is set when you call the AddFile or AddFileSet methods of the IBackgroundCopyJob interface.

Example Code

See the example code for the IBackgroundCopyFile::GetLocalName method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyFile, IBackgroundCopyFile::GetLocalName, IBackgroundCopyJob::AddFile, IBackgroundCopyJob::AddFileSet


IBackgroundCopyJob

Use the IBackgroundCopyJob interface to add files to the job, set the priority level of the job, determine the state of the job, and to start and stop the job.

To create a job, you use the IBackgroundCopyManager::CreateJob method.

The following table lists the methods in IBackgroundCopyJob.

Method | Description
AddFile | Adds a single file to the job.
AddFileSet | Adds multiple files to the job.
Cancel | Cancels the job and removes temporary files from the client.
Complete | Ends the job and saves the transferred files on the client.
EnumFiles | Returns an enumerator object that you use to enumerate the files in the job.
GetDescription | Retrieves the short description of the job.
GetDisplayName | Retrieves the display name that identifies the job.
GetError | Retrieves the error object after an error occurs.
GetId | Retrieves the identifier of the job in the queue.
GetInterruptionCount | Retrieves the number of times the job was interrupted by network failure or server unavailability.
GetMinimumRetryDelay | Retrieves the minimum length of time that the service waits after encountering a transient error condition before trying to transfer the file.
GetNoProgressTimeout | Retrieves the length of time that the service continues to try to transfer the file after encountering a transient error condition.
GetNotifyClass | Retrieves the CLSID that identifies your implementation of the IBackgroundCopyCallback interface.
GetNotifyFlags | Retrieves the event notification (callback) flags you have set for your application.
GetNotifyInterface | Retrieves a pointer to an object that implements the IBackgroundCopyCallback interface.
GetOwner | Retrieves the job owner's identity.
GetPriority | Retrieves the priority level you have set for the job.
GetProgress | Retrieves job-related progress information, such as the number of bytes and files transferred to the client.
GetProxySettings | Retrieves the proxy settings the job uses to transfer the files.
GetTimes | Retrieves timestamps for activities related to the job, such as the time the job was created.
GetType | Retrieves the type of transfer being performed, such as a file download.
GetState | Retrieves the state of the job.
Resume | Restarts a suspended job.
SetDescription | Specifies a short description of the job.
SetDisplayName | Specifies a display name that identifies the job in a user interface.
SetMinimumRetryDelay | Specifies the minimum length of time that the service waits after encountering a transient error condition before trying to transfer the file.
SetNoProgressTimeout | Specifies the length of time that the service continues to try to transfer the file after encountering a transient error condition.
SetNotifyClass | Specifies the CLSID that identifies your implementation of the IBackgroundCopyCallback interface. The class receives notification of specific job-related events.
SetNotifyFlags | Specifies the type of event notification you want to receive.
SetNotifyInterface | Specifies an object that implements the IBackgroundCopyCallback interface. The interface receives notification of specific job-related events.
SetPriority | Specifies the priority of your job relative to other jobs in the transfer queue.
SetProxySettings | Specifies which proxy to use to transfer the files.
Suspend | Pauses the job.
TakeOwnership | Changes the ownership of the job to the current user.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyFile, IEnumBackgroundCopyJobs, IBackgroundCopyManager


IBackgroundCopyJob::AddFile

Use the AddFile method to add a single file to the job.

HRESULT AddFile(
  LPCWSTR pRemoteName,
  LPCWSTR pLocalName
);

Parameters

pRemoteName
[in] Name of the file on the server. For example, http://<server>/<path>/file.ext. The format of the name must conform to the transfer protocol that you use. You cannot use wildcards in the path or file name. BITS version 1.0 supports the HTTP and HTTPS protocols.
pLocalName
[in] Name of the file on the client. The file name must include the full path, for example, d:\myapp\updates\file.ext. You cannot use wildcards in the path or file name, and the directories in the path must exist. The user must also have permissions to write to the local directory.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | File was successfully added to the job.
E_INVALIDARG | Local or remote file name is invalid.
E_ACCESSDENIED | User does not have permission to write to the specified directory on the client.
CO_E_NOT_SUPPORTED | Remote file name uses an unsupported protocol.

Remarks

To add more than one file at a time to a job, use the IBackgroundCopyJob::AddFileSet method.

If the contents of the specified file change during the file transfer, BITS restarts the transfer with the new file. BITS guarantees that the version it transfers will be consistent.

Example Code

This example shows how to add a single file to the job.

HRESULT AddFilesToJob(HWND hdlg, IBackgroundCopyJob *pJob)
{
  HRESULT  hr = 0;
  int  idx, nCount;
  BG_FILE_INFO *pFileNames;    //File information from a selected file's item data.
  BG_FILE_INFO *paFileNames;   //Array of files to pass to either add file method.

  //Get the number of files to add to the job.
  nCount = SendDlgItemMessage(hdlg, IDC_LISTOFFILES, LB_GETCOUNT, 0, 0);
  if (nCount > 0)
  {
    //Allocate memory for file(s).
    paFileNames = (BG_FILE_INFO *) _alloca(sizeof(BG_FILE_INFO) * nCount);

    hr = pJob->Suspend();

    //The dialog lets the user build a list of files to add to the job.
    //Each item in the list stores a BG_FILE_INFO structure in its item data.
    //The BG_FILE_INFO structure contains the local and remote file names.
    for (idx = 0; idx < nCount; idx++)
    {
      pFileNames = (BG_FILE_INFO *) SendDlgItemMessage(hdlg, IDC_LISTOFFILES, LB_GETITEMDATA, idx, 0);
      memcpy(paFileNames+idx, pFileNames, sizeof(BG_FILE_INFO));
    }

    if (1 == nCount)
    {
      hr = pJob->AddFile(paFileNames->RemoteName, paFileNames->LocalName);
    }
    else
    {
      hr = pJob->AddFileSet(nCount, paFileNames);
    }

    if (SUCCEEDED(hr))
    {
      hr = pJob->Resume();

      //Add files as children of the job node in the tree.
    }
  }

  return hr;
}

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::AddFileSet, IBackgroundCopyJob::EnumFiles, IBackgroundCopyJob::GetState, IBackgroundCopyJob::Resume, IBackgroundCopyJob::Suspend


IBackgroundCopyJob::AddFileSet

Use the AddFileSet method to add multiple files to the job.

HRESULT AddFileSet(
  ULONG cFileCount,
  BG_FILE_INFO* paFileSet
);

Parameters

cFileCount
[in] Number of elements in pFileSet.
paFileSet
[in] Array of BG_FILE_INFO structures that identify the local and remote file names of the files to transfer to the client.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | File was successfully added to the job.
E_INVALIDARG | Local or remote file name is invalid.
E_ACCESSDENIED | User does not have permission to write to the specified directory on the client.
CO_E_NOT_SUPPORTED | Remote file name specifies an unsupported protocol.

Remarks

To add a single file to a job, call the IBackgroundCopyJob::AddFile method.

BITS guarantees that the version of a file that it transfers will be consistent; however, it does not guarantee that a set of files will be consistent. For example, if the application transfers two files from the server, and the files are updated on the server during the second file transfer, BITS restarts the transfer of the second file; however, the first file, which already transferred successfully, will not be updated to reflect the new changes.

Example Code

See the example code for the IBackgroundCopyJob::AddFile method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::AddFile, IBackgroundCopyJob::EnumFiles, IBackgroundCopyJob::GetState, IBackgroundCopyJob::Resume, IBackgroundCopyJob::Suspend


IBackgroundCopyJob::Cancel

Use the Cancel method to delete the job from the transfer queue and to remove temporary files from the client. You can cancel a job at anytime; however, the job cannot be recovered once it is canceled.

HRESULT Cancel( );

Parameters

This method takes no parameters.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Job was successfully canceled.
BG_E_INVALID_STATE | Cannot cancel a job whose state is BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::Complete, IBackgroundCopyJob::Resume, IBackgroundCopyJob::Suspend


IBackgroundCopyJob::Complete

Use the Complete method to end the job and save the transferred files on the client.

HRESULT Complete( );

Parameters

This method takes no parameters.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Job ended successfully.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.
BG_ERROR_FATAL_ERROR_ON_COMPLETE | Unable to rename temporary files on the client.

Remarks

You must call the Complete method to acknowledge that BITS transferred the files successfully and to have the files made available to the client. If you do not call the Complete method or the IBackgroundCopyJob::Cancel method within 90 days (default JobInactivityTimeout policy), the service cancels the job.

You can call the Complete method at anytime during the transfer process; however, only files that were successfully transferred to the client before calling this method are saved. For example, if you call the Complete method while the service is processing the third of five files, only the first two files are saved. To determine which files have been transferred, call the IBackgroundCopyFile::GetProgress method and check the Transferred member of the BG_FILE_PROGRESS structure.

When the job state is BG_JOB_STATE_TRANSFERRED, all of the files have been successfully transferred. To check the state of the job, call the IBackgroundCopyJob::GetState method. You can also implement the IBackgroundCopyCallback interface to receive notification when all of the files have been transferred to the client.

BITS does not guarantee the integrity of the transferred files against third-party intrusions. Clients can implement integrity checks to validate transferred files after calling the Complete method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyCallback::JobTransferred, IBackgroundCopyJob::Cancel, IBackgroundCopyJob::GetState


IBackgroundCopyJob::EnumFiles

Use the EnumFiles method to retrieve an enumerator object that you use to enumerate the files in a job.

HRESULT EnumFiles(
  IEnumBackgroundCopyFiles** ppEnumFiles
);

Parameters

ppEnumFiles
[out] Enumerator object that you use to enumerate the files in the job. You must release ppEnumFiles when done.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Successfully generated enumerator object.

Example Code

See the example code for the IBackgroundCopyManager::EnumJobs method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IEnumBackgroundCopyFiles, IBackgroundCopyManager::EnumJobs


IBackgroundCopyJob::GetDescription

Use the GetDescription method to retrieve the short description of the job.

HRESULT GetDescription(
  LPWSTR* ppDescription
);

Parameters

ppDescription
[out] Short description of the job. Use the CoTaskMemFree function to free ppDescription.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | The parameter, ppDescription, cannot be NULL.

Example Code

See the example code for the IBackgroundCopyJob::GetDisplayName method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::SetDescription


IBackgroundCopyJob::GetDisplayName

Use the GetDisplayName method to retrieve the display name that you can use to identify the job in a user interface.

HRESULT GetDisplayName(
  LPWSTR* ppDisplayName
);

Parameters

ppDisplayName
[out] Display name that identifies the job. Use the CoTaskMemFree function to free ppDisplayName.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | The parameter, ppDisplayName cannot be NULL.

Example Code

The following code shows how to retrieve the display name property, among others, from the job object.

//Retrieve properties from the job and load them in the property sheet page.
HRESULT LoadJobProperties(HWND hdlg, IBackgroundCopyJob *pJob)
{
  HRESULT hr;
  WCHAR *pszTemp = NULL;
  BG_JOB_TYPE nJobType;
  BG_JOB_PRIORITY nPriorityLevel;
  WCHAR *pszJobType[] = { L"Download" };
  BOOL bResult;
  DWORD dwNameSize = 0;
  DWORD dwDomainSize = 0;
  WCHAR *pszName = NULL;
  WCHAR *pszDomain = NULL;
  WCHAR *pszOwner = NULL;
  PSID pSid = NULL;
  SID_NAME_USE eNameUse;
  DWORD  dwTimeInSec = 0;

  hr = pJob->GetDisplayName(&pszTemp);
  SetDlgItemText(hdlg, IDC_JOBNAME, pszTemp);
  CoTaskMemFree(pszTemp);

  hr = pJob->GetDescription(&pszTemp);
  SetDlgItemText(hdlg, IDC_DESCRIPTION, pszTemp);
  CoTaskMemFree(pszTemp);

  hr = pJob->GetType(&nJobType);
  SetDlgItemText(hdlg, IDC_XFERTYPE, pszJobType[nJobType]);

  hr = pJob->GetPriority(&nPriorityLevel);
  SendDlgItemMessage(hdlg, IDC_XFERPRIORITY, CB_SETCURSEL, nPriorityLevel, 0);

  hr = pJob->GetOwner(&pszTemp);
  bResult = ConvertStringSidToSid(pszTemp, &pSid);
  //First call to get buffer size for name and domain.
  bResult = LookupAccountSid(NULL, pSid, NULL, &dwNameSize,
                             NULL, &dwDomainSize, &NameUse);
  pszName = (WCHAR*)_alloca( sizeof(WCHAR) * dwNameSize );
  pszDomain = (WCHAR*)_alloca( sizeof(WCHAR) * dwDomainSize );
  //Second call to get name and domain.
  bResult = LookupAccountSid(NULL, pSid, pszName, &dwNameSize,
                             pszDomain, &dwDomainSize, &eNameUse);
  pszOwner = (WCHAR*)_alloca( dwDomainSize + 1 + dwNameSize );
  wsprintf(pszOwner, L"%s\\%s", pszDomain, pszName);
  SetDlgItemText(hdlg, IDC_OWNER, pszOwner);
  CoTaskMemFree(pszTemp);
  LocalFree(pSid);

  //The retry delay is in seconds. Show it as minutes on the property page.
  hr = pJob->GetMinimumRetryDelay(&dwTimeInSec);
  SetDlgItemInt(hdlg, IDC_RETRYDELAY, dwTimeInSec/60, false);

  //The retry period is in seconds. Show it as minutes on the property page.
  hr = pJob->GetNoProgressTimeout(&dwTimeInSec);
  SetDlgItemInt(hdlg, IDC_RETRYPERIOD, dwTimeInSec/60, false);

  return hr;
}

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::SetDisplayName


IBackgroundCopyJob::GetError

Use the GetError method to retrieve the error interface after an error occurs. The service generates an error object when the state of the job is BG_JOB_STATE_ERROR. The service does not create an error object when a call to an IBackgroundCopyXXXX interface method fails. The error object is available until BITS begins transferring data (BG_JOB_STATE_TRANSFERRING).

HRESULT GetError(
  IBackgroundCopyError** ppError
);

Parameters

ppError
[out] Error interface that provides a description of the error and identifies the file being transferred at the time the error occurred. You must release ppError when done.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Successfully generated the error object.
BG_E_ERROR_INFORMATION_UNAVAILABLE | The error interface is only available after an error occurs (BG_JOB_STATE_ERROR) and before BITS begins transferring data (BG_JOB_STATE_TRANSFERRING).

Remarks

The job is placed in an error state on fatal errors or after the NoProgressTimeout period expires for transient errors. You can use one of the following options to determine if the job is in error:

  • To poll for the state of the job, call the IBackgroundCopyJob::GetState method. The job is in error if the state is BG_JOB_STATE_ERROR.
  • To receive notification when an error occurs, implement the IBackgroundCopyCallback interface (specifically the JobError method). Then, call the IBackgroundCopyJob::SetNotifyClass method to register the callback and the IBackgroundCopyJob::SetNotifyFlags method to identify which events you want to receive.

The IBackgroundCopyError interface contains information that you use to determine the cause of the error and if the transfer process can proceed. After you determine the cause of the error, you can perform one of the following options:

  • To cancel the job, call the Cancel method.
  • To save those file that transferred successfully before the error occurred, call the Complete method.
  • To finish processing the job, fix the problem, and then call the Resume method.

If the job remains in an error state for 90 days (default JobInactivityTimeout policy), the service removes the job from the queue and deletes the temporary files on the client.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyCallback::JobError, IBackgroundCopyError, IBackgroundCopyJob::GetState


IBackgroundCopyJob::GetId

Use the GetId method to retrieve the identifier of the job in the queue.

HRESULT GetId(
  GUID* pJobID
);

Parameters

pJobID
[out] Identifies the job within the BITS queue.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
E_ACCESSDENIED | User does not have permission to retrieve the job identifier.

Remarks

The service generates the identifier when you create the job. To use the identifier to retrieve the job from the queue, call the IBackgroundCopyManager::GetJob method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyManager::CreateJob, IBackgroundCopyManager::GetJob


IBackgroundCopyJob::GetInterruptionCount

Use the GetInterruptionCount method to retrieve the number of times the job was interrupted by network failure or server unavailability. The count increases each time the job moves from BG_JOB_STATE_TRANSFERRING to BG_JOB_STATE_TRANSIENT_ERROR; the count is never reset.

HRESULT GetInterruptionCount(
  ULONG* pErrors
);

Parameters

pErrors
[out] Number of times the job was interrupted by network failure or server unavailability.

Return Values

This method always returns S_OK.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::GetError


IBackgroundCopyJob::GetMinimumRetryDelay

Use the GetMinimumRetryDelay method to retrieve the minimum length of time that the service waits after encountering a transient error condition before trying to transfer the file.

HRESULT GetMinimumRetryDelay(
  ULONG* pRetryDelay
);

Parameters

pRetryDelay
[in] Length of time, in seconds, that the service waits after encountering a transient error before trying to transfer the file.

Return Values

This method always returns S_OK.

Example Code

See the example code for the IBackgroundCopyJob::GetDisplayName method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::GetNoProgressTimeout, IBackgroundCopyJob::SetMinimumRetryDelay


IBackgroundCopyJob::GetNoProgressTimeout

Use the GetNoProgressTimeout method to retrieve the length of time that the service tries to transfer the file after a transient error condition occurs. If there is progress, the timer is reset.

HRESULT GetNoProgressTimeout(
  ULONG* pRetryPeriod
);

Parameters

pRetryPeriod
[in] Length of time, in seconds, that the service tries to transfer the file after a transient error occurs.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | Must pass the address of pRetryPeriod.

Example Code

See the example code for the IBackgroundCopyJob::GetDisplayName method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::GetMinimumRetryDelay, IBackgroundCopyJob::SetNoProgressTimeout


IBackgroundCopyJob::GetNotifyClass

Use the GetNotifyClass method to retrieve the CLSID that identifies your implementation of the IBackgroundCopyCallback interface. You use the IBackgroundCopyCallback interface to receive notification of job-related events, such as job completion.

HRESULT GetNotifyClass(
  GUID* pNotifyClass
);

Parameters

pNotifyClass
[out] CLSID that identifies your implementation of the IBackgroundCopyCallback interface. The value is NULL_GUID if you have not specified a callback CLSID.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | Must pass the address of pNotifyClass.
E_ACCESSDENIED | User does not have permission to retrieve the callback CLSID.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyCallback, IBackgroundCopyJob::GetNotifyFlags, IBackgroundCopyJob::GetNotifyInterface, IBackgroundCopyJob::SetNotifyClass, IBackgroundCopyManager::CreateJob


IBackgroundCopyJob::GetNotifyFlags

Use the GetNotifyFlags method to retrieve the event notification flags for the job.

HRESULT GetNotifyFlags(
  ULONG* pNotifyFlags
);

Parameters

pNotifyFlags
[out] Identifies the events that your application will receive. The following table lists the event notification flag values.
Value Description
BG_NOTIFY_JOB_TRANSFERRED
(value 0x0001) 		All of the files for the job have been transferred to the client.
BG_NOTIFY_JOB_ERROR
(value 0x0002) 		An error has occurred.
BG_NOTIFY_DISABLE
(value 0x0004) 		Event notification is disabled. The service ignores the other flags.
BG_NOTIFY_JOB_MODIFICATION
(value 0x0008) 		The job has been modified.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | Must pass the address of pNotifyFlags.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyCallback, IBackgroundCopyJob::GetNotifyClass, IBackgroundCopyJob::GetNotifyInterface, IBackgroundCopyJob::SetNotifyFlags


IBackgroundCopyJob::GetNotifyInterface

Use the GetNotifyInterface method to retrieve the interface pointer of an object that implements the IBackgroundCopyCallback interface.

HRESULT GetNotifyInterface(
  IUnknown** ppNotifyInterface
);

Parameters

ppNotifyInterface
[out] Object that implements the IBackgroundCopyCallback interface. When done, release ppNotifyInterface.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | Must pass the address of the ppNotifyInterface interface pointer.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyCallback, IBackgroundCopyJob::GetNotifyClass, IBackgroundCopyJob::GetNotifyFlags, IBackgroundCopyJob::SetNotifyInterface


IBackgroundCopyJob::GetOwner

Use the GetOwner method to retrieve the identity of the job's owner.

HRESULT GetOwner(
  LPWSTR* ppOwner
);

Parameters

ppOwner
[out] Identifies the job's owner. The GetOwner method returns the owner's identity as a string format of the SID. Use the CoTaskMemFree function to free ppOwner.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | The ppOwner parameter cannot be NULL.
E_ACCESSDENIED | User does not have permission to retrieve the ownership information for the job.

Remarks

To convert the string-format of the SID into a domain\user-name format, which is suitable for display in a user interface, call the following Win32 functions:

  • To convert the string to a valid, functional SID, call the ConvertStringSidToSid function.
  • To retrieve the domain and user name associated with the valid SID, call the LookupAccountSid function.

Example Code

See the example code for the IBackgroundCopyJob::GetDisplayName method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::TakeOwnership


IBackgroundCopyJob::GetPriority

Use the GetPriority method to retrieve the priority level for the job. The priority level determines when your job is processed relative to other jobs in the transfer queue.

HRESULT GetPriority(
  BG_JOB_PRIORITY* pPriority
);

Parameters

pPriority
[out] Priority of your job relative to other jobs in the transfer queue.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | The pPriority parameter cannot be NULL.
E_ACCESSDENIED | User does not have permission to retrieve the priority of the job.

Example Code

See the example code for the IBackgroundCopyJob::GetDisplayName method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

BG_JOB_PRIORITY, IBackgroundCopyJob::SetPriority


IBackgroundCopyJob::GetProgress

Use the GetProgress method to retrieve job-related progress information, such as the number of bytes and files transferred to the client. The progress is snapshot in time.

HRESULT GetProgress(
  BG_JOB_PROGRESS* pProgress
);

Parameters

pProgress
[out] Contains data that you can use to calculate the percentage of the job that is complete. For more information, see BG_JOB_PROGRESS.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | The pProgress parameter cannot be NULL.

Example Code

See the example code for the IBackgroundCopyManager::GetJob method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

BG_JOB_PROGRESS


IBackgroundCopyJob::GetProxySettings

Use the GetProxySettings method to retrieve the proxy information that the job uses to transfer the files.

HRESULT GetProxySettings(
  BG_JOB_PROXY_USAGE* pProxyUsage,
  LPWSTR* ppProxyList,
  LPWSTR* ppProxyBypassList
);

Parameters

pProxyUsage
[out] Specifies the proxy settings the job uses to transfer the files. For a list of proxy options, see the BG_JOB_PROXY_USAGE enumeration type.
ppProxyList
[out] Space-delimited string that contains one or more proxies to use to transfer files. For details on the format of the string, see the Listing Proxy Servers section of Enabling Internet Functionality. Use the CoTaskMemFree function to free ppProxyList.
ppProxyBypassList
[out] Contains an optional list of host names or IP addresses, or both, that were not routed through the proxy. For details on the format of the string, see the Listing the Proxy Bypass section of Enabling Internet Functionality. Use the CoTaskMemFree function to free ppProxyBypassList.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | One or more of the parameters is NULL.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

BG_JOB_PROXY_USAGE, IBackgroundCopyJob::SetProxySettings


IBackgroundCopyJob::GetState

Use the GetState method to get the current state of the job.

HRESULT GetState(
  BG_JOB_STATE* pJobState
);

Parameters

pJobState
[out] Current state of the job. For a list of job states, see the BG_JOB_STATE enumeration type.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | The parameter, pJobState, cannot be NULL.
E_ACCESSDENIED | User does not have permission to retrieve the state of the job.

Remarks

Instead of polling for the BG_JOB_STATE_ERROR and BG_JOB_STATE_TRANSFERRED states, you can register to receive notification for these events. For details, see the IBackgroundCopyCallback interface.

Example Code

See the example code for the IBackgroundCopyManager::GetJob method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

BG_JOB_STATE, IBackgroundCopyCallback


IBackgroundCopyJob::GetTimes

Use the GetTimes method to retrieve timestamps for activities related to the job. For example, the time that the job was created or last modified.

HRESULT GetTimes(
  BG_JOB_TIMES* pTimes
);

Parameters

pTimes
[out] Contains the timestamps for activities related to the job. For more information, see the BG_JOB_TIMES structure.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | The parameter, pTimes, cannot be NULL.
E_ACCESSDENIED | User does not have permission to retrieve the time-related job information.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

BG_JOB_TIMES


IBackgroundCopyJob::GetType

Use the GetType method to retrieve the type of transfer being performed, such as a file download.

HRESULT GetType(
  BG_JOB_TYPE* pJobType
);

Parameters

pJobType
[out] Type of transfer being performed. For a list of transfer types, see the BG_JOB_TYPE enumeration type.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | The pJobType parameter cannot be NULL.
E_ACCESSDENIED | User does not have permission to retrieve the job-type information.

Remarks

You specify the type of transfer when you create the job.

Example Code

See the example code for the IBackgroundCopyJob::GetDisplayName method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

BG_JOB_TYPE, IBackgroundCopyManager::CreateJob


IBackgroundCopyJob::Resume

Use the Resume method to restart a job that has been suspended.

HRESULT Resume( );

Parameters

This method takes no parameters.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
BG_E_EMPTY | There are no files to transfer.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.

Remarks

The state of the job transitions to BG_JOB_STATE_TRANSIENT_ERROR if the server is offline when you call the Resume method. BITS begins transferring data after it establishes a connection to the server.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::Cancel, IBackgroundCopyJob::Suspend


IBackgroundCopyJob::SetDescription

Use the SetDescription method to provide a short description of the job.

HRESULT SetDescription(
  LPCWSTR pDescription
);

Parameters

pDescription
[in] Short description that provides additional information about the job.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | pDescription cannot be NULL.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.

Example Code

See the example code for the IBackgroundCopyManager::CreateJob method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::GetDescription, IBackgroundCopyJob::GetState, IBackgroundCopyJob::Suspend


IBackgroundCopyJob::SetDisplayName

Use the SetDisplayName method to specify a display name that identifies the job in a user interface.

HRESULT SetDisplayName(
  LPCWSTR pDisplayName
);

Parameters

pDisplayName
[in] Name that identifies the job. Cannot be NULL.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
E_INVALIDARG | pDisplayName cannot be NULL.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.

Remarks

The display name is originally set when the job is created.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::GetDisplayName, IBackgroundCopyJob::GetState, IBackgroundCopyJob::Suspend, IBackgroundCopyManager::CreateJob


IBackgroundCopyJob::SetMinimumRetryDelay

Use the SetMinimumRetryDelay method to set the minimum length of time that the BITS waits after encountering a transient error condition before trying to transfer the file.

HRESULT SetMinimumRetryDelay(
  ULONG RetryDelay
);

Parameters

RetryDelay
[in] Minimum length of time, in seconds, that the service waits after encountering a transient error before trying to transfer the file. The default retry delay is 300 seconds (5 minutes). Set the value to 0 to have the service retry the transfer as soon as possible. If the value exceeds the NoProgressTimeout value or the JobInactivityTimeout policy value (where the default is 90 days), the service will not retry the transfer.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.

Example Code

See the example code for the IBackgroundCopyManager::CreateJob method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::GetNoProgressTimeout, IBackgroundCopyJob::GetMinimumRetryDelay, IBackgroundCopyJob::SetNoProgressTimeout


IBackgroundCopyJob::SetNoProgressTimeout

Use the SetNoProgressTimeout method to set the length of time that the service tries to transfer the file after a transient error condition occurs. If there is progress, the timer is reset.

HRESULT SetNoProgressTimeout(
  ULONG RetryPeriod
);

Parameters

RetryPeriod
[in] Length of time, in seconds, that the service tries to transfer the file after the first transient error occurs. The default retry period is 1209600 seconds (14 days). Set the retry period to 0 to prevent retries. If the retry period value exceeds the JobInactivityTimeout policy value (90-day default), the service tries to transfer the file until the policy value is exceeded.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.

Remarks

If the service does not make progress during the retry period, it moves the state of the job from BG_JOB_STATE_TRANSIENT_ERROR to BG_JOB_STATE_ERROR and calls the JobError implementation if event notification is requested.

Example Code

See the example code for the IBackgroundCopyManager::CreateJob method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::GetNoProgressTimeout, IBackgroundCopyJob::SetMinimumRetryDelay


IBackgroundCopyJob::SetNotifyClass

Use the SetNotifyClass method to specify the CLSID that identifies your implementation of the IBackgroundCopyCallback interface. You use the IBackgroundCopyCallback interface to receive notification of job-related events, such as job completion.

HRESULT SetNotifyClass(
  CLSID* pNotifyClass
);

Parameters

pNotifyClass
[in] CLSID that identifies your implementation of the IBackgroundCopyCallback interface. To remove the current callback CLSID, set this parameter to NULL.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.

Remarks

Only call the SetNotifyClass method if you implement the IBackgroundCopyCallback interface to receive notification for events such as JobTransferred or JobError.

You must use the SetNotifyClass method in conjunction with the SetNotifyFlags method to specify the type of notification that you want to receive.

As an alternative to specifying a notification class, you can call the SetNotifyInterface method to specify an object that implements the IBackgroundCopyCallback interface. The notification class differs from the notification interface in that the class receives events even after the client terminates.

Your job can specify a notification interface and a notification class. The service uses the interface unless it becomes invalid, at which time the service will use the notification class.

Note that you can also set the notification class when you create the job by specifying a value for the CallbackClass parameter of the IBackgroundCopyManager::CreateJob method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyCallback, IBackgroundCopyJob::GetNotifyClass, IBackgroundCopyJob::SetNotifyFlags, IBackgroundCopyJob::SetNotifyInterface, IBackgroundCopyManager::CreateJob


IBackgroundCopyJob::SetNotifyFlags

Use the SetNotifyFlags method to specify the type of event notification that your application is to receive, such as job completion notification.

HRESULT SetNotifyFlags(
  ULONG NotifyFlags
);

Parameters

NotifyFlags
[in] Identifies the events that your application will receive. Set one or more of the values listed in the following table.
Value Description
BG_NOTIFY_JOB_TRANSFERRED
(value 0x0001) 		All of the files for the job have been transferred to the client.
BG_NOTIFY_JOB_ERROR
(value 0x0002) 		An error has occurred.
BG_NOTIFY_DISABLE
(value 0x0004) 		Event notification is disabled. The service ignores the other flags.
BG_NOTIFY_JOB_MODIFICATION
(value 0x0008) 		The job has been modified.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
E_NOTIMPL | For flags other than those defined above for the NotifyFlags parameter..
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.

Remarks

Only set the notification flags if you implement the IBackgroundCopyCallback interface to receive notification for such events as JobTransferred or JobError.

You must use the SetNotifyFlags method in conjunction with the SetNotifyClass or the SetNotifyInterface methods to specify the type of notification that you want to receive. If you do not specify a notification class or a notification interface, you will get an error when you resume the job.

You can cancel requests for notification by clearing the notification flags or setting the BG_NOTIFY_DISABLE flag.

Example Code

See the example code for the IBackgroundCopyJob::SetNotifyInterface method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyCallback, IBackgroundCopyJob::GetNotifyFlags, IBackgroundCopyJob::SetNotifyClass, IBackgroundCopyJob::SetNotifyInterface


IBackgroundCopyJob::SetNotifyInterface

Use the SetNotifyInterface method to identify your implementation of the IBackgroundCopyCallback interface. You use the IBackgroundCopyCallback interface to receive notification of job-related events, such as job completion.

HRESULT SetNotifyInterface(
  IUnknown* pNotifyInterface
);

Parameters

pNotifyInterface
An IBackgroundCopyCallback interface pointer. To remove the current callback interface pointer, set this parameter to NULL.

Return Values

This method returns E_OUTOFMEMORY, as well as the following HRESULT values.

Value | Description
S_OK | Success.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.

Remarks

Only set the notification interface if you implement the IBackgroundCopyCallback interface to receive notification for events such as JobTransferred or JobError.

Use the SetNotifyInterface method in conjunction with the SetNotifyFlags method to specify the type of notification that you want to receive.

As an alternative to specifying a notification interface, you can call the SetNotifyClass method to specify a class that implements the IBackgroundCopyCallback interface. The notification class differs from the notification interface in that the class receives events even after the client terminates—the notification interface becomes invalid after the client terminates and cannot receive events. As a result, to capture events that occur after the client terminates, your client must poll for completed jobs or jobs that are in error at initialization time.

Your job can specify a notification interface and a notification class. The service uses the interface unless it becomes invalid, at which time the service will use the notification class.

Example Code

The following example shows how to call the SetNotifyInterface method. For details on the CNotifyInterface example class used in the following example, see the IBackgroundCopyCallback interface.

CNotifyInterface *pNotify = new CNotifyInterface();

hr = pJob->SetNotifyInterface(pNotify);
pJob->SetNotifyFlags(BG_NOTIFY_JOB_COMPLETE |
                     BG_NOTIFY_JOB_ERROR |
                     BG_NOTIFY_JOB_MODIFICATION);
pNotify->Release();

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyCallback, IBackgroundCopyJob::GetNotifyInterface, IBackgroundCopyJob::SetNotifyClass, IBackgroundCopyJob::SetNotifyFlags


IBackgroundCopyJob::SetPriority

Use the SetPriority method to specify the priority of your job. The priority level determines when your job is processed relative to other jobs in the transfer queue.

HRESULT SetPriority(
  BG_JOB_PRIORITY Priority
);

Parameters

Priority
[in] Specifies the priority level of your job relative to other jobs in the transfer queue. The default is BG_JOB_PRIORITY_NORMAL. For a list of priority levels, see the BG_JOB_PRIORITY enumeration type.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
E_NOTIMPL | The value for Priority is not defined in the BG_JOB_PRIORITY enumeration type.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.
E_ACCESSDENIED | User does not have permission to set the priority of the job.

Example Code

See the example code for the IBackgroundCopyManager::CreateJob method.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

BG_JOB_PRIORITY, IBackgroundCopyJob::GetPriority, IBackgroundCopyJob::Suspend


IBackgroundCopyJob::SetProxySettings

Use the SetProxySettings method to specify which proxy to use to transfer files.

HRESULT SetProxySettings(
  BG_JOB_PROXY_USAGE ProxyUsage,
  const WCHAR* paProxyList,
  const WCHAR* paProxyBypassList
);

Parameters

ProxyUsage
[in] Specifies whether to use the user's proxy settings, not to use a proxy, or to use application-specified proxy settings. The default is to use the user's proxy settings, BG_JOB_PROXY_USAGE_PRECONFIG. For a list of proxy options, see the BG_JOB_PROXY_USAGE enumeration type.
paProxyList
[in] Space-delimited string that contains the proxies to use to transfer files. For details on the format of the string, see the Listing Proxy Servers section of Enabling Internet Functionality.

This parameter must be NULL if the value of ProxyUsage is BG_JOB_PROXY_USAGE_PRECONFIG or BG_JOB_PROXY_USAGE_NO_PROXY.

paProxyBypassList
[in] Contains an optional list of host names, IP addresses, or both, that should not be routed through the proxy. For details on the format of the string, see the Listing the Proxy Bypass section of Enabling Internet Functionality.

This parameter must be NULL if the value of ProxyUsage is BG_JOB_PROXY_USAGE_PRECONFIG or BG_JOB_PROXY_USAGE_NO_PROXY.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
E_NOTIMPL | The value for PriorityUsage is not defined in the BG_JOB_PROXY_USAGE enumeration type.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.
E_INVALIDARG | The paProxyList parameter cannot be NULL if ProxyUsage is BG_JOB_PROXY_USAGE_OVERRIDE.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

BG_JOB_PROXY_USAGE, IBackgroundCopyJob::GetProxySettings, IBackgroundCopyJob::Suspend


IBackgroundCopyJob::Suspend

Use the Suspend method to pause a job. New jobs, jobs that are in error, or jobs that have finished transferring files are automatically suspended.

HRESULT Suspend( );

Parameters

This method takes no parameters.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Successfully stopped the job.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.
E_ACCESSDENIED | User does not have permission to suspend the job.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::Cancel, IBackgroundCopyJob::Resume


IBackgroundCopyJob::TakeOwnership

Use the TakeOwnership method to change ownership of the job to the current user. To take ownership of the job, the user must have administrator privileges on the client.

HRESULT TakeOwnership( );

Parameters

This method takes no parameters.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success.
BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.
E_ACCESSDENIED | User does not have permission to take ownership of the job.

Remarks

After ownership of the job has changed, it can only be processed when the new owner is logged on to the client. Call the IBackgroundCopyJob::GetOwner method to retrieve the SID of the new owner.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::GetOwner


IBackgroundCopyManager

Use the IBackgroundCopyManager interface to create transfer jobs, retrieve an enumerator object of jobs in the queue, and to retrieve individual jobs from the queue.

To create an instance of this interface, call the CoCreateInstance function.

The following table lists the methods in IBackgroundCopyManager.

Method | Description
CreateJob | Creates a new transfer job.
EnumJobs | Enumerates jobs in the queue.
GetJob | Retrieves a given job from the queue.
GetErrorDescription | Retrieves a description for the given error code.

Example Code

The following example shows how to open the transfer queue.

IBackgroundCopyManager *g_XferManager = NULL;

HRESULT OpenTransferQueue(void)
{
  HRESULT  hr;

  hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

  //You can specify any authentication level for your application;
  //however, you must specify RPC_C_IMP_LEVEL_DELEGATE for the
  //impersonation level. Otherwise, BITS overrides your
  //impersonation level and sets it to delegate.
  hr = CoInitializeSecurity(NULL, -1, NULL, NULL,
                            RPC_C_AUTHN_LEVEL_CONNECT,
                            RPC_C_IMP_LEVEL_DELEGATE,
                            NULL, EOAC_NONE, 0);

  hr = CoCreateInstance(CLSID_BackgroundCopyManager, NULL,
                        CLSCTX_LOCAL_SERVER,
                        IID_IBackgroundCopyManager,
                        (void**) &g_XferManager);

  return hr;
}

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob, IEnumBackgroundCopyJobs


IBackgroundCopyManager::CreateJob

Use the CreateJob method to create a new job. To activate the job in the queue, call the IBackgroundCopyJob::Resume method.

HRESULT CreateJob(
  LPCWSTR pDisplayName,
  BG_JOB_TYPE Type,
  CLSID* pCallbackClass,
  GUID* pJobID,
  IBackgroundCopyJob** ppJob
);

Parameters

pDisplayName
[in] Display name that identifies the job. Must not be NULL.
Type
[in] Type of transfer job. The default is BG_JOB_TYPE_DOWNLOAD. For a list of transfer types, see the BG_JOB_TYPE enumeration type.
pCallbackClass
[in] Registers your job to receive event notification. The CLSID identifies your IBackgroundCopyCallback implementation. This value may be NULL if you do not want to receive event notification. To register for events after you create the job, call the IBackgroundCopyJob::SetNotifyClass method.

If you specify a callback CLSID, you automatically receive event notification for BG_NOTIFY_JOB_TRANSFERRED and BG_NOTIFY_JOB_ERR. To receive notification when the job is modified, call the IBackgroundCopyJob::SetNotifyFlags method and include the BG_NOTIFY_JOB_MODIFICATION flag.

pJobID
[out] Identifies your job in the queue. Use this identifier when you call the IBackgroundCopyManager::GetJob method to get a job from the queue.
ppJob
[out] Your new job. For details, see the IBackgroundCopyJob interface. You must release ppJob when done.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Successfully generated the new job.

Example Code

The following example shows how to create a new job and modify some of the property values.

#define DISPLAY_NAME_LEN  20
//The g_XferManager variable is defined in the example code of IBackgroundCopyManager.

//Creates a new job and changes any default property values made by //the user.
HRESULT AddJobToQueue(HWND hdlg, GUID *pJobID)
{
  HRESULT  hr;
  int  idx, n;
  BG_JOB_TYPE  XferType;
  BG_JOB_PRIORITY  PriorityLevel;
  WCHAR szTemp[DISPLAY_NAME_LEN];
  IBackgroundCopyJob *pJob = NULL;

  //Get the display name the user wants to associate with the job. The name is
  //required to create the job. Applications can use the name to identify the
  //job in a user interface.
  GetDlgItemText(hdlg, IDC_DISPLAYNAME, szTemp, sizeof(szTemp));

  //Get the transfer type. Version 1.0 only supports BG_JOB_TYPE_DOWNLOAD.
  //This example pulls the transfer type from the item data associated with the
  //combobox selection.
  idx = SendDlgItemMessage(hdlg, IDC_XFERTYPE, CB_GETCURSEL, 0, 0);
  XferType = (BG_JOB_TYPE) SendDlgItemMessage(hdlg, IDC_XFERTYPE, CB_GETITEMDATA, idx, 0);

  //Creates the new job and adds it to the transfer queue. If
  //you implement the IBackgroundCopyCallback interface to receive event notification,
  //set the third parameter to the CLSID of your implementation.
  hr = g_XferManager->CreateJob(szTemp, XferType, NULL, pJobID, &pJob);

  if (SUCCEEDED(hr))
  {
    GetDlgItemText(hdlg, IDC_DESCRIPTION, szTemp, sizeof(szTemp));
    if (wcslen(szTemp) > 0)
    {
      //The user chose to provide a short description of the job to provide
      //additional information or notes.
      hr = pJob->SetDescription(szTemp);
    }

    //The default priority level for a job is BG_JOB_PRIORITY_NORMAL. An
    //application can change the priority level at any time (the job must be
    //suspended). This example pulls the priority level from the item data
    //associated with the combobox selection.
    idx = SendDlgItemMessage(hdlg, IDC_PRIORITY, CB_GETCURSEL, 0, 0);
    PriorityLevel = (BG_JOB_PRIORITY) SendDlgItemMessage(hdlg, IDC_PRIORITY, CB_GETITEMDATA, idx, 0);
    hr = pJob->SetPriority(PriorityLevel);

    //Typically, you would not have a user specify values for the retry period
    //and retry delay; in this example, it is demonstrating the use of these
    //methods. The time is multiplied by 60 because the dialog accepts time
    //in minutes and the methods require time to be specified in seconds.
    if (BST_UNCHECKED == IsDlgButtonChecked(hdlg, IDC_DEFAULTRETRY) )
    {
      n = GetDlgItemInt(hdlg, IDC_RETRYPERIOD, NULL, false);
      hr = pJob->SetNoProgressTimeout(n*60);
      n = GetDlgItemInt(hdlg, IDC_RETRYDELAY, NULL, false);
      hr = pJob->SetMinimumRetryDelay(n*60);
    }

  hr = pJob->Resume();

  }

  return hr;
}

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob, IBackgroundCopyJob::Resume


IBackgroundCopyManager::EnumJobs

Use the EnumJobs method to get an enumerator object that you use to enumerate the jobs in the transfer queue. The order of the jobs in the enumerator is arbitrary.

HRESULT EnumJobs(
  DWORD dwFlags,
  IEnumBackgroundCopyJobs** ppEnumJobs
);

Parameters

dwFlags
[in] Specifies the type of jobs to include in the enumeration. By default, the user receives all jobs that they own in the transfer queue. The following table lists the bit flag value.
Value Description
BG_JOB_ENUM_ALL_USERS
(value 0x0001) 		Includes all jobs in the transfer queue—those owned by the user and those owned by others. The user must be an administrator to use this flag.

ppEnumJobs
[out] Enumerator object to enumerate the jobs in the transfer queue. The contents of the enumerator depend on the value of dwFlags. You must release ppEnumJobs when done.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Successfully generated enumerator object.
E_ACCESSDENIED | The user must be an administrator or belong to an administrator group to enumerate jobs owned by another user.
BG_E_NOT_FOUND | The job was not found in the queue.

Example Code

The following example shows how to enumerate jobs in the transfer queue.

//The g_XferManager variable is defined in the example code of IBackgroundCopyManager.

//Enumerate jobs in the transfer queue and load them into the hwndQueue tree.
HRESULT LoadTransferJobs(HWND hwndQueue)
{
  HRESULT hr = 0;
  IEnumBackgroundCopyJobs *pJobs = NULL;
  IBackgroundCopyJob *pJob = NULL;
  IEnumBackgroundCopyFiles *pFiles = NULL;
  IBackgroundCopyFile *pFile = NULL;
  WCHAR *pszJobName = NULL;
  WCHAR *pFileName = NULL;
  GUID JobID;
  ULONG NumOfFiles = 0;

  //Delete all items in the tree.
  //Create the root node.

  //Enumerate jobs in the queue and add them to the tree. This example enumerates
  //all jobs in the transfer queue. This call fails if the current user does not
  //have administrator privileges. To enumerate jobs for only the current user,
  //replace BG_JOB_ENUM_ALL_USERS with 0.
  hr = g_XferManager->EnumJobs(BG_JOB_ENUM_ALL_USERS, &pJobs);

  if (SUCCEEDED(hr))
  {
    while ( S_OK == (hr = pJobs->Next(1, &pJob, NULL)) )
    {
      //Use the display name to identify the job in the tree.
      hr = pJob->GetDisplayName(&pszJobName);

      //Use the job identifier to get the job object on a user selection.
      hr = pJob->GetId(&JobID);

      if ( S_OK == (hr = pJob->EnumFiles(&pFiles)) )
      {
        //Get the count of files in the job. Use the count to set the number of
        //children in the job node.
        hr = pFiles->GetCount(&NumOfFiles);

        //Add the job node to the tree.
        //Set the lParam member of the tree item to JobID; use the identifier
        //to retrieve the job object on user selection.

        while ( S_OK == (hr = pFiles->Next(1, &pFile, NULL)) )
        {
          //Get the local name of the file and delete the path. Use the result
          //as the node name in the tree.
          hr = pFile->GetLocalName(&pFileName);

          //Add the file to the tree as a child of the job.

          CoTaskMemFree(pFileName);
          pFile->Release();
          pFile = NULL;
        }

        pFiles->Release();
        pFiles = NULL;
      }

      CoTaskMemFree(pszJobName);
      pJob->Release();
      pJob = NULL;
    }

    pJobs->Release();
    pJobs = NULL;
  }

  return hr;
}

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyManager::GetJob, IBackgroundCopyJob::EnumFiles, IEnumBackgroundCopyJobs


IBackgroundCopyManager::GetErrorDescription

Use the GetErrorDescription method to retrieve a description for the given error code.

HRESULT GetErrorDescription(
  HRESULT hResult,
  DWORD LanguageId,
  LPWSTR* ppErrorDescription
);

Parameters

hResult
[in] Error code from a call to a BITS method.
LanguageId
[in] Identifies the language identifier to use to generate the description. To create the language identifier, use the MAKELANGID macro. For example, to specify US English, use the following code sample.
MAKELANGID(LANG_ENGLISH, SUBLANG_ENGLISH_US)
ppErrorDescription
[out] Description of the error. You must call the CoTaskMemFree function to free the memory when done.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success

Example Code

The following example shows how to get the description associated with an error code.

//The g_XferManager variable is defined in the example code of IBackgroundCopyManager.

  HRESULT  hr = 0;
  IBackgroundCopyJob  *pJob = NULL;
  WCHAR  *pszErrorDescription = NULL;

  //Call fails because the fourth parameter is NULL.
  hr = g_XferManager->CreateJob(L"Dummy", BG_JOB_TYPE_DOWNLOAD, NULL, NULL, &pJob);

  if (SUCCEEDED(hr))
  {
  }
  else
  {
    g_XferManager->GetErrorDescription(hr,
                                       MAKELANGID(LANG_ENGLISH, SUBLANG_ENGLISH_US),
                                       &pszErrorDescription);

    //After you use the description, free the memory associated with it.
    CoTaskMemFree(pszErrorDescription);
  }

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyError, IBackgroundCopyJob::GetError


IBackgroundCopyManager::GetJob

Use the GetJob method to retrieve a given job from the transfer queue.

HRESULT GetJob(
  REFGUID JobID,
  IBackgroundCopyJob** ppJob
);

Parameters

JobID
[in] Identifies the job to retrieve from the transfer queue. The CreateJob method generates the job identifier.
ppJob
[out] Job object specified by JobID. When done, release ppJob.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Success
BG_E_NOT_FOUND | The job was not found in the queue.
E_ACCESSDENIED | User does not have permission to retrieve the job.

Example Code

The following example shows how to retrieve a single job from the transfer queue using the job identifier.

//The g_XferManager variable is defined in the example code of IBackgroundCopyManager.

//Get state and progress information for the job. The job identifier
//comes from the LParam of the selected job node in the tree.
HRESULT GetJobStats(GUID *pJobID,
                    WCHAR *pszJobState,
                    BG_JOB_PROGRESS *pProgress)
{
  HRESULT  hr = 0;
  IBackgroundCopyJob *pJob = NULL;
  BG_JOB_STATE nState;
  WCHAR *JobStates[] = { L"Queued", L"Running", L"Suspended", L"Error",
                         L"Transient Error", L"Transferred", L"Acknowledged",
                         L"Cancelled"
                       };

  hr = g_Manager->GetJob(*pJobID, &pJob);

  if (SUCCEEDED(hr))
  {
    hr = pJob->GetState(&nState);
    wcscpy(pszJobState, JobStates[nState]);
    hr = pJob->GetProgress(pProgress);

    pJob->Release();
  }

  return hr;
}

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob, IBackgroundCopyJob::GetId, IBackgroundCopyManager::EnumJobs, IBackgroundCopyManager::CreateJob


IEnumBackgroundCopyFiles

Use the IEnumBackgroundCopyFiles interface to enumerate the files that a job contains. To get the IEnumBackgroundCopyFiles object, call the IBackgroundCopyJob::EnumFiles method.

The following table lists the methods in IEnumBackgroundCopyFiles.

Method | Description
Clone | Creates another enumerator that contains the same enumeration state as the current enumerator.
GetCount | Retrieves the number of items in the enumeration.
Next | Retrieves a specified number of items in the enumeration sequence.
Reset | Resets the enumeration sequence to the beginning.
Skip | Skips a specified number of items in the enumeration sequence.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyJob::EnumFiles, IEnumBackgroundCopyJobs


IEnumBackgroundCopyFiles::Clone

The Clone method creates another IEnumBackgroundCopyFiles enumerator that contains the same enumeration state as the current one. Using this function, a client can record a particular point in the enumeration sequence, and then return to that point at a later time. The new enumerator supports the same interface as the original one.

HRESULT Clone(
  IEnumBackgroundCopyFiles** ppEnumFiles
);

Parameters

ppEnumFiles
[out] Receives the interface pointer to the enumeration object. If the method is unsuccessful, the value of this output variable is undefined. You must release ppEnumFiles when done.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Successfully generated enumerator object.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IEnumBackgroundCopyFiles


IEnumBackgroundCopyFiles::GetCount

The GetCount method retrieves a count of the number of files in the enumeration.

HRESULT GetCount(
  ULONG* pCount
);

Parameters

pCount
[out] Number of files in the enumeration.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Successfully generated enumerator object.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IEnumBackgroundCopyFiles


IEnumBackgroundCopyFiles::Next

The Next method retrieves the next celt items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements.

HRESULT Next(
  ULONG celt,
  IBackgroundCopyFile** rgelt,
  ULONG* pceltFetched
);

Parameters

celt
[in] Number of elements requested.
rgelt
[out] Array of IBackgroundCopyFile objects. You must release each object in rgelt when done
pceltFetched
[out] Number of elements in rgelt. You can set pceltFetched to NULL if celt is one.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Successfully returned the number of requested elements.
S_FALSE | Returned less than the number of requested elements.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IEnumBackgroundCopyFiles


IEnumBackgroundCopyFiles::Reset

The Reset method resets the enumeration sequence to the beginning.

HRESULT Reset( );

Parameters

This method takes no parameters.

Return Values

This method always returns S_OK.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IEnumBackgroundCopyFiles


IEnumBackgroundCopyFiles::Skip

The Skip method skips the next specified number of elements in the enumeration sequence. If there are fewer elements left in the sequence than the requested number of elements to skip, it skips past the last element in the sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Successfully skipped the number of requested elements.
S_FALSE | Skipped less than the number of requested elements.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IEnumBackgroundCopyFiles


IEnumBackgroundCopyJobs

Use the IEnumBackgroundCopyJobs interface to enumerate the list of jobs in the transfer queue. To get an IEnumBackgroundCopyJobs object, call the IBackgroundCopyManager::EnumJobs method.

The following table lists the methods in IEnumBackgroundCopyJobs.

Method | Description
Clone | Creates another enumerator that contains the same enumeration state as the current one.
GetCount | Returns the number of items in the enumeration.
Next | Retrieves a specified number of items in the enumeration sequence.
Reset | Resets the enumeration sequence to the beginning.
Skip | Skips a specified number of items in the enumeration sequence.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IBackgroundCopyManager::EnumJobs, IEnumBackgroundCopyFiles


IEnumBackgroundCopyJobs::Clone

The Clone method creates another IEnumBackgroundCopyJobs enumerator that contains the same enumeration state as the current one. Using this function, a client can record a particular point in the enumeration sequence, and then return to that point at a later time. The new enumerator supports the same interface as the original one.

HRESULT Clone(
  IEnumBackgroundCopyJobs** ppEnumJobs
);

Parameters

ppEnumJobs
[out] Receives the interface pointer to the enumeration object. If the method is unsuccessful, the value of this output variable is undefined. You must release ppEnumJobs when done.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Successfully generated enumerator object.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IEnumBackgroundCopyJobs


IEnumBackgroundCopyJobs::GetCount

The GetCount method retrieves a count of the number of jobs in the enumeration.

HRESULT GetCount(
  ULONG* pCount
);

Parameters

pCount
[out] Number of jobs in the enumeration.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Successfully generated enumerator object.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IEnumBackgroundCopyJobs


IEnumBackgroundCopyJobs::Next

The Next method retrieves the next celt items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements.

HRESULT Next(
  ULONG celt,
  IBackgroundCopyJob** rgelt,
  ULONG* pceltFetched
);

Parameters

celt
[in] Number of elements requested.
rgelt
[out] Array of IBackgroundCopyJob objects. You must release each object in rgelt when done.
pceltFetched
[out] Number of elements in rgelt. You can set pceltFetched to NULL if celt is one.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Successfully returned the number of requested elements.
S_FALSE | Returned less than the number of requested elements.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IEnumBackgroundCopyJobs


IEnumBackgroundCopyJobs::Reset

The Reset method resets the enumeration sequence to the beginning.

HRESULT Reset( );

Parameters

This method takes no parameters.

Return Values

This method always returns S_OK.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IEnumBackgroundCopyJobs


IEnumBackgroundCopyJobs::Skip

The Skip method skips the next specified number of elements in the enumeration sequence. If there are fewer elements left in the sequence than the requested number of elements to skip, it skips past last element in the sequence.

HRESULT Skip(
  ULONG celt
);

Parameters

celt
[in] Number of elements to skip.

Return Values

This method returns the following HRESULT values.

Value | Description
S_OK | Successfully skipped the number of requested elements.
S_FALSE | Skipped less than the number of requested elements.

Requirements

Windows NT/2000 or later: Requires Whistler.
Header: Declared in Bits.h and Bits.idl; include Bits.h.
Library: Use Bits.lib.

See Also

IEnumBackgroundCopyJobs


BITS Structures

The Background Intelligent Transfer Service (BITS) interfaces use the following structures.

Structure | Definition
BG_FILE_INFO | Identifies the local and remote names of the file to transfer.
BG_FILE_PROGRESS | Provides file-related progress information, such as the number of bytes transferred.
BG_JOB_PROGRESS | Provides job-related progress information, such as the number of bytes and files transferred.
BG_JOB_TIMES | Provides timestamps for activities related to a job.


BG_FILE_INFO

The BG_FILE_INFO structure provides the local and remote names of the file to transfer.

typedef struct _BG_FILE_INFO
{
  LPWSTR  RemoteName;
  LPWSTR  LocalName;
} BG_FILE_INFO;

Members

RemoteName
Name of the file on the server. For example, http://<server>/<path>/file.ext. The format of the name must conform to the transfer protocol you use. You cannot use wildcards in the path or file name. Version 1.0 supports the http and https protocols.
LocalName
Name of the file on the client. The file name must include the full path, for example, d:\myapp\updates\file.ext. You cannot use wildcards in the path or file name, and the directories in the path must exist. The user must have permission to write to the local directory.

See Also

IBackgroundCopyFile::GetLocalName, IBackgroundCopyFile::GetRemoteName, IBackgroundCopyJob::AddFileSet


BG_FILE_PROGRESS

The BG_FILE_PROGRESS structure provides file-related progress information, such as the number of bytes transferred. The progress is snapshot in time.

typedef struct _BG_FILE_PROGRESS
{
  UINT64  BytesTotal;
  UINT64  BytesTransferred;
  BOOL    Transferred;
} BG_FILE_PROGRESS;

Members

BytesTotal
Size of the file in bytes. If the value is BG_SIZE_UNKNOWN, the total size of the file has not been determined.
BytesTransferred
Number of bytes transferred.
Transferred
The value is TRUE if the file transfer is complete. Otherwise, the value is FALSE.

See Also

BG_JOB_PROGRESS, IBackgroundCopyFile::GetProgress


BG_JOB_PROGRESS

The BG_JOB_PROGRESS structure provides job-related progress information, such as the number of bytes and files transferred. The progress is snapshot in time.

typedef struct _BG_JOB_PROGRESS
{
  UINT64  BytesTotal;
  UINT64  BytesTransferred;
  ULONG   FilesTotal;
  ULONG   FilesTransferred;
} BG_JOB_PROGRESS;

Members

BytesTotal
Total number of bytes to transfer for the job. If the value is BG_SIZE_UNKNOWN, the total size of all files in the job has not been determined.
BytesTransferred
Number of bytes transferred.
FilesTotal
Total number of files to transfer for this job.
FilesTransferred
Number of files transferred.

See Also

BG_FILE_PROGRESS, IBackgroundCopyJob::GetProgress


BG_JOB_TIMES

The BG_JOB_TIMES structure provides timestamps for activities related to a job.

typedef struct _BG_JOB_TIME
{
  FILETIME  CreationTime;
  FILETIME  ModificationTime;
  FILETIME  TransferCompletionTime;
} BG_JOB_TIME;

Members

CreationTime
Time the job was created. The time is specified as FILETIME.
ModificationTime
Time the job was last modified or bytes were transferred. Adding files or calling any of the set methods in the IBackgroundCopyJob interface changes this value. In addition, changes to the state of the job and calling the Suspend, Resume, Cancel, and Complete methods change this value. The time is specified as FILETIME.
TransferCompletionTime
Time the job finished transferring all of the files. The time is specified as FILETIME.

See Also

IBackgroundCopyJob::GetTimes


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.