BITSWrappers v1.13

Welcome to BITSWrappers, a set of C++ classes to provide a complete encapsulation of the BITS (Background Intelligent Transfer Service) API for Windows.

The classes provided are: BITS::CManager, BITS::CJob, BITS::CJob2, BITS::CJob3, BITS::CJob4, BITS::CJob5, BITS::CFile, BITS::CFile2, BITS::CFile3, BITS::CFile4, BITS::CFile5, BITS::CFile6, BITS::CJobOptions, BITS::CJobOptions2, BITS::CJobOptions3, BITS::CTokenOptions, BITS::CCallback, BITS::CCallback2, BITS::CCallback3, BITS::CServerCertificateValidationCallback, BITS::CError, BITS::String, BITS::FilesArray, BITS::JobsArray, BITS::FileRangeArray & BITS::ByteArray.

CManager is the class wrapper for IBackgroundCopyManager. This interface requires Windows XP / Server 2003 or higher.

CJob is the class wrapper for IBackgroundCopyJob. This interface requires Windows XP / Server 2003 or higher.

CJob2 is the class wrapper for IBackgroundCopyJob2. This interface requires Windows XP / Server 2003 or higher.

CJob3 is the class wrapper for IBackgroundCopyJob3. This interface requires Windows XP SP2 / Server 2003 SP1 or higher.

CJob4 is the class wrapper for IBackgroundCopyJob4. This interface requires Windows Vista / Server 2008 or higher.

CJob5 is the class wrapper for IBackgroundCopyJob5. This interface requires Windows 8 / Server 2008 or higher.

CFile is the class wrapper for IBackgroundCopyFile. This interface requires Windows XP / Server 2003 or higher.

CFile2 is the class wrapper for IBackgroundCopyFile2. This interface requires Windows XP SP2 / Server 2003 SP1 or higher.

CFile3 is the class wrapper for IBackgroundCopyFile3. This interface requires Windows Vista / Server 2008 or higher.

CFile4 is the class wrapper for IBackgroundCopyFile4. This interface requires Windows 7 / Server 2008 R2 or higher.

CFile5 is the class wrapper for IBackgroundCopyFile5. This interface requires Windows 8 / Server 2012 or higher.

CFile6 is the class wrapper for IBackgroundCopyFile6. This interface requires Windows 10 version 1703 / Server 2016 or higher.

CJobOptions is the class wrapper for IBackgroundCopyJobHttpOptions. This interface requires Windows Vista / Server 2008 or higher.

CJobOptions2 is the class wrapper for using IBackgroundCopyJobHttpOption2. This interface requires Windows 10 version 1809 / Server 2019 or higher.

CJobOptions3 is the class wrapper for using IBackgroundCopyJobHttpOption3. This interface requires Windows 10 version 1903 or higher.

CTokenOptions is the class wrapper for IBitsTokenOptions. This interface requires Windows 7 / Server 2008 R2 or higher.

CCallback is the class wrapper for using IBackgroundCopyCallback. To use this class just call CJob::SetNotifyInterface. For an example see the code in test.cpp. This interface requires Windows XP / Server 2003 or higher.

CCallback2 is the class wrapper for using IBackgroundCopyCallback2. To use this class just call CJob::SetNotifyInterface. For an example see the code in test.cpp. This interface requires Windows Vista / Server 2008 or higher.

CCallback3 is the class wrapper for using IBackgroundCopyCallback3. To use this class just call CJob::SetNotifyInterface. For an example see the code in test.cpp. This interface requires Windows 10 version 1703 / Server 2016 or higher.

CServerCertificateValidationCallback is the class wrapper for using IBackgroundCopyServerCertificateValidationCallback. This interface requires Windows 10 version 1903 or higher.

CError is the class wrapper for IBackgroundCopyError. This interface requires Windows XP / Server 2003 or higher.

String is a typedef for std::wstring.

FilesArray is a typedef for std::vector<CFile>. This collection class is used in the CJob::EnumFiles method.

JobsArray is a typedef for std::vector<CJob>. This collection class is used in the CManager::EnumJobs method.

FileRangeArray is a typedef for std::vector<BG_FILE_RANGE>. This collection class is used in the CFile2::GetFileRanges and CFile6::GetFilledFileRanges methods.

