Logs

This category covers the local processing of logs and shadow files. The caller does not have to deal with native formats and compression, and can register multiple handlers if needed.

Warning:

1. The API consumes files that have reached the final stage (.final), and so does not provide a real-time workflow. The API triggers an IDAC Agent Service flush every 5 minutes by default, additional calls to HSDCFetchLogs can be performed as needed.
2. As soon as one process registers a handler, the related files are processed and then deleted after all handlers are called.
3. This local processing is exposed for installation that are not relying on SXS and when logs and shadows must be processed locally.
4. Make no assumptions regarding the thread(s) executing the callbacks, but make sure you provide thread-safe callbacks and don't just throw exception objects.

Typedefs

typedef void(HSDCAPI * HSDC_LOG_PROCESSOR_CALLBACK) (DWORD cookie, const char *jstr)

The format of the callback function for processing log events. The callback is triggered with its registration cookie and the JSON payload containing the logs.

typedef void(HSDCAPI * HSDC_SHADOW_PROCESSOR_CALLBACK) (DWORD cookie, const char *jstr, const wchar_t *filename)

Definition of the function signature for a shadow processor callback. The callback parameter is the subscription cookie, the JSON payload with shadow file information, and the shadow filename that can be used in HSDCExtractShadowStream to extract the stream.

typedef HSDCError(HSDCAPI * HSDC_SHADOW_STREAM_CALLBACK) (unsigned long long offset, const unsigned char *buffer, unsigned int length, void *parameters)

Definition of the required callback function signature for use with the /ref HSDCExtractShadowStream function.

Functions

HSDCError HSDCAPI HSDCRegisterLogProcessor (DWORD *pCookie, HSDC_LOG_PROCESSOR_CALLBACK cb)

Registers a callback to get logs by batch. The callback parameter is the subscription cookie and the JSON payload containing one to many log events.

HSDCError HSDCAPI HSDCUnregisterLogProcessor (DWORD cookie)

Unregisters a callback using the cookie returned at registration.

HSDCError HSDCAPI HSDCRegisterShadowProcessor (DWORD *pCookie, HSDC_SHADOW_PROCESSOR_CALLBACK cb)

Registers a callback to get shadow files by batch.

HSDCError HSDCAPI HSDCUnregisterShadowProcessor (DWORD cookie)

Unregisters a callback using the cookie returned at registration.

HSDCError HSDCAPI HSDCExtractShadowStream (const wchar_t *filename, char **pJstr, HSDC_SHADOW_STREAM_CALLBACK cb, void *parameters)

Extracts the content of a Device Control shadow file.

HSDCError HSDCAPI HSDCFetchLogs (BOOLEAN dismount, DWORD retry)

Triggers log and shadow processing and flush.

Typedef Documentation

HSDC_LOG_PROCESSOR_CALLBACK

typedef void(HSDCAPI * HSDC_LOG_PROCESSOR_CALLBACK) (DWORD cookie, const char *jstr)

The format of the callback function for processing log events. The callback is triggered with its registration cookie and the JSON payload containing the logs.

The log JSON is formatted as below:

{
    "filename": "C:\\Windows\\SxData\\shadow\\sdcevent-7B97FABD2AD0D001.log.final.local",
    "rows": [
        {
            "code": "DEVICE-ATTACHED",
            "devicename": "Brother MFC-5490CN USB Device, Disk drive, (Standard disk drives)",
            "devicetype": "Removable",
            "local": "2015-04-28T10:46:12.070",
            "machine": "hubertb.corp.lcl",
            "modelid": "2004696e95c206910b8152afd2ea9798374ca314",
            "other": "USBSTOR\\DiskBrother_MFC-5490CN______1.00",
            "user": "S-1-5-21-1671596716-2257663418-1665464539-500",
            "utc": "2015-04-28T09:46:12.070Z"
        },
        ...
    ],
    "transferred": "2015-08-12T06:56:00.598Z"
}

HSDC_SHADOW_PROCESSOR_CALLBACK

typedef void(HSDCAPI * HSDC_SHADOW_PROCESSOR_CALLBACK) (DWORD cookie, const char *jstr, const wchar_t *filename)

Definition of the function signature for a shadow processor callback. The callback parameter is the subscription cookie, the JSON payload with shadow file information, and the shadow filename that can be used in HSDCExtractShadowStream to extract the stream.

The payload jstr parameter is formatted as below:

{
    "devicetype": "1",
    "filenameonly": "0",
    "filesize": "3300289",
    "local": "2008-04-21T15:48:19.144",
    "machine": "hubertb.corp.lcl",
    "path": "G:\\AIDA_32_3.93_Personnal_Edition.exe",
    "shadowfilename": "C:\\Windows\\sxdata\\Shadow\\805CD91EC7A3C8010100000000000000.dat.final.local",
    "user": "S-1-5-21-1935655697-507921405-682003330-18748",
    "utc": "2008-04-21T13:48:19.144Z"
}

HSDC_SHADOW_STREAM_CALLBACK

typedef HSDCError(HSDCAPI * HSDC_SHADOW_STREAM_CALLBACK) (unsigned long long offset, const unsigned char *buffer, unsigned int length, void *parameters)

Definition of the required callback function signature for use with the /ref HSDCExtractShadowStream function.

Function Documentation

HSDCRegisterLogProcessor()

HSDCError HSDCAPI HSDCRegisterLogProcessor ( DWORD * pCookie, HSDC_LOG_PROCESSOR_CALLBACK cb )

Registers a callback to get logs by batch. The callback parameter is the subscription cookie and the JSON payload containing one to many log events.

Parameters

HSDCUnregisterLogProcessor()

HSDCError HSDCAPI HSDCUnregisterLogProcessor ( DWORD cookie )

Unregisters a callback using the cookie returned at registration.

Parameters

HSDCRegisterShadowProcessor()

HSDCError HSDCAPI HSDCRegisterShadowProcessor ( DWORD * pCookie, HSDC_SHADOW_PROCESSOR_CALLBACK cb )

Registers a callback to get shadow files by batch.

Parameters

HSDCUnregisterShadowProcessor()

HSDCError HSDCAPI HSDCUnregisterShadowProcessor ( DWORD cookie )

Unregisters a callback using the cookie returned at registration.

Parameters

See also

HSDCRegisterShadowProcessor

Returns

HSDCExtractShadowStream()

HSDCError HSDCAPI HSDCExtractShadowStream ( const wchar_t * filename, char ** pJstr, HSDC_SHADOW_STREAM_CALLBACK cb, void * parameters )

Extracts the content of a Device Control shadow file.

Parameters

Returns

HSDCFetchLogs()

HSDCError HSDCAPI HSDCFetchLogs ( BOOLEAN dismount, DWORD retry )

Triggers log and shadow processing and flush.

Parameters

A dismount of non-system volume can be done to force closure of a shadow file, this can have the side effect of terminating some transfers and closing explorer windows focused on non-system volumes.

Parameters

Returns