Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge pull request #335 from blackberry/next-BB10

Folding down docs for BB10.0.0.6 release
  • Loading branch information...
commit 0a55264681c4aee3543698468a1b4fc95ebe8151 2 parents ee9145d + 31f2d1b
Jeffrey Heifetz authored
View
47 api/blackberry_app.js
@@ -50,6 +50,7 @@ blackberry.app ={
* @description This function will cause the application to exit.
* @BB50+
* @PB10+
+ * @BB10X
* @RIPPLE
*/
exit: function(){},
@@ -96,14 +97,14 @@ A banner indicator can have an optional numeric value that usually serves as a c
* @param {String} icon The name of the icon to show on the banner. The icon must be a local resource and it's size varies from 10x10 up to 32x32 depending on current theme and device screen size.
* @param {Number} [value] Optional parameter to indicate the number to show on the banner.
*/
- showBannerIndicator:function( icon, value ){}
+ showBannerIndicator:function( icon, value ){},
/**
* @description This function will remove the indicator on the banner.
* @BB50+
* @RIPPLE
*/
- removeBannerIndicator:function(){}
+ removeBannerIndicator: function(){},
/**
* @description The ID of the author's name that is specified in the config.xml file.
@@ -231,18 +232,18 @@ A banner indicator can have an optional numeric value that usually serves as a c
* @PB10+
* @returns {JSON of all the properties}
* {
- * "data":{
- * "author":"John Doe",
- * "name":"My WebWorks Widget",
- * "authorEmail":"jdoe@company.com",
- * "authorURL":"www.company.com",
- * "description":"A sample widget",
- * "license":"Legal stuff goes here",
- * "id":"888",
- * "version":"1.0",
- * "copyright":"Company Ltd.",
- * "licenseURL":"www.company.com/license"
- * }
+ * "data": {
+ * "author":"John Doe",
+ * "name":"My WebWorks Widget",
+ * "authorEmail":"jdoe@company.com",
+ * "authorURL":"www.company.com",
+ * "description":"A sample widget",
+ * "license":"Legal stuff goes here",
+ * "id":"888",
+ * "version":"1.0",
+ * "copyright":"Company Ltd.",
+ * "licenseURL":"www.company.com/license"
+ * }
* }
* @example
* <html>
@@ -314,7 +315,23 @@ A banner indicator can have an optional numeric value that usually serves as a c
*
* </script>
*/
- resume : function(){}
+ resume : function(){},
+
+ /**
+ * @description The <b>swipedown</b> event is triggered when the user swipes down from the top of the application.
+ * @callback {function} yourCallbackFunction The callback function that will be invoked on the swipedown event
+ * @example
+ * &lt;script type="text/javascript"&gt;
+ *
+ * function onSwipedown() {
+ * alert("Swipe down event occured.");
+ * }
+ *
+ * blackberry.event.addEventListener("swipedown", onSwipedown);
+ *
+ * &lt;/script&gt;
+ */
+ swipedown : function(){}
/**#@-*/
};
View
534 api/blackberry_invoke.js
@@ -15,205 +15,387 @@
*/
/**
- * @namespace The Invoke object contains methods that interact with other applications on a BlackBerry PlayBook.
+ * @toc {Invoke} Query Response
+ * @namespace An object generated by a successful invocation query. It contains information about a set of targets that can be invoked with the specified action.
+ * @property {String} action The action that is supported for the specified query. All targets in the targets array property can be invoked using this action.
+ * @property {String} icon The path of the icon file that may be used to represent the action.
+ * @property {String} label The label that can be used to represent the action.
+ * @property {String} [default] The name of the target that should be considered as the default provider for the action. If the attribute is omitted then there is no default.
+ * @property {QueryResponseTarget[]} targets An array of objects containing information about targets that correspond to the action.
+ */
+QueryResponse = {};
+
+/**
+ * @toc {Invoke} Query Response Target
+ * @namespace An object generated as part of the QueryResponse Object. It contains information about a specific target.
+ * @property {String} key An identifier of target that supports the invocation.
+ * @property {String} icon The path of the icon that may be used to represent the target.
+ * @property {String} [splash] The path of the icon that may be used to represent the viewer while loading. This field is present if the type property is VIEWER and is otherwise omitted.
+ * @property {String} label The label that may be used to represent the target.
+ * @property {String} type Indication of the type of the invocation target. Possible values are "APPLICATION", "VIEWER" or "SERVICE".
+ */
+QueryResponseTarget = {};
+
+/**
+ * @beta
+ * @namespace The Invoke object contains methods that interact with other applications.
* <p/>
- * The invoke() method on the invoke object allows you to pass arguments to the target application. </br>The types of arguments can be one of: {@link blackberry.invoke.AddressBookArguments}, {@link blackberry.invoke.BrowserArguments},
+ * On BlackBerry OS 5.0+ and BlackBerry PlayBook 1.0+, the {@link blackberry.invoke.invoke^2} method on the invoke object allows you to pass arguments to the target application. </br>The types of arguments can be one of: {@link blackberry.invoke.AddressBookArguments}, {@link blackberry.invoke.BrowserArguments},
{@link blackberry.invoke.CalendarArguments}, {@link blackberry.invoke.CameraArguments}, {@link blackberry.invoke.JavaArguments}, {@link blackberry.invoke.MapsArguments}, {@link blackberry.invoke.MemoArguments}, {@link blackberry.invoke.MessageArguments},
{@link blackberry.invoke.PhoneArguments}, {@link blackberry.invoke.SearchArguments}, and {@link blackberry.invoke.TaskArguments}.
+ * <p/>
+ * On BlackBerry 10, the {@link blackberry.invoke.invoke} method will take arguments in the form of JavaScript object literal.
* @toc {Invoke} Invoke
* @featureID blackberry.invoke
- * @example
- * &lt;script type="text/javascript"&gt;
- *
- * function startCameraApp() {
- * var args = new blackberry.invoke.CameraArguments();
- * args.view = blackberry.invoke.CameraArguments.VIEW_RECORDER;
- *
- * blackberry.invoke.invoke(blackberry.invoke.APP_CAMERA, args);
- * }
- *
- * startCameraApp();
- * &lt;/script&gt;
*/
blackberry.invoke = {
-
- /**
-
- * @description Invokes another application on the BlackBerry Playbook.
- * @param {Number} appType an integer value representing the type of application to launch. Must be one of the 'APP_*' constants.
- * @param {Object} [args] An arguments object specifying information for the application being invoked.
- * @throws {Exception} If values supplied are not correct.
- * @BB50+
- * @PB10+
+
+ /**
+ * @description Queries device for list of invokable applications.
+ * @param {Object} request An object containing a query to be performed on applications on the device.
+ * @param {String} [request.action] An identifier of the action to be performed by the target. Omitting action implies the query should apply to any action supported for the specified type or that the target should infer the action.
+ * @param {String} [request.type] The MIME type of data to be acted on. It must be provided if the uri attribute is not provided.
+ * @param {String} [request.uri] Used to infer the MIME type of the data. It must be provided if type is not specified.
+ * @param {String[]} request.target_type Mandatory. An array that contains a set of target types that the query should return. Possible target types are "VIEWER" or "APPLICATION".
+ * @param {String} [request.action_type] Indicates the type of actions to be returned. Possible values are "MENU" or "ALL". Menu actions specify addtional icon and label properties.
+ * @param {String} [request.receiver_capabilites] The list of capabilities that must be granted to the target in order for it to be considered a candidate.
+ * @callback {function} onSuccess The callback function that will be triggerd if the query is successful.
+ * @param {QueryResponse[]} onSuccess.response An array which contains the result of the query.
+ * @callback {function} onError The callback function that will be triggered if there was an error processing the query.
+ * @param {String} [onError.error] A String that contains an error message.
+ * @RIPPLE
+ * @BB10X
+ * @example
+ * &lt;script type="text/javascript"&gt;
+ *
+ * function onSuccess(response) {
+ * alert("response: " + JSON.stringify(response, null, 2);
+ * }
+ *
+ * function onError(error) {
+ * alert("error: " + error);
+ * }
+ *
+ * function findAllTargetsThatCanOpenJPEGImages() {
+ * var request = {
+ * "action": "bb.action.OPEN",
+ * "type": "image/jpeg",
+ * "uri": "file://",
+ * "target_type": ["APPLICATION", "VIEWER"],
+ * "action_type": "ALL"
+ * };
+ *
+ * blackberry.invoke.query(request, onSuccess, onError);
+ * }
+ *
+ * function findViewersThatCanViewPDFDocs()
+ * var request = {
+ * "action": "bb.action.VIEW",
+ * "type": "application/pdf",
+ * "uri": "file://",
+ * "target_type": ["VIEWERS"],
+ * "action_type": "ALL"
+ * };
+ *
+ * blackberry.invoke.query(request, onSuccess, onError);
+ * }
+ *
+ * function findApplicationsThatCanOpenAudioFiles()
+ * var request = {
+ * "action": "bb.action.OPEN",
+ * "type": "audio/*",
+ * "uri": "file://",
+ * "target_type": ["APPLICATION"],
+ * "action_type": "ALL"
+ * };
+ *
+ * blackberry.invoke.query(request, onSuccess, onError);
+ * }
+ *
+ * function findAllTargetsThatCanHandleAllVideoFiles()
+ * var request = {
+ * "type": "video/*",
+ * "uri": "file://",
+ * "target_type": ["APPLICATION", "VIEWER"],
+ * "action_type": "ALL"
+ * };
+ *
+ * blackberry.invoke.query(request, onSuccess, onError);
+ * }
+ *
+ * &lt;/script&gt;
+ */
+ query : function(request, onSuccess, onError){},
+
+ /**
+ * @description Invokes another application
+ * @param {Object} request Object literal that specifies what to invoke. None of the fields are required. Refer to the example code for more information.
+ * @param {String} [request.target] The id that identifies the component to invoke. If target is omitted, the invocation framework would perform brokering based on the specified action, type, URI or data to locate an appropriate target to invoke.
+ * @param {String} [request.action] The action to be performed by the target.
+ * @param {String} [request.type] MIME type of data to be acted on. If the MIME type is not specified then the mime type would be inferred from the given URI. If the MIME type cannot be inferred or URI field is empty then invocation will be rejected.
+ * @param {String} [request.uri] URI pointing to invocation data. If no URI is provided then this implies that the invocation data is provided in-band in the data field of the invocation request.
+ * @param {String|Blob} [request.data] Data (String or Blob) to be acted upon encoded based on the specified type.<br/>NOTE: If a String is passed, make sure that it does not contain unicode characters or invocation will fail.
+ * @callback {function} onSuccess Callback function that will be triggered when the invocation is successful. Expected signature: function onSuccess().
+ * @callback {function} onError Callback function that will be triggered when invocation is not successful, or if request's data field cannot be encoded (e.g. when it contains unicode characters). Expected signature: function onError(error).
+ * @callback {String} [onError.error] A String that describes the error.
* @BB10X
- * @RIPPLE
- */
- invoke : function(appType, args){},
-
- /**
- * @default 0
- * @type Number
- * @constant
- * @BB50+
- * @RIPPLE
- * @description Constant used to invoke the Address Book.
- */
+ * @RIPPLE
+ * @example
+ * &lt;script type="text/javascript"&gt;
+ *
+ * function onInvokeSuccess() {
+ * alert("Invocation successful!");
+ * }
+ *
+ * function onInvokeError(error) {
+ * alert("Invocation failed, error: " + error);
+ * }
+ *
+ * function openWebLink() {
+ * // open web link - allows the system to choose an appropriate target that handles http://
+ * blackberry.invoke.invoke({
+ * uri: "http://www.blackberry.com"
+ * }, onInvokeSuccess, onInvokeError);
+ * }
+ *
+ * function openWebLinkInBrowser() {
+ * // open web link in browser
+ * blackberry.invoke.invoke({
+ * target: "sys.browser",
+ * uri: "http://www.blackberry.com"
+ * }, onInvokeSuccess, onInvokeError);
+ * }
+ *
+ * function openMP3File() {
+ * // open mp3 file - allows the system to choose an appropriate target that handles audio/mpeg3
+ * blackberry.invoke.invoke({
+ * type: "audio/mpeg3",
+ * uri: &lt;path to mp3 file&gt;
+ * }, onInvokeSuccess, onInvokeError);
+ * }
+ *
+ * function viewPicture() {
+ * // view picture
+ * blackberry.invoke.invoke({
+ * uri: &lt;path to jpg file&gt;,
+ * action: bb.action.VIEW
+ * }, onInvokeSuccess, onInvokeError);
+ * }
+ *
+ * function openAnotherApp() {
+ * // open another application that understands custom data
+ * blackberry.invoke.invoke({
+ * target: "another.app.that.handles.custom.json.data",
+ * type: "text/plain",
+ * data: "{'myData': 'A string I pass to another app'}"
+ * }, onInvokeSuccess, onInvokeError);
+ * }
+ *
+ * function openAnotherAppWithUnicodeData(unicodeStr) {
+ * // convert unicode string before calling invoke, the receiver app will have to
+ * // call decodeURIComponent(escape(str)) to get the unicode string back
+ * var convertedStr = unescape(encodeURIComponent(unicodeStr));
+ *
+ * // open another application that understands custom data
+ * blackberry.invoke.invoke({
+ * target: "another.app.that.handles.unicode.data",
+ * data: convertedStr
+ * }, onInvokeSuccess, onInvokeError);
+ * }
+ *
+ * &lt;/script&gt;
+ */
+ invoke : function(request, onSuccess, onError){},
+
+ /**
+ * @name blackberry.invoke.invoke^2
+ * @function
+ * @description Invokes another application on the BlackBerry PlayBook or Blackberry OS 5.0+.
+ * @param {Number} appType an integer value representing the type of application to launch. Must be one of the 'APP_*' constants.
+ * @param {Object} [args] An arguments object specifying information for the application being invoked.
+ * @throws {Exception} If values supplied are not correct.
+ * @BB50+
+ * @PB10+
+ * @RIPPLE
+ * @example
+ * &lt;script type="text/javascript"&gt;
+ *
+ * function startCameraApp() {
+ * var args = new blackberry.invoke.CameraArguments();
+ * args.view = blackberry.invoke.CameraArguments.VIEW_RECORDER;
+ *
+ * blackberry.invoke.invoke(blackberry.invoke.APP_CAMERA, args);
+ * }
+ *
+ * startCameraApp();
+ * &lt;/script&gt;
+ */
+ invoke : function(appType, args){},
+
+ /**
+ * @default 0
+ * @type Number
+ * @constant
+ * @BB50+
+ * @RIPPLE
+ * @description Constant used to invoke the Address Book.
+ */
APP_ADDRESSBOOK : 0,
- /**
- * @default 1
- * @type Number
- * @constant
- * @BB50+
- * @RIPPLE
- * @description Constant used to invoke the Bluetooth Configuration.
- */
+ /**
+ * @default 1
+ * @type Number
+ * @constant
+ * @BB50+
+ * @RIPPLE
+ * @description Constant used to invoke the Bluetooth Configuration.
+ */
APP_BLUETOOTH_CONFIG : 1,
- /**
- * @default 2
- * @type Number
- * @constant
- * @BB50+
- * @RIPPLE
- * @description Constant used to invoke the Calculator.
- */
+ /**
+ * @default 2
+ * @type Number
+ * @constant
+ * @BB50+
+ * @RIPPLE
+ * @description Constant used to invoke the Calculator.
+ */
APP_CALCULATOR : 2,
- /**
- * @default 3
- * @type Number
- * @constant
- * @BB50+
- * @RIPPLE
- * @description Calendar.
- */
+ /**
+ * @default 3
+ * @type Number
+ * @constant
+ * @BB50+
+ * @RIPPLE
+ * @description Calendar.
+ */
APP_CALENDAR : 3,
- /**
- * @default 4
- * @type Number
- * @constant
- * @BB50+
- * @PB10+
- * @RIPPLE
- * @description Camera.
- */
+ /**
+ * @default 4
+ * @type Number
+ * @constant
+ * @BB50+
+ * @PB10+
+ * @RIPPLE
+ * @description Camera.
+ */
APP_CAMERA : 4,
- /**
- * @default 5
- * @type Number
- * @constant
- * @BB50+
- * @PB10+
- * @RIPPLE
- * @description Maps.
- */
- APP_MAPS : 5,
- /**
- * @default 6
- * @type Number
- * @constant
- * @BB50+
- * @RIPPLE
- * @description Constant used to invoke the Memopad.
- */
+ /**
+ * @default 5
+ * @type Number
+ * @constant
+ * @BB50+
+ * @PB10+
+ * @RIPPLE
+ * @description Maps.
+ */
+ APP_MAPS : 5,
+ /**
+ * @default 6
+ * @type Number
+ * @constant
+ * @BB50+
+ * @RIPPLE
+ * @description Constant used to invoke the Memopad.
+ */
APP_MEMOPAD : 6,
- /**
- * @default 7
- * @type Number
- * @constant
- * @BB50+
- * @RIPPLE
- * @description Constant used to invoke the Messages Application.
- */
+ /**
+ * @default 7
+ * @type Number
+ * @constant
+ * @BB50+
+ * @RIPPLE
+ * @description Constant used to invoke the Messages Application.
+ */
APP_MESSAGES : 7,
- /**
- * @default 8
- * @type Number
- * @constant
- * @BB50+
- * @RIPPLE
- * @description Constant used to invoke the Phone.
- */
+ /**
+ * @default 8
+ * @type Number
+ * @constant
+ * @BB50+
+ * @RIPPLE
+ * @description Constant used to invoke the Phone.
+ */
APP_PHONE : 8,
- /**
- * @default 9
- * @type Number
- * @constant
- * @BB50+
- * @RIPPLE
- * @description Constant used to invoke the Search.
- */
+ /**
+ * @default 9
+ * @type Number
+ * @constant
+ * @BB50+
+ * @RIPPLE
+ * @description Constant used to invoke the Search.
+ */
APP_SEARCH : 9,
- /**
- * @default 10
- * @type Number
- * @constant
- * @BB50+
- * @RIPPLE
- * @description Constant used to invoke the Tasks.
- */
- APP_TASKS : 10,
- /**
- * @default 11
- * @type Number
- * @constant
- * @BB50+
- * @PB10+
- * @BB10X
- * @RIPPLE
- * @description Browser.
- */
- APP_BROWSER : 11,
- /**
- * @default 12
- * @type Number
- * @constant
- * @BB50+
- * @RIPPLE
- * @description Constant used to invoke a Java Application.
- */
- APP_JAVA : 12,
- /**
- * @default 13
- * @type Number
- * @constant
- * @PB10+
- * @RIPPLE
- * @description Music Application.
- */
- APP_MUSIC : 13,
- /**
- * @default 14
- * @type Number
- * @constant
- * @PB10+
- * @RIPPLE
- * @description Photos Application.
- */
- APP_PHOTOS : 14,
- /**
- * @default 15
- * @type Number
- * @constant
- * @PB10+
- * @RIPPLE
- * @description Videos Application.
- */
- APP_VIDEOS : 15,
- /**
- * @default 16
- * @type Number
- * @constant
- * @PB10+
- * @RIPPLE
- * @description App World Application.
- */
- APP_APPWORLD : 16
-}
+ /**
+ * @default 10
+ * @type Number
+ * @constant
+ * @BB50+
+ * @RIPPLE
+ * @description Constant used to invoke the Tasks.
+ */
+ APP_TASKS : 10,
+ /**
+ * @default 11
+ * @type Number
+ * @constant
+ * @BB50+
+ * @PB10+
+ * @RIPPLE
+ * @description Browser.
+ */
+ APP_BROWSER : 11,
+ /**
+ * @default 12
+ * @type Number
+ * @constant
+ * @BB50+
+ * @RIPPLE
+ * @description Constant used to invoke a Java Application.
+ */
+ APP_JAVA : 12,
+ /**
+ * @default 13
+ * @type Number
+ * @constant
+ * @PB10+
+ * @RIPPLE
+ * @description Music Application.
+ */
+ APP_MUSIC : 13,
+ /**
+ * @default 14
+ * @type Number
+ * @constant
+ * @PB10+
+ * @RIPPLE
+ * @description Photos Application.
+ */
+ APP_PHOTOS : 14,
+ /**
+ * @default 15
+ * @type Number
+ * @constant
+ * @PB10+
+ * @RIPPLE
+ * @description Videos Application.
+ */
+ APP_VIDEOS : 15,
+ /**
+ * @default 16
+ * @type Number
+ * @constant
+ * @PB10+
+ * @RIPPLE
+ * @description App World Application.
+ */
+ APP_APPWORLD : 16
+};
+
View
1  api/blackberry_invoke_BrowserArguments.js
@@ -22,7 +22,6 @@
* @toc {Invoke} BrowserArguments
* @BB50+
* @PB10+
-* @BB10X
* @RIPPLE
* @class The BrowserArguments object is an instance object, and is used as a parameter to the invoke() method when invoking the BlackBerry Browser application.
* @featureID blackberry.invoke
View
70 api/blackberry_invoked.js
@@ -0,0 +1,70 @@
+/*
+* Copyright 2011-2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * @beta
+ * @namespace The Invoked object allows the application to be invoked by other applications.
+ * @toc {Invoke} Invoked
+ * @featureID blackberry.invoked
+ */
+blackberry.invoked = {
+
+ /**#@+
+ * @noSignature
+ * @event
+ * @BB10X
+ * @description This event is fired by the system. If you want to listen to the event you can do so using the {@link blackberry.event.addEventListener} function and remove the listener using the {@link blackberry.event.removeEventListener} function. <br/>
+ */
+
+ /**
+ * @description The <b>invoked</b> event is triggered by the system when the application is invoked by another application.
+ * @callback {function} yourCallbackFunction The callback function that will be invoked on the invoked event
+ * @callback {JSON} yourCallbackFunction.info An object the pertinent information
+ * @callback {String} yourCallbackFunction.info.source [optional] Identifier of invocation target (as stated in its BAR manifest) to which the receiver can send results. Omitting the source attribute implies that the sender does NOT support results.
+ * @callback {String} yourCallbackFunction.info.target [optional] Identifier of target (as stated in its BAR manifest) to which invocation should be delivered. If the target is supplied then brokering is bypassed and attempt is made to invoke the specified target.
+ * @callback {String} yourCallbackFunction.info.action [optional] Identifier of action to be performed by target. Omitting action implies brokering should apply to any action supported for the specified type or that the target should infer the action.
+ * @callback {String} yourCallbackFunction.info.type [optional] MIME type of data to be acted on. If the mime type is not specified then Invocation Framework would attempt to infer the mime type from the given URI. If the mime type can not be inferred or URI field is empty then invocation will be rejected.
+ * @callback {String} yourCallbackFunction.info.uri [optional] URI pointing to invocation data. If no URI is provided then this implies the data://local URI indicating that the invocation data is provided in-band in the data field of the invocation message.
+ * @callback {String} yourCallbackFunction.info.data [optional] Data passed to target. Omitting the data implies that the action-type are sufficient to carry out the invocation. Note that target invocation allows passing arbitrary binary data that will be encoded into Base64 encoded string.
+ * @example
+ * &lt;script type="text/javascript"&gt;
+ *
+ * function onInvoked(onInvokedInfo) {
+ * if(onInvokedInfo.source) {
+ * console.log("Source: " + onInvokedInfo.source);
+ * }
+ * if(onInvokedInfo.target) {
+ * console.log("Target(me): " + onInvokedInfo.target);
+ * }
+ * if(onInvokedInfo.action) {
+ * console.log("Action: " + onInvokedInfo.action);
+ * }
+ * if(onInvokedInfo.data) {
+ * console.log("Data: " + onInvokedInfo.data);
+ * //the data comes in as a base64 string you can convert it using atob(...)
+ * //note that atob will fail if you are being passed unicode strings
+ * console.log("Data: " + atob(onInvokedInfo.data));
+ * }
+ * }
+ *
+ * blackberry.event.addEventListener("invoked", onInvoked);
+ *
+ * &lt;/script&gt;
+ */
+ invoked : function(){},
+
+ /**#@-*/
+}
View
112 api/blackberry_io.js
@@ -0,0 +1,112 @@
+/*
+* Copyright 2010-2011 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * @namespace The IO object provides the functionality to access un-sandboxed file system and other related attributes.
+ * @toc {IO} IO
+ * @featureID blackberry.io
+ * @example
+ * &lt;script type="text/javascript"&gt;
+ *
+ * function readFile() {
+ * // un-sandbox file system to access shared folder
+ * blackberry.io.sandbox = false;
+ *
+ * window.requestFileSystem = window.requestFileSystem || window.webkitRequestFileSystem;
+ *
+ * window.requestFileSystem(window.TEMPORARY, 1024 * 1024,
+ * function (fs) {
+ * // in order to access the shared folder,
+ * // config.xml must declare the "access_shared" permission
+ * // reference file by absolute path since file system is un-sandboxed
+ * fs.root.getFile(blackberry.io.sharedFolder + '/documents/log.txt', {},
+ * function (fileEntry) {
+ * fileEntry.file(function (file) {
+ * var reader = new FileReader();
+ *
+ * reader.onloadend = function (e) {
+ * var txtArea = document.createElement('textarea');
+ * txtArea.value = this.result;
+ * document.body.appendChild(txtArea);
+ * };
+ *
+ * reader.readAsText(file);
+ * }, errorHandler);
+ * }, errorHandler);
+ * });
+ * }
+ *
+ * function errorHandler(e) {
+ * var msg = '';
+ *
+ * switch (e.code) {
+ * case FileError.QUOTA_EXCEEDED_ERR:
+ * msg = 'QUOTA_EXCEEDED_ERR';
+ * break;
+ * case FileError.NOT_FOUND_ERR:
+ * msg = 'NOT_FOUND_ERR';
+ * break;
+ * case FileError.SECURITY_ERR:
+ * msg = 'SECURITY_ERR';
+ * break;
+ * case FileError.INVALID_MODIFICATION_ERR:
+ * msg = 'INVALID_MODIFICATION_ERR';
+ * break;
+ * case FileError.INVALID_STATE_ERR:
+ * msg = 'INVALID_STATE_ERR';
+ * break;
+ * default:
+ * msg = 'Unknown Error';
+ * break;
+ * };
+ *
+ * console.log('Error: ' + msg);
+ * }
+ * &lt;/script&gt;
+ */
+blackberry.io = {
+
+ /**
+ * @description Whether the file system is sandboxed. It is set to true by default.<br/>When sandbox is set to false, you must use absolute path to reference a file or directory, you can use {@link blackberry.io.sharedFolder}, {@link blackberry.io.home} or {@link blackberry.io.SDCard} to construct file paths.
+ * @type Boolean
+ * @BB10X
+ */
+ sandbox : true,
+
+ /**
+ * @description The full path of the application data folder
+ * @type String
+ * @readOnly
+ * @BB10X
+ */
+ home : "",
+
+ /**
+ * @description The full path of the shared folder. In order to access this folder, you must specify the <code>access_shared</code> permission in config.xml
+ * @type String
+ * @readOnly
+ * @BB10X
+ */
+ sharedFolder : "",
+
+ /**
+ * @description The full path of the SD card folder
+ * @type String
+ * @readOnly
+ * @BB10X
+ */
+ SDCard : ""
+}
View
100 api/blackberry_io_filetransfer.js
@@ -0,0 +1,100 @@
+/*
+* Copyright 2010-2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * @toc {IO} FileTransfer
+ * @featureID blackberry.io.filetransfer
+ * @namespace The FileTransfer object contains functions for uploading and downloading files to/from a remote server.
+ */
+blackberry.io.filetransfer = {
+
+ /**
+ * @function
+ * @description Uploads a file from the device to a remote server. <br/>
+ * The function is an asynchronous call and will not block execution.
+ * @param {String} filePath Full path of the file on the device.
+ * @param {String} server URL of the remote server that will receive the file.
+ * @callback {function} successCallback Callback function that will be invoked if the file upload is successful.
+ * @callback {Object} successCallback.info Object containing information about the upload.
+ * @callback {Number} successCallback.info.bytesSent Total number of bytes sent to the server.
+ * @callback {Number} successCallback.info.responseCode HTTP response code returned by the server.
+ * @callback {String} successCallback.info.response Response returned by the server.
+ * @callback {function} errorCallback Callback function that will be invoked if the file upload fails.
+ * @callback {Object} errorCallback.info Object containing information about the failed upload request.
+ * @callback {Number} errorCallback.info.code Error code indicating the type of error that occurred.
+ * @callback {String} errorCallback.info.source Path of the original file.
+ * @callback {String} errorCallback.info.target URL of the remote server.
+ * @param {Object} [options] Optional Object literal that allows the user to customize the file key, file name, MIME type, parameters, and chunked mode of the upload request. It is not required to provide all parameters, and these do not have to be specified in any particular order.
+ * @param {String} [options.fileKey] Name of the form element. If not set, this defaults to "file".
+ * @param {String} [options.fileName] Name that the file will be saved as on the remote server. If not set, this defaults to "image.jpg".
+ * @param {String} [options.mimeType] MIME type of the data being uploaded. If not set, this defaults to "image/jpeg".
+ * @param {Object} [options.params] A set of optional key/value pairs to be passed along in the HTTP request.
+ * @param {Boolean} [options.chunkedMode] Specifies whether the data should be uploaded in chunked streaming mode. If not set, this defaults to true.
+ * @BB10X
+ * @example
+ * &lt;script type="text/javascript"&gt;
+ *
+ * function uploadSuccess(result) {
+ * alert("Upload was successful. Bytes sent = " + result.bytesSent + ", Response code = " + result.responseCode + ", Response = " + result.response);
+ * }
+ *
+ * function uploadError(result) {
+ * alert("Upload failed. Error code = " + result.code + ", Source = " + result.source + ", Target = " + result.target);
+ * }
+ *
+ * function fileUpload() {
+ * try {
+ * var parameters = { app : "webworks" };
+ * var options = { fileKey : "file", fileName : "blackberry.jpg", mimeType : "image/jpeg", params : parameters, chunkedMode : true };
+ * blackberry.io.filetransfer.upload("/accounts/1000/shared/camera/image_123.jpg", "http://www.blackberry.com/upload", uploadSuccess, uploadError, options);
+ * } catch(e) {
+ * alert("Exception in fileUpload: " + e);
+ * }
+ * }
+ *
+ * &lt;/script&gt;
+ */
+ upload : function(filePath, server, successCallback, errorCallback, options){},
+
+ /**#@-*/
+
+ /**
+ * @type Number
+ * @constant
+ * @default 1
+ * @description The file was not found.
+ * @BB10X
+ */
+ FILE_NOT_FOUND_ERR : 1,
+
+ /**
+ * @type Number
+ * @constant
+ * @default 2
+ * @description The URL of the server was invalid.
+ * @BB10X
+ */
+ INVALID_URL_ERR : 2,
+
+ /**
+ * @type Number
+ * @constant
+ * @default 3
+ * @description The upload failed due to a connection error.
+ * @BB10X
+ */
+ CONNECTION_ERR : 3,
+}
View
89 api/blackberry_push_PushPayload.js
@@ -0,0 +1,89 @@
+/*
+* Copyright 2010-2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+* @toc {Push} PushPayload
+* @class The <code>PushPayload</code> object provides access to the payload that has arrived as the result of a push.
+* This object <b>cannot</b> be created by the new keyword. It is generated only by the system on receipt of a push notification.
+* <br/><br/>
+* For a great sample app that demonstrates how to use the push APIs, see <a href="https://github.com/blackberry/WebWorks-Samples/tree/master/pushCapture">Push Capture</a>.
+* @BB10X
+* @featureID blackberry.push
+*/
+blackberry.push.PushPayload = {};
+
+/**
+* <p>
+* Sends an acknowledgement to the PPG indicating whether a push should be accepted or rejected. It is up to the application to determine
+* whether to accept or reject a push message based on it own business rules. It is strongly recommended to accept or reject the push
+* message as soon as possible otherwise the push message will automatically be considered rejected.
+* </p>
+* <p>
+* Use the <code>isAckRequired</code> property to determine whether or not calling <code>acknowledge</code> is required.
+* </p>
+* @param {Boolean} shouldAcceptPush True if the push should be accepted; false if the push should be rejected
+* @BB10X
+* @example
+* if (pushPayload.isAcknowledgeRequired) {
+* // Accept push
+* pushPayload.acknowledge(true);
+*
+* // To reject the push, you would call:
+* // pushPayload.acknowledge(false);
+* }
+*/
+blackberry.push.PushPayload.prototype.acknowledge = function(shouldAcceptPush) { };
+
+/**
+* The ID of a push.
+* @type String
+* @readOnly
+* @BB10X
+*/
+blackberry.push.PushPayload.prototype.id = undefined;
+
+/**
+* The headers of a push in string header name-header value pairs.
+* @type Object
+* @readOnly
+* @BB10X
+* @example
+* // To access a header value with the name "header-name":
+* var headerValue = pushPayload.headers["header-name"];
+*/
+blackberry.push.PushPayload.prototype.headers = undefined;
+
+/**
+* The data (payload) of a push.
+* @type Blob
+* @readOnly
+* @BB10X
+* @example
+* // See the extractPushPayload function in the PushService
+* // class for an example of how to convert the data
+* // property from a Blob to a string (for plain text)
+* // and to an ArrayBuffer (for binary)
+*/
+blackberry.push.PushPayload.prototype.data = undefined;
+
+/**
+* Indicates whether or not a developer must acknowledge the receipt of a push.
+* True if an acknowledgement is required for the push; false otherwise.
+* @type Boolean
+* @readOnly
+* @BB10X
+*/
+blackberry.push.PushPayload.prototype.isAcknowledgeRequired = undefined;
View
591 api/blackberry_push_PushService.js
@@ -0,0 +1,591 @@
+/*
+* Copyright 2010-2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+* @namespace The <code>PushService</code> object allows you to leverage the BlackBerry push architecture to receive push data in your application.
+* The push solution includes a push-enabled application on a BlackBerry device and a content provider's server-side application (also known as the Push Initiator).
+* The Push Initiator can deliver up to 8 kB of content (images, text, etc.) and headers (metadata name-value pairs) using a Push Proxy Gateway (PPG).
+* <br/><br/>
+* Two PPGs are available: the public/BlackBerry Internet Service (BIS) PPG and the enterprise/Blackberry Enterprise Server (BES) PPG. The <code>PushService</code>
+* object will allow your application to receive push messages sent through either of these PPGs.
+* <br/><br/>
+* To work with a <code>PushService</code> object, you must first call the static <code>create</code> function. On a successful create, you will then be able
+* to perform operations using the <code>PushService</code> object you receive in the success callback.
+* <br/><br/>
+* For a great sample app that demonstrates how to use the push APIs, see <a href="https://github.com/blackberry/WebWorks-Samples/tree/master/pushCapture">Push Capture</a>.
+* @toc {Push} PushService
+* @class The <code>PushService</code> object allows you to perform all the push-related operations.
+* @featureID blackberry.push
+*/
+blackberry.push.PushService = {};
+
+/**
+* <p>
+* Creates a <code>PushService</code> object. The <code>PushService</code> object will only be available if the <code>successCallback</code> function is called.
+* It will not be available if the <code>failCallback</code> function is called instead.
+* </p>
+* @param {Object} options Object literal that allows the user to specify various options.
+* @param {String} options.invokeTargetId Your application's unique invoke target ID, as set in your config.xml, related to when a new push notification
+* is received and the application needs to be invoked.
+* @param {String} [options.appId] The provider application ID. If writing a consumer application, this corresponds to the application ID you received after registering
+* to use the public/BIS PPG push service. If writing an enterprise application, you have the choice of not specifying <code>appId</code>
+* (in which case a unique one will be generated for you under the covers) or specifying a unique value of your choosing (this second option is useful if you plan
+* to subscribe with the Push Initiator in your application).
+* @param {String} [options.ppgUrl] The PPG URL to register with. If writing a consumer application, you will be provided with this URL after registering to
+* use the public/BIS PPG push service. The URL will point to either the eval or the production environment (for eval, https://cp{cpid}.pushapi.eval.blackberry.com;
+* for production, https://cp{cpid}.pushapi.na.blackberry.com where {cpid} is replaced with your content provider ID). If writing an enterprise application,
+* no <code>ppgUrl</code> value should be specified.
+* @callback {function} successCallback The callback that is invoked when the <code>create</code> operation is successful.
+* @callback {PushService} successCallback.pushService The <code>PushService</code> object that can be used on a successful <code>create</code> operation.
+* @callback {function} failCallback The callback that is invoked when the <code>create</code> operation has failed.
+* @callback {Number} failCallback.result The reason for the failure. See the constants provided to see what result codes apply for this operation.
+* @callback {function} simChangeCallback The callback that is invoked when a SIM card change has occurred. This callback only applies on a successful create.
+* When a SIM card change occurs, the channel will automatically be destroyed since this scenario may indicate the possibility of a new user using the device.
+* Care should be taken by the application to handle this situation as well. For example, the application may wish to re-authenticate the user with the Push Initiator
+* (if your Push Initiator implementation supports subscription) and then re-create the channel using <code>createChannel</code>.
+* @throws {String} An exception is thrown if <code>create</code> is called more than once with different values for <code>options.invokeTargetId</code> and/or
+* <code>options.appId</code>.
+* @BB10X
+* @static
+* @example
+* // For a consumer application (using the public/BIS PPG)
+* var ops = { invokeTargetId : 'com.sample.pushtest.target',
+* appId : 'appId1',
+* ppgUrl : 'https://cp123.pushapi.na.blackberry.com' };
+*
+* // For an enterprise application (using the enterprise/BES PPG)
+* // var ops = { invokeTargetId : 'com.sample.pushtest.target' };
+*
+* // Or, for an enterprise application with an application ID:
+* // var ops = { invokeTargetId : 'com.sample.pushtest.target',
+* // appId : 'appId1' };
+*
+* try {
+* blackberry.push.PushService.create(ops, successCallback,
+* failCallback, simChangeCallback);
+* } catch (err) {
+* console.log("Create was called more than once with different "
+* + "values for options.invokeTargetId or options.appId.");
+* console.log(err);
+* }
+*
+* function successCallback(pushService) {
+* // The create operation was a success
+* // Use the pushService object to now perform a
+* // launchApplicationOnPush, createChannel, destroyChannel, etc.
+* pushService.createChannel(createChannelCallback);
+* }
+*
+* function failCallback(result) {
+* // The create operation failed
+* // You should compare the result code against the error
+* // constants in this PushService class that apply for
+* // create and take the recommended action for that constant
+* if (result == blackberry.push.PushService.INTERNAL_ERROR) {
+* // Retry the create up to a certain number of attempts
+* // and then display an error to the user
+* }
+* // ... handle the other possible error constants
+* // from the PushService class
+* }
+*
+* function simChangeCallback() {
+* // The SIM card was changed and the channel has been
+* // destroyed since a new user might be using the device.
+* // It is recommended that the user of this application be
+* // re-authenticated with the Push Initiator (if your
+* // Push Initiator implementation supports subscription)
+* // followed by a call to createChannel.
+* }
+*/
+blackberry.push.PushService.create = function(options, successCallback, failCallback, simChangeCallback) { };
+
+/**
+* <p>
+* Creates a push channel for the given application. Once a channel is created, it will survive application restarts and therefore
+* does not necessarily need to be called on every application start up.
+* </p>
+* <p>
+* However, for a consumer application, since it is possible for the public/BIS PPG to destroy a channel under certain circumstances it
+* may be advisable to periodicially re-create the channel (e.g. once a month).
+* </p>
+* <p>
+* A successful <code>create</code> must have been done before calling this function.
+* </p>
+* <p>
+* This function should be called in order for an application to be able to start receiving pushes. If a <code>destroyChannel</code> call
+* is then made, no pushes will be able to be received until a <code>createChannel</code> call is made again.
+* </p>
+* @callback {function} createChannelCallback The callback that is invoked when the result of the create channel operation is received.
+* @callback {Number} createChannelCallback.result The create channel operation result. See the constants provided to see what result codes apply for this operation.
+* @callback {String} createChannelCallback.token On a successful create channel operation (result of <code>SUCCESS</code>), a token is returned. This token must then be communicated
+* back to the content provider's server-side application (the Push Initiator). This token is then used by the content provider as the means to address the application on the device
+* when initiating a push request to the PPG.
+* @BB10X
+* @example
+* pushService.createChannel(createChannelCallback);
+*
+* function createChannelCallback(result, token) {
+* if (result == blackberry.push.PushService.SUCCESS) {
+* // Success, so a token should be available
+* // Subscribe with the Push Initiator using this
+* // token (if your Push Initiator supports subscription)
+* // so that you can push to this user using this token
+* } else if (result ==
+* blackberry.push.PushService.INTERNAL_ERROR) {
+* // Retry the createChannel up to a certain number of
+* // attempts and then display an error to the user
+* } else if ... (handle all the error codes possible for
+* createChannel - see the error constants
+* in this PushService class)
+* }
+*/
+blackberry.push.PushService.prototype.createChannel = function(createChannelCallback) { };
+
+/**
+* <p>
+* Destroys a push channel for the given application.
+* </p>
+* <p>
+* A successful <code>create</code> must have been done and a channel must have been created using <code>createChannel</code> before calling this function.
+* </p>
+* <p>
+* This function should be called in order for an application to stop receiving pushes.
+* No pushes will be received after a <code>destroyChannel</code> call until a <code>createChannel</code> call is made after that.
+* </p>
+* @callback {function} destroyChannelCallback The callback that is invoked when the result of the destroy channel operation is received.
+* @callback {Number} destroyChannelCallback.result The destroy channel operation result. See the constants provided to see what result codes apply for this operation.
+* @BB10X
+* @example
+* pushService.destroyChannel(destroyChannelCallback);
+*
+* function destroyChannelCallback(result) {
+* if (result == blackberry.push.PushService.INTERNAL_ERROR) {
+* // Retry the destroyChannel up to a certain number
+* // of attempts and then display an error to the user
+* } else if ... (handle all the error codes possible for
+* destroyChannel - see the error constants
+* in this PushService class)
+* }
+*/
+blackberry.push.PushService.prototype.destroyChannel = function(destroyChannelCallback) { };
+
+/**
+* <p>
+* Extracts the <code>PushPayload</code> from the passed in invoke request.
+* </p>
+* <p>
+* A successful <code>create</code> must have been done before calling this function.
+* </p>
+* @param {JSON} invokeRequest The invoke request to parse.
+* @returns {PushPayload} Returns the parsed out <code>PushPayload</code> object.
+* @throws {String} An exception is thrown if the <code>invokeRequest</code> passed in is not valid and cannot be parsed.
+* @BB10X
+* @example
+* try {
+* var pushPayload =
+* pushService.extractPushPayload(invokeRequest);
+*
+* // pushPayload.data is of type Blob
+* // If the Blob is known to contain text,
+* // then do something like this:
+* blobToText(pushPayload.data, "UTF-8", textConversionCallback);
+*
+* // If the Blob is known to contain binary, then do
+* // something like this to get an ArrayBuffer:
+* // blobToArrayBuffer(pushPayload.data,
+* // binaryConversionCallback);
+* } catch (err) {
+* console.log("Was unable to parse the invoke request.");
+* console.log(err);
+* }
+*
+* function blobToText(blob, encoding, callback) {
+* var reader = new FileReader();
+*
+* reader.onload = function(evt) {
+* // No errors, get the result and call the callback
+* callback(evt.target.result);
+* };
+*
+* reader.onerror = function(evt) {
+* console.log("Error converting Blob to string: " +
+* evt.target.error);
+* };
+*
+* reader.readAsText(blob, encoding);
+* }
+*
+* function textConversionCallback(str) {
+* console.log("Data received: " + str);
+* }
+*
+* function blobToArrayBuffer(blob, callback) {
+* var reader = new FileReader();
+*
+* reader.onload = function(evt) {
+* // No errors, get the result and call the callback
+* callback(evt.target.result);
+* };
+*
+* reader.onerror = function(evt) {
+* console.log("Error converting Blob to ArrayBuffer: " +
+* evt.target.error);
+* };
+*
+* reader.readAsArrayBuffer(blob);
+* }
+*
+* function binaryConversionCallback(arrayBuffer) {
+* // Process the ArrayBuffer containing
+* // binary content as needed
+* }
+*/
+blackberry.push.PushService.prototype.extractPushPayload = function(invokeRequest) { };
+
+/**
+* <p>
+* Indicates whether or not the application should be launched (started up) if it is currently closed (not running)
+* and a new push is received. The default system behaviour is to not launch the application.
+* </p>
+* <p>
+* A successful <code>create</code> must have been done before calling this function.
+* </p>
+* <p>
+* It is important to note that the <code>shouldLaunch</code> flag is only persisted once a channel has been created using the <code>createChannel</code> function.
+* In other words, once the create channel function has been called the state of the <code>shouldLaunch</code> flag is persisted between application and device restarts.
+* The flag is only removed once the destroy channel function is called. This flag can be toggled at any time using this function but, again, its value
+* is only persisted once the create channel function has been called at least once for the lifetime of the application.
+* </p>
+* @param {Boolean} shouldLaunch True if the application should be launched on a new push; false if the application should not be launched when a new push comes in
+* @callback {function} launchApplicationCallback The callback that is invoked when the result of the launch application operation is received.
+* @callback {Number} launchApplicationCallback.result The launch application operation result. See the constants provided to see what result codes apply for this operation.
+* @BB10X
+* @example
+* // Indicate that you want the application to launch on a new push
+* pushService.launchApplicationOnPush(true,
+* launchApplicationCallback);
+*
+* // To indicate that you do not want to launch on a new push,
+* // either leave the default behaviour or call:
+* // pushService.launchApplicationOnPush(false,
+* // launchApplicationCallback);
+*
+* function launchApplicationOnPush(result) {
+* if (result == blackberry.push.PushService.INTERNAL_ERROR) {
+* // Retry the launchApplicationOnPush up to a certain number
+* // of attempts and then display an error to the user
+* } else if ... (handle all the error codes possible for
+* launchApplicationOnPush - see the error
+* constants in this PushService class)
+* }
+*/
+blackberry.push.PushService.prototype.launchApplicationOnPush = function(shouldLaunch, launchApplicationCallback) { };
+
+/**
+* Result code for an operation that was performed successfully.
+* <br/><br/>
+* Operations this code applies to: create, createChannel, destroyChannel, launchApplicationOnPush
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.SUCCESS : 0;
+
+/**
+* Result error code for an internal error.
+* <br/><br/>
+* Operations this error can occur on: create, createChannel, destroyChannel, launchApplicationOnPush
+* <br/><br/>
+* Recommended action: Retrying the operation might correct the issue.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.INTERNAL_ERROR : 500;
+
+/**
+* Result error code for an invalid device PIN as determined by the PPG.
+* <br/><br/>
+* Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: Retrying the operation might correct the issue. The PIN is obtained under the covers
+* by the public/BIS PPG. It very rarely has issues obtaining the device PIN, so a retry might fix this.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.INVALID_DEVICE_PIN : 10001;
+
+/**
+* Result error code for an invalid provider application ID. Either an invalid one was specified or none at all.
+* <br/><br/>
+* Operations this error can occur on: create, createChannel, destroyChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: Specifying a valid value for appId programmatically and retrying might correct the issue.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.INVALID_PROVIDER_APPLICATION_ID : 10002;
+
+/**
+* Result error code when attempting to call destroy channel again after a successful destroy channel has already been done.
+* <br/><br/>
+* Operations this error can occur on: destroyChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: Most applications will typically want to just ignore this error code when it comes back.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.CHANNEL_ALREADY_DESTROYED : 10004;
+
+/**
+* Result error code when attempting to call destroy channel after a content provider has already done the destroying of the channel
+* by unregistering a user.
+* <br/><br/>
+* Operations this error can occur on: destroyChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: Most applications will typically want to just ignore this error code when it comes back.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.CHANNEL_ALREADY_DESTROYED_BY_PROVIDER : 10005;
+
+/**
+* This result error code should not typically be encountered.
+* It would only occur if a create or destroy channel operation internally causes the state of a subscriber on the PPG to be in an invalid state.
+* <br/><br/>
+* Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: If this error occurs, it should be logged and reported to the RIM support team.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.INVALID_PPG_SUBSCRIBER_STATE : 10006;
+
+/**
+* Result error code for when a destroy channel operation fails because the subscriber could not be found on the PPG's end.
+* <br/><br/>
+* Operations this error can occur on: destroyChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: This error can most likely be ignored since if the subscriber could not be found on the PPG's end, then
+* destroying the channel will have no effect anyway (it is as if they were never registered with the PPG using create channel).
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.PPG_SUBSCRIBER_NOT_FOUND : 10007;
+
+/**
+* Result error code for when a create channel or destroy channel operation internally passes an expired authentication token to the PPG.
+* <br/><br/>
+* Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: Retrying the operation might correct the issue.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.EXPIRED_AUTHENTICATION_TOKEN_PROVIDED_TO_PPG : 10008;
+
+/**
+* This result error code should not typically be encountered.
+* It would only occur if a create channel or destroy channel operation internally passes an invalid authentication token to the PPG.
+* <br/><br/>
+* Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: If this error occurs, it should be logged and reported to the RIM support team.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.INVALID_AUTHENTICATION_TOKEN_PROVIDED_TO_PPG : 10009;
+
+/**
+* Result error code for when too many devices have already performed a create channel for the provider application ID.
+* (A create channel will effectively register a user with the PPG for public/BIS.)
+* <br/><br/>
+* Operations this error can occur on: createChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: No action can be taken by the application for this error, but it should somehow be communicated
+* back to the content provider and then to RIM to try to increase the allowed subscription limit.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.PPG_SUBSCRIBER_LIMIT_REACHED : 10010;
+
+/**
+* Result error code for when a device attempting to do a create channel has an invalid operating system version number or an invalid device model number.
+* <br/><br/>
+* Operations this error can occur on: createChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: Retrying the operation is not recommended since this is an unrecoverable error that is out of control of the application.
+* It might make sense to communicate this issue up to the user.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.INVALID_OS_VERSION_OR_DEVICE_MODEL_NUMBER : 10011;
+
+/**
+* Result error code when attempting to call destroy channel after a content provider
+* has manually suspended a user.
+* <br/><br/>
+* Operations this error can occur on: destroyChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: Most applications will typically want to just ignore this error code when it comes back.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.CHANNEL_SUSPENDED_BY_PROVIDER : 10012;
+
+/**
+* Result error code when attempting to perform an operation and a create session has not been done beforehand.
+* <br/><br/>
+* Operations this error can occur on: createChannel, destroyChannel, launchApplicationOnPush
+* <br/><br/>
+* Recommended action: This usually means a programming error in the application.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.CREATE_SESSION_NOT_DONE : 10100;
+
+/**
+* Result error code when attempting to perform a create channel and a PPG URL was missing.
+* <br/><br/>
+* Operations this error can occur on: createChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: Specifying a value for ppgUrl programmatically and retrying might correct the issue.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.MISSING_PPG_URL : 10102;
+
+/**
+* Result error code when a create channel or destroy channel operation has failed due to network issues.
+* <br/><br/>
+* Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: Retrying the operation might correct the issue.
+* This error can also occur when the user's wireless connection (e.g. Wi-Fi, Mobile Network) is off or temporarily down,
+* so it might make sense to communicate this issue up to the user.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.NETWORK_FAILURE : 10103;
+
+/**
+* Result error code when a certain operation is currently not supported.
+* <br/><br/>
+* Recommended action: This operation might not yet be implemented and so should not be performed.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.OPERATION_NOT_SUPPORTED : 10105;
+
+/**
+* Result error code when attempting to perform a destroy channel and a create channel has not been done beforehand.
+* <br/><br/>
+* Operations this error can occur on: destroyChannel
+* <br/><br/>
+* Recommended action: This might mean a programming error in the application.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.CREATE_CHANNEL_NOT_DONE : 10106;
+
+/**
+* Result error code as a result of an issue on a create channel operation obtaining a port from the PPG.
+* <br/><br/>
+* Operations this error can occur on: createChannel
+* <br/><br/>
+* Recommended action: Retrying the operation might correct the issue.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.MISSING_PORT_FROM_PPG : 10107;
+
+/**
+* Result error code as a result of an issue on a create channel operation obtaining a subscription return code from the PPG.
+* <br/><br/>
+* Operations this error can occur on: createChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: Retrying the operation might correct the issue.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.MISSING_SUBSCRIPTION_RETURN_CODE_FROM_PPG : 10108;
+
+/**
+* Result error code when a create channel or destroy channel operation has failed due to a failure to communicate with the PPG.
+* <br/><br/>
+* Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)
+* <br/><br/>
+* Recommended action: Retrying the operation might correct the issue.
+* It also might make sense to communicate this issue up to the user telling them to try again later when the PPG
+* is available again.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.PPG_CURRENTLY_NOT_AVAILABLE : 10110;
+
+/**
+* Result error code when no invoke target ID is specified on a create operation.
+* <br/><br/>
+* Operations this error can occur on: create
+* <br/><br/>
+* Recommended action: Specifying a value for invokeTargetId programmatically and retrying might correct the issue.
+* @type Number
+* @constant
+* @static
+* @BB10X
+*/
+blackberry.push.PushService.MISSING_INVOKE_TARGET_ID : 10111;
View
204 api/html5_directoryEntry.js
@@ -0,0 +1,204 @@
+/*
+* Copyright 2010-2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * @toc {IO} HTML5 DirectoryEntry
+ * @class
+ * @constructedBy FileSystem.root
+ * @description This object represents a directory on a file system.
+*/
+DirectoryEntry = function() {};
+
+ /**
+ * @description Look up metadata about a directory.
+ * @callback {successCallback} callback function that will execute when the event occurs successfully.
+ * @callback {errorCallback} callback function that will execute when the event fails
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ * @example
+ * Main script:
+ *
+ *
+ */
+ DirectoryEntry.prototype.getMetadata = function(successCallBack, errorCallback) {};
+
+ /**
+ * @description Moves a directory to a different location. When moving the directory to a location where the name already exists, <b>moveTo</b> will attempt to overwrite it.
+ * @param {DirectoryEntry} The directory that you want to move
+ * @param {String} The new name of the directory. Defaults to the current name if unspecified.
+ * @callback {successCallback} callback function to execute when it is successful
+ * @callback {errorCallback} callback function to execute when there is a failure
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ * @example
+ * Main script:
+ *
+ */
+ DirectoryEntry.prototype.moveTo = function(parent, newName, successCallback, errorCallback) {};
+
+ /**
+ * @description Copies the directory to a new location. When copying to a location where the name already exists, <b>copyTo</b> will attempt to overwrite it.
+ * @param {DirectoryEntry} original directory
+ * @param {String} newName new name of directory
+ * @callback {successCallback} callback function to execute when it is successful
+ * @callback {errorCallback} callback function to execute when there is a failure
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.prototype.copyTo = function(parent, newName, successCallback, errorCallback) {};
+
+ /**
+ * @description Returns a URL that can be used to locate the directory.
+ * @type string
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.prototype.toURL = function() {};
+
+ /**
+ * @description function to delete a directory.
+ * @callback {successCallback} callback function to execute when it is successful
+ * @callback {@callback} callback function to execute when there is a failure
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.prototype.remove = function(successCallback, errorCallback) {};
+
+ /**
+ * @description returns the parent DirectoryEntry
+ * @callback {successCallback} callback function to execute when it is successful
+ * @callback {errorCallback} callback function to execute when there is a failure
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.prototype.getParent = function(successCallback, errorCallback) {};
+
+ /**
+ * @description creates a new DirectoryReader to read contents in a directory
+ * @constructor constructor for directoryReader object
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.prototype.createReader = function() {};
+
+ /**
+ * @description Create or look up a directory.
+ * @param {String} The path of the directory to be looked up or created
+ * @param {flags} Options to specify whether the directory is to be created if it doesn't exist
+ * @callback {successCallback} callback function that is called with a File object. (Function)
+ *callback {errorCallback} callback function to execute when there is an error during creating the File object. Invoked with a FileError object. (Function)
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.prototype.getDirectory = function(successCallback, errorCallback) {};
+
+ /**
+ * @description Creates or look up a file.
+ * @param {String} Path - path of the file to be looked up or created.
+ * @param {flags} Options - options to specify whether the file is created if it doesn't exist
+ * @callback {successCallback} callback function that is called with a File object. (Function)
+ * @callback {errorCallback} callback function to execute when there is an error during creating the File object. Invoked with a FileError object.
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.prototype.getFile = function(Path, Options, successCallback, errorCallback) {};
+
+ /**
+ * @description Delete a directory and all of its contents.
+ * @callback {successCallback} callback function that is called with a File object. (Function)
+ * @callback {errorCallback} callback function to execute when there is an error during creating the File object. Invoked with a FileError object.
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.prototype.removeRecursively = function(successCallback, errorCallback) {};
+
+ /**
+ * @description Returns whether the object is a file or not. Value is always false.
+ * @field
+ * @type boolean
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.isFile = false;
+
+ /**
+ * @field
+ * @description Returns whether the object is a directory or not. Value is always true.
+ * @type boolean
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.isDirectory = true;
+
+ /**
+ * @field
+ * @description {string} The full absolute path from the root to the DirectoryEntry
+ * @type File
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.fullPath = undefined;
+
+ /**
+ * @field
+ * @description {string} The file system on which the DirectoryEntry resides
+ * @type File
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryEntry.filesystem = undefined;
+
+
+/**
+ * @toc {IO} HTML5 Flags
+ * @namespace
+ * @description This object is used to indicate the the file or directory should be created or not.
+*/
+Flags = function() {};
+
+ /**
+ * @field
+ * @description {boolean} Indicates whether the file or directory should be created or not, if it does not exist.
+ * @type boolean
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ Flags.create = undefined;
+
+ /**
+ * @field
+ * @description {boolean} By itself, exclusive has no effect. Used with create, it causes the file or directory creation to fail if the target path already exists.
+ * @type boolean
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ Flags.exclusive = undefined;
View
32 api/html5_directoryReader.js
@@ -0,0 +1,32 @@
+/*
+* Copyright 2010-2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * @toc {IO} HTML5 DirectoryReader
+ * @class
+ * @description An object that lists out contents in a directory.
+*/
+DirectoryReader = function() {};
+
+ /**
+ * @description function that reads the contents of a directory
+ * @callback {successCallback} callback function that is passed an array of FileEntry and DirectoryEntry objects
+ * @callback {errorCallback} callback that is called if an error occurs retrieving the directory listing. Invoked with a FileError object.
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ DirectoryReader.prototype.readEntries = function (successCallback, errorCallback) {};
View
87 api/html5_file.js
@@ -0,0 +1,87 @@
+/*
+* Copyright 2010-2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * @toc {IO} HTML5 File
+ * @class File objects provides functionatlity to be able to read, write and navigate file system hierarchies
+ * @constructedBy fileEntry.file
+ * @description File Object
+*/
+File = function() {
+
+ /**
+ *
+ * @function
+ * @constructedBy FileEntry.file
+ * @description returns the file object associated to the fileEntry
+ * @callback {function} successCallBack function to be executed when successful
+ * @callback {File} successCallBack.File The new File object
+ * @callback {function} errorCallBack function to be executed when an error is encountered
+ * @callback {FileError} errorCallBack.FileError Invoked with a FileError object
+ */
+ file : undefined
+
+};
+
+ /**
+ * @field
+ * @description The name of the file
+ * @type File
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ File.prototype.name = undefined;
+
+ /**
+ * @field
+ * @description The full path of the file including the file name
+ * @type File
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ File.prototype.fullPath = undefined;
+
+ /**
+ * @field
+ * @description The mime type of the file
+ * @type File
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ File.prototype.type = undefined;
+
+ /**
+ * @field
+ * @description lists the date that it was last modified
+ * @type File
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ File.prototype.lastModifiedDate = undefined;
+
+ /**
+ * @field
+ * @description size of file in bytes
+ * @type File
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ File.prototype.size = undefined;
View
123 api/html5_fileEntry.js
@@ -0,0 +1,123 @@
+/*
+* Copyright 2010-2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * @toc {IO} HTML5 FileEntry
+ * @class
+ * @description An object that represents a file on the filesystem.
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+fileEntry = function() {};
+
+ /**
+ * @description returns information (metadata) regarding to the fileEntry
+ * @callback {successCallback} callback function that will execute when the event occurs successfully.
+ * @callback {errorCallback} callback function that will execute when the event fails
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ fileEntry.prototype.getMetadata = function(successCallBack, errorCallback) {};
+
+ /**
+ * @description moves a file to a different location on the file system
+ * @param {DirectoryEntry} parent directory to move the file to
+ * @param {String} newName The new name of the file.
+ * @callback {successCallback} callback function to execute when it is successful
+ * @callback {errorCallback} callback function to execute when there is a failure
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ *
+ */
+ fileEntry.prototype.moveTo = function(parent, newName, successCallback, errorCallback) {};
+
+ /**
+ * @description Copy function to copy a file to another location in the file system.
+ * @param {DirectoryEntry} parent directory to copy the file to
+ * @param {String} newName New file name.
+ * @callback {successCallback} callback function to execute when it is successful
+ * @param {errorCallback} callback function to execute when there is a failure
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ fileEntry.prototype.copyTo = function(parent, newName, successCallback, errorCallback) {};
+
+ /**
+ * @description Returns a URL that can be used to locate the file.
+ * @type string
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ fileEntry.prototype.toURL = function() {};
+
+ /**
+ * @description deletes the file from the filesystem
+ * @callback {successCallback} Callback function when the file is successful
+ * @callback {errorCallback} Callback function when there is a failure
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ fileEntry.prototype.remove = function(successCallBack, errorCallBack) {};
+
+ /**
+ * @description returns the parent directoryEntry containing the specified fileEntry
+ * @callback {successCallback} callback function to execute when it is successful
+ * @callback {errorCallback} callback function to execute when there is a failure
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ * @example
+ *
+ * function success(parent) {
+ * console.log("Parent Name: " + parent.name);
+ * }
+ *
+ * function fail(error) {
+ * alert(error.code);
+ * }
+ *
+ * // Get the parent DirectoryEntry
+ * entry.getParent(success, fail);
+ *
+ *
+ */
+ fileEntry.prototype.getParent = function(successCallback, errorCallback) {};
+
+ /**
+ * @description creates the writer to write into the file
+ * @callback {successCallback} callback function that is called with a FileWriter object.
+ * @callback {errorCallback} callback function to execute when there is a failure. Invoked with a FileError object.
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ fileEntry.prototype.createWriter = function(successCallback, errorCallback) {};
+
+ /**
+ * @description Return a File object that represents the current state of the file that this FileEntry represents.
+ * @callback {successCallback} callback function that is called with a File object.
+ * @callback {errorCallback} callback function to execute when there is an error during creating the File object. Invoked with a FileError object. (Function)
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ fileEntry.prototype.file = function(successCallback, errorCallback) {};
View
130 api/html5_fileError.js
@@ -0,0 +1,130 @@
+/*
+* Copyright 2010-2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * @toc {IO} HTML5 FileError
+ * @class
+ * @namespace Errors in the asynchronous File API are reported using callbacks that have a <b>FileError</b> object as one of their arguments.
+ */
+FileError = {
+ /**
+ * @constant
+ * @type String
+ * @description File/directory not found error
+ * @PB10+
+ * @BB10X
+ */
+ NOT_FOUND_ERR: NOT_FOUND_ERROR,
+
+ /**
+ * @constant
+ * @type String
+ * @description This is a security error code to be used in situations not covered by any other error codes.
+ * @PB10+
+ * @BB10X
+ */
+ SECURITY_ERR: SECURITY_ERR,
+
+ /**
+ * @constant
+ * @type String
+ * @description This is returned when the read operation was aborted, typically with a call to abort()
+ * @PB10+
+ * @BB10X
+ */
+ ABORT_ERR: ABORT_ERR,
+
+ /**
+ * @constant
+ * @type String
+ * @description This is returned if the file cannot be read, typically due to permission problems that occur after a reference to a file has been acquired (e.g. concurrent lock with another application).
+ * @PB10+
+ * @BB10X
+ */
+ NOT_READABLE_ERR: NOT_READABLE_ERR,
+
+ /**
+ * @constant
+ * @type String
+ * @description returned when encoding error
+ * @PB10+
+ * @BB10X
+ */
+ ENCODING_ERR: ENCODING_ERR,
+
+ /**
+ * @constant
+ * @type String
+ * @description returned when file is read-only
+ * @PB10+
+ * @BB10X
+ */
+ NO_MODIFICATION_ALLOWED_ERR: NO_MODIFICATION_ALLOWED_ERR,
+
+ /**
+ * @constant
+ * @type String
+ * @description The file is in an invalid state is, and the object is unable to perform the action due to it.
+ * @PB10+
+ * @BB10X
+ */
+ INVALID_STATE_ERR: INVALID_STATE_ERR,
+
+ /**
+ * @constant
+ * @type String
+ * @description Syntax Error
+ * @PB10+
+ * @BB10X
+ */
+ SYNTAX_ERR: SYNTAX_ERR
+
+ /**
+ * @constant
+ * @type String
+ * @description Invalid modification error due to security or privacy
+ * @PB10+
+ * @BB10X
+ */
+ INVALID_MODIFICATION_ERR: INVALID_MODIFICATION_ERR,
+
+ /**
+ * @constant
+ * @type String
+ * @description Error processing from asynchronous calls due to size
+ * @PB10+
+ * @BB10X
+ */
+ QUOTA_EXCEEDED_ERR: QUOTA_EXCEEDED_ERR,
+
+ /**
+ * @constant
+ * @type String
+ * @description Type mismatch error
+ * @PB10+
+ * @BB10X
+ */
+ TYPE_MISMATCH_ERR: TYPE_MISMATCH_ERR,
+
+ /**
+ * @constant
+ * @type String
+ * @description Directory already exists error
+ * @PB10+
+ * @BB10X
+ */
+ PATH_EXISTS_ERR: PATH_EXISTS_ERR,
+ };
View
87 api/html5_fileLocalFileSystem.js
@@ -0,0 +1,87 @@
+/*
+* Copyright 2010-2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * @toc {IO} HTML5 LocalFileSystem
+ * @class
+ * @description This object provides a way to obtain root file system
+ * @constructedBy window.requestFileSystem
+*/
+LocalFileSystem = function() {};
+
+LocalFileSystem = {
+ /**
+ * @constant
+ * @type String
+ * @description Localstorage that will persists after application has been completed.
+ */
+ PERSISTENT: PERSISTENT,
+
+ /**
+ * @constant
+ * @type String
+ * @description Localstorage that is temporary
+ */
+ TEMPORARY: TEMPORARY,
+ };
+
+ /**
+ * @description Requests the filesystem.
+ * @param {string} String to indicate the LocalFileSystem.type (ie. LocalFileSystem.PERSISTENT or LocalFileSystem.TEMPORARY)
+ * @callback {successCallback} callback function that is invoked on successful request of a file system. Argument passed in is the FileSystem object
+ * @callback {errorCallback} callback function for handling errors or when the request to obtain the file system is denied. Argument passed in is the FileError object
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ * @example
+ * Main script:
+ *
+ * &lt;script type="text/javascript"&gt;
+ * function onInitFs(fs) {
+ * console.log('Opened file system: ' + fs.name);
+ * }
+ *
+ * window.requestFileSystem(window.TEMPORARY, 5*1024*1024 onInitFs, errorHandler); // 5*1024*1024 = 5MB
+ *
+ *
+ * &lt;/script&gt;
+ *
+ */
+ LocalFileSystem.prototype.requestFileSystem = function(filetype, successCallback, errorCallback) {};
+
+
+ /**
+ * @description Requests the DirectoryEntry or FileEntry Object using local URI.
+ * @param {String} Full path and name of file
+ * @param {integer} size (in bytes) the app will require for storage
+ * @callback {successCallback} callback function that is invoked on successful request of a file system. Argument passed in is the FileSystem object
+ * @callback {errorCallback} Optional callback for handling errors or when the request to obtain the file system is denied. Argument passed in is the FileError object
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ * @example
+ * Main script:
+ *
+ * &lt;script type="text/javascript"&gt;
+ *
+ * function onSuccess(fileEntry) {
+ * console.log(fileEntry.name);
+ * }
+ *
+ * window.resolveLocalFileSystemURI("file:///example.txt", onSuccess, onError); * &lt;/script&gt;
+ *
+ */
+ LocalFileSystem.prototype.resolveLocalFileSystemURI = function( String, successCallback, errorCallback) {};
View
32 api/html5_fileMetadata.js
@@ -0,0 +1,32 @@
+/*
+* Copyright 2010-2012 Research In Motion Limited.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * @toc {IO}HTML5 Metadata
+ * @class
+ * @description This object provides some information regardign to the state of the file or directory object
+*/
+Metadata = function() {};
+
+ /**
+ * @field
+ * @description The date/ime of which the file or directory was last modified
+ * @type File
+ * @PB10+
+ * @RIPPLE
+ * @BB10X
+ */
+ Metadata.modificationTime = undefined;
View
140 api/html5_fileReader.js
@@ -0,0 +1,140 @@
+/*
+ * Copyright 2012 Research In Motion Limited.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @toc {IO} HTML5 FileReader
+ * @namespace Object to allow reading of files
+ * @PB10+
+ * @BB10X
+ */
+FileReader = {
+
+ /**
+ * @description function to abort the fileReading process
+ * @PB10+
+ * @BB50+
+ * @example
+ * function win(file) {
+ * var reader = new FileReader();
+ * reader.onloadend = function(evt) {
+ * console.log("read success");
+ * console.log(evt.target.result);
+ * };
+ *
+ * reader.readAsText(file);
+ * reader.abort();
+ * };
+ *
+ * function fail(error) {
+ * console.log(error.code);
+ * }
+ *
+ * entry.file(win, fail);
+ *
+ */
+ FileReader.prototype.abort = function () {};
+
+ /**
+ * @description function to read the file and return the data as a base64 encoded data url
+ * @type {function}
+ * @PB10+
+ * @BB50+
+ */
+ FileReader.prototype.readAsDataURL = function(){};
+
+ /**
+ * @description function to read the text file and returns the data as text
+ * @type {function}
+ * @PB10+
+ * @BB10X
+ */
+ FileReader.prototype.readAsText = function() { },
+
+ /**
+ * @description function that is called when the read has been aborted
+ * @event
+ * @type {function}
+ * @PB10+
+ * @BB10X
+ */
+ onabort : function() {
+ },
+
+ /**
+ * @description the function that is called when the read starts
+ * @event
+ * @type {function}
+ * @PB10+
+ * @BB10X
+ */
+ onloadstart : function() {
+ },
+
+