Integrating manageability applications with the Office 365 click-to-run installer

To use this interface, a manageability application invokes the COM interface and calls exposed APIs that communicate directly with the Click-to-Run installation service.

Note
The Office Click-to-Run installer can be run from the command-line with parameters that can control the behavior, as documented in Office Deployment Tool for Click-to-Run.

The Office 365 Click-to-Run installer implements a COM-based interface, IUpdateNotify registered to CLSID CLSID_UpdateNotifyObject, {b7f1785f-d69b-46f1-92fc-d2de9c994f13}.

This interface can be invoked as follows:

hr = CoCreateInstance(CLSID_UpdateNotifyObject, NULL, CLSCTX_ALL,
       IID_IUpdateNotify, 
      (void **)&p); 

The call will only succeed if the caller is running under elevated privileges, as the Click-to-Run installation program must be run with elevated privileges.

The COM interface exposes four asynchronous functions. These functions validate the command and the parameters and then sends them on to the existing Click-to-Run installation service. If the command sent was successfully scheduled for execution, the service will return an S_OK return code. Poll the Status method the command for completion, to get information about the success of the command, or to get detailed error codes.

HRESULT Download([in] LPWSTR pcwszParameters) // Download update content.
HRESULT Apply([in] LPWSTR pcwszParameters) // Apply update content. 
HRESULT Cancel() // Cancel the download action. 
HRESULT status([out] _UPDATE_STATUS_REPORT* pUpdateStatusReport) // Get status of current action. 
typedef struct _UPDATE_STATUS_REPORT  
{  
UPDATE_STATUS status;  
UINT error; 
LPCWSTR contentid  
} UPDATE_STATUS_REPORT;

Note
Rebooting: When the machine is booting there is a period of time when the Click-to-Run installer service is not available. A successful call to the Status method after a reboot will return eUPDATE_UNKNOWN.

Idle: When the Click-to-Run installer is in the idle state, you can call:

• Apply: Install previously downloaded content.

• Cancel: Returns 0x800000e, "A method was called at an unexpected time."

• Download: Downloads new content to the client for later installation.

• Status: Returns the result of the last completed action, or an error message if the action ended in failure. If there is no previous action, Status returns eUPDATE_UNKNOWN.

Downloading: When the Click-to-Run installer is in the downloading state, you can call:

• Apply: Returns an HRESULT with the value 0x800000e, "A method was called at an unexpected time."

• Cancel: Stops the download and removes the partially downloaded content.

• Download: Returns an HRESULT with the value 0x800000e, "A method was called at an unexpected time."

• Status: Returns DOWNLOAD_WIP to indicate that download work is in progress.

Applying: When the Click-to-Run installer is in the process of installing previously download content:

• Apply: Returns an HRESULT with the value 0x800000e, "A method was called at an unexpected time."

• Cancel: Returns 0x800000e, the Apply action cannot be canceled.

• Download: Returns an HRESULT with the value 0x800000e, "A method was called at an unexpected time."

• Status: Returns APPLY_WIP to indicate that apply work is in progress.

Note

Note: Since OfficeC2RCom COM+ service and is dynamically loaded component, you need to call CoCreateInstance every time you call a method on this class to ensure that you get the expected result. The COM+ service will handle creating a new instance if necessary. When one of the methods is called for the first time, COM+ will load the IUpdateNotify object and run it within one of the dllhost.exe instances. The new object will stay active for about 3 minutes in idle. If a subsequent call is made within three minutes of the last call, the IUpdateNotify object will remain loaded and a new instance is not created. If no call is made within three minutes, the IUpdateNotify object will be unloaded and a new IUpdateNotify object will be created when the next call is made.

In the following API reference documentation:

• Parameters are in a key/value pair format separated by a space.

• The parameters are not case-sensitive.

• There is a list of parameters with documentation available.

  Note
  The updatepromptuser parameter is not available through the COM interface.

Apply

HRESULT Apply([in] LPWSTR pcwszParameters) // Apply update content.

Cancel

HRESULT Cancel() // Cancel the download action.

Download

HRESULT Download([in] LPWSTR pcwszParameters) // Download update content.

Status

typdef struct _UPDATE_STATUS_REPORT
{
    UPDATE_STATUS status;
    UINT error;
    LPCWSTR contentid;
}UPDATE_STATUS_REPORT;

HRESULT status([out] _UPDATE_STATUS_REPORT& pUpdateStatusReport) // Get status of current action

The Background Intelligent Transfer Service (BITS) is a service provided by Microsoft to transfer files between a client and server. BITS is one of the channels that Office Click-To-Run installer can use to download content. By default, the Office Click-To-Run installer uses the Windows' built in implementation of BITS to download the content from the CDN.

