WriteSpbResource function

Writes data to an open Simple Peripheral Bus (SPB) resource.

Syntax


NTSTATUS WriteSpbResource(
  _In_      HANDLE DeviceHandle,
  _In_      VOID *SpbResource,
  _In_      ULONG Length,
  _In_      VOID *Buffer,
  _In_opt_  LARGE_INTEGER *ByteOffset,
  _In_opt_  HANDLE EventHandle,
  _Out_     IO_STATUS_BLOCK *IoStatusBlock
);

Parameters

DeviceHandle [in]

A handle that represents a display adapter. The display miniport driver previously obtained this handle in the DeviceHandle member of the DXGKRNL_INTERFACE structure that was passed to the DxgkDdiStartDevice function.

SpbResource [in]

A pointer to an SPB resource that the display miniport driver opened using the OpenSpbResource function.

Length [in]

The size, in bytes, of the buffer pointed to by the Buffer parameter.

Buffer [in]

A pointer to a caller-allocated buffer that contains the data to be written to the specified SPB resource.

ByteOffset [in, optional]

An optional pointer to a variable that specifies the starting byte offset in the SPB resource where the write operation will begin. If the Length and ByteOffset parameters specify a write operation past the current end-of-file mark, WriteSpbResource automatically extends the file and updates the end-of-file mark; any bytes that are not explicitly written between such old and new end-of-file marks are defined to be zero.

For more details on how to specify the byte offset, see the following Remarks section.

EventHandle [in, optional]

An optional handle for a caller-created event. If this parameter is supplied, the caller will be put into a wait state until the write operation is completed and the given event is set to the Signaled state.

This parameter can be NULL.

IoStatusBlock [out]

A pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the requested write operation. The Information member of the IO_STATUS_BLOCK structure receives the number of bytes actually written to the SPB resource.

Return value

This function returns STATUS_SUCCESS if it succeeds. Otherwise, it returns one of the error codes defined in Ntstatus.h.

Remarks

If the call to the OpenSpbResource function set only the DesiredAccess flag FILE_APPEND_DATA, the ByteOffset parameter is ignored. In this case, data in the buffer pointed to by the Buffer parameter, for Length bytes, is written starting at the current end of file.

If the call to OpenSpbResource set either of the CreateOptions flags, FILE_SYNCHRONOUS_IO_ALERT or FILE_SYNCHRONOUS_IO_NONALERT, the I/O Manager maintains the current file position. If so, the caller of WriteSpbResource can specify that the current file position offset be used instead of an explicit ByteOffset value. This specification can be made by using one of the following methods:

  • Specify a pointer to a LARGE_INTEGER value with the HighPart member set to -1 and the LowPart member set to the system-defined value FILE_USE_FILE_POINTER_POSITION (defined in Wdm.h).
  • Pass a NULL pointer for ByteOffset.

WriteSpbResource updates the current file position by adding the number of bytes written when it completes the write operation, if it is using the current file position maintained by the I/O Manager.

Even when the I/O Manager is maintaining the current file position, the caller can reset this position by passing an explicit ByteOffset value to WriteSpbResource. Doing this automatically changes the current file position to that ByteOffset value, performs the write operation, and then updates the position according to the number of bytes actually written. This technique gives the caller atomic seek-and-write service.

It is also possible to cause a write operation to start at the current end of file by specifying for ByteOffset a pointer to a LARGE_INTEGER value with HighPart set to -1 and LowPart set to FILE_WRITE_TO_END_OF_FILE. This works regardless of whether the I/O Manager is maintaining the current file position.

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Header

Dispmprt.h (include Dispmprt.h)

IRQL

PASSIVE_LEVEL

See also

IO_STATUS_BLOCK
IoCreateNotificationEvent
OpenSpbResource
ZwCreateEvent

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.