// IUCtl.idl : IDL source for IUCtl.dll // // This file will be processed by the MIDL tool to // produce the type library (IUCtl.tlb) and marshalling code. import "oaidl.idl"; import "ocidl.idl"; [ object, uuid(4F5E50AF-A2C0-40EF-AC9A-469D9462EA76), dual, helpstring("IUpdate Interface"), pointer_default(unique) ] interface IUpdate : IDispatch { /** * Gets the basic system specs * @param bstrXmlClasses a list of requested classes, NULL if any * * * * * @param pbstrXmlDetectionResult [out] * the detection result in simple xml format * * * * * * * * * * Win95 * * * * * PCI\VEN_8086&DEV_7191&SUBSYS_0000000&REV_02 * * * PCI\VEN_8086&DEV_7191&SUBSYS_0000000 * * * ... * * */ [id(1), helpstring("method GetSystemSpec() gets the basic system specs")] HRESULT GetSystemSpec( [in] BSTR bstrXmlClasses, [out, retval] BSTR* pbstrXmlDetectionResult ); /** * Gets a catalog base on the specified information * @param bstrXmlClientInfo the credentials of the client in xml format * @param bstrXmlSystemSpec the detected system specifications in xml * @param bstrXmlQuery the user query infomation in xml * @param pbstrXmlCatalog [out] the xml catalog retrieved */ [id(2), helpstring("method GetManifest() gets a catalog base on the specified information")] HRESULT GetManifest( [in] BSTR bstrXmlClientInfo, [in] BSTR bstrXmlSystemSpec, [in] BSTR bstrXmlQuery, [out, retval] BSTR* pbstrXmlCatalog ); /** * Detect * @param bstrXmlCatalog the xml catalog portion containing items to be detected * @param pbstrXmlItems [out] the detected items in xml format * e.g. * */ [id(3), helpstring("method Detect() detects software and drivers on current machine")] HRESULT Detect( [in] BSTR bstrXmlCatalog, [out, retval] BSTR* pbstrXmlItems ); /** * Synchronized download * @param bstrXmlClientInfo the credentials of the client in xml format * @param bstrXmlCatalog the xml catalog portion containing items to be downloaded * @param bstrDestinationFolder the destination folder. Null will use the default IU folder * @param lMode indicates throttled or fore-ground downloading mode * @param punkProgressListener a notification listener - that implements the * IProgressListener (see below), to receive notifications about progress. * @param pbstrXmlItems [out] the items with download status in xml format * e.g. * */ [id(4), helpstring("method Dowload() performs synchronized downloading")] HRESULT Download( [in] BSTR bstrXmlClientInfo, [in] BSTR bstrXmlCatalog, [in] BSTR bstrDestinationFolder, [in] LONG lMode, [in] IUnknown* punkProgressListener, [out, retval] BSTR* pbstrXmlItems ); /** * Download asynchronously - the method will return before completion * @param bstrXmlClientInfo the credentials of the client in xml format * @param bstrXmlCatalog the xml catalog portion containing items to be downloaded * @param bstrDestinationFolder the destination folder. Null will use the default IU folder * @param lMode indicates throttled or fore-ground downloading mode * @param punkProgressListener a notification listener - that implements the * IProgressListener (see below), to receive notifications about progress. * @param bstrUuidOperation an id provided by the client to provide further * identification to the operation as indexes may be reused. * @param pbstrUuidOperation [out] the operation ID. If it is not provided by the * in bstrUuidOperation parameter (an empty string is passed), it will generate a new UUID, * in which case, the caller will be responsible to free the memory of the * string buffer that holds the generated UUID using SysFreeString(). * Otherwise, it returns the value passed by bstrUuidOperation. */ [id(5), helpstring("method DownloadAsync() performs asynchronized downloading")] HRESULT DownloadAsync( [in] BSTR bstrXmlClientInfo, [in] BSTR bstrXmlCatalog, [in] BSTR bstrDestinationFolder, [in] LONG lMode, [in] IUnknown* punkProgressListener, [in] BSTR bstrUuidOperation, [out, retval] BSTR* pbstrUuidOperation ); /** * Synchronized install * @param bstrXmlCatalog the xml catalog portion containing items to be installed * @param bstrXmlDownloadedItems the xml of downloaded items and their respective download result as described in the result schema. Install uses this to know whether the items were downloaded and if so where they were downloaded to so that it can install the items * @param lMode indicates different installation mode (undefined) * @param punkProgressListener a notification listener - that implements the * IProgressListener (see below), to receive notifications about progress. * @param pbstrXmlItems [out] the items with installation status in xml format * e.g. * */ [id(6), helpstring("method Install() performs synchronized installation")] HRESULT Install( [in] BSTR bstrXmlClientInfo, [in] BSTR bstrXmlCatalog, [in] BSTR bstrXmlDownloadedItems, [in] LONG lMode, [in] IUnknown* punkProgressListener, [out, retval] BSTR* pbstrXmlItems ); /** * Install Asynchronously * @param bstrXmlCatalog the xml catalog portion containing items to be installed * @param bstrXmlDownloadedItems the xml of downloaded items and their respective download result as described in the result schema. Install uses this to know whether the items were downloaded and if so where they were downloaded to so that it can install the items * @param lMode indicates different installation mode (undefined) * @param punkProgressListener a notification listener - that implements the * IProgressListener (see below), to receive notifications about progress. * @param bstrUuidOperation an id provided by the client to provide further * identification to the operation as indexes may be reused. * @param pbstrUuidOperation [out] the operation ID. If it is not provided by the * in bstrUuidOperation parameter (an empty string is passed), it will generate a new UUID, * in which case, the caller will be responsible to free the memory of the * string buffer that holds the generated UUID using SysFreeString(). * Otherwise, it returns the value passed by bstrUuidOperation. */ [id(7), helpstring("method InstallAsync() performs asynchronized installation")] HRESULT InstallAsync( [in] BSTR bstrXmlClientInfo, [in] BSTR bstrXmlCatalog, [in] BSTR bstrXmlDownloadedItems, [in] LONG lMode, [in] IUnknown* punkProgressListener, [in] BSTR bstrUuidOperation, [out, retval] BSTR* pbstrUuidOperation ); /** * Set the operation status * @param bstrUuidOperation an id provided by the client to provide further * identification to the operation as indexes may be reused. * @param lMode: a bitmask for the following mode: * const LONG UPDATE_COMMAND_PAUSE = 0x00000001; * const LONG UPDATE_COMMAND_RESUME = 0x00000002; * const LONG UPDATE_COMMAND_CANCEL = 0x00000004; * */ [id(8), helpstring("method SetOperationModes() sets the mode of an asynchronous operation")] HRESULT SetOperationMode( [in] BSTR bstrUuidOperation, [in] LONG lMode ); /** * Get the history log * @param bstrDateTimeFrom the start date and time for which a log is required. * This is a string in ANSI format (YYYY-MM-DDTHH-MM). If the string is empty, * there will be no date restriction of the returned history log. * @param bstrDateTimeTo the end date and time for which a log is required. * This is a string in ANSI format (YYYY-MM-DDTHH-MM). If the string is empty, * there will be no date restriction of the returned history log. * @param bstrClient the name of the client that initiated the action. If this parameter * is null or an empty string, then there will be no filtering based on the client. * @param bstrPath the path used for download or install. Used in the corporate version * by IT managers. If this parameter is null or an empty string, then there will * be no filtering based on the path. * @param pbstrLog [out] the history log in xml format */ [id(9), helpstring("method GetHistory() gets the history log")] HRESULT GetHistory( [in] BSTR bstrDateTimeFrom, [in] BSTR bstrDateTimeTo, [in] BSTR bstrClient, [in] BSTR bstrPath, [out, retval] BSTR* pbstrLog ); /** * * Get the mode of a specified operation. * * @param bstrUuidOperation: same as in SetOperationMode() * @param plMode - the retval for the mode found in a bitmask for: * * const LONG UPDATE_MODE_PAUSED = 0x00000001; * const LONG UPDATE_MODE_RUNNING = 0x00000002; * const LONG UPDATE_MODE_NOTEXISTS = 0x00000004; * */ [id(10), helpstring("method GetOperationMode() retrieves the current mode of an operation")] HRESULT GetOperationMode( [in] BSTR bstrUuidOperation, [out,retval] LONG* plMode ); /** * * Set a property of this control * Calling this method will not cause the engine loaded * * @param lProperty - the identifier to flag which property need changed * UPDATE_PROP_OFFLINEMODE (TRUE/[FALSE]) * UPDATE_PROP_USECOMPRESSION ([TRUE]/FALSE) * * @param varValue - the value to change * */ [id(11), helpstring("method SetProperty")] HRESULT SetProperty( [in] LONG lProperty, [in] VARIANT varValue ); /** * * Retrieve a property of this control * Calling this method will not cause the engine loaded * * @param lProperty - the identifier to flag which property need retrieved * UPDATE_PROP_OFFLINEMODE (TRUE/[FALSE]), * UPDATE_PROP_USECOMPRESSION ([TRUE]/FALSE) * * @param varValue - the value to retrieve * */ [id(12), helpstring("method GetProperty")] HRESULT GetProperty( [in] LONG lProperty, [out,retval] VARIANT* pvarValue ); /** * * Primarily expose shlwapi BrowseForFolder API, can also do checking * on R/W access if flagged so. * * @param bstrStartFolder - the folder from which to start. If NULL or empty str * is being passed in, then start from desktop * * @param flag - can be one or more (OR'ed) value defined below * * @param pbstrFolder - returned folder if a valid folder selected * */ [id(13), helpstring("method BrowseForFolder pops up UI for browsing a folder")] HRESULT BrowseForFolder( [in] BSTR bstrStartFolder, [in] LONG flag, [out,retval] BSTR* pbstrFolder ); /** * constants for BrowseForFolder() API * * IUBROWSE_WRITE_ACCESS - validate write access on selected folder * IUBROWSE_AFFECT_UI - write-access validation affect OK button enable/disable * IUBROWSE_NOBROWSE - do not show browse folder dialog box. validate path passed-in only * * default: * pop up browse folder dialog box, not doing any write-access validation * */ const LONG IUBROWSE_WRITE_ACCESS = 1; const LONG IUBROWSE_AFFECT_UI = 2; const LONG IUBROWSE_NOBROWSE = 4; /** * * Allows the Caller to Request the Control to do a Reboot * */ [id(14), helpstring("method RebootMachine causes a ShutDown/Restart on the Machine")] HRESULT RebootMachine(); /** * * Initialize the control, including check update necesity and do actual update * */ [id(15), helpstring("method Initialize is the first API you have to call before the control will function")] HRESULT Initialize( [in] LONG lInitFlag, [in] IUnknown* punkUpdateCompleteListener, [out, retval] LONG* plRetVal ); /** * * Helper API to make the control can be unloaded completely from IE so update control * will not cause reboot. * * Call it with parameter 0, in order to create a clone called IUCtl.Update2 * (then set this object to nothing, create object to clone, then set clone to nothing. At * this time, you are ready to update the original control without causing reboot) * * Call it with parameter 1, in order to delete the clone file * */ [id(16), helpstring("method PrepareSelfUpdate")] HRESULT PrepareSelfUpdate([in] LONG lStep); /** * * Helper API to let the caller (script) knows the necessary information * when Initialize() returns control need updated. * * For the current implementation, bstrClientName is ignored, and * the returned bstr has format: * "|" * where: * is the expacted version number of the control * is the base url to get the control if this is a CorpWU policy controlled machine, * or empty if this is a consumer machine (in that case caller, i.e., script, knows * the default base url, which is the v4 live site) * * Script will need these two pieces of information in order to make a right tag * for control update. * */ [id(17), helpstring("method GetControlExtraInfo")] HRESULT GetControlExtraInfo([in] BSTR bstrClientName, [out,retval] BSTR *pbstrExtraInfo); /** * constants for checking Initialize() API return value * * IU_UPDATE_CONTROL_BIT - bit to tell if control needs updated * IU_UPDATE_ENGINE_BIT - bit to tell if engine needs updated * */ const LONG IU_UPDATE_CONTROL_BIT = 1; const LONG IU_UPDATE_ENGINE_BIT = 2; /** * * constants for Initialize() API flags. These flags are mutual exclusive * * IU_INIT_CHECK - only check the update neccesity. Won't cause update happen * IU_INIT_UPDATE_SYNC - cause the update engine starts in sync mode * IU_INIT_UPDATE_ASYNC - cause the update engine starts in async mode * */ const LONG IU_INIT_CHECK = 0; const LONG IU_INIT_UPDATE_SYNC = 1; const LONG IU_INIT_UPDATE_ASYNC = 2; }; [ object, uuid(229F78AE-6618-4DF3-95D2-FC26C9F97428), helpstring("IProgressListener Interface"), pointer_default(unique) ] interface IProgressListener : IUnknown { /** * fire event to notify that this item is about to be downloaded. * and (in VB) plCommandRequest can be set to pause or cancel the * whole download/install operation * @param bstrUuidOperation the operation identification guid * @param bstrXmlItem item XML node in BSTR, contains identity and platform * @param plCommandRequest a command to pass from the listener to the owner of the event, * e.g. UPDATE_COMMAND_CANCEL, zero if nothing is requested. */ [id(1), helpstring("method OnProgress() notifies the listener for the progress of the operation")] HRESULT OnItemStart( [in] BSTR bstrUuidOperation, [in] BSTR bstrXmlItem, [out] LONG* plCommandRequest ); /** * Notify the listener that a portion of the files has finished operation * (e.g downloaded or installed). Enables monitoring of progress. * @param bstrUuidOperation the operation identification guid * @param fItemCompleted TRUE if the current item has completed the operation * @param nPercentComplete total percentage of operation completed * @param plCommandRequest a command to pass from the listener to the owner of the event, * e.g. UPDATE_COMMAND_CANCEL, zero if nothing is requested. */ [id(2), helpstring("method OnProgress() notifies the listener for the progress of the operation")] HRESULT OnProgress( [in] BSTR bstrUuidOperation, [in] VARIANT_BOOL fItemCompleted, [in] BSTR bstrProgress, [out] LONG* plCommandRequest ); /** * Notify the listener when the operation is complete. * @param bstrUuidOperation the operation identification guid */ [id(3), helpstring("method OperationComplete() notifies the listener when the operation is complete")] HRESULT OnOperationComplete( [in] BSTR bstrUuidOperation, [in] BSTR bstrXmlItems); }; [ object, uuid(1C06B895-E4C8-48eb-9E03-15A53B43B6CA), helpstring("IUpdateCompleteListener Interface"), pointer_default(unique) ] interface IUpdateCompleteListener : IUnknown { /** * Notify the listener that the async engine update is finished. * * @param lErrorCode - ERROR_SUCCESS/S_OK if everything is fine. * otherwise this is error code returned * */ [id(1), helpstring("method OnComplete() notifies the listener when the async engine update is complete")] HRESULT OnComplete([in] LONG lErrorCode); }; /** * the following two groups of constants can be used to construct * lMode parameter of the following APIs: * Download() * DownloadAsync() * Install() * InstallAsync() * * Obviousely, you can only pick one from each group to make up * lMode parameter. * */ const LONG UPDATE_NOTIFICATION_DEFAULT = 0x00000000; const LONG UPDATE_NOTIFICATION_ANYPROGRESS = 0x00000000; const LONG UPDATE_NOTIFICATION_COMPLETEONLY = 0x00010000; const LONG UPDATE_NOTIFICATION_1PCT = 0x00020000; const LONG UPDATE_NOTIFICATION_5PCT = 0x00040000; const LONG UPDATE_NOTIFICATION_10PCT = 0x00080000; /** * constant can also be used for GetOperationMode() */ const LONG UPDATE_MODE_THROTTLE = 0x00000100; /** * constant can be used by Download() and DownloadAsync(), which will * tell these API's to use Corporate directory structure for destination folder. */ const LONG UPDATE_CORPORATE_MODE = 0x00000200; /** * constant can be used by Install() and InstallAsync(). Will disable all * internet related features */ const LONG UPDATE_OFFLINE_MODE = 0x00000400; /** * constants for SetOperationMode() API */ const LONG UPDATE_COMMAND_PAUSE = 0x00000001; const LONG UPDATE_COMMAND_RESUME = 0x00000002; const LONG UPDATE_COMMAND_CANCEL = 0x00000004; /** * constants for GetOperationMode() API */ const LONG UPDATE_MODE_PAUSED = 0x00000001; const LONG UPDATE_MODE_RUNNING = 0x00000002; const LONG UPDATE_MODE_NOTEXISTS = 0x00000004; /** * constants for SetProperty() and GetProperty() API */ const LONG UPDATE_PROP_USECOMPRESSION = 0x00000020; const LONG UPDATE_PROP_OFFLINEMODE = 0x00000080; [ object, uuid(8E2EF6DC-0AB8-4FE0-9049-3BEA4506BF8D), dual, helpstring("IDetection Interface"), pointer_default(unique) ] interface IDetection : IDispatch { [id(1), helpstring("method Detect() - content provider provided custom detection mechanism as a COM server")] HRESULT Detect( [in] BSTR bstrXML, /* detection manifest */ [out] DWORD *pdwDetectionResult /* detection result, see below for interpretation */ ); }; /** * declare the constants used to manipulate the result of Detect() method */ /** * First group, used in tag, to tell the detection result. This result * should combined with other expression(s) at the same level */ const LONG IUDET_BOOL = 0x00000001; /* mask */ const LONG IUDET_FALSE = 0x00000000; /* expression detect FALSE */ const LONG IUDET_TRUE = 0x00000001; /* expression detect TRUE */ const LONG IUDET_NULL = 0x00000002; /* expression detect data missing */ /** * Second group, used in tag, to tell the detection result. This result * should overwrite the rest of , if any */ const LONG IUDET_INSTALLED = 0x00000010; /* mask for result */ const LONG IUDET_INSTALLED_NULL = 0x00000020; /* missing */ const LONG IUDET_UPTODATE = 0x00000040; /* mask for result */ const LONG IUDET_UPTODATE_NULL = 0x00000080; /* missing */ const LONG IUDET_NEWERVERSION = 0x00000100; /* mask for result */ const LONG IUDET_NEWERVERSION_NULL = 0x00000200; /* missing */ const LONG IUDET_EXCLUDED = 0x00000400; /* mask for result */ const LONG IUDET_EXCLUDED_NULL = 0x00000800; /* missing */ const LONG IUDET_FORCE = 0x00001000; /* mask for result */ const LONG IUDET_FORCE_NULL = 0x00002000; /* missing */ const LONG IUDET_COMPUTER = 0x00004000; // mask for result const LONG IUDET_COMPUTER_NULL = 0x00008000; // missing [ uuid(306C2111-D294-4DD1-9C47-41036F58EBB3), version(1.0), helpstring("IUCtl 1.0 Type Library") ] library IUCTLLib { importlib("stdole32.tlb"); importlib("stdole2.tlb"); [ uuid(CD19302B-FF55-4274-BA18-D98F21FCD672), helpstring("IUpdateEvents Interface") ] dispinterface IUpdateEvents { properties: methods: /** * fire event to notify that this item is about to be downloaded. * and (in VB) plCommandRequest can be set to pause or cancel the * whole download/install operation * @param bstrUuidOperation the operation identification guid * @param bstrXmlItem item XML node in BSTR, contains identity and platform * @param plCommandRequest a command to pass from the listener to the owner of the event, * e.g. UPDATE_COMMAND_CANCEL, zero if nothing is requested. */ [id(1), helpstring("method OnProgress() notifies the listener for the progress of the operation")] void OnItemStart( [in] BSTR bstrUuidOperation, [in] BSTR bstrXmlItem, [out] LONG* plCommandRequest ); /** * Notify the listener that a portion of the files has finished operation * (e.g downloaded or installed). Enables monitoring of progress. * @param bstrUuidOperation the operation identification guid * @param fItemCompleted TRUE if the current item has completed the operation * @param nPercentComplete total percentage of operation completed * @param plCommandRequest a command to pass from the listener to the owner of the event, * e.g. UPDATE_COMMAND_CANCEL, zero if nothing is requested. */ [id(2), helpstring("method OnProgress() notifies the listener for the progress of the operation")] void OnProgress( [in] BSTR bstrUuidOperation, [in] VARIANT_BOOL fItemCompleted, [in] BSTR bstrProgress, [out] LONG* plCommandRequest ); /** * Notify the listener when the operation is complete. * @param bstrUuidOperation the operation identification guid */ [id(3), helpstring("method OnOperationComplete() notifies the listener when the operation is complete")] void OnOperationComplete( [in] BSTR bstrUuidOperation, [in] BSTR bstrXmlItems); /** * Notify the listener when the engine self-update is complete. * @param lErrorCode - the operation result */ [id(4), helpstring("method OnComplete")] void OnComplete([in] LONG lErrorCode); }; [ uuid(9F1C11AA-197B-4942-BA54-47A8489BB47F), helpstring("Update Class") ] coclass Update { [default] interface IUpdate; [default, source] dispinterface IUpdateEvents; }; [ uuid(3E873CB7-D5F5-43EF-AC4A-1F97D3118265), helpstring("ProgressListener Class") ] coclass ProgressListener { [default] interface IProgressListener; }; [ uuid(526ED46B-DBCD-4936-AB2B-D847C605C259), helpstring("IUpdateCompleteListener Interface") ] coclass UpdateCompleteListener { [default] interface IUpdateCompleteListener; }; [ uuid(B5AF6951-FFBD-4E7B-A126-8F28F86E5D2E), helpstring("Detection Class") ] coclass Detection { [default] interface IDetection; }; };