IWMDMOperation

このオプションの、アプリケーション側で実装する IWMDMOperation インターフェイスを使用すると、ファイル転送中にコンピューターとの間でデータをどのように読み取り・書き込みするかをアプリケーション側で制御できます。

BeginRead メソッドは、「デバイスからの読み取り」動作が開始されることを示します。Windows Media Device Manager は、アプリケーションが IWMDMStorageControl::Read を呼び出し、この IWMDMOperation インターフェイスを渡した場合にのみ、このメソッドを呼び出します。

アプリケーションは次のいずれかの HRESULT 値を返してください。

このメソッドは、Windows Media Device Manager が IWMDMOperation::TransferObjectData を呼び出す直前に呼び出されます。

例

次の C++ コード例は、BeginRead メソッドを実装し、デバイスからの読み取り動作が開始される際にメッセージを出力します。

HRESULT BeginRead()
{
    // TODO: Display the message: "IWMDMOperation event--BeginRead."

    // If the global handle of the source file is uninitialized, fail.
    if (m_File == INVALID_HANDLE_VALUE)
        return E_FAIL;

    // Global status to let TransferObjectData know what kind of
    // operation is happening.
    m_OperationStatus = OPERATION_READ;
    return S_OK;
}

BeginWrite メソッドは、「デバイスへの書き込み」動作が開始されることを示します。Windows Media Device Manager は、アプリケーションが IWMDMStorageControl/2/3::Insert/2/3 を呼び出し、このインターフェイスを渡した場合にのみ、このメソッドを呼び出します。

アプリケーションは次のいずれかの HRESULT 値を返してください。

このメソッドは、Windows Media Device Manager がデバイスへのデータ書き込みを開始するために IWMDMOperation::TransferObjectData を呼び出す直前に呼び出されます。

例

次の C++ コード例は、BeginWrite メソッドを実装し、デバイスへの書き込み動作が開始される際にメッセージを出力します。

HRESULT BeginWrite()
{
    // TODO: Display the message: "IWMDMOperation event--BeginWrite."
    
    // If the global handle of the destination file is uninitialized, fail.
    if (m_File == INVALID_HANDLE_VALUE)
        return E_FAIL;

    // Global status to let TransferObjectData know what kind of
    // operation is happening.
    m_OperationStatus = OPERATION_WRITE;
    return S_OK;
}

Windows Media Device Manager は、オブジェクトをデバイスに書き込む前に、デバイス上で付けるべき名前を知るために GetObjectName を呼び出します。

アプリケーションは次のいずれかの HRESULT 値を返してください。

このメソッドは、アプリケーションが Insert メソッドのパラメーターとして名前を指定しなかった場合にのみ呼び出されます。

SetObjectName メソッドは、読み取りまたは書き込み対象のコンテンツに名前を割り当てます。このメソッドは現在、Windows Media Device Manager からは呼び出されません。

アプリケーションは次のいずれかの HRESULT 値を返してください。

このメソッドは、BeginRead が呼び出された後に呼び出されます。

GetObjectAttributes メソッドを使用すると、デバイスに書き込まれるオブジェクトの属性をアプリケーション側で指定できます。Windows Media Device Manager は、ファイルをデバイスに書き込む前に、そのファイルの属性を取得するためにこのメソッドを呼び出します。

アプリケーションは次のいずれかの HRESULT 値を返してください。

デバイスへデータを転送する際は、転送を最適化するためにオブジェクト属性を提供してください。

例

次の C++ コードは GetObjectAttributes メソッドを実装した例です。読み取り対象のファイル（m_File）がファイルかフォルダーかを判定し、それに応じて返す属性を設定します。

