Guest post by Maurice White, Senior Enterprise Developer at BlackBerry, @MoReeseMo on Twitter.
Welcome Enterprise Developer Citizens! Chances are, if you’re reading this, you’re looking to build a BlackBerry 10 application in the workspace of your BlackBerry Enterprise Server-connected BlackBerry 10 devices. Although you’re going to be building your own custom applications, you should be aware of existing core applications available to you as a developer for integration into your solution.
This blog post is to provide some tips on how you can leverage the Invocation Framework to tie into those existing core apps, giving you the ability to build an even more compelling enterprise solution. It’s really simple math:
Let’s start by talking about some of the core apps available to you.
BlackBerry Enterprise Instant Messaging (EIM)
Many organizations have existing instant messenger clients leveraged by their workforce. These solutions are behind the firewall and have desktop clients. The BlackBerry Enterprise IM app provides your BlackBerry 10 device with access to your organization’s instant messenger client so you can chat with colleagues using your organization’s IM system. EIM is designed for use with Microsoft Office Communicator, Microsoft Lync and IBM Sametime. The BlackBerry device itself has to be connected to your organization’s BlackBerry Enterprise Server in order for EIM to work. As a developer, you can tie into this powerful app from your custom solution to perform tasks such as initiating chats. This would be done using the following invocation framework:
Create an InvokeManager object, to manage interaction with the invocation service
InvokeManager invokeManager;
Create an InvokeRequest object, to encapsulate the details of the request to be passed to EIM.
InvokeRequest request;
Set the target to the unique id for EIM “com.rim.bb.app.eimclient”
request.setTarget("com.rim.bb.app.eimclient");
We’re telling EIM the action that we’d like to perform. In this case “bb.action.VIEW” will launch EIM so that a chat can be initiated
request.setAction("bb.action.VIEW");
We’re sending the invocation request to the invocation framework targeting EIM. A reply message indicating the success of the request is passed to the *reply pointer. You should build code to handle that reply
InvokeTargetReply *reply = invokeManager.invoke(request);
Upon successful execution of this code, the EIM app will be launched and the user can initiate a chat like normal.
Adobe Reader
Adobe Reader is preinstalled on BlackBerry 10 devices. It’s packed with features allowing users to perform tasks like:
- Navigate, zoom and view PDF files
- Annotate, comment and search files
- Create a signature and place it on any PDF file right on your BlackBerry 10 device
- Easily share files through a variety of channels (such as email and NFC)
As a developer, you could have the requirement of building a BlackBerry app that allows interaction with PDF files, so it only makes sense to integrate with the existing Adobe Reader application from your custom app. In our code snippet, we’ll show how simple it is to invoke the Adobe Reader app as a card and display a pdf file:
*Implement InvokeManager & InvokeRequest as discussed in first code sample
I reference a pdf file stored on the device, in this case included in the application directory
QString uri = "file:" + QDir::currentPath() + "/app/native/assets/docs/panther.pdf";
Target set to ID to launch pdf file in a card “com.rim.bb.app.adobeReader.viewer”
request.setTarget("com.rim.bb.app.adobeReader.viewer ");
We’re setting the action that we’d like to perform.
request.setAction("bb.action.VIEW");
We’re setting the mime type telling it to expect pdf files
request.setMimeType ("application/pdf");
The reference to the file location of the pdf file
request.setUri(uri);
We’re sending the invocation request to the invocation framework targeting Adobe Reader. A reply message indicating the success of the request is passed to the *reply pointer. You should build code to handle that reply
InvokeTargetReply *reply = invokeManager.invoke(request);
Upon successful execution of this code, the pdf file will be launched in a previewer card. Upon exit of the previewer card, you’ll be returned to your app.
BlackBerry Browser
It’s common for a user to need to launch a browser as part of their regular usage of their BlackBerry device, but what if that could be done without the user having to leave your app to do so? Leveraging the invocation framework, the BlackBerry browser can be called from within your application. Since your app will reside in the workspace, the work browser will be launched and can be pointed to URLS of internally intranet hosted resources. The app can also open local content (htm, html, xhtml, svg) from within the BlackBerry browser. Our code sample will focus on launching a website:
*Implement InvokeManager & InvokeRequest as discussed in first code sample
A variable created to hold a url that the app will launch
QString uri = ""http://bizblog.blackberry.com";
We then set the target to the unique id for the Browser “sys.browser”
request.setTarget("sys.browser");
We’re setting the action that we’d like to perform.
request.setAction("bb.action.OPEN");
The reference to the url that will be launched
request.setUri(uri);
We’re sending the invocation request to the invocation framework targeting the Browser. A reply message indicating the success of the request is passed to the *reply pointer. You should build code to handle that reply
InvokeTargetReply *reply = invokeManager.invoke(request);
Upon successful execution of this code, a Browser will launch and navigate to the predefined URL
Phone
If you made it this far in the blog posting, I’m assuming you know what the phone application does.Your app can tie into the phone application in a few ways:
- Opening call log
- Dialing a number
- Dialing an emergency number
Our code example will cover dialing a number:
*Implement InvokeManager & InvokeRequest as discussed in first code sample
A map is created to hold the phone number and the type of call
QVariantMap map; map.insert("number", "15559223145"); // required map.insert("line_id", "cellular"); // optional QByteArray requestData = bb::PpsObject::encode(map, NULL); request.setData(requestData);
We’re setting the action that we’d like to perform.
request.setAction("bb.action.DIAL");
Set the mime type for starting a phone call
request.setMimeType("application/vnd.blackberry.phone.startcall");
We’re sending the invocation request to the invocation framework targeting the Phone app4. A reply message indicating the success of the request is passed to the *reply pointer. You should build code to handle that reply
InvokeTargetReply *reply = invokeManager.invoke(request);
Upon successful execution of this code, a message box is displayed asking the user if they’d like to make a call to the pre-designated number. If the user clicks OK, the call is made.
Hopefully this blog posting has provided you with a few helpful tips to get you going with building solutions that include the already existing core applications. A sample app has been created and posted here demonstrating the above code so feel free to use as needed. Follow me on Twitter and post any questions and comments you have in the section below.