How to register for and handle events

Hover over each item to view the pop-up details.

How do you create event handlers?

Events can be registered by calling wa_api_register_handler and passing the appropriate json to the json_event_info argument. Possible event_type values are:

• 0 = Register for callbacks when Asynchronous Invoke calls complete. Each async invoke call must be passed the handler_id inside the json_in parameter. For example, to make a DetectProducts call with an async callback it might look like this:

  {
      "handler_id" : 1234,
      "input" : {
          "method" : 0,
          "category" : 0,
          "async_job" : true
      }
  }

  The handler_id must be a valid id value that was returned from wa_api_register_handler. Completed async jobs that are passed to event callbacks will not be retrievable by calls to QueryAsyncResults.

• 1 = Register for callbacks when a process is started or stopped on the system.

• 2 = Register for callbacks when a product is installed or uninstalled on the system.

• 3 = Register for callbacks when a product state changes. This is equivalent to making an Async wa_api_invoke call for a particular product signature and method, except the wa_api_invoke will be called every 5 seconds for checking the changes and the handler will be called every time the product state changes. Currently the only supported methods are: GetRealTimeProtectionState, GetFirewallState. See wa_api_register_handler for details on configuring the call.

• 4 = Register for callbacks when the driver blocks a drive through auto-blocking mode.

• 9 = Register for callbacks when there is a progress change in the method InstallMissingPatches of Windows Update Agent.

• (Windows and macOS only) 10 = Register for callbacks when a product state changes. This is equivalent to (event_type = 3) except the changes will be monitored and notified at real time without 5 seconds interval call of wa_api_invoke. The supported signatures and methods can be found in the latest support chart. See wa_api_register_handler for details on configuring the call.

Events can be unregistered by calling wa_api_unregister_handler.

Handling results in your wa_event_handler callback function

Each type of event will pass a different json_event to the handler. The json_event format is defined below for each possible event type.

Output json_event for async Invoke events (event_type = 0)

{
    "event_type" : 0,
    "handler_id" : number,
    "result" : { ... }
}

Key	JSON	Description
event_type	number	Matches the event_type for the registered event. Included as a convenience so the same event handler could be used to process all event types, if desired.
handler_id	number	Matches the handler_id for the registered event. Included as a convenience so the event handler knows the id for the call in the event the handler is registered multiple times.
result	object	The same result object that would be returned from the async invoke call itself. This includes errors, see remarks section.

Output json_event for process change events (event_type = 1)

{
    "event_type" : 1,
    "handler_id" : number,
    "action" : string,
    "name" : string,
    "process_id" : number,
    "binary_path" : string,
    "command_line" : string
}

Key	JSON	Description
event_type	number	Matches the event_type for the registered event. Included as a convenience so the same event handler could be used to process all event types, if desired.
handler_id	number	Matches the handler_id for the registered event. Included as a convenience so the event handler knows the id for the call in the event the handler is registered multiple times.
action	string	The process change action. Possible values: 'created', 'destroyed'
name	string	The name of the process.
process_id	string	The process identifier. Note: process ids get reused by the operating system, so this value should not be used long term.
binary_path	string	The path on disk to the binary for the process.
command_line	string	The command line arguments that were passed to the process.

Output json_event for install state change events (event_type = 2)

{
    "event_type" : 2,
    "handler_id" : number,
    "action" : string,
    "name" : string,
    "install_location" : string
}

Key	JSON	Description
event_type	number	Matches the event_type for the registered event. Included as a convenience so the same event handler could be used to process all event types, if desired.
handler_id	number	Matches the handler_id for the registered event. Included as a convenience so the event handler knows the id for the call in the event the handler is registered multiple times.
action	string	The install state change action. Possible values: 'installed', 'uninstalled'
name	string	(optional) The name of the application, if available.
install_location	string	(optional) The path for the application, if available.

Output json_event for product state change events (event_type = 3) or (event_type = 10)

{
    "event_type" : 3,
    "handler_id" : number,
    "result" : { ... }
}

Key	JSON	Description
event_type	number	Matches the event_type for the registered event. Included as a convenience so the same event handler could be used to process all event types, if desired.
handler_id	number	Matches the handler_id for the registered event. Included as a convenience so the event handler knows the id for the call in the event the handler is registered multiple times.
result	object	The same result object that would be returned from the matching invoke call itself. This includes errors, see remarks section. In the event of an error, monitoring will stop to prevent continuous errors being reported.

Output json_event for driver auto-block event notifications (event_type = 4)

{
    "event_type" : 4,
    "handler_id" : number,
    "path" : string
}

Key	JSON	Description
event_type	number	Matches the event_type for the registered event. Included as a convenience so the same event handler could be used to process all event types, if desired.
handler_id	number	Matches the handler_id for the registered event. Included as a convenience so the event handler knows the id for the call in the event the handler is registered multiple times.
path	string	The mount point path for the drive which the driver had just auto-blocked.

Output json_event for reading file to buffer event (event_type = 5)

{
    "event_type" : 5,
    "handler_id" : number,
    "path" : string,
    "buffer" : string,
    "size" : number,
    "eof" : boolean
}

Key	JSON	Description
event_type	number	Matches the event_type for the registered event. Included as a convenience so the same event handler could be used to process all event types, if desired.
handler_id	number	Matches the handler_id for the registered event. Included as a convenience so the event handler knows the id for the call in the event the handler is registered multiple times.
path	string	The path of the file which is being read.
buffer	string	Numerical pointer address in string form, supplied for convenience - this pointer will match the buffer pointer which was initially configured with this handler callback.
size	number	Size (in bytes) of available data in buffer registered with this handler callback.
eof	boolean	Indicates whether end-of-file has been reached, in which case this would be the last call to this handler for file given by 'path'.

Output json_event for progress change in the method InstallMissingPatches of Windows Update Agent (event_type = 9)

{
    "event_type" : 9,
    "handler_id" : number,
    "code" : number,
    "overall_progress" : number,
    "patches" : [
        {
            "title" : string,
            "progress" : number
        },
        ...
    ]
}

Key	JSON	Description
code	number	The return code from the progress monitor. WAAPI_OK if all works correctly. Otherwise, this is an error code.
event_type	number	Matches the event_type for the registered event. Included as a convenience so the same event handler could be used to process all event types, if desired.
handler_id	number	Matches the handler_id for the registered event. Included as a convenience so the event handler knows the id for the call in the event the handler is registered multiple times.
overall_progress	number	The overall progress of the method.
patches	array	List of input patches of the method.
patches.title	string	The name of the patch.
patches.progress	number	The progress of the patch.

Remarks

If an error occurs during an event which makes product method calls then the error will be passed to the event handler. This means that the 'error' key may appear in the json_event output instead of the 'result' key.