Поделиться через

функция обратного вызова TAPE_PROCESS_COMMAND_ROUTINE (minitape.h)

  • Статья

TAPE_PROCESS_COMMAND_ROUTINE обрабатывает аспекты запроса IOCTL для конкретных устройств.

Синтаксис

TAPE_PROCESS_COMMAND_ROUTINE TapeProcessCommandRoutine;

TAPE_STATUS TapeProcessCommandRoutine(
  [in, out]      PVOID MinitapeExtension,
  [in, out]      PVOID CommandExtension,
  [in, out]      PVOID CommandParameters,
  [in, out]      PSCSI_REQUEST_BLOCK Srb,
  [in]           ULONG CallNumber,
  [in, optional] TAPE_STATUS StatusOfLastCommand,
  [in, out]      PULONG RetryFlags
)
{...}

Параметры

[in, out] MinitapeExtension

Указатель на расширение мини-приложения для конкретного драйвера. Это значение равно NULL , если драйвер мини-класса не запрашивал расширение minitape при инициализации.

[in, out] CommandExtension

Указатель на расширение команды. Это значение равно NULL , если драйвер мини-класса не запрашивал расширение команды при его инициализации.

[in, out] CommandParameters

Указатель на буфер, выделенный вызывающим объектом, который содержит структуру TAPE_CREATE_PARTITION .

[in, out] Srb

Указатель на выделенный и частично заполненный драйвером класса ленты SRB. TAPE_PROCESS_COMMAND_ROUTINE должны заполнить CDB в SRB.

  • Cdb — указатель на CDB SCSI для команды. Очистите CDB с помощью TapeClassZeroMemory , прежде чем заполнять его.
  • CdbLength — указывает количество байтов в CDB.
TAPE_PROCESS_COMMAND_ROUTINE также может заполнить следующие элементы в SRB:
  • DataBuffer — указатель на буфер данных для передачи. Используйте TapeClassAllocateSrbBuffer , чтобы выделить DataBuffer длиной больше или равной DataTransferLength.
  • DataTransferLength — указывает количество байтов, передаваемых в SRB. Этот элемент задается с помощью TapeClassAllocateSrbBuffer.
  • TimeOutValue — задает значение времени ожидания для этой команды, переопределяющее значение времени ожидания по умолчанию из расширения устройства драйвера класса ленты.
  • SrbFlags — указывает флаг для этой команды. Драйвер мини-класса ленты должен задать SRB_FLAGS_DATA_OUT, если SRB отправляет данные на ленточный накопитель. Этот элемент может быть равен нулю, если SRB запрашивает данные с ленточного накопителя или если данные не передаются командой.

[in] CallNumber

Указывает количество вызовов TAPE_PROCESS_COMMAND_ROUTINE для обработки заданной команды ленты. CallNumber равен нулю при первом вызове этой подпрограммы и увеличивается для каждого последующего вызова, пока драйвер мини-класса не вернет TAPE_STATUS значение, указывающее, что команда завершена.

[in, optional] StatusOfLastCommand

Указывает состояние последней команды. При первом вызове TAPE_PROCESS_COMMAND_ROUTINE для обработки заданного запроса statusOfLastCommand TAPE_STATUS_SUCCESS. В последующих вызовах statusOfLastCommand TAPE_STATUS_SUCCESS или состояние ошибки, если произошла ошибка и драйвер мини-класса ленты RETURN_ERRORS в RetryFlags в предыдущем вызове .

[in, out] RetryFlags

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

Слово нижнего порядка указывает количество повторных попыток, выполняемых в случае сбоя команды SCSI. Значение по умолчанию равно нулю (без повторных попыток).

Слово высокого порядка содержит флаги, указывающие, как драйвер класса ленты должен возвращать управление при возникновении ошибки:

  • Если RETURN_ERRORS и IGNORE_ERRORS не заданы (по умолчанию), драйвер класса ленты возвращает исходному инициатору запроса состояние сбоя.
  • Если драйвер мини-класса задает RETURN_ERRORS, драйвер класса ленты вызывает TAPE_PROCESS_COMMAND_ROUTINE с состоянием StatusOfLastCommand , установленным в состояние сбоя.
  • Если драйвер мини-класса задает IGNORE_ERRORS, драйвер класса ленты преобразует состояние сбоя в успешное и вызывает TAPE_PROCESS_COMMAND_ROUTINE с параметром StatusOfLastCommand , установленным на success.

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

