Функция SerCx2CustomReceiveTransactionCreate (sercx.h)

Статья
08/07/2023

Метод SerCx2CustomReceiveTransactionCreate создает объект custom-receive-transaction, который версии 2 расширения последовательной платформы (SerCx2) используется для выполнения пользовательских транзакций получения.

Синтаксис

NTSTATUS SerCx2CustomReceiveTransactionCreate(
  [in]  SERCX2CUSTOMRECEIVE                       CustomReceive,
  [in]  PSERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG CustomReceiveTransactionConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES                    Attributes,
  [out] SERCX2CUSTOMRECEIVETRANSACTION            *CustomReceiveTransaction
);

Параметры

[in] CustomReceive

Дескриптор SERCX2CUSTOMRECEIVE для объекта пользовательского получения. Драйвер последовательного контроллера ранее вызывал метод SerCx2CustomReceiveCreate для создания этого объекта.

[in] CustomReceiveTransactionConfig

Указатель на структуру SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG . Перед вызовом этого метода вызывающий объект должен вызвать функцию SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG_INIT для инициализации структуры. Эта структура содержит указатели на набор процедур обратного вызова событий, реализованных драйвером последовательного контроллера. SerCx2 вызывает эти функции для выполнения транзакции ввода-вывода, которая использует пользовательский механизм передачи данных для чтения данных, полученных последовательным контроллером.

[in] Attributes

Указатель на структуру WDF_OBJECT_ATTRIBUTES , описывающую атрибуты, назначаемые новому объекту custom-receive-transaction. Перед вызовом этого метода вызывающий объект должен вызвать функцию WDF_OBJECT_ATTRIBUTES_INIT для инициализации структуры. Этот параметр является необязательным и может быть указан как WDF_NO_OBJECT_ATTRIBUTES, если драйверу последовательного контроллера не нужно назначать атрибуты объекту. Дополнительные сведения см. в подразделе "Примечания".

[out] CustomReceiveTransaction

Указатель на расположение, в которое этот метод записывает дескриптор SERCX2CUSTOMRECEIVETRANSACTION во вновь созданный объект custom-receive-transaction. SerCx2 и драйвер последовательного контроллера используют этот дескриптор в последующих вызовах для ссылки на этот объект.

Возвращаемое значение

Этот метод возвращает STATUS_SUCCESS, если вызов выполнен успешно. Возможные возвращаемые значения ошибок включают следующие коды состояния.

Код возврата	Описание
STATUS_INVALID_DEVICE_REQUEST	Объект custom-receive-transaction уже существует из предыдущего вызова SerCx2CustomReceiveTransactionCreate .
STATUS_INFO_LENGTH_MISMATCH	Значение CustomReceiveTransactionConfig->Size не равно sizeof(SERCX2_CUSTOM_RECEIVE_TRANSACTION_CONFIG).
STATUS_INVALID_PARAMETER	Недопустимое значение параметра. Вызывающий объект должен предоставить допустимые указатели функций EvtSerCx2CustomReceiveTransactionStart и EvtSerCx2CustomReceiveTransactionQueryProgress .
STATUS_INSUFFICIENT_RESOURCES	Недостаточно ресурсов для создания объекта custom-receive-transaction.

Драйвер последовательного контроллера может вызвать этот метод для создания объекта custom-receive-transaction. SerCx2 использует этот объект для управления пользовательскими транзакциями получения, которые представляют собой транзакции ввода-вывода, использующие пользовательский механизм передачи данных для чтения данных, полученных последовательным контроллером.

В качестве варианта драйвер последовательного контроллера может использовать параметр Attributes для создания контекста для объекта пользовательского получения и предоставления указателей на функции EvtCleanupCallback и EvtDegradCallback , которые вызываются для подготовки объекта к удалению. Дополнительные сведения см. в разделе WDF_OBJECT_ATTRIBUTES.

Если параметр Attributes указывает на структуру WDF_OBJECT_ATTRIBUTES , вызывающий объект не должен перезаписывать значения, которые функция инициализации WDF_OBJECT_ATTRIBUTES_INIT записывает в элементы ParentObject, ExecutionLevel и SynchronizationScope этой структуры.

Если указанное сочетание реализованных функций обратного вызова недопустимо, вызов SerCx2CustomReceiveTransactionCreate завершается сбоем и возвращает STATUS_INVALID_PARAMETER.

Дополнительные сведения о создании объектов custom-receive-transaction см. в разделе SERCX2CUSTOMRECEIVETRANSACTION. Дополнительные сведения о пользовательских транзакциях получения см. в разделе SerCx2 Custom-Receive Transactions.

Требования

Требование	Значение
Минимальная версия клиента	Доступно, начиная с Windows 8.1.
Целевая платформа	Универсальное
Верхняя часть	sercx.h
IRQL	PASSIVE_LEVEL