IPortableDevice::Open 메서드(portabledeviceapi.h)

아티클
03/05/2024

Open 메서드는 애플리케이션과 디바이스 간의 연결을 엽니다.

구문

HRESULT Open(
  [in] LPCWSTR               pszPnPDeviceID,
  [in] IPortableDeviceValues *pClientInfo
);

매개 변수

[in] pszPnPDeviceID

디바이스의 플러그 앤 플레이 ID 문자열을 포함하는 null로 끝나는 문자열에 대한 포인터입니다. IPortableDeviceManager::GetDevices를 호출하여 이 문자열을 가져올 수 있습니다.

[in] pClientInfo

디바이스에 대한 애플리케이션을 식별하는 정보를 포함하는 IPortableDeviceValues 인터페이스에 대한 포인터입니다. 이 인터페이스는 애플리케이션을 고유하게 식별하려는 PROPERTYKEY/값 쌍을 보유합니다. CoCreated 인터페이스의 존재가 필요하지만 애플리케이션은 키/값 쌍을 보낼 필요가 없습니다. 그러나 데이터를 보내면 성능이 향상될 수 있습니다. 일반적인 키/값 쌍에는 애플리케이션 이름, 주 버전 및 부 버전 및 빌드 번호가 포함됩니다.

속성 섹션에서 "WPD_CLIENT_"로 시작하는 속성을 참조하세요.

반환 값

이 메서드는 HRESULT를 반환합니다. 가능한 값에는 다음 표에 있는 값이 포함되지만, 이에 국한되는 것은 아닙니다.

반환 코드	Description
S_OK	메서드가 성공했습니다.
E_WPD_DEVICE_ALREADY_OPENED	디바이스 연결이 이미 열려 있습니다.
E_POINTER	인수 중 하나 이상이 NULL 포인터였습니다.

설명

디바이스에서 메서드를 호출하려면 먼저 디바이스를 열어야 합니다. ( IPortableDeviceManager 메서드는 메서드를 호출하기 전에 디바이스를 열 필요가 없습니다.) 그러나 일반적으로 닫기를 호출할 필요가 없습니다.

관리자는 네트워크에서 실행되는 컴퓨터로 휴대용 디바이스의 액세스를 제한할 수 있습니다. 예를 들어 관리자는 모든 게스트 사용자를 읽기 전용 액세스로 제한할 수 있지만 인증된 사용자에게는 읽기/쓰기 권한이 부여됩니다.

이러한 보안 문제로 인해 애플리케이션이 쓰기 작업을 수행하지 않는 경우 Open 메서드를 호출하고 pClientInfo 매개 변수에서 제공하는 WPD_CLIENT_DESIRED_ACCESS 속성에 대한 GENERIC_READ 지정하여 읽기 전용 액세스를 요청해야 합니다.

애플리케이션에 쓰기 작업이 필요한 경우 다음 예제 코드와 같이 Open 메서드를 호출해야 합니다. 처음으로 pClientInfo 매개 변수에 기본 WPD_CLIENT_DESIRED_ACCESS 속성을 전달하여 읽기/쓰기 액세스를 요청해야 합니다. 이 첫 번째 호출이 실패하고 E_ACCESSDENIED 반환하는 경우 애플리케이션은 Open 메서드를 두 번째로 호출하고 pClientInfo 매개 변수에서 제공하는 WPD_CLIENT_DESIRED_ACCESS 속성에 대한 GENERIC_READ 지정하여 읽기 전용 액세스를 요청해야 합니다.

단일 스레드 아파트에 거주하는 애플리케이션은 인터페이스 포인터 마샬링의 오버헤드를 제거하므로 CLSID_PortableDeviceFTM 사용해야 합니다. CLSID_PortableDevice 여전히 레거시 애플리케이션에 지원됩니다.

예제


#define CLIENT_NAME         L"My WPD Application"
#define CLIENT_MAJOR_VER    1
#define CLIENT_MINOR_VER    0
#define CLIENT_REVISION     0

HRESULT OpenDevice(LPCWSTR wszPnPDeviceID, IPortableDevice** ppDevice)
{
    HRESULT                hr                 = S_OK;
    IPortableDeviceValues* pClientInformation = NULL;
    IPortableDevice*       pDevice            = NULL;

    if ((wszPnPDeviceID == NULL) || (ppDevice == NULL))
    {
        hr = E_INVALIDARG;
        return hr;
    }

    // CoCreate an IPortableDeviceValues interface to hold the client information.
    hr = CoCreateInstance(CLSID_PortableDeviceValues,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_IPortableDeviceValues,
                          (VOID**) &pClientInformation);
    if (SUCCEEDED(hr))
    {
        HRESULT ClientInfoHR = S_OK;

        // Attempt to set all properties for client information. If we fail to set
        // any of the properties below it is OK. Failing to set a property in the
        // client information isn't a fatal error.
        ClientInfoHR = pClientInformation->SetStringValue(WPD_CLIENT_NAME, CLIENT_NAME);
        if (FAILED(ClientInfoHR))
        {
           // Failed to set WPD_CLIENT_NAME
        }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_MAJOR_VERSION, CLIENT_MAJOR_VER);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_MAJOR_VERSION
        }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_MINOR_VERSION, CLIENT_MINOR_VER);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_MINOR_VERSION
        }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_REVISION, CLIENT_REVISION);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_REVISION
        }
    }
    else
    {
        // Failed to CoCreateInstance CLSID_PortableDeviceValues for client information
    }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_SECURITY_QUALITY_OF_SERVICE, SECURITY_IMPERSONATION);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_SECURITY_QUALITY_OF_SERVICE
        }

    if (SUCCEEDED(hr))
    {
        // CoCreate an IPortableDevice interface
        hr = CoCreateInstance(CLSID_PortableDeviceFTM,
                              NULL,
                              CLSCTX_INPROC_SERVER,
                              IID_IPortableDevice,
                              (VOID**) &pDevice);

        if (SUCCEEDED(hr))
        {
            // Attempt to open the device using the PnPDeviceID string given
            // to this function and the newly created client information.
            // Note that we're attempting to open the device the first 
            // time using the default (read/write) access. If this fails
            // with E_ACCESSDENIED, we'll attempt to open a second time
            // with read-only access.
            hr = pDevice->Open(wszPnPDeviceID, pClientInformation);
            if (hr == E_ACCESSDENIED)
            {
                 // Attempt to open for read-only access
                 pClientInformation->SetUnsignedIntegerValue(
                       WPD_CLIENT_DESIRED_ACCESS,
                       GENERIC_READ);
                 hr = pDevice->Open(wszPnPDeviceID, pClientInformation);
            }
            if (SUCCEEDED(hr))
            {
                // The device successfully opened, obtain an instance of the Device into
                // ppDevice so the caller can be returned an opened IPortableDevice.
                hr = pDevice->QueryInterface(IID_IPortableDevice, (VOID**)ppDevice);
                if (FAILED(hr))
                {
                    // Failed to QueryInterface the opened IPortableDevice
                }
            }
        }
        else
        {
            // Failed to CoCreateInstance CLSID_PortableDevice
        }
    }

    // Release the IPortableDevice when finished
    if (pDevice != NULL)
    {
        pDevice->Release();
        pDevice = NULL;
    }

    // Release the IPortableDeviceValues that contains the client information when finished
    if (pClientInformation != NULL)
    {
        pClientInformation->Release();
        pClientInformation = NULL;
    }

    return hr;
}