IWDFRemoteTarget::OpenFileByName method (wudfddi.h)

Article
10/21/2021

[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 OpenFileByName method opens a remote I/O target that is a file.

Syntax

HRESULT OpenFileByName(
  [in]           PCWSTR                      pszFileName,
  [in]           DWORD                       DesiredAccess,
  [in, optional] PUMDF_IO_TARGET_OPEN_PARAMS pOpenParams
);

Parameters

[in] pszFileName

A pointer to a caller-supplied, null-terminated string that represents the name of the file to open. For more information about this member, see the FileName parameter of CreateFile in the Windows SDK.

[in] DesiredAccess

A bitmask that specifies the caller's desired access to the file. For more information about this member, see the dwDesiredAccess 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

OpenFileByName 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

Your driver can use OpenFileByName to open a file, if the driver stack to which your driver belongs does not support the file's device. Use IWDFFileHandleTargetFactory::CreateFileHandleTarget to open a file, if the driver stack to which your driver belongs does support the file's device.

The specified file 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 OpenFileByName, the file must be accessible by the impersonated account.

Do not call OpenFileByName to open a remote target to a control device object. Instead, open the control device directly by calling CreateFile.

For more information about the OpenFileByName method and remote I/O targets, see General I/O Targets in UMDF.

Examples

The following code example creates a remote target object and opens an existing file with read-only access.

UMDF_IO_TARGET_OPEN_PARAMS openParams;
HRESULT hr;

//
// Create a new remote target object and provide a callback 
// object to handle remote target events.
//
CComPtr<IWDFRemoteTarget> fxTarget;
hr = FxDevice->CreateRemoteTarget(MyRemoteTargetIUnknown,
                                  fxRemoteInterface,
                                  &fxTarget);
if (FAILED(hr)) goto Error;

//
// Open existing file for read-only access.
//
openParams.dwShareMode = 0;
openParams.dwCreationDisposition = OPEN_EXISTING;
openParams.dwFlagsAndAttributes = FILE_ATTRIBUTE_READONLY;

hr = fxTarget->OpenFileByName(FILE_PATH,
                              GENERIC_READ,
                              &openParams);

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