By providing a customized BITS implementation to the download() method of the IUpdateNotify interface, your manageability software can control where and how the client downloads the content. A customized BITS interface is useful when providing a custom content distribution channel other than the Click-to-Run built-in channels, such as the Office CDN, IIS servers, or file shares.

The minimum requirement for a customized BITS interface to work with Office C2R service is:

• For IBackgroundCopyManager:

  Copy

  HRESULT _stdcall CreateJob(
                      [in] LPWSTR DisplayName, 
                      [in] BG_JOB_TYPE Type, 
                      [out] GUID* pJobId, 
                      [out] IBackgroundCopyJob** ppJob)
  
  HRESULT _stdcall GetJob(
                      [in] GUID* jobID, 
                      [out] IBackgroundCopyJob** ppJob)
  
  HRESULT _stdcall EnumJobs(
                      [in] unsigned long dwFlags, 
                      [out] IEnumBackgroundCopyJobs** ppenum)
  
  
  

• For IBackgroundCopyJob:

  Copy

  HRESULT _stdcall AddFile(
                      [in] LPWSTR RemoteUrl, 
                      [in] LPWSTR LocalName)
  
  HRESULT _stdcall Resume()
  
  HRESULT _stdcall Complete()
  
  HRESULT _stdcall Cancel();
  
  HRESULT _stdcall GetState([out] BG_JOB_STATE* pVal);
  
  HRESULT GetProgress( [out] BG_JOB_PROGRESS *pProgress);
  
  

• For IBackgroundCopyJob3:

  Copy

  HRESULT _stdcall AddFileWithRanges(
                      [in] LPWSTR RemoteUrl, 
                      [in] LPWSTR LocalName,
                      [in] DWORD RangeCount,
                      [in] BG_FILE_RANGE Ranges[])
  
  

  For the Addfile and AddFileWithRanges functions, the remote URL is in the following format:

  Copy

  cmbits://<contentid>/<relative path to target file>
  

  • cmbits is hard coded, and stands for customized BITS.

  • <contentid> is the contentid parameter for the Download() method.

  • <relative path to target file> provides the location and file name of the file to download.

  For example, if you have provided a contentid of f732af58-5d86-4299-abe9-7595c35136ef to the Download() method, and Office C2R wants to download the version cab file, such as v32.cab file, it will call AddFile() with the following RemoteUrl:

  Copy

  cmbits://f732af58-5d86-4299-abe9-7595c35136ef/Office/Data/V32.cab
  

• For IBackgroundCopyError:

  Copy

  HRESULT _stdcall GetErrorDescription(
        [in]  DWORD  LanguageId,
        [out] LPWSTR *ppErrorDescription);
  
  

• For IBackgroundCopyFile:

  Copy

  HRESULT _stdcall GetLocalName([out] LPWSTR *ppName); 
  HRESULT _stdcall GetRemoteName([out] LPWSTR *ppName);
  
  

IT administrators can choose to have desktop clients enabled to automatically receive updates when they are available directly from the Microsoft Content Delivery Network (CDN) or they can choose to control the deployment of updates available from the update channels using the Office Deployment Tool or System Center Configuration Manager.

The service supports the ability for management tools to recognize and automate the download of the content when updates are made available.

In the above diagram you see that a new Office 365 ProPlus image is available on the Office Content Distribution Network (CDN). Along with the Office 365 ProPlus image, an XML-formatted file list is also available which has the information needed to enable manageability software to directly create customized images replacing the need for using the Office Deployment Tool.

An enterprise configures their WSUS to sync the Office 365 Client Updates. These updates do not contain the actual image payload but does allow the manageability software to recognize when new content is available. The manageability software can then read the Client Update metadata to understand what version of Office the update applies to.

If the update is applicable, the manageability software can use the CDN content and the file list to create the custom image and store it onto the file share location that it is configured to use.

Format of the XML file list

baseURL branch="Monthly" URL="http://officecdn.microsoft.com/pr/492350f6-3a01-4f97-b9c0-c7c6ddf67d60" /

Hash verification of data files

File name="stream.x64.bg-bg.dat" hashLocation="s641026.cab/stream.x64.bg-bg.hash" hashAlgo="Sha256" relativePath="/office/data/%version%/" language="1026"

string[] readHashes = System.IO.File.ReadAllLines(tmpFile, Encoding.Unicode);
string readHash = readHashes.First();

Office 365 Client Updates