Код возврата Описание
TAPE_STATUS_SEND_SRB_AND_CALLBACK
 Указывает драйверу класса ленты, что SRB был заполнен и готов к отправке на целевое устройство. По умолчанию драйвер класса ленты снова вызывает TAPE_PROCESS_COMMAND_ROUTINE только в случае успешного выполнения SRB. Драйвер мини-класса может изменить поведение по умолчанию, задав RetryFlags перед возвращением из TAPE_PROCESS_COMMAND_ROUTINE.
TAPE_STATUS_CALLBACK
 Направляет драйвер класса ленты на увеличение CallNumber и повторное вызов TAPE_PROCESS_COMMAND_ROUTINE без отправки SRB на ленточное устройство.
TAPE_STATUS_CHECK_TEST_UNIT_READY
 Указывает драйверу класса ленты заполнить SRB для команды TEST UNIT READY и отправить SRB на устройство.
TAPE_STATUS_XXX
 Любой другой код возврата указывает драйверу класса ленты, что команда завершена, и указывает на успешное выполнение, сбой или предупреждение. Возможные возвращаемые значения завершения для этой подпрограммы включают, помимо прочего:
TAPE_STATUS_SUCCESS
TAPE_STATUS_INSUFFICIENT_RESOURCES
TAPE_STATUS_INVALID_DEVICE_REQUEST
TAPE_STATUS_INVALID_PARAMETER
TAPE_STATUS_IO_DEVICE_ERROR
TAPE_STATUS_MEDIA_WRITE_PROTECTED
TAPE_STATUS_NOT_IMPLEMENTED

Комментарии

Этому заполнителю обратного вызова можно назначить следующие функции:

CreatePartition

CreatePartition обрабатывает аспекты IOCTL_TAPE_CREATE_PARTITION запроса, относящиеся к устройству. Эта подпрограмма является обязательной. CreatePartition создает секцию на ленте, заполняя CDB в SRB, переданном драйвером класса ленты. Для создания секции обычно требуется ряд srb для завершения операции. После того как CreatePartition заполнит заданный SRB и возвратит его, драйвер класса ленты отправляет SRB на целевое устройство и в зависимости от результата SRB и значения RetryFlags снова вызывает TapeMiniCreatePartition .

Перед возвратом к драйверу класса ленты CreatePartition необходимо заполнить следующие элементы в SRB:

Если драйвер ленточного мини-класса хранит сведения о секции в расширении minitape, CreatePartition обновляет расширение, прежде чем вернуться к драйверу класса ленты с помощью TAPE_STATUS_SUCCESS.

Стереть

Erase обрабатывает аспекты IOCTL_TAPE_ERASE запроса, относящиеся к устройству. Эта подпрограмма является обязательной. Стирает ленту, заполняя CDB в SRB, переданном драйвером класса ленты. Для удаления ленты обычно требуется один SRB для завершения операции. После заполнения SRB и возврата erase драйвер класса ленты отправляет SRB на устройство и в зависимости от результата SRB и значения RetryFlags снова вызывает Erase . Затем erase возвращает TAPE_STATUS_SUCCESS.

GetDriveParameters

GetDriveParameters обрабатывает аспекты IOCTL_TAPE_GET_DRIVE_PARAMS запроса для конкретных устройств. Эта подпрограмма является обязательной. GetDriveParameters получает параметры ленточного накопителя путем заполнения CDB в SRB, переданном драйвером класса ленты. Для получения параметров диска обычно требуется ряд srb для завершения операции. После того как GetDriveParameters заполнит заданный SRB и возвратит его, драйвер класса ленты отправляет SRB на целевое устройство и в зависимости от результата SRB и значения RetryFlags снова вызывает GetDriveParameters .

