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

Статья
10/30/2024

Метод SerCx2CustomReceiveCreate создает объект пользовательского получения, который версии 2 расширения последовательной платформы (SerCx2) использует для чтения данных из последовательного контроллера с помощью пользовательского механизма передачи данных.

Синтаксис

NTSTATUS SerCx2CustomReceiveCreate(
  [in]  WDFDEVICE                     Device,
  [in]  PSERCX2_CUSTOM_RECEIVE_CONFIG CustomReceiveConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out] SERCX2CUSTOMRECEIVE           *CustomReceive
);

Параметры

[in] Device

Дескриптор WDFDEVICE для объекта устройства платформы, представляющего последовательный контроллер. Драйвер последовательного контроллера создал этот объект в своей функции обратного вызова EvtDriverDeviceAdd. Дополнительные сведения см. в разделе SerCx2InitializeDevice.

[in] CustomReceiveConfig

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

[in] Attributes

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

[out] CustomReceive

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

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

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

Возвращаемый код	Описание
STATUS_INVALID_DEVICE_REQUEST	Объект настраиваемого получения уже существует из предыдущего вызова SerCx2CustomReceiveCreate; или объект system-DMA-receive существует из предыдущего вызова SerCx2CustomReceiveCreate; или объект передачи system-DMA существует из предыдущего вызова SerCx2CustomTransmitCreate; или SerCx2PioReceiveCreate еще не вызывается для создания объекта PIO-receive.
STATUS_INVALID_PARAMETER	Недопустимое значение параметра.
STATUS_INFO_LENGTH_MISMATCH	Значение размера конфигурации не равно размеру(SERCX2_CUSTOM_RECEIVE_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Недостаточно ресурсов для создания объекта пользовательского получения.

Замечания

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

Драйвер последовательного контроллера должен успешно вызывать методы SerCx2InitializeDevice и методы SerCx2PioReceiveCreate перед вызовом SerCx2CustomReceiveCreate.

Перед вызовом SerCx2CustomReceiveCreateдрайвер последовательного контроллера должен вызвать функцию SERCX2_CUSTOM_RECEIVE_CONFIG_INIT, чтобы инициализировать структуру SERCX2_CUSTOM_RECEIVE_CONFIG, на которую указывает CustomReceiveConfig. Эта функция задает следующие элементы структуры равным нулю:

выравнивания
MinimumTransactionLength
MaximumTransactionLength
MinimumTransferUnit
эксклюзивные

При необходимости драйвер последовательного контроллера может задать для любого из этих элементов ненулевое значение после возврата функции инициализации. Однако для удобства SerCx2CustomReceiveCreate использует следующие значения по умолчанию, если эти элементы равны нулю:

Если выравнивание равно нулю, SerCx2 задает значение выравнивания данных одному, то есть буфер чтения может начинаться с произвольной границы байтов в памяти.
Если MinimumTransactionLength равно нулю, SerCx2 задает минимальную длину транзакции в один байт.
Если MaximumTransactionLength равно нулю, SerCx2 задает максимальную длину транзакции ((ULONG)-1).
Если MinimumTransferUnit равно нулю, SerCx2 задает минимальную единицу передачи в один байт.
Если монопольная равно нулю (FALSE), монопольный режим отключен.

Если вызывающий драйвер задает монопольную значение TRUE, то MinimumTransferUnit, выравниванияи элементов MinimumTransactionLength должно быть равно нулю. Дополнительные сведения см. в SERCX2_CUSTOM_RECEIVE_CONFIG.

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

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

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows 8.1.
целевая платформа	Всеобщий
заголовка	sercx.h
IRQL	PASSIVE_LEVEL