Other Users

- BlackBerry OS 5.0+

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

API Summary

inviteToBBM

---

static void inviteToBBM(onComplete : Function, invitations : Object[])

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Allows the user to invite users to their BBM contact list. A dialog will appear allowing the user to select users to invite. Users already in the current user's contact list will not be included in the dialog.

Parameter	Type	Description
onComplete	Function	Invoked when the user has finished selecting contacts to invite.
invitations	Object[]	The pin-name pairs of the users to invite to BBM.

Throws	Description
IllegalArgumentException	If PIN is invalid for any invitation.
IllegalArgumentException	If name is null or empty for any invitation.
IllegalArgumentException	If invitations.length > 24.

Code Example(s)

<script type="text/javascript">

// Invite to BBM by PIN
var onComplete = function() {
    // Continue...
}
var users = blackberry.bbm.platform.users;
var invitations = [
        { pin:"2100000A", name:"John Doe" },
        { pin:"2100000B", name:"Jane Doe" }
];
blackberry.bbm.platform.users.inviteToBBM(onComplete, invitations);

</script>

inviteToBBMFromConnections

---

static void inviteToBBMFromConnections(onComplete : Function, [connection: blackberry.bbm.platform.io.Connection])

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Allows the user to invite users to their BBM contact list. A dialog will appear allowing the user to select users to invite. Users already in the current user's contact list will not be included in the dialog.

