Background Intelligent Transfer Service

Day 10 of the Background Intelligent Transfer Service (BITS) Managed Wrapper

Matthew Podwysocki — Mon, 19 Jun 2006 00:05:00 GMT

Update: Put a comment in if you want the C# version of this code and I will get it to you

In the previous installment, I actually gave the source code which is available if you go to the Day 9 post. Anyhow, what we're going to cover today is setting up your IIS to allow for BITS upload functionality. Several things must be done in order for uploads to be supported on your machine.

First, we need to install the BITS Extensions for IIS. In order to do so, you must do the following:

Go to Add/Remove Programs from the Control Panel
From the Add/Remove Programs and click on the Add/Remove Windows Components item on the left menu
Click on Application Server and click Details
Click on Internet Information Services (IIS) and click Details
Check the Background Intelligent Transfer Service (BITS) Server Extensions and click OK.
Make sure you have the Windows CD available in case it needs and, and most likely it will.

Step 5 should look like this:

Now that we got that installed, let's go and create a virtual directory in IIS for the upload location. Go ahead and create your virtual directory much as you would for any other. This virtual directory does not require Write capability, as BITS takes care of that for you, so it is best to turn it off. If you are allowing anonymous access, the anonymous web user must have change permissions on that physical folder.

Once you do have set up the virtual directory, right click on it and go to Properties. You will now notice a BITS Server Extension tab. Below is a screenshot of what it looks like:

As you can see, we can override some of the settings which includes notifications, size limits, deleting incomplete jobs, etc. Most of the time, we really don't need to touch those values.

In the next post in this series, I'll do a simple program on how to upload a file to my local IIS instance.

Day 9 of the Background Intelligent Transfer Service (BITS) Managed Wrapper

Matthew Podwysocki — Thu, 08 Jun 2006 19:34:00 GMT

Update: Put a comment in if you want the C# version of this code and I will get it to you

Well, I was having troubles connecting to CVS on my Managed BITS Sourceforge Project over my VPC, so while I figure it out, I decided to upload the source code plus binaries to SaveFile for the time being. Let me know if you have any questions or problems regarding this.

Now that I got that out of the way, let's get back to where we left off. In the previous lesson, we talked about implementing the IBackgroundCopyCallback interface. Since this interface also implements IUnknown, we must also address that as well. I implemented the interface in a class called UnmanagedEventManager.

Let's take a look at the IUnknown interface implementation first.

// Query interface method
HRESULT Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJobEventManager::UnmanagedEventManager::QueryInterface(REFIID riid, LPVOID *ppvObj)
{
     // Check if IUnknown and IBackgroundCopyCallback
     if (riid == __uuidof(IUnknown) || riid == __uuidof(IBackgroundCopyCallback))
    {
         *ppvObj = this;
    } // if - riid
    else
   {
        *ppvObj = NULL;
        return E_NOINTERFACE;
   } // else - riid

   // Add reference
   AddRef();

return NOERROR;
} // method - UnmanagedEventManager::QueryInterface

// Add reference
ULONG Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJobEventManager::UnmanagedEventManager::AddRef()
{
return InterlockedIncrement(&m_lRefCount);
} // method - UnmanagedEventManager::AddRef

// Release
ULONG Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJobEventManager::UnmanagedEventManager::Release()
{
// Decrement count
ULONG ulCount = InterlockedDecrement(&m_lRefCount);

     // Delete if 0
     if(0 == ulCount)
          delete this;

return ulCount;
} // method - UnmanagedEventManager::Release

As you can see, we really did nothing special here. Just a standard plain-vanilla implementation of IUnknown. Now let's take a look at some of the methods that we must implement with the IBackgroundCopyCallback interface. We will note that the pCopyJobEventManager is of type gcroot<BackgroundCopyJobEventManager*>.

// Job error callback
HRESULT Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJobEventManager::UnmanagedEventManager::JobError(IBackgroundCopyJob __nogc* pJob, IBackgroundCopyError __nogc* pError)
{
// Call error event
pCopyJobEventManager->ErrorEvent(new BackgroundCopyJob(pJob), new BackgroundCopyError(pError));

return S_OK;
} // method - UnmanagedEventManager::JobError

// Job modification callback
HRESULT Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJobEventManager::UnmanagedEventManager::JobModification(IBackgroundCopyJob __nogc* pJob, DWORD dwReserved)
{
// Call modification event
pCopyJobEventManager->ModificationEvent(new BackgroundCopyJob(pJob));

return S_OK;
} // method - UnmanagedEventManager::JobModification

// Job transferred callback
HRESULT Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJobEventManager::UnmanagedEventManager::JobTransferred(IBackgroundCopyJob __nogc* pJob)
{
// Call transferred event
pCopyJobEventManager->TransferredEvent(new BackgroundCopyJob(pJob));

return S_OK;
} // method - UnmanagedEventManager::JobTransferred

Basically what these methods do is invoke the events when the IBackgroundCopyCallback is invoked from the IBackgroundCopyJob interface. You have the ability to set the IBackgroundCopyCallback interface implementation through the SetNotifyInterface and SetNotifyFlags methods. The event implementations are quite simple as well and that code follows:

// The error event
void Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJobEventManager::ErrorEvent(Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJob* pErroredJob, Podwysocki::Services::BackgroundTransferServices::BackgroundCopyError* pCopyError)
{
if(this->pJobModificationEvent != NULL)
this->pJobModificationEvent->Invoke(this, new BackgroundCopyErrorEventArgs(pCopyError, pErroredJob));
} // method - BackgroundCopyJobEventManager::ErrorEvent

// The modified event
void Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJobEventManager::ModificationEvent(Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJob* pModifiedJob)
{
if(this->pJobModificationEvent != 0)
this->pJobModificationEvent->Invoke(this, new BackgroundCopyJobEventArgs(pModifiedJob));
} // method - BackgroundCopyJobEventManager::ModificationEvent