GetMediaParameters

GetMediaParameters обрабатывает аспекты IOCTL_TAPE_GET_MEDIA_PARAMS запроса, относящиеся к устройству. Эта подпрограмма является обязательной. GetMediaParameters получает параметры ленточного носителя путем заполнения CDB в SRB, переданном драйвером класса ленты. Для получения параметров мультимедиа обычно требуется несколько SRB для завершения операции, начиная с готового тестового модуля, который драйвер мини-класса запрашивает, возвращая TAPE_STATUS_CHECK_TEST_UNIT_READY первый раз, когда драйвер класса ленты вызывает подпрограмму.

После того как GetMediaParameters заполнит заданный SRB и возвращает его, драйвер класса ленты отправляет SRB на устройство и в зависимости от результата SRB и значения RetryFlags снова вызывает GetMediaParameters.

GetMediaTypes

GetMediaTypes обрабатывает аспекты запроса IOCTL_STORAGE_GET_MEDIA_TYPES_EX для конкретных устройств. Эта подпрограмма является обязательной. GetMediaTypes получает сведения о типах мультимедиа, поддерживаемых ленточным устройством, заполнив CDB в SRB, переданном драйвером класса ленты. Получение типов мультимедиа обычно требует более одного SRB для завершения операции, начиная с готового тестового модуля, который драйвер мини-класса запрашивает, возвращая TAPE_STATUS_CHECK_TEST_UNIT_READY первый раз, когда драйвер класса ленты вызывает подпрограмму.

GetPosition

GetPosition обрабатывает аспекты запроса IOCTL_TAPE_GET_POSITION для конкретных устройств. Эта подпрограмма является обязательной. GetPosition считывает положение ленты, заполняя CDB в SRB, переданном драйвером класса ленты. Для чтения положения ленты обычно требуется несколько SRB для завершения операции, часто начиная с готового тестового модуля, который драйвер мини-класса запрашивает, возвращая TAPE_STATUS_CHECK_TEST_UNIT_READY первый раз, когда драйвер класса ленты вызывает подпрограмму.

Getstatus

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

Если устройство указывает, требуется ли диску очистка в смысле данных (в отличие от сообщения о необходимости очистки как ошибки, которую драйвер мини-класса будет обрабатывать в своей процедуре TapeMiniTapeError ), GetStatus заполняет CDB в SRB, переданном драйвером класса ленты, чтобы получить данные о смысле и при необходимости возвращает TAPE_STATUS_REQUIRES_CLEANING.

Подготовить

Подготовка обрабатывает аспекты IOCTL_TAPE_PREPARE запроса, относящиеся к устройству. Эта подпрограмма является обязательной. Подготовка подготавливает ленту, заполняя CDB в SRB, переданном драйвером класса ленты. Если устройство поддерживает запрошенную операцию, для подготовки ленты обычно требуется один SRB. После того как подготовка заполнит SRB и возвратит его, драйвер класса ленты отправляет SRB на устройство и, в зависимости от результата SRB и значения RetryFlags, снова вызывает Prepare .

SetDriveParameters

SetDriveParameters обрабатывает аспекты IOCTL_TAPE_SET_DRIVE_PARAMS запроса для конкретных устройств. Эта подпрограмма является обязательной. SetDriveParameters задает параметры для ленточного устройства, заполняя CDB в SRB, переданном драйвером класса ленты. Настройка параметров обычно включает ряд SSP для завершения операции. После того как SetDriveParameters заполнит заданный SRB и возвращает его, драйвер класса ленты отправляет SRB на устройство и в зависимости от результата SRB и значения RetryFlags снова вызывает SetDriveParameters .

SetMediaParameters

SetMediaParameters обрабатывает аспекты IOCTL_TAPE_SET_MEDIA_PARAMS запроса, относящиеся к устройству. Эта подпрограмма является обязательной. SetMediaParameters задает размер блока ленты, заполняя CDB в SRB, переданном драйвером класса ленты. Для установки размера блока обычно требуется несколько SRB для завершения операции, начиная с готового тестового модуля, который драйвер мини-класса запрашивает, возвращая TAPE_STATUS_CHECK_TEST_UNIT_READY первый раз, когда драйвер класса ленты вызывает подпрограмму.

