How to handle output results

wa_api_invoke invocations return an error code and populate a JSON formatted wa_wchar pointer that is passed as a json_out parameter. The content of this JSON formatted wa_wchar pointer will be dependent on the success/failure error code returned.

Regardless of the success or failure of the wa_api_invoke, you must pass the json_out allocated pointer to wa_api_free to release the allocated memory back to the process.

Successful call

If this functions returns a successful error code the json_out will be populated with the following:

{
    "result" : {
        "method" : number,
        "code" : number,
        "timing" : number,
        "timestamp" : string,
        "result" : object
    }
}

Key	JSON	Description
method	number	The method that generated this result.
code	number	The result code for this method call.
timing	number	The measured time for the method call in milliseconds.
timestamp	string	The timestamp in seconds of when the call was made.
result	object	The method specific results from the invocation specified on the given component. The details of value are defined in detail by each value passed in the component_method parameter to wa_api_invoke.

Failed call

If this functions returns a failure error code the json_out will be populated with error information:

{
    "error": {
        "log_paths": [
            string,
            ...
        ],
        "code" : number,
        "method" : number,
        "errors" : [
            {
                "code" : number,
                "method" : string,
                "called_at" : string,
                "returned_at" : string,
                "message" : string,
                "errors" : array
            },
            ...
        ],
        "error_message" : string,
        "description" : string,
        "define" : string,
        "timing" : number,
        "timestamp" : string
    }
}

Key	JSON	Description
code	number	The value of the error code, which is the same as the wa_int returned by the wa_api_invoke function.
method	number	The method which generated the error if call has a method number.
log_paths	array	Paths to the log files related to the installation process. For the InstallFromFiles method only.
errors	array	The error stack trace. Very useful for OPSWAT engineers for determine the location of the error for debugging.
errors.code	number	The value of the error code at this point in the call stack.
errors.method	string	(optional) The name of the method that returned an error.
errors.called_at	string	(optional) The file and line number for the function that errored.
errors.returned_at	string	(optional) The file and line number where the error was returned.
errors.message	string	(optional) An error message to provide additional details.
errors.errors	array	(optional) Recursively shows the error stack. Has the same properties as the parent errors array.
error_message	string	A human-readable message describing the underlying OS/vendor error that caused this failure, when one was recorded (e.g. a missing library file or a failed native API call). Kept in plaintext outside the encrypted errors stack. Always present on a failed call, but may be an empty string if no native error was recorded for this particular failure.
description	string	The print friendly description of the error code.
define	string	The print friendly error define, e.g. WAAPI_ERROR_GENERAL.
timestamp	string	The timestamp in seconds of when the call was made.
timing	number	The measured time for the method call in milliseconds.

Setup call

This is the expected return from a wa_api_setup call. Each deployed module can return a different configuration object with keys that may only exist for that module. Only the guaranteed keys are shown here.

{
    "errors" : [
        {
            "module" : string,
            "code" : number
        },
        ...
    ],
    "configs" : [
        {
            "timing" : number,
            "module" : string,
            ...
        },
        ...
    ]
}

Key	JSON	Description
errors	array	An array of errors that occurred when trying to load extension modules. This is a reference of what modules are currently not available. This could also contain a standard error stack if a setup error occurred.
errors.module	string	The module where the setup error occurred.
errors.code	number	The error code returned when trying to load the referenced module.
configs	array	An array of objects with the current setup configuration values for each deployed module.
configs.timing	number	The time that it took to perform the call in ms.
configs.module	string	The name of the module who owns this configuration.