// The transferred event
void Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJobEventManager::TransferredEvent(Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJob* pTransferredJob)
{
if (this->pJobTransferredEvent != 0)
this->pJobTransferredEvent->Invoke(this, new BackgroundCopyJobEventArgs(pTransferredJob));
} // method - BackgroundCopyJobEventManager::TransferredEvent

It's important that we implement this class because we want a way to fire events upon completion of a job. As you can see, it's not entirely complex to translate the unmanaged code to managed, it just takes time and lines of code. Once again, the files are available from the link above, so let me know if you have any questions.

Day 8 of the Background Intelligent Transfer Service (BITS) Managed Wrapper

Matthew Podwysocki — Fri, 02 Jun 2006 15:44:00 GMT

Update: Put a comment in if you want the C# version of this code and I will get it to you

Well, I finally managed to get a spot for the Managed BITS Wrapper on SourceForge.net. I have not uploaded any files just yet, as I am cleaning up one or two things as well as trying to add some test cases to it. I will let people know when I actually have a release out there available. The first available release will be in Managed C++ and then the second release will be in C++/CLI.

I left off last time looking at some of the functions within the BackgroundCopyJob wrapper for IBackgroundCopyJob, IBackgroundCopyJob2, and IBackgroundCopyJob3. I haven't bothered with IBackgroundCopyJob4 since it is available only on Vista for the time being.

Where I would like to go today is to cover how we're going to wrap the NotifyInterface methods and the IBackgroundCopyCallback interface in order to perform events on job transferred, job error and job modification. This involves implementing a class with an unmanaged interface and wrapping it with a managed event manager.

Below is the definition of the BackgroundCopyJobEventManager: Note that it contains a lot of information to parse.

// This class encompasses NotifyInterface and the IBackgroundCopyCallBack
public __gc class BackgroundCopyJobEventManager : public System::IDisposable
{
public:
// Job error event handler
__delegate void JobErrorEventHandler(Object* sender, BackgroundCopyErrorEventArgs* e);

// Job modification event handler
__delegate void JobModificationEventHandler(Object* sender, BackgroundCopyJobEventArgs* e);

// Job transferred event handler
__delegate void JobTransferredEventHandler(Object* sender, BackgroundCopyJobEventArgs* e);

private:
     // Member variables
     JobErrorEventHandler* pJobErrorEvent;
     JobModificationEventHandler* pJobModificationEvent;
     JobTransferredEventHandler* pJobTransferredEvent;
     bool isDisposed;

     // Unmanaged event handler
     __nogc class UnmanagedEventManager : public IBackgroundCopyCallback
     {
     private:
          gcroot<BackgroundCopyJobEventManager*> pCopyJobEventManager;
          LONG m_lRefCount;

     public:
          // Constructor that takes a BackgroundCopyJobEventManager
          UnmanagedEventManager(gcroot<BackgroundCopyJobEventManager*> pCopyJobEventManager);

// Destructor
~UnmanagedEventManager() {}

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

// Job error callback
HRESULT __stdcall JobError(IBackgroundCopyJob* pJob, IBackgroundCopyError* pError);

// Job modification callback
HRESULT __stdcall JobModification(IBackgroundCopyJob* pJob, DWORD dwReserved);

// Job transferred callback
HRESULT __stdcall JobTransferred(IBackgroundCopyJob* pJob);

}; // class - UnmanagedEvents

UnmanagedEventManager __nogc* pUnmanagedEvents;

public:
// Public constructor
BackgroundCopyJobEventManager();

// Destructor
~BackgroundCopyJobEventManager();

// Dispose method
__sealed void Dispose();

// Add a job to monitor with default flags
void AddBackgroundCopyJob(BackgroundCopyJob* pMonitoredJob);

// Adds a job to monitor with the specified flags
void AddBackgroundCopyJob(BackgroundCopyJob* pMonitoredJob, BackgroundCopyJobNotifyFlags notifyFlags);

     // Copy error event handler
     __event virtual void add_JobErrorEvent(JobErrorEventHandler* value);
     __event virtual void remove_JobErrorEvent(JobErrorEventHandler* value);

     // Job modification event handler
     __event virtual void add_JobModification(JobModificationEventHandler* value);
     __event virtual void remove_JobModification(JobModificationEventHandler* value);

     // Job transferred event handler
     __event virtual void add_JobTransferred(JobTransferredEventHandler* value);
     __event virtual void remove_JobTransferred(JobTransferredEventHandler* value);

public private:
// The error event
void ErrorEvent(BackgroundCopyJob* pErroredJob, BackgroundCopyError* pCopyError);

// The modified event
void ModificationEvent(BackgroundCopyJob* pModifiedJob);

// The transferred event
void TransferredEvent(BackgroundCopyJob* pTransferredJob);

protected:
// Overloaded dispose method
virtual void Dispose(bool disposing);

}; // class - BackgroundCopyJobEventManager

So, let's cover this little by little. We have an inner class called UnmanagedEvents which wraps the functionality in the IBackgroundCopyCallback. As you can see, we also need to implement the IUnknown interface, as the IBackgroundCopyCallback does. If you will also notice, I used the gcroot template which allows us to create managed types within unmanaged classes.

Since this is an unmanaged class, we must implement a destructor to clean up the code in the BackgroundCopyJobEventManager. To save some time, I also implement the IDisposable interface as well so that cleanup can happen more quickly than waiting for the garbage collector to hit the destructor.

As you also notice, we have three event types, one for Transferred Events which occur when the job state is Transferred, one for Modified Events which occur when a job has been modified in any way, and one for Error Events which occur when there is an error associated with the BackgroundCopyJob.

That's it for today, but stay tuned for more.

Day 7 of the Background Intelligent Transfer Service (BITS) Managed Wrapper

Matthew Podwysocki — Fri, 26 May 2006 16:01:00 GMT

Update: Put a comment in if you want the C# version of this code and I will get it to you

In previous days, I discussed the methods and properties to be implemented with the BITS wrapper BackgroundCopyJob. Let's go over some of them today.

