Edit

File stream, file, and file object event objects

This page contains reference entries in the Event objects API family. Each entry includes its declaration and requirements.

File stream

EspCreateFileStreamReferenceById

The API EspCreateFileStreamReferenceById creates an event object reference for an existing file stream by its file id. This is useful in cases where a client needs to reference a stream outside the context of an event involving the stream. For example, a client may require a reference to a stream to query properties or set event object context.

Syntax

HRESULT
WINAPI
EspCreateFileStreamReferenceById(
    _In_ ESP_CLIENT Client,
    _In_ const GUID* VolumeGuid,
    _In_ const FILE_ID_DESCRIPTOR* FileId,
    _In_opt_ PCWSTR StreamName,
    _Out_ ESP_EVENT_OBJECT_REF* ObjectRef
    );

Parameters

Client

Supplies the client.

VolumeGuid

Supplies the guid for the volume on which the stream is found.

FileId

Supplies the file id in which the stream is found.

StreamName

Supplies the stream name. The caller can supply nullptr to reference the default stream.

ObjectRef

Receives the reference. The reference must be closed by calling EspCloseEventObjectReference once it is no longer needed.

Return value

Returns an HRESULT that indicates the result of the operation. Use SUCCEEDED or FAILED to test the result.

Requirements

Requirement Value
Header espclient.h
DLL espclient.dll

See also

EspCreateFileStreamReferenceByPath

The API EspCreateFileStreamReferenceByPath creates an event object reference to an existing file stream by its path. This is useful in cases where a client needs to reference a file stream outside the context of an event involving the stream. For example, a client may require a reference to a file stream to query properties or set event object context.

Syntax

HRESULT
WINAPI
EspCreateFileStreamReferenceByPath(
    _In_ ESP_CLIENT Client,
    _In_ const ESP_PATH* StreamPath,
    _Out_ ESP_EVENT_OBJECT_REF* ObjectRef
    );

Parameters

Client

Supplies the client.

StreamPath

Supplies the stream path.

ObjectRef

Receives the reference. The reference must be closed by calling EspCloseEventObjectReference once it is no longer needed.

Return value

Returns an HRESULT that indicates the result of the operation. Use SUCCEEDED or FAILED to test the result.

Requirements

Requirement Value
Header espclient.h
DLL espclient.dll

See also

ESP_FILE_STREAM_CONFIG_FLAGS

The enum ESP_FILE_STREAM_CONFIG_FLAGS specifies flags for an ESP_FILE_STREAM_CONFIG structure.

Syntax

typedef enum ESP_FILE_STREAM_CONFIG_FLAGS
{
    ESP_FILE_STREAM_CONFIG_FLAGS_NONE                  = 0x00000000,
    ESP_FILE_STREAM_CONFIG_FLAGS_SKIP_IF_OBJECT_ABSENT = 0x00000001
} ESP_FILE_STREAM_CONFIG_FLAGS;

Requirements

Requirement Value
Header esptypes.h

See also

ESP_FILE_STREAM_CONFIG

The configuration structure for a file stream event object is ESP_FILE_STREAM_CONFIG.

Syntax

typedef struct ESP_FILE_STREAM_CONFIG
{
    ESP_FILE_STREAM_CONFIG_FLAGS Flags;
    ESP_EVENT_OBJECT_CONFIG EventObjectConfig;

    UINT32 PropertiesCount;
    _Field_size_(PropertiesCount) const ESP_FILE_STREAM_PROPERTY_ID* Properties;

    ESP_FILE_CONFIG FileConfig;
} ESP_FILE_STREAM_CONFIG;

Members

FIELD DESCRIPTION
Flags Specifies flags for the file stream.
EventObjectConfig Supplies event object configuration for the file stream.
PropertiesCount Supplies the number of elements in the "Properties" array.
Properties Supplies an array of file stream properties that should be captured for the stream.
FileConfig Supplies the configuration for stream's file.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_FILE_STREAM_INFO

The structure ESP_FILE_STREAM_INFO specifies information for a file stream. This structure is supplied as part of an event notification (one for each file stream associated with an event) and contains various details about the file stream.

Syntax

typedef struct ESP_FILE_STREAM_INFO
{
    ESP_EVENT_OBJECT_INFO ObjectInfo;
    _Maybenull_ const ESP_FILE_INFO* FileInfo;
} ESP_FILE_STREAM_INFO;

Members

FIELD DESCRIPTION
ObjectInfo Specifies information about the file stream's event object.
FileInfo Specifies information about the file stream's file. This field may be null if the client didn't specify file configuration through the "FileConfig" field in ESP_FILE_STREAM_CONFIG.

Requirements

Requirement Value
Header esptypes.h

