Utils

The Utils object provides useful utility functions and properties.


Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook 1.0+
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.utils.blobToString Y Y Y Y Y  Y
blackberry.utils.documentToBlob Y           
blackberry.utils.generateUniqueId Y Y Y Y Y  Y
blackberry.utils.parseURL Y Y Y Y Y  Y
blackberry.utils.stringToBlob Y Y Y Y Y  Y

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.utils" /> Y Y Y Y Y  Y

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Functions

static String blackberry.utils.blobToString (blob : Blob, [encoding : String])


Construct a new String by converting the blob using the specified character encoding


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
blob The Blob object to be converted.
The acceptable blob size is documented below:
 OS 5.0OS 6.0OS 7.0
BASE64<= 89,678 bytes
Other Encodings<= 524,288 bytes (512KB)<= 2,097,152 bytes (2MB)<= 524,236 bytes (511KB)
encoding [Default Value: ISO-8859-1]

The name of a supported character encoding.BlackBerry supports the following character encodings: ISO-8859-1, UTF-8, UTF-16BE, US-ASCII. Besides these encodings, Web API also supports BASE64 encoding. Support of other encodings depends on the configuration of the BlackBerry Smartphone.


Return:

The String result from converting the Blob



Code Example:
<script type="text/javascript">

 var fileName = "local:///data/fooFile.txt";

 function handleOpenedFile(fullPath, blobData) // callback function that is passed when using the blackberry.io.file.readFile API
 {
   xmlString = blackberry.utils.blobToString(blobData); 
 }

 try{
     if (blackberry.io.file.exists(fileName)) {
		    blackberry.io.file.readFile(fileName, handleOpenedFile);
     } 
 }
 catch (ex) {
     alert("exist: " + ex.toString(0));
 }

</script>

static Blob blackberry.utils.documentToBlob (doc : Document)


Deprecation Notice:

This API is deprecated, please use blackberry.utils.stringToBlob instead.

For example:
var foo = blackberry.utils.stringToBlob( document.toString() );

Convert a document into a Blob. Supported in 5.0.0 only.


Supported Platforms
 - BlackBerry OS 5.0


Parameters
doc The document to be converted.

Return:

The Blob result from converting the Document


static Number blackberry.utils.generateUniqueId ()


This method will generate a unique number.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Return:

A unique number from JavaScript's Math.random() function.



Code Example:
<script type="text/javascript">

var myID = blackberry.utils.generateUniqueId();

</script>

static blackberry.utils.URL blackberry.utils.parseURL (url : String)


Parses a URL string and returns an URL object.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
url The URL string to be parsed.

Return:

A blackberry.utils.URL object is returned if the parsing is successful.



Code Example:
<script type="text/javascript">
var myURL = "https://bdsc.webapps.blackberry.com/html5/";

var URLObj = blackberry.utils.URL(myURL); 

</script>

static Blob blackberry.utils.stringToBlob (str : String, [encoding : String])


Convert a string object into a Blob using the specified character encoding.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - Ripple Emulator


Parameters
str The string to be converted.
The acceptable string length is documented below:
 OS 5.0OS 6.0OS 7.0
BASE64<= 65,535
Other Encodings<= 524,288<= 2,097,152<= 524,236
encoding [Default Value: ISO-8859-1]

The name of a supported character encoding.BlackBerry supports the following character encodings: ISO-8859-1, UTF-8, UTF-16BE, US-ASCII. Besides these encodings, Web API also supports BASE64 encoding. Support of other encodings depends on the configuration of the BlackBerry Smartphone.


Return:

The Blob result from converting the String



Code Example:
<script type="text/javascript">

var myBlob = blackberry.utils.stringToBlob ("This is some sort of string that I would like to encode", "UTF-8");
var filePath, fileDir;

// Check what device you are using
var OSversion = blackberry.system.softwareVersion; // Note: On the Playbook, only the OS Version will actually say the what type of device it is. For handheld device, blackberry.system.model will return the actual model (ie. 9780)

// Establishing where to save my file depending on which device I have
if (OSversion.indexOf("Playbook") == -1) { // Device is BlackBerry
    
   //Now need to check if there is a SD card on the device
   if (blackberry.io.dir.exists("file:///SDCard")) { //The only way to see if the SDCard is inserted into the device is by checking to see if the directory is there.

         fileDir = "file:///SDCard/dir1";
         blackberry.io.dir.createNewDir(fileDir);

   } else { // Apparently there no SD card, so we're saving the blob on the local device

         fileDir = "file:///store/dir1";
         blackberry.io.dir.createNewDir(fileDir);

   }
} else {
   // Device is Playbook

   // To make this example easier, I did not turn on "File Sharing" and choosing to save in the app storage area.	 
   fileDir = blackberry.io.dir.appDirs.app.storage.path + "/dir1";  
                                                   
   blackberry.io.dir.createNewDir(fileDir);
}

try {
   blackberry.io.file.saveFile(filedir + "/blob.txt", myBlob);
} catch (e) {
   alert('e.message = ' + e.message);
}			

</script>
Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:45 GMT-0500 (EST)