445 lines
12 KiB
Plaintext
445 lines
12 KiB
Plaintext
|
//=======================================================================
|
||
|
|
//
|
||
|
|
// Copyright (c) 2000 Microsoft Corporation. All Rights Reserved.
|
||
|
|
//
|
||
|
|
// File: bits.idl
|
||
|
|
//
|
||
|
|
// Description:
|
||
|
|
//
|
||
|
|
// Interface to the background file copier.
|
||
|
|
//
|
||
|
|
//=======================================================================
|
||
|
|
|
||
|
|
#ifndef DO_NO_IMPORTS
|
||
|
|
import "unknwn.idl";
|
||
|
|
#endif
|
||
|
|
|
||
|
|
cpp_quote("#include \"bitsmsg.h\"")
|
||
|
|
cpp_quote("#define BG_SIZE_UNKNOWN (UINT64)(-1)")
|
||
|
|
|
||
|
|
#define BG_ENUM_SIZEIS(maxcount) maxcount
|
||
|
|
#define BG_ENUM_LENGTHIS(maxcount,lengthptr) \
|
||
|
|
lengthptr ? *lengthptr : maxcount
|
||
|
|
|
||
|
|
//
|
||
|
|
// =============================
|
||
|
|
// Marshalled interfaces
|
||
|
|
// =============================
|
||
|
|
|
||
|
|
[
|
||
|
|
uuid(01b7bd23-fb88-4a77-8490-5891d3e4653a),
|
||
|
|
odl
|
||
|
|
]
|
||
|
|
interface IBackgroundCopyFile : IUnknown
|
||
|
|
{
|
||
|
|
typedef struct _BG_FILE_PROGRESS
|
||
|
|
{
|
||
|
|
UINT64 BytesTotal;
|
||
|
|
UINT64 BytesTransferred;
|
||
|
|
BOOL Completed;
|
||
|
|
}
|
||
|
|
BG_FILE_PROGRESS;
|
||
|
|
|
||
|
|
//--------------------------------------------------------------------
|
||
|
|
|
||
|
|
HRESULT GetRemoteName( [out] LPWSTR *pVal );
|
||
|
|
HRESULT GetLocalName( [out] LPWSTR *pVal );
|
||
|
|
|
||
|
|
HRESULT GetProgress( [out] BG_FILE_PROGRESS *pVal );
|
||
|
|
}
|
||
|
|
|
||
|
|
//--------------------------------------------------------------------
|
||
|
|
//
|
||
|
|
[
|
||
|
|
uuid(ca51e165-c365-424c-8d41-24aaa4ff3c40),
|
||
|
|
helpstring("IEnumBackgroundCopyFiles Interface"),
|
||
|
|
odl
|
||
|
|
]
|
||
|
|
interface IEnumBackgroundCopyFiles : IUnknown
|
||
|
|
{
|
||
|
|
HRESULT Next( [in] ULONG celt,
|
||
|
|
[out, size_is(BG_ENUM_SIZEIS(celt)), length_is(BG_ENUM_LENGTHIS(celt,pceltFetched))] IBackgroundCopyFile **rgelt,
|
||
|
|
[in,out,unique] ULONG *pceltFetched );
|
||
|
|
|
||
|
|
HRESULT Skip( [in] ULONG celt);
|
||
|
|
|
||
|
|
HRESULT Reset();
|
||
|
|
|
||
|
|
HRESULT Clone( [out] IEnumBackgroundCopyFiles **ppenum );
|
||
|
|
|
||
|
|
HRESULT GetCount( [out] ULONG *puCount );
|
||
|
|
}
|
||
|
|
|
||
|
|
//--------------------------------------------------------------------
|
||
|
|
//
|
||
|
|
|
||
|
|
[
|
||
|
|
uuid(19c613a0-fcb8-4f28-81ae-897c3d078f81),
|
||
|
|
helpstring("error object for IBackgroundCopyJob"),
|
||
|
|
odl
|
||
|
|
]
|
||
|
|
interface IBackgroundCopyError : IUnknown
|
||
|
|
{
|
||
|
|
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_REMOTE_APPLICATION = 7
|
||
|
|
} BG_ERROR_CONTEXT;
|
||
|
|
|
||
|
|
HRESULT GetError( [out,ref] BG_ERROR_CONTEXT *pContext,
|
||
|
|
[out,ref] HRESULT *pCode );
|
||
|
|
|
||
|
|
// Returns BG_E_FILE_NOT_AVAILABLE if no file is available
|
||
|
|
HRESULT GetFile( [out] IBackgroundCopyFile ** pVal );
|
||
|
|
|
||
|
|
// Return a human readable description of the error.
|
||
|
|
// Use CoTaskMemFree to free the description.
|
||
|
|
HRESULT GetErrorDescription( [in] DWORD LanguageId,
|
||
|
|
[out,ref] LPWSTR *pErrorDescription );
|
||
|
|
|
||
|
|
// Return a human readable description of the error context.
|
||
|
|
// Use CoTaskMemFree to free the description.
|
||
|
|
HRESULT GetErrorContextDescription(
|
||
|
|
[in] DWORD LanguageId,
|
||
|
|
[out,ref] LPWSTR *pContextDescription );
|
||
|
|
|
||
|
|
// Returns BG_E_PROTOCOL_NOT_AVAILABLE if no protocol is available
|
||
|
|
HRESULT GetProtocol( [out,ref] LPWSTR *pProtocol );
|
||
|
|
}
|
||
|
|
|
||
|
|
// ==============================================
|
||
|
|
// Job Interface
|
||
|
|
[
|
||
|
|
uuid(37668d37-507e-4160-9316-26306d150b12),
|
||
|
|
helpstring("IBackgroundCopyJob Interface"),
|
||
|
|
odl
|
||
|
|
]
|
||
|
|
interface IBackgroundCopyJob : IUnknown
|
||
|
|
{
|
||
|
|
typedef struct _BG_FILE_INFO
|
||
|
|
{
|
||
|
|
LPWSTR RemoteName;
|
||
|
|
LPWSTR LocalName;
|
||
|
|
}
|
||
|
|
BG_FILE_INFO;
|
||
|
|
|
||
|
|
typedef struct _BG_JOB_PROGRESS
|
||
|
|
{
|
||
|
|
UINT64 BytesTotal;
|
||
|
|
UINT64 BytesTransferred;
|
||
|
|
|
||
|
|
ULONG FilesTotal;
|
||
|
|
ULONG FilesTransferred;
|
||
|
|
}
|
||
|
|
BG_JOB_PROGRESS;
|
||
|
|
|
||
|
|
typedef struct _BG_JOB_TIMES
|
||
|
|
{
|
||
|
|
FILETIME CreationTime;
|
||
|
|
FILETIME ModificationTime;
|
||
|
|
FILETIME TransferCompletionTime;
|
||
|
|
}
|
||
|
|
BG_JOB_TIMES;
|
||
|
|
|
||
|
|
typedef enum
|
||
|
|
{
|
||
|
|
BG_JOB_PRIORITY_FOREGROUND,
|
||
|
|
BG_JOB_PRIORITY_HIGH,
|
||
|
|
BG_JOB_PRIORITY_NORMAL,
|
||
|
|
BG_JOB_PRIORITY_LOW,
|
||
|
|
|
||
|
|
} BG_JOB_PRIORITY;
|
||
|
|
|
||
|
|
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;
|
||
|
|
|
||
|
|
typedef enum
|
||
|
|
{
|
||
|
|
BG_JOB_TYPE_DOWNLOAD,
|
||
|
|
BG_JOB_TYPE_UPLOAD,
|
||
|
|
BG_JOB_TYPE_UPLOAD_REPLY
|
||
|
|
|
||
|
|
} BG_JOB_TYPE;
|
||
|
|
|
||
|
|
typedef enum
|
||
|
|
{
|
||
|
|
BG_JOB_PROXY_USAGE_PRECONFIG,
|
||
|
|
BG_JOB_PROXY_USAGE_NO_PROXY,
|
||
|
|
BG_JOB_PROXY_USAGE_OVERRIDE
|
||
|
|
} BG_JOB_PROXY_USAGE;
|
||
|
|
|
||
|
|
//--------------------------------------------------------------------
|
||
|
|
|
||
|
|
//
|
||
|
|
// Returns E_INVALIDARG if one of the filesets has
|
||
|
|
// - local name is blank
|
||
|
|
// - local name contains invalid characters
|
||
|
|
// - remote name is blank
|
||
|
|
// - remote name has invalid format
|
||
|
|
//
|
||
|
|
// Returns CO_E_NOT_SUPPORTED if
|
||
|
|
// - remote URL contains unsupported protocol
|
||
|
|
//
|
||
|
|
HRESULT
|
||
|
|
AddFileSet(
|
||
|
|
[in] ULONG cFileCount,
|
||
|
|
[in, size_is(cFileCount)] BG_FILE_INFO *pFileSet
|
||
|
|
);
|
||
|
|
|
||
|
|
HRESULT
|
||
|
|
AddFile(
|
||
|
|
[in] LPCWSTR RemoteUrl,
|
||
|
|
[in] LPCWSTR LocalName
|
||
|
|
);
|
||
|
|
|
||
|
|
//
|
||
|
|
// Gets an enumerator object for all files in the job.
|
||
|
|
//
|
||
|
|
HRESULT
|
||
|
|
EnumFiles(
|
||
|
|
[out] IEnumBackgroundCopyFiles ** pEnum
|
||
|
|
);
|
||
|
|
|
||
|
|
//
|
||
|
|
// Pause all activity on the job. The service will take no action until one of
|
||
|
|
// Resume(), Cancel(), Complete() is called.
|
||
|
|
//
|
||
|
|
// if already suspended, just returns S_OK.
|
||
|
|
//
|
||
|
|
HRESULT Suspend();
|
||
|
|
|
||
|
|
//
|
||
|
|
// Enable downloading for this job. Job properties cannot be modified
|
||
|
|
// after Resume() until the app calls Suspend().
|
||
|
|
//
|
||
|
|
// if already running, just returns S_OK.
|
||
|
|
//
|
||
|
|
HRESULT Resume();
|
||
|
|
|
||
|
|
//
|
||
|
|
// Permanently stop the job. The service will delete the job metadata and downloaded files.
|
||
|
|
//
|
||
|
|
// If already cancelled or resumed, returns ???
|
||
|
|
//
|
||
|
|
HRESULT Cancel();
|
||
|
|
|
||
|
|
//
|
||
|
|
// Acknowledges receipt of the job-complete notification. The service will delete
|
||
|
|
// the job metadata and leave the downloaded files.
|
||
|
|
//
|
||
|
|
HRESULT Complete();
|
||
|
|
|
||
|
|
//--------------------------------------------------------------------
|
||
|
|
|
||
|
|
HRESULT GetId( [out] GUID *pVal );
|
||
|
|
|
||
|
|
HRESULT GetType( [out] BG_JOB_TYPE * pVal );
|
||
|
|
|
||
|
|
HRESULT GetProgress( [out] BG_JOB_PROGRESS *pVal );
|
||
|
|
|
||
|
|
HRESULT GetTimes( [out] BG_JOB_TIMES * pVal );
|
||
|
|
|
||
|
|
HRESULT GetState( [out] BG_JOB_STATE *pVal );
|
||
|
|
|
||
|
|
HRESULT GetError( [out] IBackgroundCopyError ** ppError );
|
||
|
|
|
||
|
|
//
|
||
|
|
// The owner of the job, represented as a string.
|
||
|
|
// Only the owner and admins are allowed to see or change the job.
|
||
|
|
//
|
||
|
|
HRESULT GetOwner( [out] LPWSTR *pVal );
|
||
|
|
|
||
|
|
//
|
||
|
|
// name of the job, suitable for display in UI
|
||
|
|
//
|
||
|
|
HRESULT SetDisplayName( [in] LPCWSTR Val );
|
||
|
|
HRESULT GetDisplayName( [out] LPWSTR *pVal );
|
||
|
|
|
||
|
|
//
|
||
|
|
// a field for use by the app
|
||
|
|
//
|
||
|
|
HRESULT SetDescription( [in] LPCWSTR Val );
|
||
|
|
HRESULT GetDescription( [out] LPWSTR *pVal );
|
||
|
|
|
||
|
|
//
|
||
|
|
// the priority of the job in the queue.
|
||
|
|
// default = PRIORITY_NORMAL
|
||
|
|
// values not in BG_JOB_PRIORITY return E_NOTIMPL.
|
||
|
|
//
|
||
|
|
HRESULT SetPriority( [in] BG_JOB_PRIORITY Val );
|
||
|
|
HRESULT GetPriority( [out] BG_JOB_PRIORITY *pVal );
|
||
|
|
|
||
|
|
//
|
||
|
|
// ignores extra flags?
|
||
|
|
//
|
||
|
|
HRESULT SetNotifyFlags( [in] ULONG Val );
|
||
|
|
HRESULT GetNotifyFlags( [out] ULONG *pVal );
|
||
|
|
|
||
|
|
// interface pointer that implements the IBackgroundCallback interface for notifications.
|
||
|
|
// If the pointer becomes invalid, the service will try to create a new notification object
|
||
|
|
// with the notify CLSID.
|
||
|
|
HRESULT SetNotifyInterface( [in] IUnknown * Val );
|
||
|
|
HRESULT GetNotifyInterface( [out] IUnknown ** pVal );
|
||
|
|
|
||
|
|
HRESULT SetMinimumRetryDelay( [in] ULONG Seconds );
|
||
|
|
HRESULT GetMinimumRetryDelay( [out] ULONG * Seconds );
|
||
|
|
|
||
|
|
HRESULT SetNoProgressTimeout( [in] ULONG Seconds );
|
||
|
|
HRESULT GetNoProgressTimeout( [out] ULONG * Seconds );
|
||
|
|
|
||
|
|
HRESULT GetErrorCount( [out] ULONG * Errors );
|
||
|
|
|
||
|
|
HRESULT SetProxySettings(
|
||
|
|
[in] BG_JOB_PROXY_USAGE ProxyUsage,
|
||
|
|
[in,string,unique] const WCHAR * ProxyList,
|
||
|
|
[in,string,unique] const WCHAR * ProxyBypassList );
|
||
|
|
|
||
|
|
HRESULT GetProxySettings(
|
||
|
|
[out] BG_JOB_PROXY_USAGE *pProxyUsage,
|
||
|
|
[out] LPWSTR *pProxyList,
|
||
|
|
[out] LPWSTR *pProxyBypassList );
|
||
|
|
|
||
|
|
HRESULT TakeOwnership();
|
||
|
|
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
// ==============================================
|
||
|
|
// IEnumJobs Interface
|
||
|
|
// This interface allows enumerating the jobs under a Job
|
||
|
|
[
|
||
|
|
uuid(1af4f612-3b71-466f-8f58-7b6f73ac57ad),
|
||
|
|
helpstring("IEnumBackgroundCopyJobs2 Interface"),
|
||
|
|
odl
|
||
|
|
]
|
||
|
|
interface IEnumBackgroundCopyJobs : IUnknown
|
||
|
|
{
|
||
|
|
HRESULT Next( [in] ULONG celt,
|
||
|
|
[out, size_is(BG_ENUM_SIZEIS(celt)), length_is(BG_ENUM_LENGTHIS(celt,pceltFetched))] IBackgroundCopyJob **rgelt,
|
||
|
|
[in,out,unique] ULONG *pceltFetched );
|
||
|
|
|
||
|
|
HRESULT Skip( [in] ULONG celt);
|
||
|
|
|
||
|
|
HRESULT Reset();
|
||
|
|
|
||
|
|
HRESULT Clone( [out] IEnumBackgroundCopyJobs **ppenum );
|
||
|
|
|
||
|
|
HRESULT GetCount( [out] ULONG *puCount );
|
||
|
|
}
|
||
|
|
|
||
|
|
cpp_quote("#define BG_NOTIFY_JOB_TRANSFERRED 0x0001")
|
||
|
|
cpp_quote("#define BG_NOTIFY_JOB_ERROR 0x0002")
|
||
|
|
cpp_quote("#define BG_NOTIFY_DISABLE 0x0004")
|
||
|
|
cpp_quote("#define BG_NOTIFY_JOB_MODIFICATION 0x0008")
|
||
|
|
|
||
|
|
|
||
|
|
// ==============================================
|
||
|
|
// IBackgroundCallback Interface
|
||
|
|
// This interface is implemented by the client and is used by the queue manager
|
||
|
|
// to supply progress information to the client.
|
||
|
|
[
|
||
|
|
uuid(97ea99c7-0186-4ad4-8df9-c5b4e0ed6b22),
|
||
|
|
#if !defined( BITS_DONT_USE_ASYNC_DCOM )
|
||
|
|
async_uuid(ca29d251-b4bb-4679-a3d9-ae8006119d54),
|
||
|
|
#endif
|
||
|
|
helpstring("IBackgroundCopyCallback Interface"),
|
||
|
|
odl
|
||
|
|
]
|
||
|
|
interface IBackgroundCopyCallback : IUnknown
|
||
|
|
{
|
||
|
|
//
|
||
|
|
// A job has transferred successfully.
|
||
|
|
//
|
||
|
|
HRESULT JobTransferred( [in] IBackgroundCopyJob *pJob );
|
||
|
|
|
||
|
|
//
|
||
|
|
// An error occurred, and the service has suspended the job.
|
||
|
|
// Fix the error and resume the job.
|
||
|
|
// Get error details by calling (*pFailingJob)->GetStatus().
|
||
|
|
//
|
||
|
|
HRESULT JobError( [in] IBackgroundCopyJob *pJob,
|
||
|
|
[in] IBackgroundCopyError * pError );
|
||
|
|
|
||
|
|
//
|
||
|
|
// The job has been modified. Intendended for user interfaces.
|
||
|
|
//
|
||
|
|
HRESULT JobModification( [in] IBackgroundCopyJob *pJob,
|
||
|
|
[in] DWORD dwReserved );
|
||
|
|
|
||
|
|
}
|
||
|
|
|
||
|
|
//
|
||
|
|
// IBackgroundCopyManager is the "root" interface to the background file copy component.
|
||
|
|
//
|
||
|
|
[
|
||
|
|
uuid(5ce34c0d-0dc9-4c1f-897c-daa1b78cee7c),
|
||
|
|
helpstring("Background Copy interface"),
|
||
|
|
odl
|
||
|
|
]
|
||
|
|
interface IBackgroundCopyManager : IUnknown
|
||
|
|
{
|
||
|
|
|
||
|
|
HRESULT CreateJob(
|
||
|
|
[in] LPCWSTR DisplayName,
|
||
|
|
[in] BG_JOB_TYPE Type,
|
||
|
|
[out] GUID * pJobId,
|
||
|
|
[out] IBackgroundCopyJob **ppJob );
|
||
|
|
|
||
|
|
HRESULT GetJob( [in] REFGUID jobID,
|
||
|
|
[out] IBackgroundCopyJob **ppJob );
|
||
|
|
|
||
|
|
//
|
||
|
|
// Without this flag, jobs not owned by the caller are excluded from the enumeration.
|
||
|
|
// With this flag, those jobs are included. Only works if the caller is an administrator.
|
||
|
|
//
|
||
|
|
cpp_quote("#define BG_JOB_ENUM_ALL_USERS 0x0001")
|
||
|
|
|
||
|
|
HRESULT EnumJobs( [in] DWORD dwFlags,
|
||
|
|
[out] IEnumBackgroundCopyJobs **ppEnum );
|
||
|
|
|
||
|
|
HRESULT GetErrorDescription(
|
||
|
|
[in] HRESULT hResult,
|
||
|
|
[in] DWORD LanguageId,
|
||
|
|
[out] LPWSTR *pErrorDescription );
|
||
|
|
}
|
||
|
|
|
||
|
|
//---------------------------------------------------------------------------
|
||
|
|
|
||
|
|
[
|
||
|
|
uuid(1deeb74f-7915-4560-b558-918c83f176a6),
|
||
|
|
helpstring("Microsoft Background Copy Queue Manager 1.0"),
|
||
|
|
lcid(0x0000),
|
||
|
|
version(1.0)
|
||
|
|
]
|
||
|
|
library BackgroundCopyManager
|
||
|
|
{
|
||
|
|
[
|
||
|
|
uuid(4991d34b-80a1-4291-83b6-3328366b9097),
|
||
|
|
helpstring("Background copy control class")
|
||
|
|
]
|
||
|
|
coclass BackgroundCopyManager
|
||
|
|
{
|
||
|
|
[default] interface IBackgroundCopyManager;
|
||
|
|
};
|
||
|
|
interface IBackgroundCopyCallback;
|
||
|
|
}
|
||
|
|
|
||
|
|
cpp_quote("#include \"bits1_5.h\"")
|