Управляющий код FSCTL_SET_OBJECT_ID_EXTENDED изменяет пользовательские данные, связанные с идентификатором объекта указанного файла или каталога.
Чтобы выполнить эту операцию, вызовите функцию DeviceIoControl с ниже перечисленными параметрами.
Синтаксис
BOOL DeviceIoControl( (HANDLE) hDevice, // дескриптор устройства FSCTL_SET_OBJECT_ID_EXTENDED, // dwIoControlCode (LPVOID) lpInBuffer, // буфер ввода данных (DWORD) nInBufferSize, // размер буфера ввода данных NULL, // lpOutBuffer 0, // nOutBufferSize (LPDWORD) lpBytesReturned, // число возвращаемых данных (LPOVERLAPPED) lpOverlapped // структура OVERLAPPED ); |
Параметры
hDevice
[in] Дескриптор файла или каталога, для которого устанавливается идентификатор объекта данных пользователя. Процесс должен иметь доступ для записи в объект. Чтобы извлечь дескриптор устройства, вызовите функцию CreateFile.dwIoControlCode
[in] Управляющий код операции. Для этой операции используйте FSCTL_SET_OBJECT_ID_EXTENDED.lpInBuffer
[in] Указатель на буфер ввода данных, который - член ExtendedInfo структуры FILE_OBJECTID_BUFFER. Член этой структуры ObjectId игнорируется. Для этого идентификатора объекта применяются только пользовательские данные, которые в члене структуры ExtendedInfo.nInBufferSize
[in] Размер буфера ввода данных, в байтах.lpOutBuffer
Не используется этой операцией; устанавливается в ПУСТО (NULL).nOutBufferSize
Не используется этой операцией; устанавливается в нуль ('0').lpBytesReturned
[out] Указатель на переменную, которая получает размер данных, сохраненных в буфере вывода данных, в байтах.Если lpOverlapped равен ПУСТО (NULL), параметр lpBytesReturned не может быть ПУСТО (NULL). Даже когда операция не возвращает никакого вывода данных, и lpOutBuffer - ПУСТО (NULL), функция DeviceIoControl использует параметр lpBytesReturned. После такой операции, значение lpBytesReturned не имеет смысла.
Если lpOverlapped - не ПУСТО (NULL), параметр lpBytesReturned может быть ПУСТО (NULL). Если этот параметр - не ПУСТО (NULL), и операция возвращает данные, то параметр lpBytesReturned не имеет смысла до тех пор, пока не завершилась асинхронная операция. Чтобы извлечь данные о числе возвращаемых данных, вызовите GetOverlappedResult. Если параметр hDevice связан с портом завершения ввода-вывода данных (I/O), Вы можете извлечь число возвращаемых данных при помощи вызова GetQueuedCompletionStatus.
lpOverlapped
[in] Указатель на структуру OVERLAPPED.Если параметр hDevice открывался без определения флажка FILE_FLAG_OVERLAPPED, параметр lpOverlapped игнорируется.
Если параметр hDevice открывался с флажком FILE_FLAG_OVERLAPPED, операция выполняется как перекрывающая (асинхронная) операция. В этой ситуации, lpOverlapped должен указывать на допустимую структуру OVERLAPPED, которая содержит дескриптор объекта события. В противном случае, функция завершается ошибкой непредсказуемого вида.
Для асинхронных операций, функция DeviceIoControl возвращает значение немедленно, а объект события подает сигнал, когда операция завершилась. В противном случае, функция не возвращает значение до тех пор, пока операция не завершится или не произойдет ошибка.
Возвращаемые значения
Если операция завершается успешно, DeviceIoControl возвращает ненулевое значение.
Если операция завершается ошибкой, DeviceIoControl возвращает нуль. Чтобы получить дополнительную информацию об ошибке, вызовите GetLastError.
Замечания
Идентификаторы объекта используются, чтобы отслеживать файлы и каталоги. Они невидимы в большинстве приложений и никогда не должны модифицироваться ими. Изменение идентификатора объекта может в результате привести к потере данных от части файла вплоть до всего тома данных.
Эта операция устанавливает пользовательские данные только в идентификаторе объекта. Возможное использование - сохранение отметки времени создания идентификатора объекта или монотонно возрастающего номера версии. Член ObjectId структуры FILE_OBJECTID_BUFFER игнорируется. Нет никакого механизма чтобы изменять член структуры ObjectId. Обычно управляющий код FSCTL_SET_OBJECT_ID_EXTENDED используется там, где прикладная программа не использует пользовательские данные, созданные файловой системой NTFS, для которых система создает идентификатор объекта.
Чтобы установить идентификатор для объекта, который еще не имеет его, используйте управляющий код FSCTL_SET_OBJECT_ID. Чтобы файловая система NTFS создала идентификатор объекта, если он не существует, используйте управляющий код FSCTL_CREATE_OR_GET_OBJECT_ID.
| Обратите внимание! на то, что то отметки времени не могут обновляться правильно для удаленного файла. Чтобы гарантировать непротиворечивые результаты, используйте не буферизованный ввод - вывод (I/O). |
Смотри также
Обзор Управление файлами, Управляющие коды, используемые файловыми системами, Идентификаторы объекта, DeviceIoControl, CreateFile, FILE_OBJECTID_BUFFER, FSCTL_CREATE_OR_GET_OBJECT_ID, FSCTL_DELETE_OBJECT_ID, FSCTL_GET_OBJECT_ID, FSCTL_SET_OBJECT_ID
|
Размещение и совместимость FSCTL_SET_OBJECT_ID_EXTENDED |
||
| К |
Windows XP |
Да |
| л |
Windows 2000 Professional |
Да |
| и |
Windows NT |
Нет |
| е |
Windows Me |
Нет |
| н |
Windows 98 |
Нет |
| т |
Windows 95 |
Нет |
| С |
Windows Server 2003 |
Да |
| е | Windows 2000 Server | Да |
| р | Windows NT Server | Нет |
| в | ||
| е | ||
| р | ||
|
Используемая библиотека |
- |
|
| Используемая DLL | - | |
| Заголовочный файл | ||
|
- объявлено в |
Winioctl.h |
|
| - включено в |
- |
|
| Unicode |
- |
|
| Замечания по платформе |
Не имеется |
|