AppCapture Method (CLIENT)

PLB Web Only, 9.9

The AppCapture method allows access to a mobile device's audio, image, and video capture capabilities. The method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A CLIENT object.

return

Optional. A Numeric Variable that returns the success or failure of the method.

type

Required. A Numeric Variable or decimal number that specifies the type of data being captured at the mobile device.

options

Optional. A Character String Variable or literal that specifies a JSON notation string used for the specific {type}.

Flags Affected: OVER, ZERO

Note the following:

1. This method is only used for a Sunbelt PL/B Web Client App using Cordova\PhoneGap operations. See the following link for details on the Cordova plugin:

 

     https://www.npmjs.com/package/cordova-plugin-media-capture

 

2. The ZERO flag is set when the {return} value is zero.

3. The OVER flag is set if the value returned is too large to be stored into the {return} variable.

4. The supported {type} values are defined as follows:

 

Value	Type	Description
0	AppCaptureImage	This method captures an image on a mobile device. The {options} parameter string can be specified using JSON notation to limit the number of images captured in a single capture operation. The default limit is one (1) image.
1	AppCaptureAudio	This method captures audio clips on a mobile device. The {options} parameter string can be specified using JSON notation to limit the number of audio clips captured in a single capture operation. The default image is one (1) audio clip. The {options} parameter string can be specified to set the maximum duration of an audio sound clip given in seconds.
2	AppCaptureVideo	This method captures video clips on a mobile device. The {options} parameter string can be specified to limit the number of video clips captured in a single capture operation. The default limit isone (1) video clip. The {options} parameter string can be specified to set the maximum duration of a video clip given in seconds.

 

5. The {options} parameter controls the behavior of the Cordova plugin when the AppCapture method operation is being performed. The {options} JSON property strings are defined as follows:

AppCaptureImage

String	Description
limit	Limit the number of images captured by the mobile device method operation.
duration	The maximum duration of an audio clip specified in seconds.

 

AppCaptureAudio

String	Description
limit	Limit the number of audio clips captured by the mobile device method operation.
duration	The maximum duration of a audio clip specified in seconds.

 

AppCaptureVideo

String	Description
limit	Limit the number of video clips captured by the mobile device method operation.
duration	The maximum duration of an video clip specified in seconds.

Examples {options}:

 

In this case, the 'AppCapture' is set to allow 2 images to be captured at the mobile device.

 

Client.AppCapture Using *Type=AppCaptureImage,*Options="{#"limit#": 2 }"

 

In this case, the number of audio clips are limited to 2 clips each with a maximum duration of 20 seconds.

 

Client.AppCapture Using *Type=AppCaptureAudio,*Options="{#"limit#": 2, #"duration#": 20 }"

 

6. This method starts an asynchronous operation on the mobile device which returns the result using the 'AppEventDoCapture' CLIENT object event where the event data is returned in ARG1 which contains a JSON notation stream.

 

The event number used in EVENTREG is:

 

AppEventDoCapture EQU 103 //Event number for EVENTREG.

 

The event result is defined as follows:

 

The event data returned by this method can be either an error formatted as a JSON string or an array of file data JSON objects found in the PLB Event ARG1 parameter. JSON objects with JSON fields defined as follows:

 

Field	Description
name	The name of the file, without path information.
localURL	The name of the file as a URL.
fullPath	The full path of the file, including the name.
type	The file's mime type.
lastModifiedDate	The date and time when the file was last modified.
size	The size of the file, in bytes.

Example Event Data returned in ARG1:

 

jData DIM 400

Client CLIENT

.

       EVENTREG Client,AppEventDoCapture,Event103,ARG1=jData

.

       ...

.

. Do AppCapture method event!

. ARG1 data variable 'jData' contains a JSON string that can be processed using

. the PLB XDATA object. A sample of the JSON returned could be:

.

.{[

. {

. "name": "photo_005.jpg",

. "localURL": "cdvfile://localhost/temporary/

. photo_005.jpg",

. "type": "image/jpeg",

. "lastModifiedDate": 499276952,

. "size": 429145,

. "fullPath": "/var/mobile/Containers/Data/

. Application/2B60A96C-C125-4AF1

. -B9CB-42DCEC80E090/tmp/photo_

. 005.jpg"

. }]

.}

.

xData      XDATA

.

Event103

         xData.LoadJson USING jData

.

...Process the JSON data using XDATA.

.

         RETURN

 

The event data can be an error that is reported as a JSON string format as:

 

{ "code": num }

 

Where:

num

One of the pre-defined error codes listed below:

 

Code	Equate	Description
CAPTURE_INTERNAL_ERR	0	The camera or microphone failed to capture an image or sound.
CAPTURE_APPLICATION_BUSY	1	The camera or audio capture application is currently serving another capture request.
CAPTURE_INVALID_ARGUMENT	2	Invalid use of the API (e.g., the value of `limit` is less than one).
CAPTURE_NO_MEDIA_FILES	3	The user exits the camera or audio capture application before capturing anything.
CAPTURE_NOT_SUPPORTED	4	The requested capture operation is not supported.

 

See Also: CLIENT, Client Methods, Method Syntax