Let's start off with the IDisposable pattern which must be implemented when using these unmanaged objects. Here is the simple implementation required:

// BackgroundCopyJob finalizer
Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJob::~BackgroundCopyJob()
{
// Call dispose(false)
Dispose(false);
} // finalizer- BackgroundCopyJob

// Dispose method
void Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJob::Dispose()
{
// Call dispose(true)
Dispose(true);
} // method - BackgroundCopyJob::Dispose

// Overloaded protected Dispose method
void Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJob::Dispose(bool disposing)
{
     // Check if disposed
     if(!isDisposed)
     {
          // Check if disposing, suppress finalize
          if(disposing)
               GC::SuppressFinalize(this);

          // Dispose of copy job
          if(pCopyJob)
               pCopyJob->Release();

isDisposed = true;
} // if - isDisposed
} // method - BackgroundCopyJob::Dispose(bool)

Now that we've looked at implementing the IDisposable pattern properly, let's look at some of the basic methods that we need to implement. Since this class implements the IDisposable pattern, we need to check in each method and property to check whether the Dispose has been called. This class could have disasterous results should any method be called after the BITS object has been released.

Now let's take a look at adding a file to the job via the IBackgroundCopyJob.AddFile method. We must also make sure to validate all data coming into this method as well as validate that the instance has not been disposed as well. Below is the code to add a file:

// Adds a file to the copy job
void Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJob::AddFile(String* remoteUrl, String* localName)
{
// Validate disposed
ArgumentValidation::CheckForDisposedObject(isDisposed, this->GetType()->Name);

     // Validate arguments
     ArgumentValidation::CheckForEmptyOrNullString(remoteUrl, S"remoteUrl");
     ArgumentValidation::CheckForEmptyOrNullString(localName, S"localName");

     // Check if type not download and if already a file on record
     if(BackgroundCopyJobType::Download != Type && Files->Count > 0)
          throw new InvalidOperationException(ResourceMessageManager::MultipleFilesUploadExceptionMessage);

     // Initialize locals
     HRESULT hr;

     // Convert strings
     IntPtr pRemoteUrl = Marshal::StringToCoTaskMemUni(remoteUrl);
     IntPtr pLocalName = Marshal::StringToCoTaskMemUni(localName);
     LPCWSTR pszRemoteUrl= (LPCWSTR)pRemoteUrl.ToPointer();
     LPCWSTR pszLocalName = (LPCWSTR)pLocalName.ToPointer();

    try
    {
         // Add file and check for error
         hr = pCopyJob->AddFile(pszRemoteUrl, pszLocalName);
         if(E_INVALIDARG == hr)
              throw new ArgumentException(ResourceMessageManager::UnsupportedProtocolExceptionMessage);
         else if(E_ACCESSDENIED == hr)
              throw new SecurityException(ResourceMessageManager::WriteAccessDeniedExceptionMessage);
         else if(FAILED(hr))
              throw new COMException(ResourceMessageManager::UnknownExceptionMessage(S"IBackgroundCopyJob", S"AddFile", hr), hr);
    } // try
    __finally
    {
         // Free memory
         Marshal::FreeCoTaskMem(pRemoteUrl);
         Marshal::FreeCoTaskMem(pLocalName);
         CoTaskMemFree((void*)pszRemoteUrl);
         CoTaskMemFree((void*)pszLocalName);
    } // finally
} // method - BackgroundCopyJob::AddFile

As you can see, we handled all error conditions coming back from the IBackgroundCopyJob interface and made sure that the unmanaged pointers were cleaned before the method finished.

Now let's implement the IBackgroundCopyJob3.AddFileWithRanges method. We must take into account the same things as above. We must also query the IBackgroundCopyJob interface through IUnknown to get a reference to IBackgroundCopyJob3. Below is the code to implement the method:

// Add a file to a download job and specify the ranges of the file to download
void Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJob::AddFileWithRanges(String* remoteUrl, String* localName, Podwysocki::Services::BackgroundTransferServices::BackgroundCopyFileRange ranges[])
{
// Validate disposed
ArgumentValidation::CheckForDisposedObject(isDisposed, this->GetType()->Name);

     // Validate arguments
     ArgumentValidation::CheckForEmptyOrNullString(remoteUrl, S"remoteUrl");
     ArgumentValidation::CheckForEmptyOrNullString(localName, S"localName");
     if(ranges->Length == 0)
          throw new ArgumentException(ResourceMessageManager::EmptyRangesExceptionMessage);

     // Validate job type
     if(BackgroundCopyJobType::Download != Type)
          throw new NotImplementedException(ResourceMessageManager::DownloadJobOnlyExceptionMessage);

     // Initialize locals
     HRESULT hr;
     IBackgroundCopyJob3* pCopyJob3 = NULL;
     int rangeCount = ranges->Length;
     DWORD dwRangeCount = rangeCount;
     IntPtr pRemoteUrl = IntPtr::Zero;
     IntPtr pLocalName = IntPtr::Zero;
     LPCWSTR pszRemoteUrl = NULL;
     LPCWSTR pszLocalName = NULL;
     BG_FILE_RANGE* fileRanges = NULL;

     try
     {
          // Convert strings
          pRemoteUrl = Marshal::StringToCoTaskMemUni(remoteUrl);
          pLocalName = Marshal::StringToCoTaskMemUni(localName);
          pszRemoteUrl = (LPCWSTR)pRemoteUrl.ToPointer();
          pszLocalName = (LPCWSTR)pLocalName.ToPointer();

// Create file ranges

          fileRanges = (BG_FILE_RANGE*) malloc(sizeof(BG_FILE_RANGE) * dwRangeCount);
          if(NULL == fileRanges)
               throw new ExternalException(ResourceMessageManager::MallocExceptionMessage(S"BG_FILE_RANGE"));

          // Iterate through ranges
          for(int rangeIdx=0; rangeIdx<rangeCount; rangeIdx++)
          {
               fileRanges[rangeIdx].InitialOffset = ranges[rangeIdx].InitialOffset;
               fileRanges[rangeIdx].Length = ranges[rangeIdx].Length;
          } // for - rangeIdx<rangeCount

          // Query interface to get IBackgroundCopyJob3
          hr = pCopyJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pCopyJob3);
          if(E_NOINTERFACE == hr)
               throw new NotSupportedException(ResourceMessageManager::BitsVersionNotSupportedExceptionMessage(S"2.0"));
          else if(FAILED(hr))
               throw new COMException(ResourceMessageManager::QueryInterfaceExceptionMessage(S"IBackgroundCopyJob3"), hr);

// Release pCopyJob to decrement count
pCopyJob->Release();

          // Call AddFileWithRanges
          hr = pCopyJob3->AddFileWithRanges(pszRemoteUrl, pszLocalName, dwRangeCount, fileRanges);
          if(E_ACCESSDENIED == hr)
               throw new SecurityException(ResourceMessageManager::WriteAccessDeniedExceptionMessage);
          else if(BG_E_INVALID_RANGE == hr)
               throw new ArgumentException(ResourceMessageManager::InvalidRangeExceptionMessage);
          else if(BG_E_OVERLAPPING_RANGES == hr)
               throw new ArgumentException(ResourceMessageManager::OverlappingRangeExceptionMessage);
          else if(E_INVALIDARG == hr)
               throw new ArgumentException(ResourceMessageManager::UnsupportedProtocolExceptionMessage);
          else if(FAILED(hr))
               throw new COMException(ResourceMessageManager::UnknownExceptionMessage(S"IBackgroundCopyJob3", S"AddFileWithRanges", hr), hr);
     } // try
     __finally
     {
          // Release pCopyJob3
          if(pCopyJob3)
               pCopyJob3->Release();

          // Free memory
          Marshal::FreeCoTaskMem(pRemoteUrl);
          Marshal::FreeCoTaskMem(pLocalName);
          CoTaskMemFree((void*)pszRemoteUrl);
          CoTaskMemFree((void*)pszLocalName);

          // Free ranges
          free(fileRanges);
     } // finally
} // method - BackgroundCopyJob::AddFileWithRanges

