IWDFRemoteTarget::OpenRemoteInterface method (wudfddi.h)

Article
02/22/2024

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

The OpenRemoteInterface method opens a device interface so that the driver can send I/O requests to it.

Syntax

HRESULT OpenRemoteInterface(
  [in]           IWDFRemoteInterface         *pRemoteInterface,
  [in, optional] PCWSTR                      pszRelativeFileName,
  [in]           DWORD                       DesiredAccess,
  [in, optional] PUMDF_IO_TARGET_OPEN_PARAMS pOpenParams
);

Parameters

[in] pRemoteInterface

A pointer to a IWDFRemoteInterface interface that the driver obtained from a previous call to IWDFDevice2::CreateRemoteInterface.

[in, optional] pszRelativeFileName

An optional pointer to a caller-supplied, null-terminated string that the framework appends to the symbolic link name of the device interface.

[in] DesiredAccess

A bitmask that specifies the caller's desired access to the file. For more information about this member, see the DesiredAccess parameter of CreateFile in the Windows SDK.

[in, optional] pOpenParams

A pointer to a caller-allocated UMDF_IO_TARGET_OPEN_PARAMS structure that contains additional parameters. This parameter is optional and can be NULL.

Return value

OpenRemoteInterface returns S_OK if the operation succeeds. Otherwise, the method might return the following value:

Return code	Description
E_OUTOFMEMORY	The framework's attempt to allocate memory failed.

This method might return one of the other values that Winerror.h contains.

The framework's verifier reports an error if the framework cannot open the file.

Remarks

After a driver's IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival callback function receives notification that a device interface is available, and after the driver calls IWDFDevice2::CreateRemoteInterface to create a remote interface object, the driver can call OpenRemoteInterface so that it can send I/O requests to the device interface.

The device interface must be accessible by the account that loaded the UMDF-based driver, which is typically the Local Service account. However, if the driver uses impersonation when it calls OpenRemoteInterface, the device interface must be accessible by the impersonated account.

For more information about OpenRemoteInterface and how to use device interfaces in UMDF-based drivers, see Using Device Interfaces in UMDF-based Drivers.

Examples

The following code example shows how an IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival callback function can create a remote interface and remote target objects for a device interface and then open the interface for I/O operations.

void 
STDMETHODCALLTYPE
CMyDevice::OnRemoteInterfaceArrival(
    __in IWDFRemoteInterfaceInitialize * FxRemoteInterfaceInit
    )
...
    HRESULT hr;
    CComPtr<IWDFRemoteInterface> fxRemoteInterface;
    CComPtr<IWDFRemoteTarget> m_FxTarget;

    hr = m_FxDevice->CreateRemoteInterface(FxRemoteInterfaceInit, 
                                           NULL, 
                                           &fxRemoteInterface);
    if (FAILED(hr)) goto Error;
    hr = FxDevice->CreateRemoteTarget(unknown,
                                      fxRemoteInterface,
                                      &m_FxTarget);
    if (FAILED(hr)) goto Error;
    hr = m_FxTarget->OpenRemoteInterface(fxRemoteInterface, 
                                         NULL,
                                         GENERIC_READ | GENERIC_WRITE,
                                         NULL);
...
Error:
...

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.9
Header	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll