view release on metacpan or  search on metacpan

README  view on Meta::CPAN

      * extra-fields

      optionally add more fields (columns) to the report by ps, as an
      ARRAY_REF. For example, ['TTY','TIME'].

    It needs that connect_device() to have been called prior to this call

    It returns undef on failure or a hash with these keys on success:

      * raw : contains the raw `ps` output as a string.

      * perl : contains the parsed raw output as a Perl hash with each item
      corresponding to one process, keyed on process command and arguments
      (as reported by ps, verbatim), as a hash keyed on each field (column)
      of the ps output.

      * json : the above data converted into a JSON string.

 pidof($params)

    It returns the PID of the specified command name. The specified command
    name must match the app or command name exactly. Use L/pgrep() if you
    want to match command names with a regular expression>.

    $params is a HASH_REF which should contain:

      * name

      the name of the process. It can be a command name, e.g. audioserver
      or an app name e.g. android.hardware.vibrator-service.example.

    It returns undef on failure or the PID of the matched command on
    success.

 pgrep($params)

    It returns the PIDs matching the specified command or app name (which
    can be an extended regular expression that pgrep understands). The
    returned array will contain zero, one or more hashes with keys pid and
    command. The former key is the pid of the command whose full name (as
    per the process table) will be under the latter key. Unless parameter
    dont-show-command-name was set to 1.

    $params is a HASH_REF which should contain:

      * name

      the name of the process. It can be a command name, e.g. audioserver
      or an app name e.g. android.hardware.vibrator-service.example or part
      of these e.g. audio or hardware or an extended regular expression
      that Android's pgrep understands, e.g. ^com.+google.+mess.

    It returns undef on failure or an ARRAY_REF containing a HASH_REF of
    data for each command matched (under keys pid and command). The
    returned ARRAY_REF can contain 0, 1 or more items depending on what was
    matched.

 geofix($params)

    It fixes the geolocation of the device to the specified coordinates.
    After this, app API calls to get current geolocation will result to
    this position (unless they use their own, roundabout way).

    $params is a HASH_REF which should contain:

      * latitude

      the latitude of the position as a floating point number.

      * longitude

      the longitude of the position as a floating point number.

    It returns 1 on failure or a 0 on success.

 dump_current_location()

    It finds the current GPS location of the device according to ALL the
    GPS providers available.

    It needs that connect_device() to have been called prior to this call

    It takes no parameters.

    On failure, it returns undef.

    On success, it returns a HASH_REF of results. Each item will be keyed
    on provider name (e.g. 'network provider') and will contain the parsed
    output of what each GPS provider returned as a HASH_REF with the
    following keys:

      * provider : the provider name. This is also the key of the item in
      the parent hash.

      * latitude : the latitude as a floating point number (can be negative
      too) or  <na>  if the provider failed to return valid output.

      * longitude : the longitude as a floating point number (can be
      negative too) or	<na >  if the provider failed to return valid
      output.

      * last-location-string : the last location string, or  <na >  if the
      provider failed to return valid output.

 pull_app_apk_from_device($params)

    It pulls the APK file (bytecode) for the app(s) matched by the
    specified package specification, from the device and writes them into
    the specified output directory, locally.

    $params is a HASH_REF which should contain:

      * package

      the package name of the app to pull from the device. package can be a
      string containing the fully qualified package name or a Regexp
      object. The former should be a fully qualified package name, for
      example 'com.android.gallery2'. The latter is a regular expression
      matching the package name and can be created via the qr//modifiers
      construct, for example: qr/gallery\d$/i. The regular expression does
      not need to match exactly one app. Any apps matched they will be

README  view on Meta::CPAN

      Default is 1.

      * force-reload-apps-list

      is a flag to be passed on to "find_installed_apps($params)", if
      needed, and can be set to 1 to erase previous packages information
      and start fresh. Default is 0.

    It returns a HASH_REF of matched packages names (keys) along with
    enquired information (as a
    Android::ElectricSheep::Automator::AppProperties object). At the
    moment, because "close_app($params)" allows closing only a single app,
    this hash will contain only one entry unless we allow closing multiple
    apps (e.g. via a regex which it is already supported) in the future.