As you see, when doing mixed mode coding in Managed C++, you can see how careful we need to be with our unmanaged types. We had to do malloc and free of an array as well. Be careful to pay attention to the API for BITS, as it tells you which objects you must free using a particular method. It's always interesting in the COM world to know what to free and how to free it.

Lastly today, we will cover setting the priority of the BackgroundCopyJob through the IBackgroundCopyJob.SetPriority method. This is a rather straight forward method that validates the arguments as always and sets the priority. Below is the implementation:

// Sets the BackgroundCopyJob priority
void Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJob::set_Priority(Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJobPriority value)
{
// Validate disposed
ArgumentValidation::CheckForDisposedObject(isDisposed, this->GetType()->Name);

// Validate arguments
ArgumentValidation::CheckForInvalidEnum(__box(value)->GetType(), __box(value), S"value");

     // Check for state
     if(BackgroundCopyJobState::Acknowledged == State || BackgroundCopyJobState::Cancelled == State)
          throw new InvalidOperationException(ResourceMessageManager::AcknowledgedCancelledStateExceptionMessage);

     // Initialize locals
     HRESULT hr;
     BG_JOB_PRIORITY bgJobPriority = (BG_JOB_PRIORITY)value;

     // Set priority
     hr = pCopyJob->SetPriority(bgJobPriority);
     if(FAILED(hr))
          throw new COMException(ResourceMessageManager::UnknownExceptionMessage(S"IBackgroundCopyJob", S"SetPriority", hr), hr);
} // method - BackgroundCopyJob::set_Priority

So, as you can see, it takes a bit of work to do the translation and to be type safe while doing so. The great thing about Managed C++ is that you can mix and match your existing C++ code with Managed CLR code seamlessly. Many times this can be used to prevent having to reinvent the wheel with some legacy code. I'm providing these examples of how you can move any type of existing code to Managed C++ and beyond with some work.

Day 6 of the Background Intelligent Transfer Service (BITS) Managed Wrapper

Matthew Podwysocki — Wed, 24 May 2006 22:47:00 GMT

UPDATE: See Day 9 of the Background Intelligent Transfer Service (BITS) Managed Wrapper for the source code plus binaries.

In previous lessons, I covered the BackgroundCopyManager and how I wrapped the IBackgroundCopyManager in Managed C++. Today, I'll go a step further to look at the BackgroundCopyJob wrapped class.

The BackgroundCopyJob wraps the following interfaces:

* IBackgroundCopyJob

* IBackgroundCopyJob2

* IBackgroundCopyJob3

As we are dealing with unmanaged types, we must also take into consideration of implementing the System.IDisposable interface. Let's go over the basic layout of the IDisposable pattern:

public:

void Dispose();

protected:

virtual void Dispose(bool disposing);

private:

bool isDisposed;

Now that we got that out of the way, let's go over the methods and properties we will be implementing. Let's go over the public properties first:

// Gets or sets the ACL tags
__property BackgroundCopyJobFileACLFlags get_ACLTags();
__property void set_ACLTags(BackgroundCopyJobFileACLFlags value);

// Gets the creation time
__property DateTime get_CreationTime();

// Gets and sets the description
__property String* get_Description();
__property void set_Description(String* value);

// Gets and sets the display name
__property String* get_DisplayName();
__property void set_DisplayName(String* value);

// Gets the error for the job
__property BackgroundCopyError* get_Error();

// Gets the error count
__property System::Int64 get_ErrorCount();

// Gets the BackgroundCopyFiles
__property BackgroundCopyFileCollection* get_Files();

// Gets the ID
__property Guid get_Id();

// Gets and sets the minimum retry delay
__property System::Int64 get_MinimumRetryDelay();
__property void set_MinimumRetryDelay(System::Int64 value);

// Gets the modification time
__property DateTime get_ModificationTime();