Office 365 Client Updates enable manageability software to treat the Office 365 Client Updates in a manner very similar to any other WU update with one exception; the client updates do not contain an actual payload. The Office 365 Client Updates should not be installed on any clients but rather used to trigger the workflows with the manageability software replacing the installation command with the COM based installation mechanism shown above.

Office 365 Client Update workflow

Each Office 365 Client Update that is published includes metadata about the update. This metadata includes a parameter called MoreInfoUrl which can be used to derive the following information:

• Ver: Identifies the Office version associated with this update. For example 16.0.4229.1004.

• Branch: Identifies the Update Channel for this update. Values include InsiderFast, Insiders, Monthly, Targeted, Broad. Additional values may be added in the future.

• Arch: Identifies the processor architecture associated with this update.

• xmlVer: Identifies the version of the XML file lists to use to construct the base image for this update.

• xmlPath: Path to the OFL.CAB file that contains the XML file lists.

• xmlFile: The name of the file list that should be used for this update. The value will be O365Client_32bit or O365Client_64bit and will match the value in Arch.

The following is an example of the MoreInfoURL parameter which refers to the Office 365 Client Update for the 32-bit version of Office with build version of 16.0.2342.2343 on the Current channel.

Copy

http://officecdn.microsoft.com/pr/wsus/ofl.cab is the location of the XML file lists for this update, specifically the O365Client_32bit.xml from within the OFL.CAB.

http://go.microsoft.com/fwlink/?LinkId=626090&Ver=16.0.8326.2096&Branch=Current&Arch=64&XMLVer=1.4&xmlPath=http://officecdn.microsoft.com/pr/wsus/ofl.cab&xmlFile=O365Client_64bit.xml 

Note
This summary is provided as a compliment info to Integrating manageability applications with the Office 365 click-to-run installer. Once the public doc is updated, this doc can be considered as obsolete.

From C2RTenant 16.0.8208.6352 (First publicly available build should be June fork build -- 8326.*) we have added a new IUpdateNotify2 interface. Here is some basic info about this interface:

• CLSID_UpdateNotifyObject2, {52C2F9C2-F1AC-4021-BF50-756A5FA8DDFE}

• This interface also hosted the original IUpdateNotify interface to provide backward compatibility. Which means if you use this interface, you have access to all the methods provided in UpdateNotifyObject interface.

• New methods added to IUpdateNotify2

  • HRESULT GetBlockingApps([out] BSTR * AppsList). Get updates blocking apps list. This call will return running Office apps which will block the update process from proceeding.

  • HRESULT GetOfficeDeploymentData([in] int dataType, [in] LPCWSTR pcwszName, [out] BSTR * OfficeData). Get Office deployment Data.

• • If you want to use the new methods, you need to make sure:

  • Your C2R version is newer than the above build (>= June fork build).

  • Use UpdateNotifyObject2, instead of UpdateNotifyObject to call CoCreateInstance.

If you don't use any of the new methods, you don't need to change anything. All the existing methods will work as exact the same way as before.

Note
This is an internal tool. Just use it for the purpose of getting better understanding of how these methods works.

You can find the tool at \\officefile\public\douglago\TestCOM This tool works with both IUpdateNotify and iUpdateNotify2 interfaces.

TestUpdateNotifyV2 /[download | apply] para1=value1 para2=value2...
TestUpdateNotifyV2 /[cancel | status | getblockingapps]
TestUpdateNotifyV2 /getofficedata datatype [settingname]
 
  datatype
    1: InstalledProduct
    2: ConfigSetting. Valid settingname includes:
cdnbaseurl, updateenabled, updatesfromadminsource, versiontoreport, sclcacheoverride, sclcacheoverridedirectory, hosteridentity, audienceid, sharedcomputerlicensing, productreleaseid, platform, clientculture, streamingfinished, clientversiontoreport, pidkeys, act
    3: Progress
    4: ExecutingScenario
    5: ProductVersion
    6: UpdateSetting. Valid names include:
updatesreadytoapply, updateculturestoremove, updateculturestoadd, updateproductstoremove, updateproductstoadd, updatesreadyfordownload
    7: UpdateDeadline
    8: UpdatesLate
    9: UpdatesEnabled
    10: ChannelID
    11: BlockingApps. Equivalent to /getblockingapps.
  settingname: Only needed when datatype is 2 or 6

The following list shows sample usage of the TestUpdateNotifyV2:

• To get CDNBaseUrl setting TestUpdateNotifyV2 /getofficedata 2 cdnbaseurl

• To get the UpdateDeadline TestUpdateNotifyV2 /getofficedata 7

• To get the blocking apps list TestUpdateNotifyV2 /getblockingapps -or-TestUpdateNotifyV2 /getofficedata 11