使用 Active Desktop 物件

發行項
06/12/2023

[此功能僅支援 Windows XP 或更早版本。 ]

本文包含屬於 Windows Shell API 一部分的 ActiveDesktop 物件資訊。這個物件透過其 IActiveDesktop 介面，可讓您在桌面上新增、移除和變更專案。

使用中桌面介面的概觀

存取使用中桌面
新增桌面專案
列舉桌面專案

Active Desktop 是 Microsoft Internet Explorer 4.0 引進的功能，可讓您直接將 HTML 檔案和專案包含在桌面 (，例如 Microsoft ActiveX 控制項和 JAVA 小程式) 。 IActiveDesktop介面是 Windows Shell API 的一部分，可用來以程式設計方式新增、移除和修改桌面上的專案。您也可以使用通道定義格式 (CDF) 檔案來新增使用中桌面專案。

存取使用中桌面

若要存取 Active Desktop，用戶端應用程式必須使用 CoCreateInstance 函式建立 ActiveDesktop 物件的實例 (CLSID_ActiveDesktop) ，並擷取物件的 IActiveDesktop 介面指標。

下列範例示範如何擷取 IActiveDesktop 介面的指標。

HRESULT hr;
IActiveDesktop *pActiveDesktop;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
                      IID_IActiveDesktop, (void**)&pActiveDesktop);

//Insert code to call the IActiveDesktop methods

// Call the Release method
pActiveDesktop->Release();

新增桌面專案

有三種方法可用來新增桌面專案： IActiveDesktop：：AddDesktopItem、 IActiveDesktop：：AddDesktopItemWithUI和 IActiveDesktop：：AddUrl。新增至 Active Desktop 的每個桌面專案都必須有不同的來源 URL。

IActiveDesktop：：AddDesktopItemWithUI和IActiveDesktop：：AddUrl方法都提供選項來顯示可在將桌面專案新增至 Active Desktop 之前顯示的各種使用者介面。介面會確認使用者是否要將桌面專案新增至其作用中桌面。這些介面也會通知使用者 URL 安全性區域設定所保證的任何安全性風險，並詢問使用者是否要為此桌面專案建立訂用帳戶。這兩種方法也提供隱藏使用者介面的方式。 IActiveDesktop：：AddDesktopItem方法需要呼叫IActiveDesktop：：ApplyChanges才能更新登錄。針對 IActiveDesktop：：AddDesktopItemWithUI，用戶端應用程式必須立即釋放 IActiveDesktop 介面，然後使用 CoCreateInstance 函式來擷取包含新新增桌面專案的 ActiveDesktop 物件的實例介面。

除非 URL 安全性區域設定防止它， 否則 IActiveDesktop：：AddDesktopItem 方法會將指定的桌面專案新增至 Active Desktop，而不會有任何使用者介面。如果 URL 安全性區域設定不允許新增桌面專案而不提示使用者，此方法就會失敗。 IActiveDesktop：：AddDesktopItem 也需要呼叫 IActiveDesktop：：ApplyChanges 才能更新登錄。

下列範例示範如何使用 IActiveDesktop：：AddDesktopItem 方法新增桌面專案。

HRESULT hr;
IActiveDesktop *pActiveDesktop;
COMPONENT compDesktopItem;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
                      IID_IActiveDesktop, (void**)&pActiveDesktop);

// Initialize the COMPONENT structure
compDesktopItem.dwSize = sizeof(COMPONENT);

// Insert code that adds the information about the desktop item 
// to the COMPONENT structure

// Add the desktop item
pActiveDesktop->AddDesktopItem(&compDesktopItem,0);

// Save the changes to the registry
pActiveDesktop->ApplyChanges(AD_APPLY_ALL);

列舉桌面專案

若要列舉目前安裝在 Active Desktop 上的桌面專案，用戶端應用程式必須使用IActiveDesktop：：GetDesktopItemCount方法擷取安裝的桌面專案總數，然後使用桌面專案索引呼叫IActiveDesktop：：GetDesktopItem方法來建立迴圈，以擷取每個桌面專案的COMPONENT結構。

下列範例示範列舉桌面專案的其中一種方式。

HRESULT hr;
IActiveDesktop *pActiveDesktop;
COMPONENT compDesktopItem;
int intCount;
int intIndex = 0;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
                      IID_IActiveDesktop, (void**)&pActiveDesktop);

pActiveDesktop->GetDesktopItemCount(&intCount,0);

compDesktopItem.dwSize = sizeof(COMPONENT);

while(intIndex<=(intCount-1))
{
    //get the COMPONENT structure for the current desktop item
    pActiveDesktop->GetDesktopItem(intIndex, &compDesktopItem,0);

    //Insert code that processes the structure

    //Increment the index
    intIndex++;

    //Insert code to clean-up structure for next component
}

// Call the Release method
pActiveDesktop->Release();