//======================================================================= // // Copyright (c) 2000 Microsoft Corporation. All Rights Reserved. // // File: qmgr.idl // // Description: // Declares the QMgr COM interface // //======================================================================= #ifndef DO_NO_IMPORTS import "unknwn.idl"; import "ocidl.idl"; import "oleidl.idl"; import "oaidl.idl"; import "docobj.idl"; #endif cpp_quote("// Background Copy QMgr Public Interface") //various events and flags /*************Notify flags**************/ cpp_quote("#define QM_NOTIFY_FILE_DONE 0x00000001") cpp_quote("#define QM_NOTIFY_JOB_DONE 0x00000002") cpp_quote("#define QM_NOTIFY_GROUP_DONE 0x00000004") cpp_quote("#define QM_NOTIFY_DISABLE_NOTIFY 0x00000040") cpp_quote("#define QM_NOTIFY_USE_PROGRESSEX 0x00000080") /*************Status flags**************/ cpp_quote("#define QM_STATUS_FILE_COMPLETE 0x00000001") cpp_quote("#define QM_STATUS_FILE_INCOMPLETE 0x00000002") cpp_quote("#define QM_STATUS_JOB_COMPLETE 0x00000004") cpp_quote("#define QM_STATUS_JOB_INCOMPLETE 0x00000008") cpp_quote("#define QM_STATUS_JOB_ERROR 0x00000010") cpp_quote("#define QM_STATUS_JOB_FOREGROUND 0x00000020") cpp_quote("#define QM_STATUS_GROUP_COMPLETE 0x00000040") cpp_quote("#define QM_STATUS_GROUP_INCOMPLETE 0x00000080") cpp_quote("#define QM_STATUS_GROUP_SUSPENDED 0x00000100") cpp_quote("#define QM_STATUS_GROUP_ERROR 0x00000200") cpp_quote("#define QM_STATUS_GROUP_FOREGROUND 0x00000400") /*************Protocol flags***************/ cpp_quote("#define QM_PROTOCOL_HTTP 1") cpp_quote("#define QM_PROTOCOL_FTP 2") cpp_quote("#define QM_PROTOCOL_SMB 3") cpp_quote("#define QM_PROTOCOL_CUSTOM 4") /**************Progress Flags**************/ cpp_quote("#define QM_PROGRESS_PERCENT_DONE 1") cpp_quote("#define QM_PROGRESS_TIME_DONE 2") cpp_quote("#define QM_PROGRESS_SIZE_DONE 3") /**************Error Codes****************/ cpp_quote("#define QM_E_INVALID_STATE 0x81001001") cpp_quote("#define QM_E_SERVICE_UNAVAILABLE 0x81001002") cpp_quote("#define QM_E_DOWNLOADER_UNAVAILABLE 0x81001003") cpp_quote("#define QM_E_ITEM_NOT_FOUND 0x81001004") #if defined(TEST_TIMES) typedef struct _BACKGROUND_COPY_TIMES { FILETIME ftCreationTime; FILETIME ftModificationTime; FILETIME ftCompletionTime; } BACKGROUND_COPY_TIMES; #endif // // ============================= // Marshalled interfaces // ============================= // ============================================== // IJob Interface // The IJob interface is the management layer for a file (or set of files) // to be transferred. [ uuid(59f5553c-2031-4629-bb18-2645a6970947), helpstring("IBackgroundCopyJob Interface"), odl ] interface IBackgroundCopyJob1 : IUnknown { typedef struct _FILESETINFO { BSTR bstrRemoteFile; BSTR bstrLocalFile; DWORD dwSizeHint; } FILESETINFO; HRESULT CancelJob(); /* return Job2::Cancel(); */ HRESULT GetProgress([in] DWORD dwFlags, [out] DWORD *pdwProgress); /* flags == TIME_DONE: return E_NOTIMPL flags == SIZE_DONE: return BYTES_DOWNLOADED property flags == PERCENT_DONE: return 100 * (BYTES_DOWNLOADED property) / (BYTES_TOTAL property) */ HRESULT GetStatus( [out] DWORD *pdwStatus, [out] DWORD *pdwWin32Result, [out] DWORD *pdwTransportResult, [out] DWORD *pdwNumOfRetries ); /* dwStatus: if (foreground priority) set QM_STATUS_JOB_FOREGROUND get JOBPROP_STATUS_FLAGS if flags & QM_STATUS_COMPLETE set QM_JOB_STATUS_COMPLETE else set QM_JOB_STATUS_INCOMPLETE if flags & QM_STATUS_ERROR set QM_JOB_STATUS_ERROR dwWin32Result: return JOBPROP_LAST_LOCAL_STATUS dwTransportResult: return JOBPROP_LAST_TRANSPORT_STATUS dwNumOfRetries: return JOBPROP_RETRY_COUNT */ HRESULT AddFiles([in] ULONG cFileCount, [in, size_is(cFileCount)] FILESETINFO **ppFileSet); /* return Job2::AddFiles( cFileCount, ppFileSet ); */ HRESULT GetFile([in] ULONG cFileIndex, [out] FILESETINFO *pFileInfo); /* allocate FILESETINFO struct Job2::GetFile( cFileIndex, &pInterface ) fill in struct from interface calls */ HRESULT GetFileCount([out] DWORD *pdwFileCount); /* return JOBPROP_FILES_TOTAL; */ HRESULT SwitchToForeground(); /* set JOBPROP_PRIORITY = PRIORITY_FOREGROUND */ HRESULT get_JobID([out] GUID *pguidJobID); // used to a identify a job when enumerating jobs /* return JOBPROP_ID */ #if defined(TEST_TIMES) HRESULT GetTimes( [out,ref] BACKGROUND_COPY_TIMES *pTimes ); #endif } // ============================================== // IEnumJobs Interface // This interface allows enumerating the jobs under a Group [ uuid(8baeba9d-8f1c-42c4-b82c-09ae79980d25), helpstring("IEnumBackgroundCopyJobs Interface"), odl ] interface IEnumBackgroundCopyJobs1 : IUnknown { /* constructor creates an EnumJobs2 interface */ HRESULT Next([in] ULONG celt, [out, size_is(celt), length_is(*pceltFetched)] GUID *rgelt, [out] ULONG *pceltFetched); /* IJob2 * Array[ celt ]; pInterface->Next( celt, Array, *count ); for (i=0; i < count; ++i) rgelt = Array[i]->JOBPROP_ID; */ HRESULT Skip([in] ULONG celt); HRESULT Reset(); HRESULT Clone([out] IEnumBackgroundCopyJobs1 **ppenum); HRESULT GetCount([out] ULONG *puCount); /* pass all four to pInterface */ } // ============================================== // IGroup Interface // This interface is the base unit of management for a Job or Set of Jobs [ uuid(1ded80a7-53ea-424f-8a04-17fea9adc4f5), helpstring("IBackgroundCopyGroup Interface"), odl ] interface IBackgroundCopyGroup : IUnknown { typedef enum GROUPPROP { GROUPPROP_PRIORITY = 0, // DWORD Priority Level for this Group GROUPPROP_REMOTEUSERID = 1, // User Credentials for Remote Server GROUPPROP_REMOTEUSERPWD = 2, GROUPPROP_LOCALUSERID = 3, // User Credentials for Local Machine, or flag for system credentials on NT, GROUPPROP_LOCALUSERPWD = 4, GROUPPROP_PROTOCOLFLAGS = 5, // specifies the protocol information about the server, HTTP, SSL, SMB, DAV GROUPPROP_NOTIFYFLAGS = 6, // Notification Type/Frequency Flags (per Job, per Group, progress and error notifications) GROUPPROP_NOTIFYCLSID = 7, // CLSID that implements the IBackgroundCallback interface for notifications, we'll create this to do callbacks GROUPPROP_PROGRESSSIZE = 8, // Turns on Progress Notifications for Size Values (e.g. notify every 4k, 8k, etc..) GROUPPROP_PROGRESSPERCENT = 9, // Turns on Progress Notifications for Percent Value (e.g. Notify every 10%, 5%, etc..) GROUPPROP_PROGRESSTIME = 10, // Turns on Progress Notifications for Time GROUPPROP_DISPLAYNAME = 11, // friendly display name of the group (something we can display in a future UI GROUPPROP_DESCRIPTION = 12 } GROUPPROP; HRESULT GetProp([in] GROUPPROP propID, [out] VARIANT *pvarVal); [local] HRESULT SetProp([in] GROUPPROP propID, [in] VARIANT *pvarVal); [call_as(SetProp)] HRESULT InternalSetProp([in] GROUPPROP propID, [in] VARIANT *pvarVal); HRESULT GetProgress([in] DWORD dwFlags, [out] DWORD *pdwProgress); HRESULT GetStatus([out] DWORD *pdwStatus, [out] DWORD *pdwJobIndex); /* translate into Group2 properties */ HRESULT GetJob([in] GUID jobID, [out] IBackgroundCopyJob1 **ppJob); HRESULT SuspendGroup(); HRESULT ResumeGroup(); // New groups are by default suspended, when all jobs are initialized call resumegroup to enable the group HRESULT CancelGroup(); HRESULT get_Size([out] DWORD *pdwSize); // gets the calculated size of the jobs in this group HRESULT get_GroupID([out] GUID *pguidGroupID); // used to identify a group when enumerating groups /* pass to Group2 interface */ HRESULT CreateJob([in] GUID guidJobID, [out] IBackgroundCopyJob1 **ppJob); /* create a Job2 and a wrapper Job */ HRESULT EnumJobs([in] DWORD dwFlags, [out] IEnumBackgroundCopyJobs1 **ppEnumJobs); /* create an EnumJobs which will wrap around an EnumJobs2 */ HRESULT SwitchToForeground(); // end of the original Mars interface is here HRESULT QueryNewJobInterface( [in] REFIID iid, [out, iid_is(iid)] IUnknown ** pUnk ); HRESULT SetNotificationPointer( [in] REFIID iid, [in] IUnknown * pUnk ); } // ============================================== // IEnumGroups Interface [ uuid(d993e603-4aa4-47c5-8665-c20d39c2ba4f), helpstring("IEnumBackgroundCopyGroups Interface"), odl ] interface IEnumBackgroundCopyGroups : IUnknown { /* analagous to EnumJobs interface */ HRESULT Next([in] ULONG celt, [out, size_is(celt), length_is(*pceltFetched)] GUID *rgelt, [out] ULONG *pceltFetched); HRESULT Skip([in] ULONG celt); HRESULT Reset(); HRESULT Clone([out] IEnumBackgroundCopyGroups **ppenum); HRESULT GetCount([out] ULONG *puCount); } // ============================================== // IBackgroundCallback Interface // This interface is implemented by the client and is used by the queue manager to supply status and // progress information to the client. [ uuid(084f6593-3800-4e08-9b59-99fa59addf82), helpstring("IBackgroundCopyCallback Interface"), odl ] interface IBackgroundCopyCallback1 : IUnknown { HRESULT OnStatus( [in] IBackgroundCopyGroup *pGroup, [in] IBackgroundCopyJob1 *pJob, [in] DWORD dwFileIndex, [in] DWORD dwStatus, [in] DWORD dwNumOfRetries, [in] DWORD dwWin32Result, [in] DWORD dwTransportResult ); /* return corresponding properties from active Job2 */ HRESULT OnProgress( [in] DWORD ProgressType, [in] IBackgroundCopyGroup *pGroup, [in] IBackgroundCopyJob1 *pJob, [in] DWORD dwFileIndex, [in] DWORD dwProgressValue ); HRESULT OnProgressEx( [in] DWORD ProgressType, [in] IBackgroundCopyGroup *pGroup, [in] IBackgroundCopyJob1 *pJob, [in] DWORD dwFileIndex, [in] DWORD dwProgressValue, [in] DWORD dwByteArraySize, [in, size_is(dwByteArraySize)] BYTE *pByte ); /* see which features are actually in use; translate into Job2 properties. BUGBUG need to decide whether to implement ProgressEx (streaming) */ } [ uuid(16f41c69-09f5-41d2-8cd8-3c08c47bc8a8), // IID_IQMgr helpstring("Background Copy QMgr interface"), odl ] interface IBackgroundCopyQMgr : IUnknown { // Group Interface Methods (Groups contain sets of related Jobs) HRESULT CreateGroup([in] GUID guidGroupID, [out] IBackgroundCopyGroup **ppGroup); HRESULT GetGroup([in] GUID groupID, [out] IBackgroundCopyGroup **ppGroup); HRESULT EnumGroups([in] DWORD dwFlags, [out] IEnumBackgroundCopyGroups **ppEnumGroups); /* direct translation into Group2 etc. */ } //--------------------------------------------------------------------------- // IQMgr [ uuid(f5b26dcb-b37e-4d7c-ae7a-1cb3fbeb183e), // LIBID_QMgr helpstring("Microsoft Background Copy Queue Manager 1.0"), lcid(0x0000), version(1.0) ] library BackgroundCopyQMgr { //------------------------------------------------------------- // QMgr //------------------------------------------------------------- [ uuid(69AD4AEE-51BE-439b-A92C-86AE490E8B30), helpstring("Background Copy QMgr Class") ] coclass BackgroundCopyQMgr { [default] interface IBackgroundCopyQMgr; }; }