IWMDMDeviceSession：：BeginSession 方法 (mswmdm.h)

發行項
02/29/2024

BeginSession 方法會開始裝置會話。

語法

HRESULT BeginSession(
  [in] WMDM_SESSION_TYPE type,
  [in] BYTE              *pCtx,
  [in] DWORD             dwSizeCtx
);

參數

[in] type

描述要開始之會話類型的 WMDM_SESSION_TYPE 。這是任何值的位 OR ，但WMDM_SESSION_NONE除外。必須在 EndSession 期間指定類型 (或類型組合) 。

[in] pCtx

應用程式與服務提供者之間私人通訊之呼叫端配置的會話內容緩衝區選擇性指標。具備基礎服務提供者知識的應用程式可以使用這個緩衝區將內容特定數據傳遞給它。 Windows Media 裝置管理員不會對此內容執行任何動作。呼叫端負責釋放此緩衝區。

[in] dwSizeCtx

內容緩衝區的大小，以位元組為單位。如果大小為 0，則會忽略 pCtx 。如果大小為非零， pCtx 必須是有效的指標。

傳回值

方法會傳回 HRESULT。 Windows Media 裝置管理員中的所有介面方法都可以傳回下列任何一種錯誤碼類別：

標準 COM 錯誤碼
轉換成 HRESULT 值的 Windows 錯誤碼
Windows Media 裝置管理員錯誤碼

如需可能錯誤碼的廣泛清單，請參閱錯誤碼。

備註

將數個作業統合到會話，並不會讓所有動作延後並在群組中執行;所有動作 (例如呼叫 Insert) 仍會以同步方式執行。相反地，使用會話可讓 Windows Media 裝置管理員元件 (，例如安全內容提供者和服務提供者) 只執行一次每個會話的一次作業，以提供效能改善。例如，在檔案傳送至裝置期間，安全內容提供者可以在會話開始時取得裝置憑證一次，而不是針對每個檔案傳輸取得一次。

應用程式可以在 Windows Media 裝置管理員裝置物件上呼叫 BeginSession，再執行一組作業，並在完成時呼叫 EndSession。

應用程式通常會在多個檔案傳輸或刪除期間呼叫 BeginSession 。為了響應該情況，Windows Media 裝置管理員在安全內容提供者和服務提供者上呼叫 BeginSession 或 EndSession。為了回應，安全的內容提供者和服務提供者可以針對每個會話作業執行一次。如果開啟會話在任何元件上失敗，Windows Media 裝置管理員會傳回元件所傳回的失敗。

會話是以每個裝置為基礎實作。不同裝置上的會話不會彼此干擾。

下列限制適用於會話：

特定裝置一次只能使用一個會話。嘗試在裝置上開啟多個會話會導致錯誤。
會話類型可以合併。 在 BeginSession 和 EndSession 期間必須指定相同的旗標集。因此，不可能只結束會話的一部分。
例如，如果使用呼叫 BeginSession

WMDM_SESSION_TRANSFER_TO_DEVICE |WMDM_SESSION_DELETE

然後，也應該使用呼叫 EndSession

WMDM_SESSION_TRANSFER_TO_DEVICE |WMDM_SESSION_DELETE

否則，Windows Media 裝置管理員會傳回E_INVALIDARG。
Windows 媒體裝置管理員會話只是優化的括號機制，而且對裝置的鎖定或擁有權沒有任何影響。服務提供者或較低層級的裝置驅動程式仍然需要同步處理可能來自不同 Windows 媒體裝置管理員應用程式的裝置存取。

範例

下列 C++ 程式代碼示範如何使用工作階段來組合裝置上的 Insert3 呼叫。程式代碼會迴圈查看一些儲存在向量中的檔案，並將其傳送至裝置。


// Get the session interface.
CComQIPtr<IWMDMDeviceSession> pSession(pDevice);
if (pDevice == NULL)
{
    // TODO: Display a message that the application couldn't get an 
    // IWMDMDeviceSession interface.
    return E_NOINTERFACE;
}

// Start the session. We don't use a custom buffer.
hr = pSession->BeginSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
if (hr != S_OK)
{
    // TODO: Display a message indicating that the session failed to start.
    return hr;
}
else
{
    // TODO: Display a message that the session started.
}


// Insert files. These calls happen synchronously.
UINT flags = WMDM_MODE_BLOCK | WMDM_STORAGECONTROL_INSERTINTO | WMDM_FILE_CREATE_OVERWRITE | WMDM_CONTENT_FILE;
CComPtr<IWMDMStorage> pNewStorage;
for(int i = 0; i < sourceFiles.size(); i++)
{
    hr = pStorageControl3->Insert3(
        flags,
        WMDM_FILE_ATTR_FOLDER,
        sourceFiles[i],
        NULL, // Use default name.
        NULL, // Don't specify IWMDMOperation.
        NULL, // Don't specify IWMDMProgress.
        NULL, // Don't specify metadata.
        NULL, // Nothing to send to the SCP.
        &pNewStorage);

    if (pNewStorage != NULL)
        pNewStorage.Release();
    CHECK_HR(hr, "Sent file " << sourceFiles[i] << " to the device.", "Couldn't send file " << sourceFiles[i] << " to the device");
}

// Close the session.
hr = pSession->EndSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
CHECK_HR(hr,"Closed the session.","Couldn't close the session.");