HRESULT GetObjectAttributes(DWORD* pdwAttributes, _WAVEFORMATEX* pFormat)
{
    // TODO: Display the message: IWMDMOperation event--GetObjectAttributes.
    *pdwAttributes = WMDM_FILE_ATTR_FILE | 
        WMDM_STORAGE_ATTR_REMOVABLE | 
        WMDM_FILE_ATTR_AUDIO;

    BY_HANDLE_FILE_INFORMATION fileInformation;
    if (GetFileInformationByHandle(m_File, &fileInformation))
    {
        if (fileInformation.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY)
            *pdwAttributes |= WMDM_FILE_ATTR_FOLDER;
        else
            *pdwAttributes |= WMDM_FILE_ATTR_FILE;

        if (fileInformation.dwFileAttributes & FILE_ATTRIBUTE_READONLY)
            *pdwAttributes |= FILE_ATTRIBUTE_READONLY;
    }

    return S_OK;
}

SetObjectAttributes メソッドはファイル属性を指定します。このメソッドは現在、Windows Media Device Manager からは呼び出されません。

アプリケーションは次のいずれかの HRESULT 値を返してください。

オーディオ属性には、サンプルレート（毎秒のサンプル数）や1 サンプルあたりのバイト数などが含まれます。

Windows Media Device Manager は、ファイルをデバイスに書き込む前に、オブジェクト全体のサイズ（バイト単位）を取得するために GetObjectTotalSize を呼び出します。

アプリケーションは次のいずれかの HRESULT 値を返してください。

このメソッドは、GetObjectAttributes メソッドが呼び出された後に呼び出されます。転送時には、このインターフェイスを実装するオブジェクトに、送信されるコンテンツ全体のサイズが渡されます。

例

次の C++ コードは GetObjectTotalSize を実装した例です。Win32 関数 GetFileInformationByHandle を使用して、デバイスに書き込まれようとしているファイル（m_File）のサイズを取得し、その値を返します。

// About to start writing to the device.
HRESULT GetObjectTotalSize(DWORD*  pdwSize,    DWORD*  pdwSizeHigh)
{
    BY_HANDLE_FILE_INFORMATION fileInfo;
    GetFileInformationByHandle(
        m_File,
        &fileInfo);

    *pdwSize = fileInfo.nFileSizeLow;
    *pdwSizeHigh = fileInfo.nFileSizeHigh;
    // TODO: Display the message: "IWMDMOperation event--GetObjectTotalSize."
    return S_OK;
}

SetObjectTotalSize メソッドは、オブジェクト全体のサイズ（バイト単位）を割り当てます。このメソッドは現在、Windows Media Device Manager からは呼び出されません。

アプリケーションは次のいずれかの HRESULT 値を返してください。

このメソッドは、SetObjectAttributes の後に呼び出されます。

TransferObjectData メソッドは、アプリケーションがコンピューターとの間でデータブロックを転送できるようにするために呼び出されます。

アプリケーションは次のいずれかの HRESULT 値を返してください。

アプリケーションは、このメソッドの呼び出し直前に BeginRead と BeginWrite のどちらが呼び出されたかを監視することで、デバイスからデータを読み取っているのか、デバイスに書き込んでいるのかを判別できます。

例

次の C++ コードは、アプリケーションがファイル転送を自分で処理するために TransferObjectData を実装する例です。このコードは、デバイスからのデータ読み取りとデバイスへのデータ書き込みの両方を処理します。データの方向は、直前の BeginRead または BeginWrite の呼び出しで設定されるメンバー変数 m_OperationStatus で示されます。

