navigator_invoke()

Open a URI in the navigator.

Synopsis:

#include <bps/navigator.h>
 
BPS_API int navigator_invoke(const char *url, char **err)

Arguments:

url
The URI to invoke.
err
If this function fails, and if err is not null, it will be set to a short description of the error. The caller must free this buffer using bps_free().

Library:

libbps

Description:

The navigator_invoke() function sends a navigator invoke request to display the contents of the specified URI in the navigator.

When you specify an application URI, the URI also indicates the context that you want to open the application in. For example, to open the camera in photo mode, you can call navigator_invoke() with a parameter of camera://photo. To open the camera in video mode, you can call navigator_invoke() with a parameter of camera://video.

The following sections list the application URIs that you can use when you call navigator_invoke() . Note: Spaces or line breaks have been inserted in the URIs before the & in query strings for readability purposes and should not be passed into navigator_invoke() .

BlackBerry World

  • appworld://myworld - Opens BlackBerry World and loads the My World screen

  • appworld://content/12345 - Opens BlackBerry World and loads the Application Details screen for the content with content ID 12345. This is the preferred format to invoke BlackBerry World content

  • appworld://content=12345 - Same as above

Browser

  • http://URL - Opens the browser and displays the content at the specified URL

  • https://URL - Opens the browser and displays the content at the specified URL

Camera

  • camera://photo - Opens the camera in photo mode

  • camera://video - Opens the camera in video mode

Calendar

  • calendar:// - Opens the calendar

  • calendar://showEvent?accountId=account_ID &eventId=event_ID - Opens the calendar and displays the event with the specified event ID

  • calendar://editEvent?accountId=account_ID &eventId=event_ID - Opens the calendar and displays the edit screen for the event with the specified event ID

  • calendar://newEvent?accountId=account_ID &dateStart=YYYY-MM-DD HH:MM:SS &dateEnd=YYYY-MM-DD HH:MM:SS &attd=comma_delimited_list_of_email_addresses &subj=subject &loc=location &body=body_of_message - Opens the calendar and displays the new event screen with the specified event properties (for example, start date, end date, and so on) pre-populated. All properties are optional and must be URL encoded

Maps

  • maps://?where1=address - Opens Bing Maps and displays the specified address. The address can include spaces and should not be URL encoded

  • maps://?style=style - Opens Bing Maps and changes the map view to the specified style ("u": auto (default), this style switches views automatically based on zoom level; "a": aerial; "r": road; "h": aerial with labels turned on; "o": bird's eye; "b": bird's eye with labels turned on)