// Gets and sets the no progress timeout
__property System::Int64 get_NoProgressTimeout();
__property void set_NoProgressTimeout(System::Int64 value);

// Gets or sets the notify command line
__property NotifyCommandLine get_NotifyCmdLine();
__property void set_NotifyCmdLine(NotifyCommandLine value);

// Gets the owner
__property String* get_OwnerId();

// Gets the owner name
__property String* get_OwnerName();

// Gets and sets the priority
__property BackgroundCopyJobPriority get_Priority();
__property void set_Priority(BackgroundCopyJobPriority value);

// Gets the progress
__property BackgroundCopyJobProgress get_Progress();

// Gets and sets the proxy settings
__property BackgroundCopyJobProxySettings get_ProxySettings();
__property void set_ProxySettings(BackgroundCopyJobProxySettings value);

// Gets an in-memory copy of the reply data from the server application
__property MemoryStream* get_ReplyData();

// Gets or sets the name of the file that contains the reply data from the server application.
__property String* get_ReplyFileName();
__property void set_ReplyFileName(String* value);

// Gets the progress information related to the transfer of the reply data from an upload-reply job
__property BackgroundCopyJobReplyProgress get_ReplyProgress();

// Gets the background copy job state
__property BackgroundCopyJobState get_State();

// Get transfer completion time
__property DateTime get_TransferCompletionTime();

// Gets the job type
__property BackgroundCopyJobType get_Type();

And after all that, we still have the methods to review. Luckily, there are not as many methods as properties. So, let's review those now:

// Adds a file to the copy job
void AddFile(String* remoteUrl, String* localName);

// Adds a set of files to the copy job
void AddFileSet(BackgroundCopyFileInfo fileInfo[]);

// Add a file to a download job and specify the ranges of the file to download
void AddFileWithRanges(String* remoteUrl, String* localName, BackgroundCopyFileRange ranges[]);

// Cancels the job
void Cancel();

// Completes the job
void Complete();

// Dispose method
__sealed void Dispose();

// Removes credentials
void RemoveCredentials(AuthenticationTarget target, AuthenticationScheme scheme);

// Replace the beginning text of all remote names in the download job with the given string.
void ReplaceRemotePrefix(String* oldPrefix, String* newPrefix);

// Resume job
void Resume();

// Set credentials
void SetCredentials(String* userName, String* password, AuthenticationTarget target, AuthenticationScheme scheme);

// Suspend the job
void Suspend();

// Take ownership of job
void TakeOwnership();

So, as you can see, we have a ton of things to implement. It especially gets to be a lot of code to not only validate the incoming data (which is important), but translate the unmanaged types into managed ones. We'll go over some examples of that in another installment.

Day 5 of the Background Intelligent Transfer Service (BITS) Managed Wrapper

Matthew Podwysocki — Mon, 15 May 2006 19:08:00 GMT

Update: Put a comment in if you want the C# version of this code and I will get it to you

Sorry about the delay about getting back to this, but I have been rebuilding a clean build environment for this tool for both Visual Studio 2003 and Visual Studio 2005 which required a little bit of work. I'm in the process of getting some sort of hosting so that I can share the source code, but if you need or want it in the mean time, please do not hesitate to contact me.

Anyhow, we left off with the total number of classes and structures that we need to create. So, now that this is out of the way, let me start off with the header and implementation of the BackgroundCopyManager. I created this class in a singleton pattern because we are connecting to a service. Below is an abbreviated header file for the BackgroundCopyManager:

namespace Podwysocki

