windows-xp/Source/XPSP1/NT/base/win32/fusion/installer/includes/bits.idl

//=======================================================================
//
//  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   Transferred;
    }
    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;

    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;

    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),
    async_uuid(ca29d251-b4bb-4679-a3d9-ae8006119d54),
    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;
    };
}