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

Статья
12/21/2024

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

Синтаксис

NTSTATUS SerCx2CustomTransmitCreate(
  [in]  WDFDEVICE                      Device,
  [in]  PSERCX2_CUSTOM_TRANSMIT_CONFIG CustomTransmitConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES         Attributes,
  [out] SERCX2CUSTOMTRANSMIT           *CustomTransmit
);

Параметры

[in] Device

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

[in] CustomTransmitConfig

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

[in] Attributes

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

[out] CustomTransmit

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

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

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

Возвращаемый код	Описание
STATUS_INVALID_DEVICE_REQUEST	Объект пользовательской передачи уже существует из предыдущего вызова SerCx2CustomTransmitCreate; или объект передачи данных системы DMA существует из предыдущего вызова SerCx2SystemDmaTransmitCreate; или объект передачи данных системы DMA существует из предыдущего вызова SerCx2SystemDmaTransmitCrea te; или SerCx2PioTransmitCreate еще не вызывается для создания объекта передачи piO-передачи.
STATUS_INVALID_PARAMETER	Недопустимое значение параметра.
STATUS_INFO_LENGTH_MISMATCH	Значение размераконфигурации не равно размеру(SERCX2_CUSTOM_TRANSMIT_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Недостаточно ресурсов для создания пользовательского объекта передачи.

Замечания

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

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

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

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

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

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

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

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

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

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

Требования

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