{

namespace Services

{

namespace BackgroundTransferServices

{

public __gc class BackgroundCopyManager

{

private:

// Member variables

static BackgroundCopyManager* managerInstance;

static Object* syncLock = new Object();

IBackgroundCopyManager __nogc* pCopyManager;

static const Int64 defaultRetryPeriod = 1209600;

static const Int64 defaultRetryDelay = 600;

// Default constructor

BackgroundCopyManager();

public:

// Destructor

~BackgroundCopyManager();

// Gets the singleton instance

__property static BackgroundCopyManager* get_Instance();

// CreateCopyJob methods

CreateCopyJob(String* displayName);

CreateCopyJob(String* displayName, String* description);

CreateCopyJob(String* displayName, String* description, BackgroundCopyJobType type);

CreateCopyJob(String* displayName, String* description, BackgroundCopyJobType type, Int64 retryPeriod, Int64 retryDelay);

// Get job by ID

BackgroundCopyJob* GetJob(System::Guid id);

// Get jobs

BackgroundCopyJobCollection* GetJobs();

BackgroundCopyJobCollection* GetJobs(JobUserFlag userFlag);

}; // class - BackgroundCopyManager

};

Now let's hit a few portions of interest. Like I said, you can get the whole thing by just requesting it. First off, let's look at the Instance property implementation.

Podwysocki::Services::BackgroundTransferServices::BackgroundCopyManager*

Podwysocki::Services::BackgroundTransferServices::BackgroundCopyManager::get_Instance()

{

     try
     {
          // Enter synch lock
        Monitor::Enter(syncLock);

          // Check if already created
          if(managerInstance == NULL)
               managerInstance = new BackgroundCopyManager();

          return bgCopyManager;
     } // try
     __finally
    {
         // Exit synch lock
         Monitor::Exit(syncLock);
    } // finally

} // method - get_Instance()

Next, we will cover creating a connection to BITS in our constructor. What we need to do is connect to the BITS service via the CoCreateInstance. Here is the implementation:

// Default BackgroundCopyManager constructor
Podwysocki::Services::BackgroundTransferServices::BackgroundCopyManager::BackgroundCopyManager()
{
// Set principal policy
AppDomain::CurrentDomain->SetPrincipalPolicy(PrincipalPolicy::WindowsPrincipal);

// Initialize locals
HRESULT hr;

     // Create instance
     IBackgroundCopyManager __nogc* lpCopyManager = pCopyManager;
     hr = CoCreateInstance(__uuidof(BackgroundCopyManager2_0), NULL,
      CLSCTX_LOCAL_SERVER,
      __uuidof(IBackgroundCopyManager),
      (void**) &lpCopyManager);

// Reset reference
pCopyManager = lpCopyManager;

     // Throw exception if failed
     if(FAILED(hr))
         throw new COMException(ResourceMessageManager::UnknownExceptionMessage(String::Empty, S"CoCreateInstance", hr), hr);
} // constructor - BackgroundCopyManager

Next, we will look at how to create a job through the CreateJob method. This is using all the items in the fully overloaded method:

Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJob* Podwysocki::Services::BackgroundTransferServices::BackgroundCopyManager::CreateCopyJob(String* displayName, String* description, BackgroundCopyJobType jobType, System::Int64 retryPeriod, System::Int64 retryDelay)
{
     // Validate arguments
     ArgumentValidation::CheckForEmptyOrNullString(displayName, S"displayName");
     ArgumentValidation::CheckForStringMaxLength(256, displayName, S"displayName");
     ArgumentValidation::CheckForNullReference(description, S"description");

     // Initialize locals
     HRESULT hr;
     GUID pJobId;
     IBackgroundCopyJob* pJob = NULL;
     BackgroundCopyJob* pBgJob = NULL;
     IntPtr pDisplayName = Marshal::StringToCoTaskMemUni(displayName);
     LPCWSTR lpDisplayName = (LPCWSTR)pDisplayName.ToPointer();

     try
    {
         // Create job
         hr = pCopyManager->CreateJob(lpDisplayName, (BG_JOB_TYPE)jobType, &pJobId, &pJob);
         if(FAILED(hr))
              throw new COMException(ResourceMessageManager::UnknownExceptionMessage (S"IBackgroundCopyManager", S"CreateJob", hr), hr);

// Create BackgroundCopyJob
pBgJob = new BackgroundCopyJob(pJob);

// Set properties
pBgJob->Description = description;

         // Check if retry period not default
         if(retryPeriod != defaultRetryPeriod)
              pBgJob->NoProgressTimeout = retryPeriod;

         // Check if retry delay not default
         if(retryDelay != defaultRetryDelay)
              pBgJob->MinimumRetryDelay = retryDelay;

         return pBgJob;
    } // try
    __finally
   {
        // Release pDisplayName
        Marshal::FreeCoTaskMem(pDisplayName);
        CoTaskMemFree((void*)lpDisplayName);
   } // finally
} // BackgroundCopyManager::CreateCopyJob(String*, String*, BackgroundCopyJobType, Int64, Int64)

The next method is to get the jobs from the current manager. The implementation is here:

Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJobCollection* Podwysocki::Services::BackgroundTransferServices::BackgroundCopyManager::GetJobs(JobUserFlag jobUser)
{
     // Check if job flag set to all users
     if(JobUserFlag::AllUsers == jobUser)
     {
          // Get the current principal and check if part of BUILTIN\Administrators
          WindowsPrincipal* principal = dynamic_cast<WindowsPrincipal*>(Thread::CurrentPrincipal);
          if(!principal->IsInRole(S"BUILTIN\\Administrators"))
               throw new SecurityException(ResourceMessageManager::GetJobAccessDeniedExceptionMessage);
     } // if - JobUserFlag

     // Initialize locals
     HRESULT hr;
     IEnumBackgroundCopyJobs* pJobs = NULL;
     IBackgroundCopyJob* pJob = NULL;
     ULONG cJobCount = 0;
     BackgroundCopyJobCollection* jobCollection = new BackgroundCopyJobCollection();

     try
     {
          hr = pCopyManager->EnumJobs((DWORD)jobUser, &pJobs);
          if(SUCCEEDED(hr))
          {
               // Get count of jobs in queue
               pJobs->GetCount(&cJobCount);

               // Iterate through jobs enum
               for(ULONG idx=0; idx<cJobCount; idx++)
               {
                    // Get next item and break if error
                    hr = pJobs->Next(1, &pJob, NULL);

                    if(SUCCEEDED(hr))
                         jobCollection->Add(new BackgroundCopyJob(pJob));
                    else
                         throw new COMException(ResourceMessageManager::UnknownExceptionMessage(S"IEnumBackgroundCopyJobs", S"Next", hr), hr);
               } // for - idx<cJobCount

               return jobCollection;
          } // if - SUCCEEDED
          else
          {
               throw new COMException(ResourceMessageManager::UnknownExceptionMessage(S"IBackgroundCopyManager", S"EnumJobs", hr), hr);
          } // else - SUCCEEDED
    } // try
    __finally
    {
         // Release pJobs
         if(pJobs)
              pJobs->Release();
    } // finally
} // method - BackgroundCopyManager::GetJobs

Finally, we're going to going to get a job by a Guid. This of course must be converted to a BITS GUID before we can pass it to the service. This requires a bit of translation which we have in an internal class. Here is the implementation:

Podwysocki::Services::BackgroundTransferServices::BackgroundCopyJob* Podwysocki::Services::BackgroundTransferServices::BackgroundCopyManager::GetJobById(System::Guid id)
{
     // Define locals
     HRESULT hr;
     IBackgroundCopyJob* pJob = NULL;
     REFGUID wGuid = BackgroundTransferServicesUtility::ConvertToWinGuid(id);

     // Get by ID
     hr = pCopyManager->GetJob(wGuid, &pJob);
     if(BG_E_NOT_FOUND == hr)
          throw new ArgumentException(ResourceMessageManager::JobNotFoundExceptionMessage(id.ToString()), S"id");
     else if(E_ACCESSDENIED == hr)
          thow new SecurityException(ResourceMessageManager::GetJobAccessDeniedExceptionMessage);
     else if(FAILED(hr))
          throw new COMException(ResourceMessageManager::UnknownExceptionMessage(S"IBackgroundCopyManager", S"GetJob", hr), hr);

return new BackgroundCopyJob(pJob);
} // method - BackgroundCopyManager::GetJobById

As you can see, it's not the most pretty thing to convert between managed and unmanaged types. Once you get the pattern down, the conversion process can be quite easy as I found. As always you must clean up after your objects. I will cover a little more in depth, but the code can get massive for just a little blog. I just want people to get the absolute basics of going between managed and unmanaged types.

Day 4 of the Background Intelligent Transfer Service (BITS) Managed Wrapper

Matthew Podwysocki — Wed, 10 May 2006 11:37:00 GMT

UPDATE: See Day 9 of the Background Intelligent Transfer Service (BITS) Managed Wrapper for the source code plus binaries.

In previous lessons, I laid out the basic API for BITS. Now I think it's time for us to start doing the actual planning on how to wrap this API. Let's start by mapping out the BITS types and then creating our own wrapped types. Below, I have a table of those native types and what the wrapped types will be:

Enumerations
Unmanaged BITS Type	Wrapped Type
BG_AUTH_SCHEME	AuthenticationScheme
BG_AUTH_TARGET	AuthenticationTarget
BG_ERROR_CONTEXT	BackgroundErrorContext
BG_JOB_PRIORITY	BackgroundCopyJobPriority
BG_JOB_PROXY_USAGE	BackgroundCopyJobProxyUsage
BG_JOB_STATE	BackgroundCopyJobState
BG_JOB_TYPE	BackgroundCopyJobType
Flags from IBackgroundCopyJob3::SetFileACLFlags	BackgroundCopyJobFileACLTags
Flags from IBackgroundCopyJob::SetNotifyFlags	BackgroundCopyJobNotifyFlags

Structures
Unmanaged BITS Type	Wrapped Type
BG_FILE_INFO	BackgroundCopyFileInfo
BG_FILE_PROGRESS	BackgroundCopyFileProgress
BG_FILE_RANGE	BackgroundCopyFileRange
BG_JOB_PROGRESS	BackgroundCopyJobProgress
BG_JOB_REPLY_PROGRESS	BackgroundCopyJobReplyProgress

Classes
Unmanaged BITS Type	Wrapped Type
IBackgroundCopyCallback	BackgroundCopyJobEventManager UnmanagedEventManager BackgroundCopyJobEventArgs BackgroundCopyErrorEventArgs
IBackgroundCopyError	BackgroundCopyError
IBackgroundCopyFile IBackgroundCopyFile2	BackgroundCopyFile
IBackgroundCopyJob IBackgroundCopyJob2 IBackgroundCopyJob3	BackgroundCopyJob
IBackgroundCopyManager	BackgroundCopyManager
IEnumBackgroundCopyFiles	BackgroundCopyFileCollection
IEnumBackgroundCopyJobs	BackgroundCopyJobCollection

So, in short, we have a lot of work ahead of us laying out these files. I won't cover every excruciating detail unless need be, but I want to show how you translate between unmanaged and managed types. That will be the next lesson.

Day 3 of the Background Intelligent Transfer Service (BITS) Managed Wrapper

Matthew Podwysocki — Wed, 10 May 2006 11:34:00 GMT

Update: Put a comment in if you want the C# version of this code and I will get it to you

In the previous lesson, I left off with the basic understanding of the IBackgroundCopyManager. Today, we're going to dive a little deeper into what exactly the IBackgroundCopyManager creates, the IBackgroundCopyJob.

There are many methods in the IBackgroundCopyJob and so much so that it's really difficult to talk about each one in detail. As the versions of BITS evolved, more interfaces were added to support additional functionality. Since we are developing this wrapper for BITS 2.0, we need to also include IBackgroundCopyJob2 and IBackgroundCopyJob3. We are not concerned about IBackgroundCopyJob4 and IBackgroundCopyJob5 as they require Vista. With those other two, many of the methods are TBD anyhow, so they won't help us.

Since there are many things to cover with regards the IBackgroundCopyJob, instead of going over the full method signature, I'll just group them into properties and methods.

Methods for IBackgroundCopyJob, 2 and 3:

Method Name	Description
AddFileSet	Add multiple files to a download job.
AddFile	Add a single file to a job.
AddFileWithRanges (IBackgroundCopyJob3)	Adds a file to the download job with a set of ranges to download from the file.
Cancel	Cancels the current job.
Complete	Completes the job that has been transferred.
RemoveCredentails (IBackgroundCopyJob2)	Removes the credentials from the current job.
ReplaceRemotePrefix (IBackgroundCopyJob3)	Replaces the prefix of all remote files such as server name.
SetCredentials (IBackgroundCopyJob2)	Sets the credentials for the current job. This can be NTLM, Negotiate, Basic, etc.
Suspend	Suspends the current job.
TakeOwnership	Takes ownership of the current job. This requires administrator rights.

Properties for IBackgroundCopyJob, 2 and 3:

Method Name	Description
GetDescription SetDescription	Gets or sets the job description.
GetDisplayName SetDisplayName	Gets or sets the job display name.
EnumFiles	Gets an enumerator to iterate through the IBackgroundCopyFiles.
GetError	Gets the current error for the job.
GetErrorCount	Gets the number of errors for the job.
GetFileACLTags SetFileACLTags (IBackgroundCopyJob3)	Gets or sets the owner and ACL tags for SMB download jobs.
GetId	Gets the ID for the job.
GetMinimumRetryDelay SetMinimumRetryDelay	Gets or sets the minimum retry delay.
GetNoProgressTimeout SetNoProgressTimeout	Gets or set the no progress timeout for the job.
GetNotifyCmdLine SetNotifyCmdLine (IBackgroundCopyJob2)	Gets or sets the command line to execute once the job enters error or transferred state.
GetNotifyFlags	Gets the notification flags.
GetNotifyInterface	Gets the notify interface for the job.
GetNotifyInterface	Gets the notify interface for the job.
GetPriority SetPriority	Gets or sets the priority of the job.
GetProgress	Gets the progress structure for the job.
GetProxySettings SetProxySettings	Gets or sets the proxy settings for the job.
GetReplyData(IBackgroundCopyJob2)	Gets the data from the upload reply job.
GetReplyFileName SetReplyFileName (IBackgroundCopyJob2)	Gets or sets the file name that contains the reply data.
GetReplyProgress(IBackgroundCopyJob2)	Gets the progress for the current upload reply job.
GetTimes	Gets the time structure for the job.
GetType	Gets the IBackgroundCopyJob type.

So, as you can see from even the IBackgroundCopyJob and the other versions, there are a lot of methods that we need to cover in our design. In the next lesson, we will cover the start of how to turn this into a .NET managed wrapper.

Day 2 of the Background Intelligent Transfer Service (BITS) Managed Wrapper

Matthew Podwysocki — Wed, 10 May 2006 11:33:00 GMT

Update: Put a comment in if you want the C# version of this code and I will get it to you

In my previous lesson, I gave a brief overview of the Background Intelligent Transfer Service. Today we will dig a bit deeper into some of the API as well as give reasons why I chose Managed C++ over a C# implementation.

First off, there was plenty of reading to do from the last time. If you want to read more about the uses of BITS as well as the key technologies behind it, please check out this link: http://msdn.microsoft.com/library/en-us/bits/bits/about_bits.asp. Read up? Good... Let's continue!

Now I will discuss why I chose to do a Managed C++ version of this instead of a C# implementation. As you will note with your installation of the Microsoft Windows Server 2003 SP1 SDK that I indicated was a required download, there are bits header files and libraries and all sorts of goodies. Look in the Include directory, which in my instance is C:\Program Files\Microsoft Platform SDK\Include. In this folder you will notice a bits2_0.h and a bits2_0.idl.

There are several examples out there especially on the MSDN about using the MIDL tool to create the type library and then use the tlbimp tool in order to create the .NET wrapper library. This approach was all well and good for BITS 1.0 which included download capability only and no ability to set credentials. Of course the argument can be made to wrap 99% of the code in C# and only use C++ for the extra stuff such as setting credentials and getting upload reply data. The C# only version will not work because C# does not support struct UNIONS which is essential to setting the username and password. I've tried this approach in the past, but the better performer on mission critical applications such as this made it better to stick with just one language.

On the MSDN, the article wraps BITS 1.0 functionality in a VB.NET solution http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwxp/html/WinXP_BITS.asp. There is another example out there that uses the BITSAdmin tool to do uploads which is located here: http://www.codeproject.com/vb/net/Bitsup.asp. I wanted full functionality that neither could really provide, so I took lessons learned from each and went on my way.

We will now dive right into the Reference material provided on this site. Since there is so much material to cover, I will only cover the top level information at this moment. Please keep in mind that we are creating a "Managed Wrapper" for BITS, so don't panic when we start working with native type conversion. There will be no need to Google the results as I will include how to do things right here.

Let us take a brief look at the BITS Interfaces. Note that these interfaces all implement IUnknown and return HRESULTs with each method to indicate success or failure. Today's lesson will cover briefly the heart of it all, the IBackgroundCopyManager. This interface allows the implementer to add a job, get a job by an identifier, get all jobs for the current user or if an administrator, get all jobs for that machine.

Now we will look at each method in some detail.

The CreateJob method gives the implementer the ability to create a job, given a null terminated string, and a job type and returns a Guid and an IBackgroundCopyJob. The signature is as follows:

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

The EnumJobs method gives the implementer the ability to get an enumerator to iterate through a collection of IBackgroundCopyJobs. This has the parameter to be able to see all jobs for all users on the current machine if the user is an administrator. The signature is as follows:

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

The GetJob method provides the ability to get a particular IBackgroundCopyJob by the Guid. We will worry about translating this GUID into a System.Guid later. The signature is as follows:

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

Lastly, the GetErrorDescription method provides the ability to get the error message for a particular HRESULT based upon the LCID which is available from the System.Threading.Thread. The signature of this method is:

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

Until the next lesson, keep reading and I will then show you what I created in terms of the header file wrapper for the IBackgroundCopyManager as well as starting to get into the wrapping of the IBackgroundCopyJob.

Day 1 of the Background Intelligent Transfer Service (BITS) Managed Wrapper

Matthew Podwysocki — Tue, 09 May 2006 16:47:00 GMT

Update: Put a comment in if you want the C# version of this code and I will get it to you

A large client of mine wanted an automated way of delivery large files picture files throughout their network. After listening to their initial solution of FTP, I realized after some research that the Background Intelligent Transfer Service (BITS) would be a good alternative. I could programatically use BITS to transfer files automatically to the other computer using upload job types.

BITS has an advantage over FTP in several ways. The first word in the product says why it can be useful, Background. With this solution, BITS will use only the unused bandwidth for the particular machine it is hosted. This means ultimately that you will not face network load issues especially during mission critical operations.

This service also has an advantage as it uses HTTP instead of FTP to transfer files. This is an advantage in several regards. First, FTP uses clear text to transfer user names and passwords which can be problematic. BITS supports many types of authentication models such as Negotiate, NTLM, Digest, Basic and yes, even Passport. BITS also supports HTTPS which may add some latency and overhead, but for secure transmissions, it is a must.

The second advantage of BITS over FTP is that it is much harder to filter out FTP traffic at the firewall due to the client opening an arbitrary port to open an FTP session. FTP requires multiple TCP connections for directory listing, upload, download, etc. BITS traffic can be isolated to the standard ports of 80 and 443.

The third advantage of BITS over FTP is that BITS can suspend and resume jobs and begin again where it was suspended. The built in FTP functionality has no such built-in mechanism to support this functionality, although there are common extensions that will support it.

Let's get started with two things. First, we need the Windows 2003 SP1 SDK to get the most up to date BITS 2.0 libraries. The download is available at this link: http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&displaylang=en

The second thing to do is familiarize ourselves with the BITS SDK which is available on the MSDN at this link:

http://msdn.microsoft.com/library/en-us/bits/bits/bits_start_page.asp

Next lesson, we will talk more about the interfaces and classes involved.