Export (0) Print
Expand All

IBackgroundCopyJob::SetNotifyInterface method

Identifies your implementation of the IBackgroundCopyCallback interface to BITS. Use the IBackgroundCopyCallback interface to receive notification of job-related events.

Syntax


HRESULT SetNotifyInterface(
  IUnknown *pNotifyInterface
);

Parameters

pNotifyInterface

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

Return value

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

Return codeDescription
S_OK

Notification interface pointer was successfully set.

BG_E_INVALID_STATE

The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED.

 

Remarks

Call this method only if you implement the IBackgroundCopyCallback interface. Use the SetNotifyInterface method in conjunction with the SetNotifyFlags method to specify the type of notification that you want to receive.

The notification interface becomes invalid when your application terminates; BITS does not persist the notify interface. As a result, your application's initialization process should call the SetNotifyInterface method on those existing jobs for which you want to receive notification. If you need to capture state and progress information that occurred since the last time your application was run, poll for state and progress information during application initialization.

Note that BITS will call your callback even if the event for which you registered already occurred.

As an alternative to receiving callback notification, you can register to have BITS execute a command line for error and transferred events. For more details, see the IBackgroundCopyJob2::SetNotifyCmdLine method.

Note that if more than one application calls the SetNotifyInterface method to set the notification interface for the job, the last application to call the SetNotifyInterface method is the one that will receive notifications—the other applications will not receive notifications.

Examples

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. The example assumes the IBackgroundCopyJob interface pointer is valid.


IBackgroundCopyJob* pJob;
CNotifyInterface* pNotify = new CNotifyInterface();

hr = pJob->SetNotifyInterface(pNotify);
if (SUCCEEDED(hr))
{
  hr = pJob->SetNotifyFlags(BG_NOTIFY_JOB_TRANSFERRED | 
                            BG_NOTIFY_JOB_ERROR);
}
pNotify->Release();
pNofity = NULL;

if (FAILED(hr))
{
  //Handle error - unable to register for event notification.
}

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header

Bits.h

IDL

Bits.idl

Library

Bits.lib

DLL

QmgrPrxy.dll

IID

IID_IBackgroundCopyJob is defined as 37668D37-507E-4160-9316-26306D150B12

See also

IBackgroundCopyCallback
IBackgroundCopyJob::GetNotifyInterface
IBackgroundCopyJob::SetNotifyFlags
IBackgroundCopyJob2::SetNotifyCmdLine

 

 

Community Additions

ADD
Show:
© 2014 Microsoft