FSCTL_CREATE_OR_GET_OBJECT_ID IOCTL

Description

Retrieves the object identifier for the specified file or directory. If no object identifier exists, using FSCTL_CREATE_OR_GET_OBJECT_ID creates one.

To perform this operation, call the DeviceIoControl function with the following parameters.

BOOL DeviceIoControl(
  (HANDLE) hDevice,              // handle to file
  FSCTL_CREATE_OR_GET_OBJECT_ID, // dwIoControlCode
  NULL,                          // lpInBuffer
  0,                             // nInBufferSize
  (LPVOID) lpOutBuffer,          // output buffer
  (DWORD) nOutBufferSize,        // size of output buffer
  (LPDWORD) lpBytesReturned,     // number of bytes returned
  (LPOVERLAPPED) lpOverlapped    // OVERLAPPED structure
);

Parameters

hDevice [in]

A handle to the file object.

To retrieve a device handle, call the CreateFile function.

dwIoControlCode [in]

The control code for the operation.

Use FSCTL_CREATE_OR_GET_OBJECT_ID for this operation.

lpInBuffer [in, optional]

Not used with this operation. Set to NULL.

nInBufferSize [in]

The size of the input buffer, in bytes. Set to 0 (zero).

lpOutBuffer [out, optional]

A pointer to the output buffer that is to receive the FILE_OBJECTID_BUFFER data returned by the operation.

nOutBufferSize [in]

The size of the output buffer, in bytes. It must be >= sizeof(FILE_OBJECTID_BUFFER).

lpBytesReturned [out, optional]

A pointer to a variable that receives the size of the data stored in the output buffer, in bytes.

lpOverlapped [in, out, optional]

A pointer to an OVERLAPPED structure.

Status block

Irp->IoStatus.Status is set to STATUS_SUCCESS if the request is successful.

Otherwise, Status to the appropriate error condition as a NTSTATUS code.

For more information, see NTSTATUS Values.

Remarks

Object identifiers are used to track files and directories. They are invisible to most applications and should never be modified by applications. Modifying an object identifier can result in the loss of data from portions of a file, up to and including entire volumes of data.

This operation creates an object identifier if the object does not already have one. To test for the presence of an object identifier, and retrieve it if it exists, use the FSCTL_GET_OBJECT_ID operation. To manually assign an object identifier, use the FSCTL_SET_OBJECT_ID operation.

In Windows Server 2012, this function is supported by the following technologies.

See also

• DeviceIoControl
• FILE_OBJECTID_BUFFER
• FSCTL_DELETE_OBJECT_ID
• FSCTL_GET_OBJECT_ID
• FSCTL_SET_OBJECT_ID
• FSCTL_SET_OBJECT_ID_EXTENDED
• Object Identifiers