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 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

Output json_event for async Invoke events (event_type = 0)

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

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
}

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

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

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

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

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

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

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
}

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
        },
        ...
    ]
}

*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.