código de controle FSCTL_SUSPEND_OVERLAY

Artigo
02/02/2024

O código de controle FSCTL_SUSPEND_OVERLAY suspende uma fonte de suporte anexada a um volume, impedindo o acesso à fonte de suporte e permitindo que ela seja modificada ou removida.

Para executar essa operação, chame FltFsControlFile ou ZwFsControlFile com os parâmetros a seguir.

BOOL 
   WINAPI 
   DeviceIoControl( (HANDLE)       hDevice,         // handle to device
                    (DWORD)        FSCTL_SUSPEND_OVERLAY, // dwIoControlCode
                    (LPDWORD)      lpInBuffer,      // input buffer
                    (DWORD)        nInBufferSize,   // size of input buffer
                    (LPDWORD)      lpOutBuffer,     // output buffer
                    (DWORD)        nOutBufferSize,  // size of output buffer
                    (LPDWORD)      lpBytesReturned, // number of bytes returned
                    (LPOVERLAPPED) lpOverlapped );  // OVERLAPPED structure

Parâmetros

Instância [in]: somente FltFsControlFile . Um ponteiro de instância opaco para o chamador. Esse parâmetro é necessário e não pode ser NULL.
FileObject [in]: somente FltFsControlFile . O objeto de ponteiro de arquivo do volume para o qual a sobreposição é atualizada. Esse parâmetro é necessário e não pode ser NULL.
FileHandle [in]: somente ZwFsControlFile . O identificador do volume para o qual a sobreposição é atualizada. Esse parâmetro é necessário e não pode ser NULL.
FsControlCode [in]: o código de controle da operação. Use FSCTL_SUSPEND_OVERLAY para esta operação.
InputBuffer [in]: um ponteiro para o buffer de entrada, que deve conter uma estrutura WOF_EXTERNAL_INFO . Quando necessário, dados adicionais específicos do provedor são incluídos imediatamente após WOF_EXTERNAL_INFO. Se o provedor for um arquivo WIM, uma estrutura de WIM_PROVIDER_SUSPEND_OVERLAY_INPUT será incluída após WOF_EXTERNAL_INFO.
InputBufferLength [in]: defina como sizeof(WOF_EXTERNAL_INFO) mais o tamanho de quaisquer dados de entrada de provedor adicionais.
OutputBuffer [out]: não usado. Definido como NULL.
OutputBufferLength [in]: definido como 0.

Bloco de status

FltFsControlFile ou ZwFsControlFile retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, a função apropriada pode retornar um dos seguintes valores NTSTATUS.

Código	Significado
STATUS_ACCESS_DENIED	O solicitante não tem privilégios administrativos.
STATUS_BUFFER_TOO_SMALL	O comprimento do buffer de entrada apontado por InputBuffer e especificado por InputBufferLength é muito pequeno.
STATUS_INTERNAL_ERROR	O volume solicitado não está acessível.
STATUS_INVALID_DEVICE_REQUEST	O serviço de backup não está presente ou não foi iniciado.

Comentários

Quando a fonte de suporte a ser removida for um arquivo WIM (Windows Imaging Format), o buffer de entrada conterá uma estrutura WOF_EXTERNAL_INFO seguida por uma estrutura WIM_PROVIDER_SUSPEND_OVERLAY_INPUT . O InputBufferLength nesse caso será sizeof(WOF_EXTERNAL_INFO) + sizeof(WIM_PROVIDER_REMOVE_OVERLAY_INPUT). O valor DataSourceId em WIM_PROVIDER_SUSPEND_OVERLAY_INPUT deve ser para um arquivo WIM adicionado anteriormente em uma solicitação FSCTL_ADD_OVERLAY .

Provedores de suporte adicionais definirão suas próprias estruturas de parâmetro de entrada específicas.