SCRIPTS

    For convenience, a few simple scripts are provided:

 electric-sheep-find-installed-apps.pl

    Find all install packages in the connected device. E.g.

        electric-sheep-find-installed-apps.pl --configfile config/myapp.conf --device Pixel_2_API_30_x86_ --output myapps.json
    
        electric-sheep-find-installed-apps.pl --configfile config/myapp.conf --device Pixel_2_API_30_x86_ --output myapps.json --fast

 electric-sheep-open-app.pl

    Open an app by its exact name or a keyword matching it (uniquely):

        electric-sheep-open-app.pl --configfile config/myapp.conf --name com.android.settings
    
        electric-sheep-open-app.pl --configfile config/myapp.conf --keyword 'clock'

    Note that it constructs a regular expression from escaped user input.

 electric-sheep-close-app.pl

    Close an app by its exact name or a keyword matching it (uniquely):

        electric-sheep-close-app.pl --configfile config/myapp.conf --name com.android.settings
    
        electric-sheep-close-app.pl --configfile config/myapp.conf --keyword 'clock'

    Note that it constructs a regular expression from escaped user input.

 electric-sheep-dump-ui.pl

    Dump the current screen UI as XML to STDOUT or to a file:

        electric-sheep-dump-ui.pl --configfile config/myapp.conf --output ui.xml

    Note that it constructs a regular expression from escaped user input.

 electric-sheep-dump-current-location.pl

    Dump the GPS / geo-location position for the device from its various
    providers, if enabled.

        electric-sheep-dump-current-location.pl --configfile config/myapp.conf --output geolocation.json

 electric-sheep-emulator-geofix.pl

    Set the GPS / geo-location position to the specified coordinates.

        electric-sheep-dump-ui.pl --configfile config/myapp.conf --latitude 12.3 --longitude 45.6

 electric-sheep-dump-screen-shot.pl

    Take a screenshot of the device (current screen) and save to a PNG
    file.

        electric-sheep-dump-screen-shot.pl --configfile config/myapp.conf --output screenshot.png

 electric-sheep-dump-screen-video.pl

    Record a video of the device's current screen and save to an MP4 file.

        electric-sheep-dump-screen-video.pl --configfile config/myapp.conf --output video.mp4 --time-limit 30

 electric-sheep-pull-app-apk.pl

    Extract the APK file (java bytecode) for an app installed on the device
    and save locally, perhaps, for disassembly and/or modification and/or
    re-installation.

        electric-sheep-pull-app-apk.pl --package calendar2 --wildcard --output anoutdir --configfile config/myapp.conf --device Pixel_2_API_30_x86_

 electric-sheep-install-app

    Install an APK file onto the device, passing extra installation
    parameters -r (for re-install) and -g (for granting permissions),

        electric-sheep-install-app --apk-filename test.apk -p '-r' -p '-g' --configfile config/myapp.conf --device Pixel_2_API_30_x86_

 electric-sheep-viber-send-message.pl

    Send a message using the Viber app.

        electric-sheep-viber-send-message.pl --message 'hello%sthere' --recipient 'george' --configfile config/myapp.conf --device Pixel_2_API_30_x86_

    This one saves a lot of debugging information to debug which can be
    used to deal with special cases or different versions of Viber:

        electric-sheep-viber-send-message.pl --outbase debug --verbosity 1 --message 'hello%sthere' --recipient 'george' --configfile config/myapp.conf --device Pixel_2_API_30_x86_

TESTING

    The normal tests under the t/ directory, initiated with make test
    command, are quite limited in scope because they do not assume a
    connected device. That is, they do not check any functions which
    require interaction with a connected device.

    The live tests under the xt/live directory, initiated with make
    livetest command, require an Android emulator or real device (the
    latter is not recommended) connected to your desktop computer on which
    you are doing the testing. Note that testing with your smartphone is
    not a good idea, please do not do this, unless it is some phone which
    you do not store important data. It is very easy to get an emulated
    Android device running on any OS.