AppDirAdd Method (CLIENT)

PLB Web Only, 9.9B

The AppDirAdd method creates a path on a mobile device where the 'Plbwebcli' client is executing. This method starts an asynchronous operation to create the path on the mobile device. When the asynchronous operation is completed on the mobile device, a CLIENT object event named 'AppEventDirAdd' is generated with the event data being returned as a JSON string found in ARG1. 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.

path

Required. A Character String Variable or string literal that specifies the path which is being added to the 'Plbwebcli' App persistent or temporary storage.

flags

Optional. A Numeric Variable or decimal number that specifies a bit mask value that controls the behaviors of this method.

Flags Affected: OVER, ZERO

Note the following:

1. This method uses the Cordova plugin described as follows:
    

https://www.npmjs.com/package/cordova-plugin-file

 

2. The ZERO flag is always set when the {return} value is zero which indicates that the method execution was successful. The ZERO flag is clear if the {return} value is not zero which indicates that the method execution failed.

3. The OVER flag is set if the {return} variable is too small to receive the numeric result.

4. The {path} is required and it specifies the path being added to the 'Plbwebcli' APP persistent\temporary storage. A {path} has one of the following formats:

Persistent Storage Path

"cdvfile://localhost/persistent/{dir}"

 

Temporary Storage Path

"cdvfile://localhost/temporary/{dir}"
 

5. The {options} bitmask value allows for special method behaviors to be used. At this time, there are no specialized {flags} bit mask values defined.

6. The {return} value returns the numeric result of 0 when the method successfully started the asynchronous creation operation. The {return} value is returned as a non-zero value when the method failed to start the asynchronous creation operation. The {return} values are defined as follows:
    

Value	Meaning
0	Asynchronous creation started successfully.
1	Cordova App support not provided by client.
2	Cordova App extended error. See the CLIENT object 'AppExtendedError' to retrieve the extended error information.
11	Invalid path specified.

 

7. This method starts a path asynchronous creation operation on the mobile device. The EVENTREG instruction must be used to register the 'AppEventDirAdd' event. When this event occurs, the path recreation operation result is stored as a JSON string in ARG1.

 

AppEventDirAdd EQU 127

 

If the 'AppDirAdd' method encounters an error on the mobile device, the ARG1 result contains a JSON error string reported by the FileSystem API as follows:

 

{ "code": nnn }

 

Where 'nnn' is an error code from the 'cordova-plugin-file' described as follows:

 

Code Constant	Description
1	NOT_FOUND_ERR
2	SECURITY_ERR
3	ABORT_ERR
4	NOT_READABLE_ERR
5	ENCODING_ERR
6	NO_MODIFICATION_ALLOWED_ERR
7	INVALID_STATE_ERR
8	SYNTAX_ERR
9	INVALID_MODIFICATION_ERR
10	QUOTA_EXCEEDED_ERR
11	TYPE_MISMATCH_ERR
12	PATH_EXISTS_ERR

 

If the 'AppDirAdd' method creation operation executes successfully on the mobile device, the event data is returned in ARG1 as a JSON string that contains fields reported by the FileSystem API as follows:

 

{

  "isFile": false,

  "isDirectory": true,

  "name": "dir",

  "fullPath": "/dir/",

  "filesystem": "<FileSystem: persistent>",

   "nativeURL": "ms-appdata:///local/dir/"

}

 

Where as:

 

 

Field	Description
isFile	Is added path a file. Should always be 'false'.
isDirectory	Is added path a directory. Should always be 'true'.
name	The name of the path (i.e., dir) added.
fullPath	Is added path a directory. Should always be 'true'.
filesystem	This indicates whether the path was created in 'persistent' or 'temporary' storage.
nativeURL	The native URL of the created path for the mobile device OS being used.

Example of CLIENT 'AppDirAdd':

Failure Event Result in ARG1:

{

     "code": 1

}

Successful Event Result in ARG1:

{

     "isFile": false,

     "isDirectory": true,

     "name": "sds",

           "fullPath": "/sds/",

     "filesystem": "<FileSystem: persistent>",

     "nativeURL": "ms-appdata:///local/sds/"

}

See Also: CLIENT, Client Methods, Method Syntax