See also

File

EspCreateFileReferenceById

The API EspCreateFileReferenceById creates an event object reference for an existing file by its file id. This is useful in cases where a client needs to reference a file outside the context of an event involving the file. For example, a client may require a reference to a file to query properties or set event object context.

Syntax

HRESULT
WINAPI
EspCreateFileReferenceById(
    _In_ ESP_CLIENT Client,
    _In_ const GUID* VolumeGuid,
    _In_ const FILE_ID_DESCRIPTOR* FileId,
    _Out_ ESP_EVENT_OBJECT_REF* ObjectRef
    );

Parameters

Client

Supplies the client.

VolumeGuid

Supplies the guid for the volume on which the file is found.

FileId

Supplies the file id for the file.

ObjectRef

Receives the reference. The reference must be closed by calling EspCloseEventObjectReference once it is no longer needed.

Return value

Returns an HRESULT that indicates the result of the operation. Use SUCCEEDED or FAILED to test the result.

Requirements

Requirement Value
Header espclient.h
DLL espclient.dll

See also

EspCreateFileReferenceByPath

The API EspCreateFileReferenceByPath creates an event object reference for an existing file by its path. This is useful in cases where a client needs to reference a file outside the context of an event involving the file. For example, a client may require a reference to a file to query properties or set event object context.

Syntax

HRESULT
WINAPI
EspCreateFileReferenceByPath(
    _In_ ESP_CLIENT Client,
    _In_ const ESP_PATH* FilePath,
    _Out_ ESP_EVENT_OBJECT_REF* ObjectRef
    );

Parameters

Client

Supplies the client.

FilePath

Supplies the file path.

ObjectRef

Receives the reference. The reference must be closed by calling EspCloseEventObjectReference once it is no longer needed.

Return value

Returns an HRESULT that indicates the result of the operation. Use SUCCEEDED or FAILED to test the result.

Requirements

Requirement Value
Header espclient.h
DLL espclient.dll

See also

ESP_FILE_CONFIG_FLAGS

The enum ESP_FILE_CONFIG_FLAGS specifies flags for an ESP_FILE_CONFIG structure. There are currently no supported flags.

Syntax

typedef enum ESP_FILE_CONFIG_FLAGS
{
    ESP_FILE_CONFIG_FLAGS_NONE = 0x00000000
} ESP_FILE_CONFIG_FLAGS;

Requirements

Requirement Value
Header esptypes.h

See also

ESP_FILE_CONFIG

The configuration structure for a file event object is ESP_FILE_CONFIG.

Syntax

typedef struct ESP_FILE_CONFIG
{
    ESP_FILE_CONFIG_FLAGS Flags;
    ESP_EVENT_OBJECT_CONFIG EventObjectConfig;

    UINT32 PropertiesCount;
    _Field_size_(PropertiesCount) const ESP_FILE_PROPERTY_ID* Properties;

    ESP_VOLUME_CONFIG VolumeConfig;
} ESP_FILE_CONFIG;

Members

FIELD DESCRIPTION
Flags Specifies flags for the file.
EventObjectConfig Supplies event object configuration for the file.
PropertiesCount Supplies the number of elements in the "Properties" array.
Properties Supplies an array of file properties that should be captured for the file.
VolumeConfig Supplies the configuration for the file's volume.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_FILE_INFO

The structure ESP_FILE_INFO specifies information for a file. This structure is supplied as part of an event notification (one for each file associated with an event) and contains various details about the file.

Syntax

typedef struct ESP_FILE_INFO
{
    ESP_EVENT_OBJECT_INFO ObjectInfo;
    _Maybenull_ const ESP_VOLUME_INFO* VolumeInfo;
} ESP_FILE_INFO;

Members

FIELD DESCRIPTION
ObjectInfo Specifies information about the file's event object.
VolumeInfo Specifies information about the file's volume. This field may be null if the client didn't specify volume configuration through the "VolumeConfig" field in ESP_FILE_CONFIG.

Requirements

Requirement Value
Header esptypes.h

See also

File object

ESP_FILE_OBJECT_CONFIG_FLAGS

The enum ESP_FILE_OBJECT_CONFIG_FLAGS specifies flags for an ESP_FILE_OBJECT_CONFIG structure.

Syntax

typedef enum ESP_FILE_OBJECT_CONFIG_FLAGS
{
    ESP_FILE_OBJECT_CONFIG_FLAGS_NONE                  = 0x00000000,
    ESP_FILE_OBJECT_CONFIG_FLAGS_SKIP_IF_OBJECT_ABSENT = 0x00000001
} ESP_FILE_OBJECT_CONFIG_FLAGS;

Values

