Skip to content

Latest commit

 

History

History
266 lines (222 loc) · 10.1 KB

how-to-simulate-update-result.md

File metadata and controls

266 lines (222 loc) · 10.1 KB

How To Simulate Update Results

You can use the Simulator Update Handler to simulate the Device Update workflow without actually downloading and installing any files to the actual device for demonstration or testing purposes.

The source code for this Simulator Update Handler can be found at src/extensions/step_handlers/simulator_handler

Register Simulator Update Handler

To register the Simulator Update Handle, use following command:

sudo /usr/bin/AducIotAgent --extension-type updateContentHandler --extension-id <update type> --register-extension <full path to the simulator update handler>

Below is an example of how to register Simulator Update Handler for handle 'microsoft/apt:1' update:

sudo /usr/bin/AducIotAgent --extension-type updateContentHandler --extension-id 'microsoft/apt:1' --register-extension /var/lib/adu/extensions/sources/libmicrosoft_simulator_1.so

Create Simulator Data File

The Simulator Update Handler by default will returns following results:

Function Default Result
Download { "resultCode" : 500 }
Install { "resultCode" : 600 }
Apply { "resultCode" : 700 }
Cancel { "resultCode" : 800 }
IsInstalled { "resultCode" : 900 }

Note: See ADUC_ResultCode enum in aduc_core.h

To override one or more default result above, the desired result can be specified in the Simulator Data file (du-simulator-data.json).

The Simulator Update Handler will search for this file in temp directories specified by following system environment variables (in order):

TMPDIR
TMP
TEMP
TEMPDIR

If none of the above system environment variables are specified, the file must be place in /tmp directory (/tmp/du-simulator-data.json)

You can modify the Simulator Update Handler source code to specify your own search preference. See simulator_handler.cpp

Simulate Data File Schema

{
    "version" : "1.0",
    "download" : {
            "<file name #1>" : {
                "resultCode" : <desired result code>,
                "extendedResultCode" : <desired extended result code>,
                "resultDetails" : "<desired result details string>"
            }
            "<file name #2>" : {
                "resultCode" : <desired result code>,
                "extendedResultCode" : <desired extended result code>,
                "resultDetails" : "<desired result details string>"
            },
            ...
            "<file name #N>" : {
                "resultCode" : <desired result code>,
                "extendedResultCode" : <desired extended result code>,
                "resultDetails" : "<desired result details string>"
            },
            "*" : { // A fall back result for all unmatched file names
                "resultCode" : <desired result code>,
                "extendedResultCode" : <desired extended result code>,
                "resultDetails" : "<desired result details string>"
            }
        },
    "install" : {
        "resultCode" : <desired result code>,
        "extendedResultCode" : <desired extended result code>,
        "resultDetails" : "<desired result details string>"
    },
    "apply" : {
        "resultCode" : <desired result code>,
        "extendedResultCode" : <desired extended result code>,
        "resultDetails" : "<desired result details string>"
    },
    "cancel" : {
        "resultCode" : <desired result code>,
        "extendedResultCode" : <desired extended result code>,
        "resultDetails" : "<desired result details string>"
    },
    "isInstalled" : {
        "<installed criteria string #1>" : {
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        },
        "<installed criteria string #2>" : {
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        },
        ...
        "<installed criteria string #N>" : {
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        },
        "*" : { // A fall back result for all unmatched 'installedCriteria' string
                // IMPORTANT: For Update Manifest version 4.0 or later, only this fall-back result will be return.
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        }
    }
}

Simulate 'Download' Action Result

To simulate the desired result for 'download' action, place the following JSON data in the Simulator Data file:

    "download" : {
        "<file name #1>" : {
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        }
        "<file name #2>" : {
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        },
        ...
        "<file name #N>" : {
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        },
        "*" : { // A fall back result for all unmatched file names
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        }
    }

NOTE: The map keys above must match the file name specified in the Update Manifest that the Device Update Agent received.

The "*" name indicates a fallback value for all un-matched file names.

The following is an example of how to simulate all download succeeded:

    "download" : {
        "*" : {  // A fall back result for all unmatched file names
            "resultCode" : 500,         // ADUC_Result_Download_Success
            "extendedResultCode" : 0,   // No extended result
            "resultDetails" : ""
        }
    }

Simulate 'Install' Action Result

You can specify only one result for the 'install' action. To simulate the desired result for the 'install' action, place the following JSON data in the Simulator Data file:

    "install" : {
        "resultCode" : <desired result code>,
        "extendedResultCode" : <desired extended result code>,
        "resultDetails" : "<desired result details string>"
    }

Following is an example of how to simulate an install error caused by missing file:

    "install" : {
        "resultCode" : 0,                 // ADUC_Result_Failure
        "extendedResultCode" : 805306670, // 0x3000012E - ADUC_ERC_UPDATE_CONTENT_HANDLER_INSTALL_FAILURE_MISSING_PRIMARY_FILE
        "resultDetails" : "Simulating error caused by missing file."
    }

Simulate 'Apply' Action Result

You can specify only one result for the 'apply' action. To simulate the desired result for the 'apply' action, place the following JSON data in the Simulator Data file:

    "apply" : {
        "resultCode" : <desired result code>,
        "extendedResultCode" : <desired extended result code>,
        "resultDetails" : "<desired result details string>"
    }

Simulate 'Cancel' Action Result

You can specify only one result for the 'cancel' action. To simulate the desired result for the 'cancel' action, place the following JSON data in the Simulator Data file:

    "cancel" : {
        "resultCode" : <desired result code>,
        "extendedResultCode" : <desired extended result code>,
        "resultDetails" : "<desired result details string>"
    }

Simulate 'IsInstalled' Check Result

To simulate the desired result for the 'isInstalled' check, place the following JSON data in the Simulator Data file:

    "isInstalled" : {
        "<installed criteria string #1>" : {
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        },
        "<installed criteria string #2>" : {
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        },
        ...
        "<installed criteria string #N>" : {
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        },
        "*" : { // A fall back result for all unmatched 'installedCriteria' string
            "resultCode" : <desired result code>,
            "extendedResultCode" : <desired extended result code>,
            "resultDetails" : "<desired result details string>"
        }
    }

You can specify multiple results for 'isInstalled' check, for example:

    "isInstalled" : {
        "1.0" : {
            "resultCode" : 900,         // ADUC_Result_IsInstalled_Installed
            "extendedResultCode" : 0,
            "resultDetails" : ""
        },

        "1.2" : {
            "resultCode" : 900,         // ADUC_Result_IsInstalled_Installed
            "extendedResultCode" : 0,
            "resultDetails" : ""
        },

        "*" : {                         // Indicates a fall back result for all unmatched 'installedCriteria' string
            "resultCode" : 901,         // ADUC_Result_IsInstalled_NotInstalled
            "extendedResultCode" : 0,
            "resultDetails" : "This update is not installed."
        }
    }

NOTE: The map keys above must match the installedCriteria string specified in the Update Manifest that the Device Update Agent received.