IWMDMStorageControl3::Insert3 메서드(mswmdm.h)
Insert3 메서드는 콘텐츠를 스토리지 옆에 배치합니다. 이 메서드는 애플리케이션이 전송되는 개체의 메타데이터 및 형식을 명시적으로 지정할 수 있도록 하여 IWMDMStorageControl2::Insert2 를 확장합니다.
구문
HRESULT Insert3(
[in] UINT fuMode,
[in] UINT fuType,
[in] LPWSTR pwszFileSource,
[in] LPWSTR pwszFileDest,
[in] IWMDMOperation *pOperation,
[in] IWMDMProgress *pProgress,
[in] IWMDMMetaData *pMetaData,
[in] IUnknown *pUnknown,
[out] IWMDMStorage **ppNewObject
);
매개 변수
[in] fuMode
Insert3 작업에 사용되는 처리 모드입니다. 다음 표에서는 fuMode 매개 변수에 지정할 수 있는 처리 모드를 나열합니다. 처음 두 모드 중 하나, 정확히 STORAGECONTROL 모드 중 하나 및 콘텐츠 모드 중 하나를 정확히 지정해야 합니다. WMDM_MODE_BLOCK 및 WMDM_MODE_THREAD 모두 지정되면 블록 모드가 사용됩니다. 이 함수에서 WMDM_FILE_ATTR* 플래그를 지정하는 것이 먼저 이 함수를 호출한 다음, 생성 또는 전송된 후 파일에 이러한 특성을 설정하는 것보다 더 효율적입니다.
| 조합 | Mode | Description |
|---|---|---|
| 정확히 다음 중 하나입니다. | WMDM_MODE_BLOCK | 작업은 블록 모드 처리를 사용하여 수행됩니다. 작업이 완료될 때까지 호출이 반환되지 않습니다. |
| - | WMDM_MODE_THREAD | 작업은 스레드 모드 처리를 사용하여 수행됩니다. 호출은 즉시 반환되고 작업은 백그라운드 스레드에서 수행됩니다. |
| 선택 사항 | WMDM_MODE_QUERY | 삽입 작업이 성공할 수 있는지 여부를 확인하기 위한 테스트가 수행되지만 삽입은 수행되지 않습니다. |
| 정확히 다음 중 하나입니다. | WMDM_STORAGECONTROL_INSERTBEFORE | 개체가 대상 개체 앞에 삽입됩니다. |
| - | WMDM_STORAGECONTROL_INSERTAFTER | 개체는 대상 개체 뒤에 삽입됩니다. |
| - | WMDM_STORAGECONTROL_INSERTINTO | 개체가 현재 개체에 삽입됩니다. 현재 개체가 폴더인 경우에만 작동합니다. |
| 선택 사항 | WMDM_FILE_CREATE_OVERWRITE | 개체는 대상 개체를 대체합니다. |
| 정확히 다음 중 하나입니다. | WMDM_CONTENT_FILE | 삽입되는 콘텐츠는 파일입니다. |
| - | WMDM_CONTENT_FOLDER | 삽입되는 콘텐츠가 폴더입니다. 이렇게 하면 폴더의 내용이 전송되지 않습니다. |
| 선택 사항 | WMDM_CONTENT_OPERATIONINTERFACE | 애플리케이션이 데이터 전송을 제어하기 위해 IWMDMOperation 인터페이스를 전달합니다. |
| 0개 이상: | WMDM_FILE_ATTR_READONLY | 스토리지는 디바이스에서 읽기 전용으로 설정해야 합니다. |
| - | WMDM_FILE_ATTR_HIDDEN | 스토리지는 디바이스에서 숨김으로 설정해야 합니다. |
| - | WMDM_FILE_ATTR_SYSTEM | 스토리지는 디바이스의 시스템으로 설정해야 합니다. |
| 선택 사항 | WMDM_MODE_PROGRESS | 삽입이 진행 중입니다. |
| 선택 사항 중 하나: | WMDM_MODE_TRANSFER_PROTECTED | 삽입이 보호된 전송 모드에 있습니다. |
| - | WMDM_MODE_TRANSFER_UNPROTECTED | 삽입이 보호되지 않는 전송 모드에 있습니다. |
[in] fuType
현재 스토리지를 지정하는 다음 형식 중 하나입니다.
| 값 | Description |
|---|---|
| WMDM_FILE_ATTR_FILE | 현재 스토리지는 파일입니다. |
| WMDM_FILE_ATTR_FOLDER | 현재 스토리지는 폴더입니다. |
[in] pwszFileSource
삽입 작업의 콘텐츠를 찾을 위치를 나타내는 null로 끝나는 와이드 문자열에 대한 포인터입니다. fuMode에서 WMDM_CONTENT_OPERATIONINTERFACE 지정한 경우 이 매개 변수는 NULL이어야 합니다. 재생 목록 또는 앨범을 만드는 경우 이 매개 변수는 NULL 일 수 있습니다.
[in] pwszFileDest
디바이스의 파일 이름(선택 사항)입니다. 지정하지 않고 애플리케이션이 IWMDMOperation 포인터를 pOperation에 전달하는 경우 Windows Media 장치 관리자 IWMDMOperation::GetObjectName을 호출하여 대상 이름을 요청합니다. 지정하지 않고 애플리케이션이 pOperation을 사용하지 않는 경우 원래 파일 이름 및 확장명은 경로 없이 사용됩니다.
[in] pOperation
미디어 디바이스로의 콘텐츠 전송을 제어하기 위한 IWMDMOperation 인터페이스에 대한 선택적 포인터입니다. 지정한 경우 fuMode 에는 WMDM_CONTENT_OPERATIONINTERFACE 플래그가 포함되어야 합니다. fuMode에서 WMDM_CONTENT_FILE 또는 WMDM_CONTENT_FOLDER 지정한 경우 이 매개 변수는 NULL이어야 합니다.
[in] pProgress
작업 진행률을 애플리케이션에 다시 보고하기 위한 IWMDMProgress 인터페이스에 대한 선택적 포인터입니다. 이 매개 변수는 NULL일 수 있습니다.
[in] pMetaData
메타데이터 개체에 대한 선택적 포인터입니다. IWMDMStorage3::CreateEmptyMetadataObject를 호출하여 새 메타데이터 개체를 만듭니다. 이 매개 변수를 사용하면 애플리케이션이 디바이스에서 개체를 만드는 동안 디바이스에서 설정할 메타데이터(형식 포함)를 지정할 수 있으며, 이는 나중에 메타데이터를 설정하는 것보다 더 효율적입니다. 파일 형식(g_wszWMDMFormatCode 지정)을 설정해야 합니다. 이 메서드를 사용할 때 파일의 형식 코드를 지정하지 않으면 MTP 디바이스는 해당 사용자 인터페이스에 있는 것처럼 파일을 표시하지 않으며 MTP가 아닌 디바이스는 예측할 수 없이 동작합니다.
[in] pUnknown
보안 콘텐츠 공급자에 전달할 사용자 지정 COM 개체의 선택적 IUnknown 포인터입니다. 이렇게 하면 애플리케이션에 보안 콘텐츠 공급자에 대한 충분한 정보가 있는 경우 보안 콘텐츠 공급자에 사용자 지정 정보를 전달할 수 있습니다.
[out] ppNewObject
새 콘텐츠를 포함할 IWMDMStorage 인터페이스에 대한 포인터입니다. 호출자는 이 인터페이스가 완료되면 이 인터페이스를 해제해야 합니다.
반환 값
이 메서드는 HRESULT를 반환합니다. Windows Media 장치 관리자 모든 인터페이스 메서드는 다음 오류 코드 클래스 중 어느 것을 반환할 수 있습니다.
- 표준 COM 오류 코드
- HRESULT 값으로 변환된 Windows 오류 코드
- Windows Media 장치 관리자 오류 코드
설명
디바이스로 보낸 후 스토리지에서 메타데이터를 설정할 수 있지만 이 메서드의 pMetaData 매개 변수에서 이 정보를 설정하는 것이 더 효율적입니다. 이렇게 하면 디바이스에 파일을 적절히 전송하고 처리할 수 있도록 추가 정보를 제공하거나(예: 올바른 위치에 저장) 유용한 정보(예: 사진에 대한 사용자 작성 설명)를 표시합니다.
WPD(Windows 이식 장치) 디바이스에 대한 속성을 설정하기 위해 애플리케이션은 IPortableDeviceValues 개체를 만들고 각 속성을 이 컬렉션으로 설정합니다. 그런 다음, 애플리케이션은 컬렉션을 BLOB(Binary Large Object)로 직렬화합니다. 데이터가 직렬화되면 애플리케이션은 g_wszWPDPassthroughPropertyValues 메타데이터 상수를 사용하여 pMetadata 인수에서 참조하는 IWMDMMetaData에 추가합니다.
WMDM_MODE_THREAD 플래그가 지정된 경우 IWMDMProgress2::End2 또는 IWMDMProgress3::End3을 호출하여 완료 상태 가져와야 합니다. 이러한 메서드는 작업이 완료되었는지 확인하고 성공 또는 실패 정보가 포함된 HRESULT도 반환합니다.
애플리케이션이 WMDM_MODE_THREAD 사용하고 null이 아닌 pProgress 매개 변수를 전달하는 경우 Windows Media 장치 관리자 이 개체에 진행률 알림을 보내기 때문에 pProgress가 속한 개체가 읽기 작업이 완료될 때까지 제거되지 않도록 해야 합니다. 이 개체는 최종 알림을 받은 후에만 제거할 수 있습니다. 이렇게 하지 않으면 액세스 위반이 발생합니다.
재생 목록 또는 기타 참조 개체를 만들 때 "삽입"되는 개체는 실제로 데이터를 포함하지 않지만 단순히 다른 개체(예: 음악 파일)에 대한 메타데이터 참조 그룹으로 디바이스에 저장됩니다. 재생 목록에서 이러한 "추상" 개체를 만드는 방법은 디바이스에서 재생 목록 만들기에 설명되어 있습니다.
예제
다음 C++ 함수는 디바이스에 파일을 보냅니다. 전송의 일부로 새 스토리지 유형을 지정하려면 스토리지에 메타데이터를 추가해야 합니다.
HRESULT mySendFile(LPCWSTR pwszFileName, IWMDMStorage* pStorage, IWMDMOperation* pOperation)
{
HRESULT hr = S_OK;
// A dummy loop to handle unrecoverable errors. When we hit an error we
// can't handle or don't like, we just use a 'break' statement.
// The custom BREAK_HR macro checks for failed HRESULT values and does this.
do
{
if (pwszFileName == NULL || pStorage == NULL)
{
BREAK_HR(E_POINTER,"","Bad pointer passed in.");
return E_POINTER;
}
// Make sure the destination is a folder.
DWORD attributes = 0;
_WAVEFORMATEX format;
hr = pStorage->GetAttributes(&attributes, &format);
if (!(attributes | WMDM_FILE_ATTR_FOLDER))
{
BREAK_HR(E_FAIL, "", "Storage submitted to mySendFile is not a folder.");
return E_FAIL;
}
// Transcode the file
hr = myTranscodeMethod(pwszFileName);
BREAK_HR(hr, "Couldn't transcode the file in mySendFile.", "Transcoded the file in mySendFile.");
//
// Let's set some metadata in the storage.
//
CComPtr<IWMDMStorage3> pStorage3;
hr = pStorage->QueryInterface(__uuidof(IWMDMStorage3), (void**)(&pStorage3));
BREAK_HR(hr, "Got an IWMDMStorage3 interface in mySendFile.","Couldn't get an IWMDMStorage3 in mySendFile.");
// First create the IWMDMMetaData interface.
IWMDMMetaData* pMetadata;
hr = pStorage3->CreateEmptyMetadataObject(&pMetadata);
BREAK_HR(hr,"Created an IWMDMMetaData interface in mySendFile.","Couldn't create an IWMDMMetaData interface in mySendFile.");
//
// Set the file format.
//
WMDM_FORMATCODE fileFormat = myGetWMDM_FORMATCODE(pwszFileName);
hr = pMetadata->AddItem(WMDM_TYPE_DWORD, g_wszWMDMFormatCode, (BYTE*)&fileFormat, sizeof(WMDM_TYPE_DWORD));
//
// Get the proper interface and transfer the file.
//
CComPtr<IWMDMStorageControl3> pStgCtl3;
CComPtr<IWMDMStorage> pNewStorage;
hr = pStorage->QueryInterface(__uuidof(IWMDMStorageControl3),(void**)(&pStgCtl3));
// Get the simple file name to use for the destination file.
wstring destFile = pwszFileName;
destFile = destFile.substr(destFile.find_last_of(L"\\") + 1);
// Get a progress indicator.
CComQIPtr<IWMDMProgress> pProgress(this);
// Set the flags for the operation.
UINT flags = WMDM_MODE_BLOCK | // Synchronous call.
WMDM_STORAGECONTROL_INSERTINTO | // Insert it into the destination folder.
WMDM_CONTENT_FILE | // We're inserting a file.
WMDM_FILE_CREATE_OVERWRITE; // Overwrite existing files.
if (pOperation != NULL)
flags |= WMDM_CONTENT_OPERATIONINTERFACE;
// Send the file and metadata.
hr = pStgCtl3->Insert3(
flags,
WMDM_FILE_ATTR_FOLDER, // The current storage is a folder.
const_cast<WCHAR*>(pwszFileName), // Source file.
NULL, // Destination file name.
pOperation, // Null to allow Windows Media Device Manager to read
// the file; non-null to present raw data bytes to
// Windows Media Device Manager.
pProgress, // Interface to send simple progress notifications.
pMetadata, // IWMDMMetaData interface previously created and filled.
NULL,
&pNewStorage);
if (FAILED(hr))
m_pLogger->LogDword(WMDM_LOG_SEV_ERROR, NULL, "Error calling Insert3 in mySendFile: %lX", hr);
BREAK_HR(hr, "Wrote a file to the device in mySendFile", "Couldn't write to the device in mySendFile.");
} while (FALSE); // End of dummy loop
return hr;
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 대상 플랫폼 | Windows |
| 헤더 | mswmdm.h |
| 라이브러리 | Mssachlp.lib |