ByteArray is a typedef for std::vector<BYTE>. This collection class is used in the CJob2::GetReplyData and CJobHttpOptions::GetClientCertificate methods.

The development of BITSWrappers took a number of weeks researching, developing and testing and hopefully you should find them useful in your C++ Windows Internet programming efforts.

Features

• Provides a simple C++ Header only module to easily encapsulate the BITS APIs.
• Provides cleaner C++ wrappers for various methods of the underlying COM methods. For example the encapsulation for IBackgroundCopyManager::EnumJobs method is BITS::CManager::EnumJobs. These wrapper methods will look after hiding the details of COM enumerators, memory allocation and all the other COM minutiae.
• Provides a simple C++ wrapper for BITS callback. This is also implemented internally by using the ATL classes CComObjectRootEx. For example, here is the code you need to setup call-back on your "CMyCallback" class when a job is transferred:

  class CMyCallback : public BITS::CCallback
{
public:
  HRESULT OnJobTransferred(BITS::CJob& /*job*/) override
  {
    //Your code goes here
    return S_OK;
  }
};


BITS::CJob job;
//Some code to obtain a valid "job" instance here.
job.SetNotifyInterface<CMyCallback>();

• Integrates with the various STL collection classes for easier client coding.

Usage

• To use the various BITSWrappers classes in your project simply #include "BITSWrappers.h" from the test application in your application.
• As of v1.06, the classes are now designed for VC 2017 or later. They will not compile on earlier releases of VC.
• Included in the download is a VC 2017 console based application which demonstrates most of the classes functionality.

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

History

v1.13 (16 March 2022)

• Updated copyright details
• Updated the code to use C++ uniform initialization for all variable declarations.

1 August 2021

• Updated copyright details.

v1.12 (12 April 2020)

• Fixed more Clang-Tidy static code analysis warnings in the code.

v1.11 (10 March 2020)

• Updated copyright details.
• Fixed more Clang-Tidy static code analysis warnings in the code.

v1.10 (15 September 2019)

• Fixed a number of compiler warnings when the code is compiled with VS 2019 Preview

v1.09 (19 April 2019)

• Updated copyright details
• Updated the code to clean compile on VC 2019

v1.08 (18 November 2018)

• Implemented support for IBackgroundCopyJobHttpOptions2 via new CJobOptions2 class
• Implemented support for IBackgroundCopyServerCertificateValidationCallback via new CServerCertificateValidationCallback class.
• Renamed CJobHttpOptions class to CJobOptions
• Implemented support for IBackgroundCopyJobHttpOptions3 via new CJobOptions3 class

v1.07 (7 September 2018)

• Fixed a number of compiler warnings when using VS 2017 15.8.4

v1.06 (7 July 2018)

• Updated copyright details.
• Fixed a number of C++ core guidelines compiler warnings. These changes mean that the code will now only compile on VC 2017 or later.
• Remove the code path which supported CBITSWRAPPERS_MFC_EXTENSIONS

v1.05 (29 October 2017)

• Implemented support for IBackgroundCopyCallback2 via new CCallback2 class.
• Implemented support for IBackgroundCopyCallback3 via new CCallback3 class.
• Implemented support for IBackgroundCopyFile5 via new CFile5 class.
• Implemented support for IBackgroundCopyFile6 via new CFile6 class.
• Fixed an issue in CJobHttpOptions::GetClientCertificate where the wrapper code did not correctly handle a S_FALSE return value from the low level API.
• Fixed an issue in CJob::SetNotifyInterface related to getting IUnknown interface prior to passing to calling SetNotifyInterface low level API.
• Replaced NULL with nullptr throughout the codebase. This means that the code now requires VC 2010 at a minimum to compile.
• Replaced BOOL throughout the codebase with bool.
• Replaced CString::operator LPC*STR() calls with CString::GetString calls

v1.04 (29 April 2017)

• Updated copyright details.
• Updated the code to compile cleanly using /permissive-.

v1.03 (15 January 2016)

• Updated copyright details.
• Added SAL annotations to all the code
• Verified the code compiles cleanly in VC 2015

v1.02 (10 August 2013)

• Added support for the IBitsTokenOptions interface

v1.01 (6 August 2013)

• Provided a CJob::GetOwner wrapper method
• Provided a CJob::GetProxySettings wrapper method

v1.0 (6 August 2013)

• Initial Public release

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
16 March 2022