Users from connection (who are not in the user's contact list) will be shown in the dialog.

If connection is not provided, then users from all connections the application has open (who are not in the user's contact list) will be shown in the dialog.

Parameter	Type	Description
onComplete	Function	Invoked when the user has finished selecting contacts to invite.
connection	blackberry.bbm.platform.io.Connection Optional	The connection to invite users from.

Code Example(s)

<script type="text/javascript">

// Invite to BBM from a specific connection
blackberry.bbm.platform.users.inviteToBBMFromConnections(function () {
    // Continue...
}, connection);

</script>

<script type="text/javascript">

// Invite to BBM from all open connections in the application
blackberry.bbm.platform.users.inviteToBBMFromConnections(function () {
    // Continue...
});

</script>

inviteToDownload

---

static void inviteToDownload(onComplete : Function)

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Allows the user to invite contacts to download the application. A Contact Picker dialog will appear allowing the user to select contacts to invite.

Only contacts without the application can be invited to download.

Parameter	Type	Description
onComplete	Function(result : String)	Invoked when the user is complete. result: "limitreached" if the download invitation limit has been reached;undefined otherwise. A maximum of 10 download invitations per minute is allowed.

Code Example(s)

blackberry.bbm.platform.users.inviteToDownload(function(result) {
    if(result == "limitreached") {
        // Download invitation limit reached
    } else {
        // User is finished inviting
    }
});

pickUsers

---

static void pickUsers(options : Object, onComplete : Function)

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Shows Contact Picker dialog allowing the user to select users.

Parameter	Type	Description
options	Object	Object containing Contact Picker options. title: Title of the Contact Picker dialog. type: Type of users to include in the dialog. May be "contactswithapp". users: Users shown in the dialog. multiSelect: true to allow the user to select multiple users; false to only allow 1. showSelectAll: true to show Select All option; false otherwise. Ignored if options.multiSelect == false.
onComplete	Function(users : blackberry.bbm.platform.users.BBMPlatformUser[])	Function called when user is finished. users: The picked users. users.length == 0 if no users were selected.

Code Example(s)

<script type="text/javascript">

blackberry.bbm.platform.users.pickUsers( {
    title : "Who would you like to chat with?",
    type : "contactswithapp"
}, function(users) {
    if (users.length == 0) {
        // No users picked
    } else {
        // One or more users picked
    }
});

</script>

sendFile

---

static void sendFile(fileURI : String, comment : String, onFailure : Function, [contact: blackberry.bbm.platform.users.BBMPlatformUser])

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Sends a file to a contact. The user will be prompted to edit the comment and choose to send or cancel the file transfer.

If contact is not provided then the Contact Picker dialog be shown first, allowing the user to pick someone in their contact list whom to send the file. Otherwise, the Contact Picker dialog will not be shown.

Files can be sent to any contact.

If the contact cannot receive the specific file type, the file will not be sent.

The application is notified of any errors that occur through the onFailure(reason) callback. The reasons are:

• "filenotfound": The file transfer failed because the file does not exist.
• "filetoolarge": The file transfer failed because the file size exceeds the limit permitted by BBM.
• "fileempty": The file transfer failed because the file is empty.
• "fileforwardlocked": The file transfer failed because the file is forward-locked.
• "filebadtype": The file transfer failed because the recipient is not permitted to receive files of the file type.
• "usercanceled": The file transfer failed because the current user canceled the file transfer.
• "noncontact": The file transfer failed because the recipient is not a BBM contact of the user.

Parameter	Type	Description
fileURI	String	The fully qualified path of the file to send.
comment	String	The default comment on the file. The user may edit this comment before sending.
onFailure	Function(reason : String)	Invoked if the file transfer fails. reason: The reason why the transfer failed.
contact	blackberry.bbm.platform.users.BBMPlatformUser Optional	The recipient of the file. The recipient must be in the current user's contact list.

Code Example(s)

<script type="text/javascript">

var onFailure = function(reason) {
    var message = getFileFailureString(reason);
    if(message) {
        alert(message);
    }
};    
blackberry.bbm.platform.users.sendFile("file:///SDCard/smiley.jpg", "Check out this file.", onFailure);

function getFileFailureString(reason) {
    if(reason == "filenotfound") {
        return "The file does not exist.";
    } else if(reason == "filetoolarge") {
        return "The file is too large.";
    } else if(reason == "fileforwardlocked") {
        return "The file is DRM protected.";
    } else if(reason == "filebadtype") {
        return "The user is unable to receive files of this type.";
    } else if(reason == "fileempty") {
        return "The file is empty and cannot be sent.";
    } else if(reason == "usercanceled") {
        return "You canceled the file transfer.";
    } else if(reason == "noncontact") {
        return "You may only send files to your BBM contacts.";
    }
};

</script>

startBBMChat

---

static void startBBMChat(onComplete : Function, message : String, [users: blackberry.bbm.platform.users.BBMPlatformUser[]])

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Starts a chat within BBM, bringing the chat screen to the foreground and entering a message in the reply field.

If users is provided, the chat screen is opened immediately; otherwise a Contact Picker dialog is displayed beforehand.

Chats can be started with any contact.

Parameter	Type	Description
onComplete	Function	Invoked when the chat has been started or canceled.
message	String	The initial message in the reply field of the chat screen.
users	blackberry.bbm.platform.users.BBMPlatformUser[] Optional	The users with whom to chat. Must not contain blackberry.bbm.platform.self.

Code Example(s)

<script type="text/javascript">

// Start chat with Contact Picker dialog
blackberry.bbm.platform.users.startBBMChat(function() {
    // Continue with application...
}, "Did you see the game?");

</script>

onupdate

---

static void onupdate(user : blackberry.bbm.platform.users.BBMPlatformUser, event : String)

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Invoked when a user's information is updated. Assign a function to receive user updates.

User updates can be captured such as profile information and application installation changes. Updates can be received from the current user, contacts who have the application, and non-contacts who have joined in an application connection with the current user.

• "displayname": Display name update.
• "displaypicture": Display picture update.
• "personalmessage": Personal message update.
• "status": Status and/or status message update.
• "install": User installed or unblocked application.
• "uninstall" User uninstalled or blocked application.
• "invited": The current user received an invitation to join this application in BBM. This only applies to the current user.

Parameter	Type	Description
user	blackberry.bbm.platform.users.BBMPlatformUser	The user whose information updated.
event	String	The type of update.

Code Example(s)

<script type="text/javascript">

blackberry.bbm.platform.users.onupdate = function(user, event) {
    // Handle events for the current user
    if(user.handle == blackberry.platform.self.handle) {
        if (event == "displaypicture") {
            var displayPicImg = document.getElementById("myPicture"); // Must have img element with id="myPicture"
            displayPicImg.src = user.displayPicture;
        }
        // Handle other events for the current user...
    }
    // Handle events for other users...
};

</script>

Properties:

---

Property	Type	Description	Supported Platform(s)
contactsWithApp	Static blackberry.bbm.platform.users.BBMPlatformUser[] readonly	Contacts who have the application installed.	- BlackBerry OS 5.0+

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:21 GMT-0500 (EST)