HRESULT TransferObjectData(BYTE* pData, DWORD* pdwSize, BYTE* pMac)
{
    HRESULT hr = S_OK;

    // Verify parameters.
    if (pData == NULL || pdwSize == NULL || pMac == NULL || m_File == INVALID_HANDLE_VALUE) 
    {
        // TODO: Display the message: "Invalid argument in SetObjectTotalSize."
        return E_INVALIDARG;
    }
    if ((m_OperationStatus != OPERATION_READ) && (m_OperationStatus != OPERATION_WRITE))
    {
        // TODO: Display the message: "Unable to determine direction of data transfer."
        return E_FAIL;
    }

    //////////////////////////////////////////////////////////////////////////
// Sending data to the device.
//////////////////////////////////////////////////////////////////////////
    if (m_OperationStatus == OPERATION_WRITE)
    {
        DWORD   dwReadLen;
        // The SAC is used to encrypt the data sent to the device.
        if (m_pSAC == NULL) 
        {
               // TODO: Display the message: "SAC not initialized in TransferObjectData."
            return E_FAIL;
        }

        // Read pdwSize bytes from the file into pData.
        dwReadLen = *pdwSize;
        if (ReadFile(m_File, pData, dwReadLen, pdwSize, NULL) == FALSE) 
        {
               // TODO: Display the message: "Couldn't read the file in TransferObjectData."
            return E_FAIL;
        }

        // If there is no more data, terminate the transfer.
        if (*pdwSize == 0)
        {
            return S_FALSE;
        }

        // Create the MAC to return to Windows Media Device Manager.
        HMAC hMAC;
        hr = m_pSAC->MACInit(&hMAC);
        hr = m_pSAC->MACUpdate(hMAC, (BYTE*)(pData), *pdwSize);
        hr = m_pSAC->MACUpdate(hMAC, (BYTE*)(pdwSize), sizeof(DWORD));
        hr = m_pSAC->MACFinal(hMAC, (BYTE*)pMac);
        if (hr != S_OK) return E_FAIL;

        // Encrypt the data to send to the service provider/device.
        hr = m_pSAC->EncryptParam((BYTE*)(pData), *pdwSize);
        if (hr != S_OK) 
        {
            return E_FAIL;
        }
    }
    //////////////////////////////////////////////////////////////////////////
// Receiving data from the device.
//////////////////////////////////////////////////////////////////////////
    else 
    {
        // Copy the data to a temporary file for decryption.
        BYTE *pTmpData = new BYTE [*pdwSize];
        if (pTmpData == NULL)
        {
            return E_OUTOFMEMORY;
        }
        memcpy(pTmpData, pData, *pdwSize);

        // Decrypt the pData Parameter
        hr = m_pSAC->DecryptParam(pTmpData, *pdwSize);
        
        // Verify the MAC of the decrypted data.
        HMAC hMAC;
        BYTE pTestMac[WMDM_MAC_LENGTH];
        hr = m_pSAC->MACInit(&hMAC);
        hr = m_pSAC->MACUpdate(hMAC, (BYTE*)(pTmpData), *pdwSize);
        hr = m_pSAC->MACUpdate(hMAC, (BYTE*)(pdwSize), sizeof(*pdwSize));
        hr = m_pSAC->MACFinal(hMAC, pTestMac);
        if ((memcmp(pMac, pTestMac, WMDM_MAC_LENGTH) != 0) || (hr != S_OK))
        {
            delete [] pTmpData;
            return WMDM_E_MAC_CHECK_FAILED;
        }

        // Write the data to file, and record the amount of data written.
        DWORD dwWritten = 0;
        if (WriteFile(m_File,pTmpData,*pdwSize,&dwWritten,NULL))
        {
            hr = S_OK;
            *pdwSize = dwWritten;
        }
        else 
        {
            hr = HRESULT_FROM_WIN32(GetLastError());
        }
        if (pTmpData)
        {
            delete [] pTmpData;
        }
    }
    return hr;
}

End メソッドは、読み取りまたは書き込み操作が、成否にかかわらず終了したことを示し、完了コードを返します。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準的な COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

End メソッドは転送の成否にかかわらず呼び出され、最後に呼び出される IWMDMOperation メソッドです。このメソッドは、読み取りまたは書き込み操作で必要となったすべてのファイルハンドルやオブジェクトを閉じるようアプリケーションに通知する目的で利用できます。

例

次の C++ コードは、読み取りまたは書き込み動作の後にグローバルなファイルハンドルを閉じ、メッセージを出力します。

HRESULT End(HRESULT* phCompletionCode, IUnknown* pNewObject)
{
    // TODO: Display the message: "IWMDMOperation event--End."

    // Close the file handle now that we're done with it.
    if (m_File != INVALID_HANDLE_VALUE)
        if (!CloseHandle(m_File))
            // TODO: Display the message: "Couldn't close the file."

    // Reset global status flag.
    m_OperationStatus = OPERATION_UNINITIALIZED;
    return S_OK;
}