VALUE DESCRIPTION
ESP_FILE_OBJECT_CONFIG_FLAGS_SKIP_IF_OBJECT_ABSENT Specifies to skip applying the configuration if the file object doesn't exist. For example, if a client specifies "ParentOfTarget" configuration for a set-file-information event, but there's no such file object, the file object configuration won't be applied.
If the file object is absent, this flag implicitly evaluates the file object's filter to true.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_FILE_OBJECT_CONFIG

The configuration structure for a file object event object is ESP_FILE_OBJECT_CONFIG.

Syntax

typedef struct ESP_FILE_OBJECT_CONFIG
{
    ESP_FILE_OBJECT_CONFIG_FLAGS Flags;
    ESP_EVENT_OBJECT_CONFIG EventObjectConfig;

    UINT32 PropertiesCount;
    _Field_size_(PropertiesCount) const ESP_FILE_OBJECT_PROPERTY_ID* Properties;

    ESP_KTM_TRANSACTION_CONFIG TransactionConfig;

    ESP_FO_TARGET_OBJECT_TYPE TargetObjectType;
    ESP_FO_TARGET_OBJECT_CONFIG TargetObjectConfig;
} ESP_FILE_OBJECT_CONFIG;

Members

FIELD DESCRIPTION
Flags Specifies flags for the file object.
EventObjectConfig Supplies event object configuration for the file object.
PropertiesCount Supplies the number of elements in the "Properties" array.
Properties Supplies an array of file object properties that should be captured for the file object.
TransactionConfig Supplies configuration for the file object's transaction. Note that if the file object is not part of a transaction, transaction properties won't be retrieved if the rule matches.
TargetObjectType Supplies the target object's type
TargetObjectConfig Supplies configuration for the file object's target object. This parameter is ignored if the TargetObjectType is ESP_EVENT_OBJECT_TYPE_NONE.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_FILE_OBJECT_INFO

The structure ESP_FILE_OBJECT_INFO specifies information for a file object. This structure is supplied as part of an event notification (one for each file object associated with an event) and contains various details about the file object.

Syntax

typedef struct ESP_FILE_OBJECT_INFO
{
    ESP_EVENT_OBJECT_INFO ObjectInfo;
    _Maybenull_ const ESP_KTM_TRANSACTION_INFO* TransactionInfo;

    ESP_FO_TARGET_OBJECT_TYPE TargetObjectType;
    _Maybenull_ const ESP_FO_TARGET_OBJECT_INFO* TargetObjectInfo;
} ESP_FILE_OBJECT_INFO;

Members

FIELD DESCRIPTION
ObjectInfo Specifies information about the file object's event object.
TransactionInfo Specifies information about the file object's KTM transaction. This field may be null if the client didn't specify KTM transaction configuration through the "TransactionConfig" field in ESP_FILE_OBJECT_CONFIG.
TargetObjectType Specifies the file object's target object type.
TargetObjectInfo Specifies information about the file object's target object. This field may be null if the client didn't specify target object configuration through the "TargetObjectConfig" field in ESP_FILE_OBJECT_CONFIG.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_FO_TARGET_OBJECT_CONFIG

The union ESP_FO_TARGET_OBJECT_CONFIG specifies configuration for the file object's target object. The active member in the union is determined by the "TargetObjectType" in ESP_FILE_OBJECT_CONFIG.

Syntax

typedef union ESP_FO_TARGET_OBJECT_CONFIG
{
    ESP_FILE_STREAM_CONFIG FileStream;
    ESP_VOLUME_CONFIG Volume;
    ESP_PIPE_CONFIG Pipe;
    ESP_MAILSLOT_CONFIG Mailslot;
} ESP_FO_TARGET_OBJECT_CONFIG;

Members

Member Description
FileStream Configuration for the file stream target object.
Volume Configuration for the volume target object.
Pipe Configuration for the pipe target object.
Mailslot Configuration for the mailslot target object.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_FO_TARGET_OBJECT_INFO

The union ESP_FO_TARGET_OBJECT_INFO specifies information for the file object's target object. The active member in the union is determined by the "TargetObjectType" in ESP_FILE_OBJECT_INFO.

Syntax

typedef union ESP_FO_TARGET_OBJECT_INFO
{
    ESP_FILE_STREAM_INFO FileStream;
    ESP_VOLUME_INFO Volume;
    ESP_PIPE_INFO Pipe;
    ESP_MAILSLOT_INFO Mailslot;
} ESP_FO_TARGET_OBJECT_INFO;

Members

Member Description
FileStream Information for the file stream target object.
Volume Information for the volume target object.
Pipe Information for the pipe target object.
Mailslot Information for the mailslot target object.

Requirements

Requirement Value
Header esptypes.h

See also