После того как SetMediaParameters заполнит заданный SRB и возвращает его, драйвер класса ленты отправляет SRB на устройство и в зависимости от результата SRB и значения RetryFlags снова вызывает SetMediaParameters .

SetPosition

SetPosition обрабатывает аспекты IOCTL_TAPE_SET_POSITION запроса, относящиеся к устройству. Эта подпрограмма является обязательной. SetPosition задает положение ленты путем заполнения CDB в SRB, переданном драйвером класса ленты. Для установки позиции обычно требуется один SRB. После того как SetPosition заполнит SRB и возвратит его, драйвер класса ленты отправляет SRB на устройство и в зависимости от результата SRB и значения RetryFlags снова вызывает SetPosition . Затем SetPosition возвращает TAPE_STATUS_SUCCESS.

WriteMarks

WriteMarks обрабатывает аспекты запроса IOCTL_TAPE_WRITE_MARKS для конкретных устройств. Эта подпрограмма является обязательной. WriteMarks записывает метки на ленту, заполняя CDB в SRB, переданном драйвером класса ленты. Для записи меток обычно требуется один SRB для завершения операции. После того как WriteMarks заполнит SRB и возвратит его, драйвер класса ленты отправляет SRB на устройство и в зависимости от результата SRB и значения RetryFlags снова вызывает WriteMarks . Затем WriteMarks возвращает TAPE_STATUS_SUCCESS.

PreProcessReadWrite

PreProcessReadWrite — это необязательная подпрограмма специального назначения, которая выполняет все операции, связанные с устройством, перед операциями чтения и записи. Большинство ленточных мини-классов драйверов не нуждаются в этой процедуре. Действия подпрограммы PreProcessReadWrite зависят от устройства. Подпрограмма может использовать сведения, переданные ей драйвером класса, для реализации специальной предварительной обработки для операций чтения и записи. Если диск имеет ограниченные возможности, драйверу может потребоваться эта подпрограмма для поддержания согласованного состояния, например.

Если драйвер ленточного мини-класса задает для этой подпрограммы точку входа, отличной от NULL , в TAPE_INIT_DATA_EX структуре, которую он передает в TapeClassInitialize из подпрограммы DriverEntry , драйвер класса ленты вызывает ее перед каждой операцией чтения и записи на ленточных устройствах. Драйвер класса не ожидает каких-либо сведений из этой подпрограммы.

Операции WMI

WMIOperations — это общая точка входа для всех вызовов WMI из драйвера класса ленты. Мини-диск, поддерживающий инструментарий WMI, должен задавать элемент указателя функции WMIOperations в структуре, TAPE_INIT_DATA_EX указывать на подпрограмму TAPE_PROCESS_COMMAND_ROUTINE мини-драйвера. Мини-driver должен сделать это в своей процедуре DriverEntry перед вызовом TapeClassInitialize. Если мини-диск не поддерживает операции WMI, он должен задать для поля TapeWMIOperations значение NULL.

Драйвер класса ленты присваивает значения членам структуры TAPE_WMI_OPERATIONS и передает эту структуру подпрограмме WMIOperations minidriver в параметре CommandParameters . Как и в случае с другими подпрограммами minidriver, WMIOperations заполняет, создает и инициализирует блоки запросов SCSI (SRB) и блоки дескриптора команд (CDB), необходимые для реализации указанного метода WMI, и возвращает управление драйверу класса ленты. Затем драйвер класса ленты вызывает драйвер порта для выполнения запроса.

Мини-диск возвращает данные WMI в буфере, на который указывает элемент DataBuffer структуры TAPE_WMI_OPERATIONS.

Требования

Требование Значение
Целевая платформа Персональный компьютер
Верхняя часть minitape.h (включая Minitape.h)

См. также раздел

SCSI_REQUEST_BLOCK

TAPE_STATUS

TapeClassAllocateSrbBuffer

TapeClassZeroMemory