Note: You can use these variables in succession by using an ampersand- delimited query string (for example, maps://?where1=waterloo ontario&style=h).

Messages

  • messages:// - Opens the messages application

  • messages://newMessage?accountId=account_ID &to=comma_delimited_list_of_email_addresses &cc=comma_delimited_list_of_email_addresses &bcc=comma_delimited_list_of_email_addresses &body=body_of_message &subject=subject_of_message - Opens the messages application and displays the compose email screen with the specified message properties pre-populated

  • messages://showAccount?accountId=account_ID - Opens the messages application and displays the specified account

  • messages://showMessage?accountId=account_ID &conversationId=conversation_ID &messageId=message_ID - Opens the messages application and displays the specified conversation or message

  • mailto:comma_delimited_list_of_email_addresses ?to=comma_delimited_list_of_email_addresses &cc=comma_delimited_list_of_email_addresses &bcc=comma_delimited_list_of_email_addresses &body=body_of_message &subject=subject_of_message - Creates and sends a message with the specified properties

Music

  • music://albums - Opens the music application and displays the Albums screen

  • music://albums/album?id=album_id - Opens the music application and displays the track list that is associated with the specified album ID (which maps to the audio_metadata.album_id field of mmlibrary)

  • music://albums/album?id=album_ID &play=file_ID - Opens the music application, displays the track list that is associated with the specified album ID, and begins playback at the specified file ID (which maps to the audio_metadata.fid field of mmlibrary). If the file ID does not correspond to a track in the album, nothing is played

  • music://artists - Opens the music application and displays the Artists screen

  • music://artists/artist?id=artist_ID - Opens the music application and displays the track list that is associated with the specified artist ID (which maps to the audio_metadata.artist_id field of mmlibrary)

  • music://artists/artist?id=artist_ID &play=file_ID - Opens the music application, displays the track list that is associated with the specified artist ID, and begins playback at the specified file ID. If the file ID does not correspond to a track in the artist's albums, nothing is played

  • music://genres - Opens the music application and displays the Genres screen

  • music://genres/genre?id=genre_ID - Opens the music application and displays the track list that is associated with the specified genre ID (which maps to the audio_metadata.genre_id field of mmlibrary)

  • music://genres/genre?id=genre_ID &play=file_ID - Opens the music application, diplays the track list that is associated with the specified genre ID, and begins playback at the specified file ID. If the file ID does not correspond to a track in the genre, nothing is played

  • music://playlists - Opens the music application and displays the Playlists screen

  • music://playlists/playlist?id=playlist_ID - Opens the music application and displays the track list that is associated with the specified playlist ID (which maps to the playlist_entries.plid field of mmlibrary)

  • music://playlists/playlist?id=playlist_ID &play=file_ID - Opens the music application, displays the track list that is associated with the specified playlist ID, and begins playback at the specified file ID. If the file ID does not correspond to a track in the playlist, nothing is played

  • music://songs - Opens the music application and displays the All Songs screen

  • music://songs?play=file_ID - Opens the music application, displays the All Songs screen, and begins playback at the specified file ID

  • file_URL - Opens the music application and begins playback of the specified file (for example, /accounts/1000/shared/music/sample.mp3)

Photos

  • photos:// - Opens the pictures application in the default view. The default view is device dependent

  • photos://file_URL - Opens the pictures application and displays the specified file in full screen view. If the file doesn't exist, the default view is displayed. If the file is located in the Downloads, Wallpapers, or Camera folder, or if the file is located in a subfolder in the Photos folder, the user can continue navigating from this entry point (for example, by swiping to the next or previous image)

  • photos://album_name - Opens the pictures application and displays the specified album. If the album doesn't exist, the default view is displayed

Videos

  • videos://recorded - Opens the videos application and displays the Recorded Videos tab

  • videos://file_URL - Opens the videos application and plays the specified file

Music Store

  • musicstore://search=album_search_string - Opens the Music Store and displays the album search results for the specified string

  • musicstore://search/song=song_search_string - Opens the Music Store and displays the song search results for the specified string

  • musicstore://search/artist=artist_search_string - Opens the Music Store and displays the artist search results for the specified string

Settings

  • settings://about - Displays the About screen

  • settings://airplane - Displays the Airplane Mode screen

  • settings://enterprise - Displays the Enterprise/Balance screen

  • settings://wifi - Displays the Wi-Fi screen

  • settings://softwareupdate - Displays the Software Updates screen

  • settings://bluetooth - Displays the Bluetooth screen

  • settings://bb_bridge - Displays the BlackBerry Bridge screen

  • settings://internettethering - Displays the Internet Tethering screen

  • settings://screen - Displays the Screen screen

  • settings://hdmi - Displays the HDMI screen

  • settings://sounds - Displays the Sounds screen

  • settings://general - Displays the General screen

  • settings://storagesharing - Displays the Storage & Sharing screen

  • settings://security - Displays the Security screen

  • settings://language - Displays the Language screen

  • settings://keyboard - Displays the Keyboard screen

  • settings://date_time - Displays the Date & Time screen

  • settings://pim - Displays the PIM Account screen

  • settings://pim/listAccounts - Displays the PIM Account screen

  • settings://pim/defaultAccounts - Displays the PIM Default Accounts screen

  • settings://pim/createAccount - Displays the PIM New Account screen

  • settings://pim/showAccount?id=account_ID - Displays the PIM Edit Account screen for the specified account ID

Video Chat

  • vchat://URI?camera=camera_param &displayname=displayname_param &callingApplication=callingApplication_param - Opens the Video Chat application and places a call with the specified parameters. The URI is the destination of the call, and is required. Possible optional parameters include "camera": "on" to place a video call, "off" to place an audio only call; "displayname": display name to associate with the contact; "smallimage": path to a small image of the contact; "largeimage": path to a large image of the contact; "originalImage": path to the original image of the contact; "callingApplication": name of the application that's starting the call (for example, BBM)

Returns:

BPS_SUCCESS upon success, BPS_FAILURE upon failure with a short description of the error in err.