BlackBerry - Java - SDK 1638866 1219123258 005 7.0 ES

BlackBerry Java SDK
Integration Guide
Versin: 7.0
Gua de desarrollo
SWD-1638866-1219123257-005
Contenido
1 Integracin con aplicaciones de BlackBerry Device Software..........................................................................
Invocar una aplicacin de BlackBerry Device Software....................................................................................
6
6
2 Bsqueda unificada...........................................................................................................................................
Hacer que los datos puedan ser encontrados..................................................................................................
Exponer los datos de sus aplicaciones.......................................................................................................
Pasar consultas a otros motores de bsqueda..........................................................................................
Definir una clase EntityBasedSearchable para sus objetos SearchableEntity...................................................
Personalizar la apariencia de sus datos en los resultados de la bsqueda................................................
Especificar un icono en EntityBasedSearchable o en la clase SearchableEntity........................................
Encapsular datos en la clase SearchableEntity.................................................................................................
Specifying what users can do with your data in search results........................................................................
Specify an operation for a selected search result......................................................................................
Provide an alternate entry point for your application...............................................................................
Expose your UiAction objects....................................................................................................................
Registrar su objeto EntityBasedSearchable en el Servicio de bsqueda unificada...........................................
Notificar al Servicio de bsqueda unificada acerca de los cambios hechos a sus datos...................................
Rastrear las respuestas del Servicio de bsqueda unificada............................................................................
Eliminar sus datos del repositorio de contenido..............................................................................................
Utilizar otros motores de bsqueda.................................................................................................................
Asegurar que un dispositivo ejecuta una sola instancia de su aplicacin.........................................................
Insertar datos al iniciar un dispositivo..............................................................................................................
Bsquedas.........................................................................................................................................................
Configurar e iniciar una bsqueda.............................................................................................................
Procesar los resultados de la bsqueda....................................................................................................
7
7
7
9
10
12
13
14
15
16
17
18
19
20
20
21
22
23
25
25
26
27
3 Compatibilidad de interaccin de dispositivo...................................................................................................

API de capacidad de dispositivo........................................................................................................................
Detectar el soporte...........................................................................................................................................
Gestionar soportes...........................................................................................................................................
Trabajar con los sensores de un dispositivo.....................................................................................................
Buscar un sensor en el dispositivo.............................................................................................................
Comprobar el estado de un sensor...........................................................................................................
Notificar a una aplicacin cuando cambie el estado de un sensor............................................................
Ejemplo de cdigo: Trabajar con un sensor...............................................................................................
29
29
29
31
32
32
33
34
35
4 Lista de mensajes..............................................................................................................................................
Crear un mensaje de texto SMS en blanco nuevo............................................................................................
38
38
Crear un mensaje de texto rellenado nuevo....................................................................................................

Crear un mensaje MMS en blanco nuevo.........................................................................................................
Crear un mensaje de correo electrnico en blanco nuevo...............................................................................
Crear un mensaje de correo electrnico rellenado nuevo...............................................................................
Crear un mensaje PIN en blanco nuevo............................................................................................................
Crear un mensaje PIN rellenado nuevo............................................................................................................
Recibir una notificacin de mensaje.................................................................................................................
Agregar un servicio de escucha al almacn de mensajes.................................................................................
Agregar un servicio de escucha al almacn de mensajes para actualizaciones por lotes.................................
Agregar un servicio de escucha a una carpeta..................................................................................................
Recuperar el nmero total de mensajes de correo electrnico sin leer de todas las carpetas del almacn....
Abrir un mensaje..............................................................................................................................................
Recuperar el cuerpo de un mensaje de correo electrnico..............................................................................
Recuperar el texto sin formato y el contenido HTML del cuerpo de un mensaje de correo electrnico
utilizando un mtodo recursivo.................................................................................................................
Recuperar el contenido de texto sin formato de un mensaje de correo electrnico................................
Recuperar contenido HTML de un mensaje de correo electrnico...........................................................
Notificar a una aplicacin del dispositivo BlackBerry que est a punto de enviarse un mensaje de correo
electrnico........................................................................................................................................................
Notificar a una aplicacin del dispositivo BlackBerry que est a punto de enviarse un mensaje MMS...........
Notificar a una aplicacin del dispositivo BlackBerry que est a punto de enviarse un mensaje SMS............
Enviar un mensaje.............................................................................................................................................
Responder a un mensaje..................................................................................................................................
Reenviar un mensaje........................................................................................................................................
Trabajar con carpetas de mensajes..................................................................................................................
38
38
39
39
39
40
40
41
41
42
42
42
43
50
50
51
51
53
54
55
5 Mensajes personalizados..................................................................................................................................
Utilizar mensajes y carpetas personalizados en la lista de mensajes...............................................................
Crear un mdulo para procesos en segundo plano..........................................................................................
Crear un mdulo para la IU...............................................................................................................................
Crear un mdulo para procesos en segundo plano..........................................................................................
Iniciar el mdulo para procesos en segundo plano o el mdulo para la IU......................................................
Crear un icono para un mensaje personalizado...............................................................................................
Crear una carpeta personalizada en la lista de mensajes.................................................................................
Enviar una notificacin cuando una carpeta personalizada cambie.................................................................
Crear un indicador personalizado.....................................................................................................................
Ocultar un indicador.........................................................................................................................................
Eliminar indicadores personalizados................................................................................................................
57
57
57
57
58
58
59
60
61
62
63
63
44
46
47
6 Archivos adjuntos.............................................................................................................................................
Crear un gestor de archivos adjuntos...............................................................................................................
Recuperar el contenido de un archivo adjunto................................................................................................
Recuperar informacin sobre un archivo adjunto............................................................................................
Enviar un mensaje con un archivo adjunto.......................................................................................................
Descargar automticamente archivos adjuntos...............................................................................................
64
64
65
65
65
66
7 Calendario.........................................................................................................................................................
Abrir el calendario............................................................................................................................................
Ver o cambiar una entrada del calendario.......................................................................................................
Abrir una nueva entrada de calendario rellenada............................................................................................
Actualizar informacin de entradas del calendario..........................................................................................
Recuperar informacin de entradas de calendario..........................................................................................
Exportar una entrada de calendario.................................................................................................................
Importar una entrada de calendario.................................................................................................................
Recuperar varias listas de entradas de calendario...........................................................................................
Notificar a una aplicacin del dispositivo BlackBerry cuando cambie una lista de entradas de calendario.....
Notificar a una aplicacin del dispositivo BlackBerry cuando cambie la lista predeterminada de entradas
de calendario....................................................................................................................................................
Actualizar una entrada del calendario sin ninguna notificacin.......................................................................
Eliminar una entrada del calendario sin ninguna notificacin..........................................................................
68
68
68
68
69
71
72
73
73
73
8 Lista de contactos.............................................................................................................................................
Compatibilidad con diversas listas de contactos..............................................................................................
Abrir la aplicacin de contactos........................................................................................................................
Abrir la aplicacin de contactos utilizando los datos de contacto....................................................................
Abrir la aplicacin de contactos con una lista de contactos especfica............................................................
Crear un contacto y asignarlo a una lista de contactos....................................................................................
Recuperar informacin de contacto.................................................................................................................
Recuperar un UID de listas de contactos..........................................................................................................
Exportar un contacto........................................................................................................................................
Importar un contacto........................................................................................................................................
Eliminar un contacto.........................................................................................................................................
Notificar a una aplicacin cuando una lista de contactos cambia....................................................................
Crear y eliminar listas de contactos..................................................................................................................
Crear una lista de contactos......................................................................................................................
Eliminar listas de contactos.......................................................................................................................
Recuperar el contacto asociado con una llamada activa..................................................................................
Recuperar el contacto asociado con una llamada finalizada............................................................................
78
78
78
79
80
81
82
83
84
85
85
86
88
88
89
90
92
74
74
76
Recuperar contactos por nmero de telfono.................................................................................................

Vincular contactos de terceros con contactos de la aplicacin Contactos.......................................................
Vincular un contacto..................................................................................................................................
Eliminar un vnculo....................................................................................................................................
Crear elementos del men para contactos vinculados.............................................................................
Crear elementos del men para contactos vinculados.............................................................................
Crear un proveedor de informacin para un contacto vinculado.............................................................
92
94
94
95
96
97
98
9 Lista de tareas...................................................................................................................................................
Ver o cambiar una tarea...................................................................................................................................
Crear una tarea nueva en blanco......................................................................................................................
Crear una tarea nueva rellenada......................................................................................................................
Abrir una lista de tareas....................................................................................................................................
Creacin de una tarea.......................................................................................................................................
Agregar informacin de tareas.........................................................................................................................
Cambiar informacin de tareas........................................................................................................................
Guardar una tarea.............................................................................................................................................
Recuperar informacin de tareas.....................................................................................................................
Exportar una tarea............................................................................................................................................
Importar una tarea...........................................................................................................................................
Eliminar una tarea.............................................................................................................................................
Cerrar la lista de tareas.....................................................................................................................................
Notificar a una aplicacin del dispositivo BlackBerry cuando una lista de tareas cambia................................
101
101
101
101
102
102
103
103
104
104
105
105
106
106
107
10 Telfono............................................................................................................................................................
Realizar una llamada desde una aplicacin del dispositivo BlackBerry............................................................
Hacer una llamada desde una aplicacin del dispositivo BlackBerry (entorno de una sola lnea)...................
Realizar una llamada desde una aplicacin del dispositivo BlackBerry (entorno de varias lneas)..................
Agregar tonos DTMF a la cola de envo............................................................................................................
Tonos DTMF de BlackBerry...............................................................................................................................
Escuchar y administrar eventos del telfono....................................................................................................
Escuchar y administrar eventos de varias lneas..............................................................................................
Recuperar informacin de llamadas utilizando registros de llamadas.............................................................
Recuperar a un participante de una llamada....................................................................................................
Recuperar informacin de llamadas.................................................................................................................
Recuperar el nmero de telfono de un dispositivo BlackBerry......................................................................
Recuperar una llamada por el ID de llamada....................................................................................................
Visualizar contenido en una pantalla de llamada.............................................................................................
Mostrar contenido en una pantalla de telfono.......................................................................................
108
108
108
108
109
109
109
110
111
111
112
112
113
113
114
Ejemplo de cdigo: Mostrar contenido en una pantalla de telfono........................................................ 115

Visualizar contenido en dispositivos que operan en una red CDMA......................................................... 116
11 BlackBerry Browser...........................................................................................................................................
Recuperar una sesin de BlackBerry Browser..................................................................................................
Recuperar una sesin no predeterminada de BlackBerry Browser..................................................................
Solicitar una pgina Web..................................................................................................................................
Compatibilidad mejorada para contenido Web en aplicaciones del dispositivo BlackBerry............................
Mostrar contenido HTML en un campo de navegador..............................................................................
Mostrar contenido HTML de una pgina Web en un campo de navegador..............................................
Mostrar contenido HTML de un recurso en su aplicacin.........................................................................
Configurar un campo de navegador..........................................................................................................
Enviar datos de formularios a una direccin Web en un campo de navegador........................................
118
118
118
118
118
119
120
121
122
123
12 Opciones de men............................................................................................................................................
Aadir elementos del men a aplicaciones de BlackBerry Device Software....................................................
Crear y registrar un elemento del men...........................................................................................................
Send Menu API.................................................................................................................................................
Retrieving Send commands..............................................................................................................................
Creating a Send menu.......................................................................................................................................
Create a Send menu..................................................................................................................................
Code sample: Creating a Send menu.........................................................................................................
Creating a context object..................................................................................................................................
Using context keys............................................................................................................................................
Using context filters..........................................................................................................................................
Create a context filter................................................................................................................................
125
125
125
126
128
129
129
131
132
133
134
134
13 Obtener ms informacin................................................................................................................................. 138

14 Glosario............................................................................................................................................................. 139
15 Comentarios..................................................................................................................................................... 141
16 Historial de revisin del documento................................................................................................................. 142
17 Aviso legal......................................................................................................................................................... 145
Integracin con aplicaciones de BlackBerry Device Software
Gua de desarrollo
Integracin con aplicaciones de BlackBerry

Device Software
Esta seccin describe cmo invocar una aplicacin de BlackBerry Device Software, como la aplicacin de
contactos, la aplicacin Telfono y la aplicacin Multimedia.
Para obtener ms informacin acerca de cmo integrar su aplicacin con aplicaciones de BlackBerry Device
Software, consulte la descripcin general de las categoras de integracin de aplicaciones en la referencia de API
para BlackBerry Java Development Environment.
Invocar una aplicacin de BlackBerry Device Software

Puede crear aplicaciones del dispositivo BlackBerry que invoquen aplicaciones de BlackBerry Device Software,
como la aplicacin de mensajes, la aplicacin de telfono y la aplicacin multimedia. Cuando su aplicacin invoca
una aplicacin de BlackBerry Device Software, puede hacer que la aplicacin de BlackBerry Device Software realice
una accin o muestre informacin.
1.
Importe las clases y las interfaces necesarias.

import
import
import
import
import
2.
net.rim.blackberry.api.invoke.CalendarArguments;
net.rim.blackberry.api.invoke.Invoke;
net.rim.blackberry.api.invoke.MapsArguments;
net.rim.blackberry.api.invoke.MessageArguments;
net.rim.blackberry.api.invoke.PhoneArguments;
Invoque el mtodo Invoke.invokeApplication() y utilice los parmetros pertinentes. Por ejemplo:

Para iniciar la aplicacin Mensajes y crear un mensaje SMS nuevo en blanco, invoque el
Invoke.invokeApplication() y utilice los parmetros siguientes: Invoke.APP_TYPE_MESSAGES y un
objeto MessageArguments que utilice el campo ARG_NEW_SMS.
Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES,
new MessageArguments( MessageArguments.ARG_NEW_SMS) );
Para iniciar el calendario, invoque Invoke.invokeApplication(APP_TYPE_CALENDAR,

CalendarArguments).
Para iniciar la aplicacin Telfono, invoque
Invoke.invokeApplication(APP_TYPE_PHONE,PhoneArguments).
Para iniciar BlackBerry Maps y mostrar la vista de mapa predeterminada, invoque
Invoke.invokeApplication() y proporcione como parmetros Invoke.APP_TYPE_MAPS y un objeto
MapsArguments nuevo.
Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments() );
Para obtener ms informacin acerca del uso de la clase net.rim.blackberry.api.invoke.Invoke, consulte

la referencia de API para BlackBerry Java Development Environment.
Bsqueda unificada
Gua de desarrollo
Bsqueda unificada
El Servicio de bsqueda unificada es un motor de bsqueda que se incluye con BlackBerry Device Software Device
Software 6.0 o posterior. Los usuarios del dispositivo BlackBerry interactan con el Servicio de bsqueda unificada
principalmente desde la caracterstica de bsqueda Universal haciendo clic en el icono de bsqueda de la pantalla
de inicio. Los desarrolladores pueden utilizar el Servicio de bsqueda unificada a travs de la API de bsqueda
unificada. Puede utilizar la API para incluir los datos de su aplicacin en el repositorio de contenido del Servicio y
buscar el ndice de contenido de su aplicacin.
Por ejemplo, imagnese que tiene una gran coleccin de libros y los presta frecuentemente a otras personas.
Quizs sea til crear una aplicacin que le permita catalogarlos y mantener una lista de personas a quienes los
presta. Si esta aplicacin utiliz la API de bsqueda unificada, podra buscar un libro desde la pantalla de inicio o
desde cualquier aplicacin, para encontrar el libro y los datos de contacto de la persona que lo tiene.
Como desarrollador, controla si sus datos aparecen en las bsquedas que los usuarios realizan desde la pantalla de
inicio de un dispositivo BlackBerry, desde otras aplicaciones del dispositivo o slo desde su aplicacin. Adems,
puede buscar los datos de otras aplicaciones cuando estn registrados en el Servicio de bsqueda unificada.
Hacer que los datos puedan ser encontrados

Hay dos maneras de incluir sus datos en resultados de la bsqueda del Servicio de bsqueda unificada. Si quiere
exponer los datos en su aplicacin, debe implementar la interfaz EntityBasedSearchable. En esta situacin,
debe ajustar sus datos en una clase que implemente la interfaz SearchableEntity. Si quiere pasar una consulta
de bsqueda a su propio motor de bsqueda, situado en un servidor de red o dentro de su aplicacin, debe
implementar la interfaz ExternalSearchProvider. Los motores de bsqueda disponibles en un servidor
pueden estar situados detrs de un firewall de empresa o ser un servicio pblico de Internet.
Exponer los datos de sus aplicaciones

El Servicio de bsqueda unificada mantiene un ndice de contenido en un dispositivo BlackBerry . Su aplicacin
utiliza las clases SearchRegistry, AppContentManager y AppContentListener para comunicarse con el
servicio de bsqueda unificada. Para hacer que los datos de su aplicacin puedan encontrarse, debe realizar cinco
tareas.
Tarea
Defina una clase
EntityBasedSearchable para
sus objetos SearchableEntity.
Descripcin
Un objeto EntityBasedSearchable representa sus datos que se pueden
buscar para el servicio de bsqueda unificada. Cuando registra su
EntityBasedSearchable, el servicio solicita que su aplicacin prepare
los datos para su envo llamando a EntityBasedSearchable.load().
Cuando sus datos de aplicaciones estn listos para su envo, debe invocar
completed() en el parmetro NotificationListener pasado a
load().
Gua de desarrollo
Tarea
Encapsule sus datos en un objeto
SearchableEntity.
Descripcin
Un objeto SearchableEntity es la unidad ms pequea de datos que
una aplicacin puede enviar al servicio de bsqueda unificada. Su objeto
EntityBasedSearchable enva sus objetos SearchableEntity al
servicio cuando se le pregunta. Debe encapsular sus datos de aplicaciones
en un objeto SearchableEntity. El Servicio indexa los metadatos
expuestos por estos objetos para que sean considerados durante las
operaciones de bsqueda. Adems, los objetos SearchableEntity se
devuelven en resultados de bsqueda del servicio.
El Servicio de bsqueda unificada puede necesitar interrumpir su operacin
de carga si el dispositivo BlackBerry est ocupado o tiene un nivel bajo de
batera. Si es necesaria una interrupcin, el servicio invoca
EntityBasedSearchable.pause(). Cuando el servicio detecta que su
operacin puede continuar, invoca
EntityBasedSearchable.resume(). Responda a estos eventos de
manera oportuna para que su aplicacin no provoque la interrupcin de
otras aplicaciones del dispositivo.
Registre su objeto
EntityBasedSearchable con el
Servicio de bsqueda unificada.
Notifique al Servicio de bsqueda

unificada acerca de los cambios
hechos a sus datos.
Rastree las respuestas del Servicio
de bsqueda unificada.
Despus de que notifique al Servicio de bsqueda unificada que sus datos

estn listos, ste llama a
EntityBasedSearchable.getSearchableEntities() para indexar
sus datos. El Servicio puede invocar load() y getSearchableEntities()
de nuevo si detecta que su ndice de contenido y sus datos no estn
sincronizados.
Despus de que prepare sus datos para la bsqueda y defina cmo se
indexarn, debe registrar EntityBasedSearchable con el Servicio de
bsqueda unificada. Pase EntityBasedSearchable cuando invoque
SearchRegistry.register(). A continuacin, el Servicio recupera e
indexa sus datos para su inclusin en los resultados de la bsqueda.
Para notificar al ndice de contenido los cambios en sus datos de
aplicaciones, utilice los mtodos insert(), delete() y update() en el
objeto AppContentManager.
Cuando notifica al Servicio de bsqueda unificada los cambios en sus datos
de aplicaciones, debe proporcionar un objeto AppContentListener
donde el Servicio pueda notificar a su aplicacin el resultado de su solicitud.
El siguiente diagrama ilustra la relacin entre los componentes utilizados en las tareas anteriores.
Gua de desarrollo
Pasar consultas a otros motores de bsqueda

Puede utilizar la interfaz ExternalSearchProvider para pasar las consultas a otro motor de bsqueda. Por
ejemplo, una aplicacin en un dispositivo BlackBerry que tiene una manera eficaz de buscar sus propios datos
podra dar a los usuarios y a otras aplicaciones acceso a sus datos implementando ExternalSearchProvider.
De forma alternativa, una compaa de seguros puede tener una aplicacin que permita a representantes hacer
bsquedas en una base de datos de plizas de seguros. La empresa podra ofrecer a sus representantes de ventas
acceso al motor de bsqueda de directivas detrs del firewall, desde un dispositivo BlackBerry, implementando
ExternalSearchProvider.
Hay dos maneras en las que los usuarios pueden ampliar una bsqueda. La caracterstica Universal de la pantalla
Inicio muestra los proveedores de bsqueda externos al final de la lista de resultados de la bsqueda. Si un
usuario hace clic en el icono de su aplicacin en el resultado de la bsqueda, el Servicio de bsqueda unificada
invoca search() desde su objeto ExternalSearchProvider. Su aplicacin es entonces responsable de crear
una conexin con el proveedor de bsqueda (otra aplicacin o sobre una red), pasando la cadena de consulta y
mostrando cualquier resultado que recupere.
Otras aplicaciones pueden invocar su aplicacin en una manera semejante. El mtodo
UnifiedSearchServices.getSearchProviders() devuelve una lista de todos los proveedores externos de
bsqueda que se instalaron en un dispositivo BlackBerry. De este modo, una aplicacin puede encontrar y utilizar
su ExternalSearchProvider especficamente, o permitir que el usuario elija uno de la lista.
Para garantizar que su aplicacin aparezca en la lista de proveedores externos de bsqueda, debe registrar
ExternalSearchProvider con el Servicio de bsqueda unificada. Pase su objeto ExternalSearchProvider
cuando invoque SearchRegistry.register().
El diagrama siguiente muestra la relacin entre algunos de los componentes necesarios para implementar
ExternalSearchProvider.
Definir una clase EntityBasedSearchable para sus objetos SearchableEntity.
Gua de desarrollo
Definir una clase EntityBasedSearchable para sus objetos

SearchableEntity.
Su implementacin de la interfaz EntityBasedSearchable administra la relacin entre el servicio de bsqueda
unificada y las entidades que cree y se puedan buscar. Cada objeto EntityBasedSearchable administra un
grupo de objetos SearchableEntity que tienen las mismas propiedades que se pueden buscar.
1.

import net.rim.device.api.unifiedsearch.SearchField;
import net.rim.device.api.unifiedsearch.searchables.EntityBasedSearchable;
import
net.rim.device.api.unifiedsearch.searchables.SearchableContentTypeConstants;
import net.rim.device.api.unifiedsearch.searchables.Searchable;
2.
Cree las variables de instancia para almacenar informacin que sea pertinente a su EntityBasedSearchable.
private
private
private
private
private
private
3.
MySearchableEntity[] _myEntities; // You will need this in steps 8 and 11

long _registrationID;
SearchField[] _searchFields;
Image _icon;
final Object _monitor = new Object();
boolean _wait = false;
En el constructor, cree una matriz de objetos SearchField. Cada SearchField almacena el nombre de una
propiedad de sus datos que se puede buscar. En el siguiente ejemplo de cdigo, los objetos de datos de aplicacin
administrados por esta clase tienen tres propiedades que se pueden buscar. Por ejemplo, si los datos de su
aplicacin modelaron libros, estos campos pueden incluir el ttulo, el editor y el nmero de pginas.
class MyEBS implements EntityBasedSearchable
{
_searchFields = new SearchField[3];
4.
10
Asigne un nombre significativo a cada SearchField.
Gua de desarrollo
5.
6.
_searchFields[0] = new SearchField("Title");

_searchFields[1] = new SearchField("Publisher");
_searchFields[2] = new SearchField("Number of pages");
Cree un icono que aparecer en los resultados de bsqueda que incluyan las entidades que se pueden buscar
administradas por EntityBasedSearchable. Para obtener ms informacin acerca de crear iconos, consulte
"Personalizacin de la apariencia de sus datos en los resultados de la bsqueda ".
Implemente getType(). Devuelva el tipo de contenido que encaje mejor con los datos de su aplicacin. Para
ver una lista de tipos de contenido vlidos, consulte la interfaz
net.rim.device.api.unifiedsearch.searchables.SearchableContentTypeConstants en la
referencia de la API.
public long getType() {
return SearchableContentTypeConstants.CONTENT_TYPE_MEMO;
7.
Elija los iniciadores de bsqueda que deben recibir resultados de bsqueda desde su aplicacin. Para obtener
ms informacin acerca de la exposicin de sus datos a las bsquedas, consulte la clase
net.rim.device.api.unifiedsearch.entity.ExposureLevel en la referencia de la API.
public int getPrivacyLevel() {
return ExposureLevel.LEVEL_PUBLIC;
}
8.
Implemente load(). Si el dispositivo BlackBerry est ocupado o el nivel de batera es bajo, puede que tenga
que detener la operacin de este mtodo y reanudarlo cuando le sea solicitado.
a. Para EntityBasedSearchable, determine cuntos objetos de datos existen actualmente en su
aplicacin.
public void load (NotificationListener observer, int loadType) {
Vector myObjects = MyObjectManager.getDataObjects();
if (myObjects != null) {
int size = myObjects.size()
if(size < 1) {
_myEntities = new MySearchableEntity[0];
} else {
_myEntities = new MySearchableEntity[size];
}
} else {
// handle the condition where you have no data objects
}
b.
Utilice un bucle while para rellenar una matriz de entidades que se pueden buscar.
Enumeration objects = myObjects.elements();
int count = 0;
while (objects.hasMoreElements()) {
c.
Compruebe si el servicio de bsqueda unificada ha enviado un comando pause. Si es as, detenga la

operacin que rellena su matriz de entidades que se pueden buscar y notifqueselo al Servicio.
if (_wait){
try {
synchronized(_monitor) {
11
Gua de desarrollo
observer.partiallyCompleted(this, null,
NotificationListener.TYPE_SEARCHABLE);
_monitor.wait();
}
} catch (InterruptedException e){
observer.error(e);
return;
}
}
d.
Cuando su aplicacin recupere el control del subproceso, contine rellenando su matriz de entidades que
se pueden buscar.
e.
Notifique al Servicio de bsqueda unificada cuando haya terminado de cargar sus datos.
}
9.
MyObject dataObject = (MyObject) objects.nextElement();

_myEntities[count++] = new MySearchableEntity(dataObject, this);
observer.completed(this, NotificationListener.TYPE_SEARCHABLE);
El servicio de bsqueda unificada invoca getSearchableEntities() a continuacin para recuperar la matriz

que ha rellenado.
En pause(), cambie el valor de la variable _wait a true. El Servicio de bsqueda unificada llama a este mtodo
cuando quiere que su aplicacin deje de cargar datos.
public void pause() {
_wait = true;
}
10. En resume(), cambie el valor de la variable _wait a false. Tambin, notifique al mtodo load() que puede
reanudar la ejecucin. El servicio de bsqueda unificada invoca resume() cuando desea que su aplicacin
reanude los datos que carga.
public void resume() {
_wait = false;
synchronized(_monitor) {
_monitor.notifyAll();
}
}
11. En getSearchableEntities(), devuelva la matriz _myEntities que cre en el paso 8.

public SearchableEntity[] getSearchableEntities() {
return _myEntities;
}
Personalizar la apariencia de sus datos en los resultados de la bsqueda

El mtodo getIcon(), en las interfaces EntityBasedSearchable y SearchableEntity, especifica el icono
que aparece en los resultados de la bsqueda. En la caracterstica de bsqueda Universal de la pantalla Inicio, los
resultados de la bsqueda se agrupan por aplicacin. El mtodo EntityBasedSearchable.getIcon()
especifica el icono que aparece para el grupo.
12
Gua de desarrollo
Tambin puede especificar un icono para diferentes categoras de entidades que se pueden buscar. Por ejemplo,
si crea una aplicacin para catalogar libros, quiz quiera tener iconos diferentes para categoras diferentes de
libros, como superventas, libros grandes y primeras ediciones. Estas categoras son de toda clase de libros, as que
se incluiran lgicamente en un objeto EntityBasedSearchable que administr los libros. Sin embargo, una
aplicacin que los muestre quiz quiera dar una indicacin visual para ayudar al usuario a determinar rpidamente
si puede encontrar un libro en un estante regular, un estante grande o en una sala con control ambiental. En este
caso, podra crear tres clases SearchableEntity para ajustar tres clases diferentes de objetos de libro, cada una
con su propia implementacin de getIcon(). Las tres clases seguiran estando administradas por un solo
EntityBasedSearchable.
Especificar un icono en EntityBasedSearchable o en la clase

SearchableEntity
Antes de comenzar: Incluya un archivo grfico adecuado para utilizarlo como icono en la carpeta de recursos de
su proyecto. Para obtener ms informacin acerca de disear grficos para dispositivos BlackBerry, consulte
Directrices sobre IU.
1.
Importe las clases necesarias.

import net.rim.device.api.ui.image.Image;
import net.rim.device.api.ui.image.ImageFactory;
import net.rim.device.api.system.Bitmap;
2.
Cree una variable de instancia para almacenar el icono.

private Image _icon;
3.
Importe el grfico a su aplicacin desde su carpeta de recursos.

Bitmap img = Bitmap.getBitmapResource("icon.png")
4.
Compruebe si la importacin fue correcta y a continuacin cree un icono.

if(img != null) {
_icon = ImageFactory.createImage(img);
} else {
_icon = null;
}
5.
En getIcon(), devuelva la imagen.

public Image getIcon() {
return _icon;
}
13
Encapsular datos en la clase SearchableEntity
Gua de desarrollo

El servicio de bsqueda unificada indexa los metadatos expuestos por un objeto SearchableEntity. El servicio
tambin devuelve SearchableEntity como el contenido de un resultado de la bsqueda. Debe preparar los
datos de su aplicacin para el servicio encapsulndolos en su clase SearchableEntity.
1.

import
import
import
import
import
2.
net.rim.device.api.unifiedsearch.SearchField;
net.rim.device.api.unifiedsearch.SearchFieldCriteria;
net.rim.device.api.unifiedsearch.SearchFieldCriteriaList;
net.rim.device.api.unifiedsearch.entity.SearchableEntity;
net.rim.device.api.unifiedsearch.searchables.Searchable;
Recupere una matriz de objetos SearchField de EntityBasedSearchable.

SearchField[] searchfields = mySearchable.defineSupportedSearchFields();
3.
Cree un objeto SearchFieldCriteria para cada una de sus propiedades que se pueden buscar. En el ejemplo
de cdigo siguiente, el objeto de datos de aplicaciones myObject tiene un mtodo getProperty() que
devuelve una cadena para un ndice dado. Por ejemplo, si myObject describi un libro, los ndices 0, 1 y 2 de
getProperty() podran devolver el nombre, el editor y el nmero de pginas del libro.
int size = searchfields.length
SearchFieldCriteria[] criteria = new SearchFieldCriteria[size];
for (int i = size -1; i >= 0; --i) {
criteria[i] = new SearchFieldCriteria(searchfields[i], new String[]
{myObject.getProperty(i)});
}
4.
Cree y rellene un objeto SearchFieldCriteriaList para mantener sus criterios de campo de bsqueda.
SearchFieldCriteriaList _sfcl = new SearchFieldCriteriaList();
for (int i = size -1; i >= 0; --i) {
sfcl.addCriteria(criteria[i]);
}
5.
Implemente getSearchCriteria() para devolver SearchFieldCriteriaList.

pubic SearchFieldCriteriaList getSearchCriteria() {
return _sfcl;
}
6.
En getData(), devuelva su objeto de datos de aplicaciones. Continuando con el ejemplo del libro, este mtodo
devolvera un objeto que representa al libro.
public Object getData() {
return myObject;
}
7.
14
En getTitle(), asigne un ttulo a esta entidad que se puede buscar. El texto del ttulo aparece en los resultados
de la bsqueda. Para continuar con el ejemplo del libro, myObject.getName() podra devolver el nombre de
un libro.
Gua de desarrollo
Specifying what users can do with your data in search results
public String getTitle() {

return myObject.getName();
}
8.
En getSummary() proporcione un resumen de los datos en esta entidad que se puede buscar. El texto del
resumen aparece en los resultados de la bsqueda. Continuando con el ejemplo del libro,
myObject.getDescription() podra devolver una descripcin del libro.
public String getSummary() {
return myObject.getDescription();
}
9.
Implemente getSearchable(). Recupere el EntityBasedSearchable que su aplicacin crea para

administrar este objeto, y devulvalo.
public Searchable getSearchable() {
return myPublisher.getSearchable();
}
10. Defina qu opciones deben aparecer en el men contextual cuando un usuario del dispositivo BlackBerry haga
clic en su entidad desde una lista de resultados de la bsqueda. Para obtener ms informacin, consulte
"Especifique lo que pueden hacer los usuarios con sus datos en los resultados de la bsqueda".
11. Si desea que SearchableEntity muestre un icono diferente al de su icono de aplicacin, proporcione el icono
en getIcon(). Para obtener ms informacin, consulte "Personalizacin de la apariencia de sus datos en los
resultados de la bsqueda".
Specifying what users can do with your data in search

results
When a user selects your search result and presses the menu key, the BlackBerry device displays a list of
operations the user can perform with that data. For example, if your application holds recipes, you might want to
enable your user to email a recipe or add the ingredients to a shopping list from a list of search results. Each item
in a search result represents a SearchableEntity object from an application that registered data with the
Unified Search Service. The UiAction class helps you specify an operation that a user or an application can invoke
on your SearchableEntity objects.
In your application, you must create a UiAction subclass for each operation you want to make available to your
user. You can expose your UiAction objects by using the getUiActions(Object, UiAction[]) method of
your SearchableEntity object. You must configure an alternate entry point for the Unified Search Service to
execute the operation a user selects.
15
Gua de desarrollo
Specify an operation for a selected search result

A UiAction subclass defines an operation that is available to users when they select an item in a list of search
results provided by the Unified Search Service. The following steps demonstrate how to create a class named
DisplayBookInfo that enables a user to display detailed information about a book in an application that stores
information about books.
1.
Import the required classes and interfaces.

import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.unifiedsearch.action.UiAction;
2.
Declare a class that extends UiAction, and create an empty constructor.

class DisplayBookInfo extends UiAction
{
DisplayBookInfo ()
{
}
3.
In the runAction() method, retrieve the SearchableEntity object that the user selected from a search
result.
protected void runAction()
{
BookEntity book = (BookEntity) this.getSearchableEntity();
4.
In runAction(), Create an instance of the DisplayBookScreen class to display the book information. Provide
the SearchableEntity object that you retrieved to the new screen object.
DisplayBookScreen showBook = new DisplayBookScreen(book);
5.
Invoke pushScreen() to make the new screen object visible.

}
6.
UiApplication.getUiApplication().pushScreen(showBook);
Implement the toString() method to provide a description of the operation this class performs.
public String toString() {
return "Show book info";
}
7.
Implement the getIcon() method to associate an icon with this operation. In this task, no icon is provided.
16
public Image getIcon() {

return null;
}
Gua de desarrollo
8.
In the getUiActions() method of your SearchableEntity class, populate the uiActions parameter with
your actions like DisplayBookInfo. Change the uiActions array reference using the Arrays object. If you
try to change the array without the Arrays object, you will create a local copy of the array. Your local copy is
not passed back to the application that requested your UiAction objects.
In the following code sample, the ActionTwo and ActionThree classes were added to provide a more complete
example.
public UiAction getUiActions(Object contextObject, UiAction[] uiActions) {
ActionOne act1 = new ActionOne(this);
Arrays.add(uiActions, act1);
Arrays.add(uiActions, new ActionTwo());
Arrays.add(uiActions, new ActionThree());
9.
Return the UiAction object you want to highlight the menu of actions by default.
return act1;
Provide an alternate entry point for your application

Your application must detect when the BlackBerry device activates it using an alternate entry point. The following
steps demonstrate how to enable an application to accept an alternate entry point for a UiAction object.
Antes de comenzar: Configure an alternate entry point for your application. For more information about declaring
an alternate entry point in your project, see Specify the alternate entry point settings for a BlackBerry application
project.
1.

2.
Create the application framework by extending the UiApplication class.

public class MyApp extends UiApplication
{
public static void main(args[])
{
}
3.
public MyApp(String entryPoint)

{
}
In the main() method, indentify whether a user launched the application from the Home screen of a BlackBerry
device, or through a search result. This step assumes that you configured an alternate entry point for your project
named uiAction.
if( args != null && args.length > 0 && args[0].equals("uiAction"))
{
4.
Create an application object. Provide the entry point type as a parameter.

17
Gua de desarrollo
app = new MyApp("uiAction");

} else
{
app = new MyApp("user");
}
5.
Start your application.

app.enterEventDispatcher;
6.
In your application constructor, indentify the entry point used to launch the application.
if(entryPoint.equals("normal")
{
7.
If the your appilcation was launched from the Home screen, display your first screen.
{
8.
pushScreen(new MyAppScreen());
If a user launched your application from a search result, do nothing. The application that provided the search
result prompts your application to execute the UiAction automatically.
} else
{
}
Expose your UiAction objects

You must implement the SearchableEntity.getUiActions(Object, UiActions[]) method to expose
your UiAction objects. The following steps demonstrate how to expos an object based on a class named
DisplayBookInfo, created in Create a UiAction subclass.
Antes de comenzar: Create a class that implements the SearchableEntity interface. For more information, see
Encapsulate your data in the SearchableEntity class.
1.
In your SeachableEntity implementation, import the Arrays class.

import net.rim.device.api.util.Arrays;
2.
In your SearchableEntity.getUiAction(Object, UiAction[]) method, instantiate a

DisplayBookInfo object.
displayAction = new DisplayBookInfo();
3.
Invoke the setEntryPointIndex() method and specify a single parameter with a value of 1. This configures
the UiAction object to use an alternate entry point for your application.
displayAction.setEntryPointIndex(1);
4.
In your SearchableEntity.getUiAction(Object, UiAction[]) method, invoke the Arrays.add()

method to add displayAction to the UiAction[] parameter.
Arrays.add(uiActions, displayAction);
18
Registrar su objeto EntityBasedSearchable en el Servicio de bsqueda unificada
Gua de desarrollo
5.
Return displayAction set the default opertion for SearchableEntity.

return displayAction;
Despus de terminar: You must provide an alternate entry point for your application. For more information, see
Provide an alternate entry point for your application.
Registrar su objeto EntityBasedSearchable en el Servicio de

bsqueda unificada
Despus de definir su clase SearchableEntity y crear una clase EntityBasedSearchable para representar
sus entidades que se pueden buscar en el Servicio de bsqueda unificada, utilice SearchRegistry para
registrarlas con el Servicio de bsqueda unificada.
1.

import net.rim.device.api.unifiedsearch.registry.RegistrationToken;
import net.rim.device.api.unifiedsearch.registry.SearchRegistry;
2.
Cree su EntityBasedSearchable.
public class MyClass {
private MySearchable _searchable;
private RegistryToken _regToken;
public MyClass() {
_searchable = new MySearchable()
3.
Registre su EntityBasedSearchable con el Servicio de bsqueda unificada.

_regToken = SearchRegistry.getInstance().register(_searchable);
4.
Es recomendable comprobar si el registro ha sido correcto.
if (! _regToken.isValid()) {
// Action to take if the registration is not valid.
}
Nota: El identificador del registro es nico para su EntityBasedSearchable hasta que el dispositivo BlackBerry
se reinicie. Debe almacenar su identificador de registro y volver a utilizarlo cuando actualice el contenido
mediante la clase AppContentManager.
19
Gua de desarrollo
Notificar al Servicio de bsqueda unificada acerca de los cambios hechos a sus datos
Notificar al Servicio de bsqueda unificada acerca de los

cambios hechos a sus datos
Cuando su aplicacin cambie, elimine o cree nuevos datos que pueden buscarse, puede notificrselo al Servicio de
bsqueda unificada mediante el objeto AppContentManager.
Antes de comenzar: Recupere un identificador de registro para comunicarse con el Servicio de bsqueda
unificada. Una aplicacin recupera un identificador de registro cuando registra un objeto
Defina una variable (como _myListener en el siguiente ejemplo de cdigo) para una implementacin de
AppContentListener. Para obtener ms informacin, consulte "Rastrear las respuestas del Servicio de
bsqueda unificada".
1.

import net.rim.device.api.unifiedsearch.content.AppContentManager;
2.
Para actualizar un objeto SearchableEntity que el Servicio de bsqueda unificada ya ha indexado, invoque
updateContent().
public void updateUSS(MyEntity entity, RegistrationToken regToken) {

MyEntity[] toUpdate = new MyEntity[1];
toUpdate[0] = entity;
AppContentManager.getInstance().updateContent(toUpdate, _myListener, regToken);
}
3.
Para eliminar un objeto SearchableEntity, invoque deleteContent().

public void deleteUSS(MyEntity entity, RegistrationToken regToken) {
MyEntity[] toDelete = new MyEntity[1];
toDelete[0] = entity;
AppContentManager.getInstance().deleteContent(toDelete, _myListener, regToken);
}
4.
Para insertar un nuevo SearchableEntity, invoque el mtodo insertContent().

public void insertUSS(MyEntity entity, RegistrationToken regToken) {
MyEntity[] toInsert = new MyEntity[1];
toInsert[0] = entity;
AppContentManager.getInstance().insertContent(toInsert, _myListener, regToken);
}
Rastrear las respuestas del Servicio de bsqueda unificada

Cuando manipula contenido con mtodos AppContentManager, debe especificar la clase que implementa la
interfaz AppContentListener. Despus de que el Servicio de bsqueda unificada haya procesado su solicitud, se
lo notifica al mtodo AppContentListener correspondiente a la operacin solicitada.
Cada mtodo AppContentManager tiene un parmetro que indica cuntos objetos se han visto afectados por la
operacin. Si la operacin falla, el valor del parmetro es 0.
20
Eliminar sus datos del repositorio de contenido
Gua de desarrollo
Ejemplo de cdigo: Implementar la interfaz AppContentListener

public class MyListener implements AppContentListener {
public void onDeleteComplete(int delCount) {
// Action to take after records deleted.
}
public void onInsertComplete(int insertCount) {
// Action to take after new records inserted.
}
public void onUpdateComplete(int updCount) {
// Action to take after records updated.
}
}

Dependiendo del ciclo de vida de su aplicacin, quiz tenga que eliminar todos los datos de su aplicacin del
repositorio de contenido del Servicio de bsqueda unificada. Por ejemplo, un usuario de dispositivo BlackBerry
puede tener mltiples cuentas en su aplicacin. Podra ser conveniente que los datos de la aplicacin aparezcan
en resultados de bsqueda slo si el usuario est actualmente autenticado por su aplicacin. De forma alternativa,
su aplicacin puede necesitar responder a cambios de configuracin regional. En este caso, debe eliminar los
datos del repositorio de contenido y a continuacin volver a rellenarlo con los datos apropiados para la
configuracin regional actual.
La siguiente tabla describe dos enfoques para eliminar todos los datos de su aplicacin del repositorio de
contenido del Servicio de bsqueda unificada.
Enfoque
Elimine el registro de un objeto
Descripcin
Este enfoque elimina su objeto EntityBasedSearchable y todos los
datos asociados con l del ndice de contenido del Servicio de bsqueda
unificada. Su EntityBasedSearchable ya no aparece en la lista de
fuentes de datos que se pueden buscar registradas en el dispositivo
BlackBerry.
Para eliminar el registro de EntityBasedSearchable, invoque
SearchRegistry.deregister() y pase el identificador de registro
devuelto cuando se registr EntityBasedSearchable.
Elimine todos los datos del

repositorio de contenido de un
objeto EntityBasedSearchable.
Este enfoque elimina todos los datos de su aplicacin del repositorio. Puede
utilizar este enfoque cuando deba eliminar todos los datos y sin embargo
planea continuar rellenando el repositorio con datos nuevos en un futuro
prximo.
Para eliminar todos los datos del repositorio de contenido para
EntityBasedSearchable, invoque
UnifiedSearchServices.removeAllData() y pase el identificador de
registro que se devolvi cuando se registr EntityBasedSearchable.
21
Gua de desarrollo
Utilizar otros motores de bsqueda

La interfaz ExternalSearchProvider permite que los usuarios de BlackBerry busquen datos fuera del Servicio
de bsqueda unificada. Si un usuario recibe un resultado de bsqueda poco satisfactorio, puede hacer clic en
otros proveedores de bsqueda externos utilizando la caracterstica de bsqueda Universal de la pantalla de
inicio. Estos proveedores de bsqueda implementan la interfaz ExternalSearchProvider.
Cuando un usuario hace clic en un proveedor de bsqueda, la caracterstica de bsqueda universal invoca
search() para ese ExternalSearchProvider. El proveedor de bsqueda es responsable de crear una
conexin de red o una conexin de comunicacin entre procesos, invocando una bsqueda en el servidor remoto,
recuperando los resultados y mostrndoselos al usuario. Si su aplicacin utiliza un motor de bsqueda remoto,
puede considerar insertar los resultados de la bsqueda en el repositorio de contenido del Servicio de bsqueda
unificada para mejorar la velocidad y la eficiencia de bsquedas posteriores.
Algunos proveedores de bsqueda externos predefinidos son YouTube y Google. Las aplicaciones de terceros
tambin pueden acceder a proveedores de bsqueda externos. El mtodo
UnifiedSearchServices.getSearchProviders() devuelve una lista de objetos registrados
ExternalSearchProvider donde una aplicacin puede enviar una bsqueda.
De forma similar a los objetos EntityBasedSearchable, un ExternalSearchProvider debe registrarse con
el Servicio de bsqueda unificada utilizando el objeto SearchRegistry. Para obtener ms informacin, consulte
"Registrar su objeto EntityBasedSearchable en el Servicio de bsqueda unificada".
Ejemplo de cdigo: Implementar la interfaz ExternalSearchProvider
import net.rim.device.api.ui.image.ImageFactory;
import net.rim.device.api.unifiedsearch.searchables.ExternalSearchProvider;
import net.rim.device.api.unifiedsearch.searchables.SearchableContentTypeConstants;
public class MySearchProvider implements ExternalSearchProvider {
// A unique registration ID for this provider.
private long _regId;
// The external search provider icon.
private Image _icon;
// Constructor
public MySearchProvider() {
// Read the icon from the resource bundle
Bitmap img = Bitmap.getBitmapResource("myicon.png");
if(img != null) {
_icon = ImageFactory.createImage(img);
} else {
_icon = null;
}
}
// The provider name to be displayed.
public String getProviderName() {
return "Sample External Search Provider";
}
// The provider icon to be displayed.
public Image getProviderIcon() {
22
Gua de desarrollo
Asegurar que un dispositivo ejecuta una sola instancia de su aplicacin
return _icon;
}
// The content type this provider offers.
public long getContentType() {
return SearchableContentTypeConstants.CONTENT_TYPE_MEDIA_MEMO;
}
// The search initiator will pass control to your application using this method.
public void search(String keywords) {
// Create network or IPC connections, send search keywords, and display the
results.
}
// Allows the Unified Search Service and your application to keep track of
// this searchable's registration
public long getRegistrationID()
{
return _regId;
}
public setRegistrationID(long id)
{
_regId = id;
}
}
Asegurar que un dispositivo ejecuta una sola instancia de

su aplicacin
Para mejorar la eficiencia de su aplicacin, debe asegurarse de que el dispositivoBlackBerry ejecuta slo una
instancia cuando se invoca search() en su implementacin de ExternalSearchProvider.
1.
En su implementacin de ExternalSearchProvider, los paquetes de importacin le ayudan a descubrir las

aplicaciones que se estn ejecutando en el dispositivo.
import
import
import
import
2.
net.rim.device.api.system.ApplicationDescriptor;
net.rim.device.api.system.ApplicationManager;
net.rim.device.api.system.ApplicationManagerException;
net.rim.device.api.system.CodeModuleManager;
En search(), recupere un identificador para su aplicacin.

public void search(String keywords) {
int modHandle = CodeModuleManager.getModuleHandle("MyApplication");
3.
Recupere una matriz de objetos que representan las aplicaciones que se estn ejecutando en el dispositivo.
ApplicationDescriptor[] allApps =
ApplicationManager.getApplicationManager().getVisibleApplications();
4.
Examine cada elemento de la matriz para determinar si su aplicacin se est ejecutando en el dispositivo.
for(int i = allApps.length -1; i >= 0; --i) {
if(allApps[i].getModuleHandle() == modHandle) {
23
Gua de desarrollo
5.
Si es as, envele las palabras clave de la bsqueda. Invoque postGlobalEvent() para enviar un mensaje a su
aplicacin que debe mostrar una pantalla con los resultados para las palabras clave nuevas. Debe detectar un
evento global publicado en su GUID, en el constructor de su aplicacin.
int procID =
ApplicationManager.getApplicationManager().getProcessId(allApps[i]);
ApplicationManager.getApplicationManager().postGlobalEvent(procID,
your application's GUID, 0, 0, keywords, null);
}
}
6.
Si su aplicacin no se est ejecutando en el dispositivo, recupere un objeto ApplicationDescriptor que

represente a su aplicacin.
ApplicationDescriptor[] myAppDes =
CodeModuleManager.getApplicationDescriptors(modHandle);
7.
Inicie su aplicacin. Pase las palabras clave de la bsqueda como un argumento. En el constructor de su
aplicacin, debe detectar si hay un argumento que contiene palabras clave de bsqueda.
try {
ApplicationManager.getApplicationManager().runApplication(new
ApplicationDescriptor(myAppDes[0], new String[]{keywords}));
}
catch(ApplicationManagerException e)
{
// Process the error condition
}
}
}
8.
En su clase de aplicacin, importe el paquete net.rim.device.api.system.GlobalEventListener para

escuchar eventos globales.
import net.rim.device.api.system.GlobalEventListener;
9.
Importe la clase UiApplication.

10. Registre su aplicacin para rastrear eventos globales, como el que cre en el paso 5 y muestre su primera pantalla.
public class MySearchProviderApp extends UiApplication implements
GlobalEventListener {
public MySearchProviderApp(String searchKeywords) {
addGlobalEventListener(this);
pushScreen(new MySearchScreen(searchKeywords));
}
11. Implemente eventOccured() para responder a eventos globales.

public void eventOccurred(long guid, int data0, int data1, Object object0,
Object object1) {
12. Si su aplicacin se est ejecutando en el dispositivo, cierre la pantalla existente y muestre otra pantalla.
24
Insertar datos al iniciar un dispositivo
Gua de desarrollo
if(guid == G53DDE84S97JHVEK390) {
if(object0 instanceof String) {
popScreen();
pushScreeen(new MySearchScreen((String) object0));
requestForeground();
}
}
13. Pruebe las palabras clave de bsqueda en los argumentos para el mtodo main. Inicie su aplicacin con las
palabras clave dadas o con una cadena vaca si no las hay.
public static void main(String[] args) {

String searchKeywords = "";
if(args != null && args.length > 0) {
searchKeywords = args[0];
}
MySearchProviderApp app = new MySearchProviderApp(searchKeywords);
app.enterEventDispatcher();
}

Cada vez que se reinicia un dispositivo BlackBerry (por ejemplo, cuando se quita la batera), el Servicio de
bsqueda unificada se inicia con un repositorio vaco de registro y contenido. Si desea que los datos de su
aplicacin aparezcan en los resultados de la bsqueda antes de que se ejecute la aplicacin, debe crear un punto
de entrada alternativo que registre las entidades que se pueden buscar cuando se inicia el dispositivo.
Bsquedas
Puede utilizar la clase UnifiedSearchServices para configurar e iniciar una operacin de bsqueda desde su
aplicacin. En el caso ms sencillo, puede buscar todas las fuentes de datos cuando enva una palabra clave al
Servicio de bsqueda unificada. Sin embargo, puede limitar su bsqueda a fuentes de datos especficos que se
pueden buscar y a campos de bsqueda dentro de esas fuentes.
Una vez completada la bsqueda, el Servicio de bsqueda unificada devuelve un objeto SearchResponse que
contiene las entidades que se pueden buscar que coinciden con sus criterios de bsqueda. El Servicio devuelve los
datos organizados por fuente que se puede buscar y por campo de bsqueda. La estructura del resultado le
permite ver los metadatos relacionados con el resultado. De este modo, puede tomar decisiones ms detalladas
acerca de la relevancia de los resultados de la bsqueda para sus usuarios.
25
Bsquedas
Gua de desarrollo
Configurar e iniciar una bsqueda

Esta tarea demuestra cmo iniciar una bsqueda limitada a las entidades que se pueden buscar creadas por su
aplicacin. El mtodo UnifiedSearchServices.search() bloquea la ejecucin del subproceso, as que
doSearch() lo invoca en un subproceso separado.
1.

import net.rim.device.api.unifiedsearch.*;
import net.rim.device.api.unifiedsearch.searchables.*;
import java.util.*;
2.
Cree una variable de instancia para almacenar una referencia al objeto UnifiedSearchServices.
public class MySearchScreen() {
UnifiedSearchServices _uss = UnifiedSearchServices.getInstance();
3.
Recupere una referencia a su objeto EntityBasedSearchable y asgnelo a una variable de instancia. Cuando
recupere una lista de aplicaciones que se pueden buscar en el dispositivo, cambie el valor
SearchableContentTypeConstants por uno que sea apropiado para su bsqueda. Asegrese de realizar
alguna accin si EntityBasedSearchable no se encuentra en el vector deviceSearchables.
MySearchable _searchable = null;
Vector deviceSearchables =
_uss.getDeviceSearchables(SearchableContentTypeConstants.CONTENT_TYPE_MEMO);
for(int i = deviceSearchables.size() -1; i >=0; --i) {
if(deviceSearchables.elementAt(i).getName().equals("name of your searchable"))
{
_searchable = (MySearchable) deviceSearchables.elementAt(i);
}
}
// Do something if _searchable is still null
4.
Cree un mtodo para iniciar la bsqueda. Acepte la palabra clave de la bsqueda como un parmetro en el que
su aplicacin especifica las palabras clave de la bsqueda que proporciona el usuario del dispositivo
BlackBerry. Este mtodo invoca un subproceso nuevo, as que declare el parmetro String como final.
private void doSearch(final String keyword) {
5.
Cree el objeto Thread que ejecutar su bsqueda.

Thread searchThread = new Thread(new Runnable() {
public void run() {
try {
6.
Inicie la bsqueda y recupere los resultados, si los hay. Si hay algn resultado, envelo a otro mtodo para ser
analizado.
SearchResponse results = null;
results = _uss.search(keyword, _searchable);
if(results != null) {
parseResponse(results);
}
26
Bsquedas
Gua de desarrollo
7.
Alcance los errores que surjan.

} catch (Exception e) {
// Do something about the error
}
8.
Complete la definicin Thread y ejectela.

}, "Search Thread");
searchThread.start();
Despus de terminar: Implemente parseResponse. Para obtener ms informacin, consulte "Procesar los
resultados de la bsqueda".
Procesar los resultados de la bsqueda

El objeto SearchResponse que recibe del Servicio de bsqueda unificada estructura sus resultados de bsqueda
por EntityBasedSearchable y los campos de bsqueda que coincidieron con sus palabras clave. Para acceder a
los datos, debe analizar este objeto.
Antes de comenzar: Asegrese de que UnifiedSearchServices.search() ha devuelto un objeto
SearchResponse con datos. Pase SearchResponse a parseResponse().
1.

import
import
import
import
2.
net.rim.device.api.unifiedsearch.entity.*;
net.rim.device.api.util.Arrays;
net.rim.device.api.system.Application;
java.util.*;
Cree una variable de la instancia para almacenar las entidades que se pueden buscar, para mostrrselas al usuario
del dispositivo BlackBerry.
MySearchableEntity[] _myEntities;
3.
Implemente parseResponse. Este mtodo se ejecuta despus de la terminacin de su subproceso de

bsqueda, as que declare el parmetro SearchResponse como final.
private void parseResponse(final SearchResponse searchResult) {
4.
Configure este mtodo para que se ejecute cuando su aplicacin recupere el control sobre el subproceso de
eventos.
Application.getApplication().invokeLater(new Runnable() {
public void run() {
5.
De los resultados de la bsqueda, recupere un objeto Hashtable que contenga campos de bsqueda y
entidades que se pueden buscar para EntityBasedSearchable.
final Hashtable results = searchResult.getSearchResult(_searchable);
6.
Recupere un objeto Enumeration que contenga los valores en Hashtable y declare una matriz para almacenar
los valores nicos desde la enumeracin.
27
Bsquedas
Gua de desarrollo
Enumeration values = results.elements();

Object[] searchableEntities;
7.
Inicialice su matriz de entidades que se pueden buscar y que se mostrarn.

_myEntities = new MySearchableEntity[0];
8.
Itere a travs de la enumeracin de values y agregue los valores nicos a searchableEntities.
});
while(values.hasMoreElements()) {
searchableEntities = (Object[]) values.nextElement();
for(int i = searchableEntities - 1; i >= 0; --i) {
if(!Arrays.contains(_myEntities, searchableEntities[i]) {
Arrays.add(_myEntities, searchableEntities[i]);
}
}
}
La matriz _myEntities contiene un conjunto de objetos nicos MySearchableEntity que puede utilizar para
mostrar los resultados de la bsqueda al usuario.
28
Gua de desarrollo
Compatibilidad de interaccin de dispositivo
Compatibilidad de interaccin de dispositivo
API de capacidad de dispositivo

Puede consultar las capacidades de un dispositivo BlackBerry utilizando la API de capacidad de dispositivo que se
proporciona en el paquete net.rim.device.api.system.capability. Puede utilizar la clase
DeviceCapability para consultar si el dispositivo admite caractersticas especficas, como un teclado virtual o
un teclado fsico, si la caracterstica est actualmente disponible para el usuario del dispositivo BlackBerry (por
ejemplo, si el control deslizante en un dispositivo est abierto y el usuario puede utilizar el teclado fsico), y si su
aplicacin puede acceder actualmente a la caracterstica.
Por ejemplo, DeviceCapability.isVirtualKeyboardAvailable() devuelve true si el dispositivo tiene un
teclado virtual actualmente mostrado. En caso contrario, el mtodo devuelve false.
Puede definir un servicio de escucha para que notifique a la aplicacin acerca de los cambios en las capacidades
especificadas del dispositivo implementando la interfaz DeviceCapabilityListener.
Para ver un ejemplo de cmo utilizar la API de capacidad de dispositivo, consulteDetectar el soporte.
Para obtener ms informacin acerca de la API de capacidad de dispositivo, consulte la referencia de API de
BlackBerry Java SDK.
Detectar el soporte
Puede detectar cundo un dispositivoBlackBerry se conecta a un soporte (como un soporte de manos libres)
utilizando el tipo de capacidad DeviceCapability.TYPE_CRADLE que forma parte de la API de capacidad del
dispositivo.
Puede utilizar DeviceCapability.isSupported() y DeviceCapability.isAvailable() para detectar el
estado del soporte. Los dispositivos que ejecutan BlackBerry Device Software6.0 devuelven true para
isSupported(DeviceCapability.TYPE_CRADLE). Cuando un dispositivo que ejecuta BlackBerry Device
Software 6.0 se conecta a un soporte, isAvailable(DeviceCapability.TYPE_CRADLE) devuelve true.
Cuando detecta una conexin de soporte, puede utilizar la clase CradleProtocol para detectar el tipo y las
propiedades del soporte. CradleProtocol se proporciona en el paquete net.rim.device.api.accessory.
La clase proporciona campos para el tipo de soporte (como un soporte de manos libres, una funda o una estacin
de carga) y sus propiedades (como si un soporte tiene luz o botones que pueden cambiarse mediante
programacin).
CradleProtocol.getCradleType() devuelve el tipo de soporte que el mismo soporte ofrece. Es posible que
un soporte no proporcione su tipo exacto. Por ejemplo, un soporte de manos libres puede devolver
CradleProtocol.TYPE_SIMPLE, en vez de CradleProtocol.TYPE_CAR_KIT.
Ejemplo de cdigo: Detectar si un dispositivo est conectado a un soporte

El siguiente ejemplo de cdigo comprueba si el dispositivo est conectado a un soporte. Si lo est, se muestra el
tipo de soporte.
29
Gua de desarrollo
Detectar el soporte
import net.rim.device.api.accessory.CradleProtocol;
import net.rim.device.api.system.capability.DeviceCapability;
import net.rim.device.api.ui.component.RichTextField;
import net.rim.device.api.ui.container.MainScreen;
class CradleDemoScreen extends MainScreen
{
public CradleDemoScreen()
{
setTitle("Cradle Demo");
RichTextField statusField = new RichTextField();
add(statusField);
boolean isConnected =
DeviceCapability.isAvailable(DeviceCapability.TYPE_CRADLE);
if (isConnected)
{
CradleProtocol myCradle = CradleProtocol.getInstance();
int cradleType = myCradle.getCradleType();
switch (cradleType)
{
case CradleProtocol.TYPE_CAR_KIT:
statusField.setText("Device is connected to a car kit cradle.");
break;
case CradleProtocol.TYPE_AUDIO:
statusField.setText("Device is connected to an audio cradle.");
break;
case CradleProtocol.TYPE_BEDSIDE:
statusField.setText("Device is connected to a charging pod
cradle.");
break;
case CradleProtocol.TYPE_CHARGER:
statusField.setText("Device is connected to a charger cradle.");
break;
case CradleProtocol.TYPE_DESKTOP:
statusField.setText("Device is connected to a desktop cradle.");
break;
case CradleProtocol.TYPE_HOLSTER:
statusField.setText("Device is connected to a holster cradle.");
break;
case CradleProtocol.TYPE_MULTIMEDIA:
statusField.setText("Device is connected to a multimedia
cradle.");
break;
case CradleProtocol.TYPE_SIMPLE:
statusField.setText("Device is connected to a simple cradle.");
break;
default:
statusField.setText("Can't determine type of cradle.");
}
}
else
{
statusField.setText("Device is not connected.");
}
}
}
30
Gua de desarrollo
Gestionar soportes
Gestionar soportes
Puede registrar su aplicacin como gestor de soportes. Un gestor de soportes es una aplicacin que puede iniciar
cuando un dispositivo BlackBerry se conecta a un soporte especfico. Por ejemplo, si su aplicacin ofrece
informacin sobre viajes locales quiz le convendra registrarlo como gestor para soportes de manos libres, para
que pueda iniciarse automticamente cuando el dispositivo se conecte a un soporte de ese tipo.
Para registrar su aplicacin como un controlador de soporte, use
CradleHandlerRegistry.registerHandler(). La clase CradleHandlerRegistry se proporciona en el

paquete net.rim.blackberry.api.cradle. Cuando registre su aplicacin, especifique el tipo de soporte que
quiere gestionar y su descriptor de aplicacin. Los tipos de soporte se definen como campos en la clase
CradleProtocol que se ofrece en el paquete net.rim.device.api.accessory.
El registro como gestor de soportes es persistente. Slo necesita registrar su aplicacin una vez despus de que se
haya instalado en el dispositivo.
Si hay algn gestor registrado para algn tipo de soporte, al usuario le aparecer un cuadro de dilogo cuando el
dispositivo se conecte a ese tipo de soporte.
El usuario puede seleccionar qu gestor desea utilizar, si es que quiere utilizar alguno, y se inicia la aplicacin
gestora seleccionada. El usuario tambin puede indicar que la aplicacin gestora seleccionada debe iniciarse
automticamente la prxima vez que se conecte el soporte del tipo especificado.
31
Gua de desarrollo
Trabajar con los sensores de un dispositivo
El usuario puede cambiar la configuracin del gestor de soportes del dispositivo haciendo clic en Opciones>
Aplicaciones de terceros en la pantalla de inicio.
Ejemplo de cdigo: Registrar a un gestor de soportes
El siguiente ejemplo de cdigo registra la aplicacin actual como gestor de soportes de manos libres.
CradleHandlerRegistry.registerHandler(
CradleProtocol.TYPE_CAR_KIT,
ApplicationDescriptor.currentApplicationDescriptor());

Puede utilizar la clase Sensor que se incluye en el paquete net.rim.device.api.system para determinar la
existencia y los estados de los sensores en un dispositivo BlackBerry. Los sensores con los que puede trabajar
incluyen los sensores de funda, los del control deslizante y los de la tapa.
Puede utilizar la clase SensorListener que tambin se incluye en net.rim.device.api.system para
permitir que una aplicacin de un dispositivo BlackBerry reciba notificaciones cuando cambie el estado de un
sensor.
Buscar un sensor en el dispositivo

Los sensores del dispositivo BlackBerry con los que puede trabajar incluyen los sensores de funda, los del control
deslizante y los de la tapa.
1.

import net.rim.device.api.system.Sensor;
2.
Invoque Sensor.isSupported() y especifique el tipo de sensor que quiere buscar. Los tipos de sensor se
definen como constantes en la clase Sensor. El siguiente ejemplo de cdigo comprueba si el dispositivo tiene
control deslizante.
boolean hasSliderSensor;
hasSliderSensor = Sensor.isSupported(Sensor.SLIDE);
El mtodo devuelve true si el dispositivo contiene el sensor especificado, y devuelve false en caso contrario.
Ejemplo de cdigo: Buscar un sensor en el dispositivo
El siguiente ejemplo de cdigo comprueba si el dispositivo tiene sensor de funda, sensor de control deslizante o
sensor de tapa.
class SensorDemoScreen extends MainScreen
{
private RichTextField statusField;
public SensorDemoScreen()
{
setTitle("Sensor Demo");
32
Gua de desarrollo
statusField = new RichTextField();

add(statusField);
boolean hasHolsterSensor, hasSliderSensor, hasFlipSensor;
hasHolsterSensor = Sensor.isSupported(Sensor.HOLSTER);
hasFlipSensor = Sensor.isSupported(Sensor.FLIP);
statusField.setText("Holster: " + hasHolsterSensor +
"\nSlider: " + hasSliderSensor +
"\nFlip: " + hasFlipSensor);
Comprobar el estado de un sensor

1.

2.
Invoque Sensor.getState() y especifique el tipo de sensor que quiere comprobar. Los tipos de sensor se
definen como constantes en la clase Sensor. El siguiente ejemplo de cdigo comprueba el estado del control
deslizante de un dispositivo BlackBerry.
int sliderState = Sensor.getState(Sensor.SLIDE);
El mtodo devuelve el estado del sensor como una constante int. Las constantes que se pueden devolver se
definen en la clase Sensor. Puede utilizar los mtodos siguientes para determinar si el sensor est en un estado
determinado: Sensor.isSlideClosed(), Sensor.isSlideOpen(), Sensor.isSlideInTransition().
Ejemplo de cdigo: Mostrar el estado del control deslizante del dispositivo
class SensorDemoScreen extends MainScreen implements SensorListener
{
{
add(statusField);
if (Sensor.isSupported(Sensor.SLIDE))
{
switch (sliderState)
{
case Sensor.STATE_SLIDE_CLOSED:
// do something if slider is closed
statusField.setText("Slider is closed.");
break;
case Sensor.STATE_SLIDE_IN_TRANSITION:
// do something if slider in transition
statusField.setText("Slider is between open and closed.");
break;
case Sensor.STATE_SLIDE_OPEN:
// do something if slider is open
statusField.setText("Slider is open.");
33
Gua de desarrollo
break;
default:
statusField.setText("Can't determine state of slider.");
Notificar a una aplicacin cuando cambie el estado de un sensor

1.

import net.rim.device.api.system.SensorListener;
2.
Cree una clase que implemente la interfaz SensorListener.

{
}
3.
En la clase, implemente SensorListener.onSensorUpdate() y realice las acciones necesarias segn el tipo

de sensor (el primer parmetro del mtodo) y el estado nuevo del sensor (el segundo parmetro). El siguiente
ejemplo de cdigo comprueba el estado del control deslizante de un dispositivo BlackBerry.
public void onSensorUpdate(int sensorID, int update)
{
if (sensorID == Sensor.SLIDE)
{
if (update == Sensor.STATE_SLIDE_OPEN)
{
// do something if slider is now open
statusField.setText("Slider is now open.");
}
else if (update == Sensor.STATE_SLIDE_IN_TRANSITION)
{
// do something if slider is now in transition
statusField.setText("Slider state is now in transition.");
}
else if (update == Sensor.STATE_SLIDE_CLOSED)
{
// do something if slider is now closed
statusField.setText("Slider is now closed.");
}
}
}
4.
Invoque SensorListener.addListener() para agregar el servicio de escucha a su aplicacin. Especifique

la aplicacin, el servicio de rastreo que se va a agregar y los tipos de cambios de sensor que se van a rastrear.
El siguiente ejemplo de cdigo agrega un servicio de rastreo a la aplicacin actual para los cambios del control
deslizante. Puede invocar Sensor.removeListener() para eliminar un servicio de escucha.
Sensor.addListener(Application.getApplication(), this, Sensor.SLIDE);
34
Gua de desarrollo
5.
Para escuchar los cambios en varios sensores, actualice el tercer argumento de addListener() para agregar
marcas adicionales de estado de sensor. El siguiente ejemplo de cdigo rastrea los cambios hechos al sensor de
la tapa o al del control deslizante.
Sensor.addListener(Application.getApplication(), this, Sensor.FLIP |
Sensor.SLIDE);
Ejemplo de cdigo: Rastrear los cambios del estado del control deslizante del dispositivo
{
{
add(statusField);
Sensor.addListener(Application.getApplication(), this, Sensor.SLIDE);
}
{
{
{
statusField.setText("Slider is now open.");
}
{
// do something if slider is now in transition
statusField2.setText("Slider state is now in transition.");
}
{
statusField.setText("Slider is now closed.");
}
}
}
}
Ejemplo de cdigo: Trabajar con un sensor

import net.rim.device.api.system.*;
import net.rim.device.api.ui.component.RichTextField;
import net.rim.device.api.ui.container.MainScreen;
public class SensorDemo extends UiApplication
{
public SensorDemo()
{
SensorDemoScreen screen = new SensorDemoScreen();
35
Gua de desarrollo
pushScreen(screen);
}
public static void main(String[] args)
{
SensorDemo app = new SensorDemo();
}
{
private RichTextField statusField1;
private RichTextField statusField2;
{
statusField1 = new RichTextField();
statusField2 = new RichTextField();
add(statusField1);
add(statusField2);
// Check for the presence of a sensor
boolean hasFlipSensor, hasHolsterSensor, hasSliderSensor;
hasFlipSensor = Sensor.isSupported(Sensor.FLIP);
hasHolsterSensor = Sensor.isSupported(Sensor.HOLSTER);
statusField1.setText("Flip: " + hasFlipSensor + "\nHolster: "
+ hasHolsterSensor + "\nSlider: " + hasSliderSensor + "\n");
// Check for the state of a sensor
if (Sensor.isSupported(Sensor.SLIDE))
{
switch (sliderState)
{
case Sensor.STATE_SLIDE_CLOSED:
// do something if slider is closed
statusField2.setText("Slider is closed.");
break;
case Sensor.STATE_SLIDE_IN_TRANSITION:
// do something if slider in transition
statusField2.setText("Slider is between open and closed.");
break;
case Sensor.STATE_SLIDE_OPEN:
// do something if slider is open
statusField2.setText("Slider is open.");
break;
default:
statusField2.setText("Can't determine state of slider.");
}
}
// Listen for changes to a sensor
Sensor.addListener(Application.getApplication(), this,
Sensor.SLIDE);
}
// implementation of SensorListener.onSensorUpdate()
// only checks for slider changes
{
36
Gua de desarrollo
{
statusField2.setText("Slider is now open.");
}
{
// do something if slider is now transitioning
statusField2.setText("Slider state is changing.");
}
{
statusField2.setText("Slider is now closed.");
}
37
Lista de mensajes
Gua de desarrollo
Lista de mensajes
Esta seccin describe cmo utilizar las capacidades de mensajera del dispositivo BlackBerry.
Para obtener ms informacin, consulte la descripcin general de las categoras de mensajera en la referencia de
la API para BlackBerry Java Development Environment.
Crear un mensaje de texto SMS en blanco nuevo

1.

import net.rim.blackberry.api.invoke.Invoke;
import net.rim.blackberry.api.invoke.MessageArguments;
2.
Invoque Invoke.invokeApplication(). Utilice los parmetros siguientes: el parmetro constante

APP_TYPE_MESSAGES y un objeto MessageArguments nuevo que utilice el campo ARG_NEW_SMS.
new MessageArguments( MessageArguments.ARG_NEW_SMS));
Crear un mensaje de texto rellenado nuevo

Utilice los elementos API en el paquete javax.wireless.messaging (JSR 120).
1.

import
import
import
import
import
2.
javax.microedition.io.Connector;
javax.wireless.messaging.MessageConnection;
javax.wireless.messaging.TextMessage;
Cree y rellene un objeto TextMessage nuevo.

MessageConnection mc = (MessageConnection)Connector.open("sms://");
TextMessage m = (TextMessage)mc.newMessage( MessageConnection.TEXT_MESSAGE );
m.setAddress("sms://5558888");
m.setPayloadText("An SMS message for you");
3.
Invoque Invoke.invokeApplication() con los parmetros siguientes:

APP_TYPE_MESSAGES: un parmetro constante
MessageArguments: un objeto MessageArguments nuevo que utiliza el objeto TextMessage nuevo.
Invoke.invokeApplication( Invoke.APP_TYPE_MESSAGES, new MessageArguments(m) );
Crear un mensaje MMS en blanco nuevo

1.
38
Crear un mensaje de correo electrnico en blanco nuevo
Gua de desarrollo
2.
Invoque Invoke.invokeApplication() mediante el parmetro constante APP_TYPE_MESSAGES y un

objeto MessageArguments nuevo que utilice el campo ARG_NEW_MMS.
new MessageArguments( MessageArguments.ARG_NEW_MMS));
Crear un mensaje de correo electrnico en blanco nuevo

1.

2.

objeto MessageArguments nuevo que utilice el campo ARG_NEW.
new MessageArguments( MessageArguments.ARG_NEW));
Crear un mensaje de correo electrnico rellenado nuevo

1.

import
import
import
import
2.
net.rim.blackberry.api.mail.Address;
net.rim.blackberry.api.mail.Message;
Cree y rellene un objeto Message de correo electrnico nuevo.

Message m = new Message();
Address a = new Address("mLi@rim.com", "Ming Li");
Address[] addresses = {a};
m.addRecipients(net.rim.blackberry.api.mail.Message.RecipientType.TO, addresses);
m.setContent("A message for you...");
m.setSubject("Email for you");
3.

APP_TYPE_MESSAGES
un objeto MessageArguments que utiliza el objeto Message nuevo.
Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES, new MessageArguments(m));
Crear un mensaje PIN en blanco nuevo

1.
39
Crear un mensaje PIN rellenado nuevo
Gua de desarrollo
2.

objeto MessageArguments nuevo que utilice el campo ARG_NEW_PIN.
new MessageArguments( MessageArguments.ARG_NEW_PIN));
Crear un mensaje PIN rellenado nuevo

1.

import
import
import
import
import
2.
net.rim.blackberry.api.mail.PINAddress;
Cree y rellene un mensaje PIN nuevo.

Message m = new Message();
PINAddress pa = new PINAddress("ABCDEF99", "Mark Chapters");
Address[] addresses = {pa};
m.addRecipients( net.rim.blackberry.api.mail.Message.RecipientType.TO,
addresses );
m.setContent("A message for you...");
m.setSubject("PIN message for you");
3.

APP_TYPE_MESSAGES
un objeto MessageArguments que utiliza el mensaje PIN nuevo.
Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGES, new MessageArguments(m));
Recibir una notificacin de mensaje

1.

import net.rim.blackberry.api.mail.event.FolderListener;
import net.rim.blackberry.api.mail.event.StoreListener;
import net.rim.device.api.system.ControlledAccessException;
2.
Implemente las interfaces FolderListener y StoreListener .

public class MailTest implements FolderListener, StoreListener { ... }
3.
40
Busque una ControlledAccessException si su aplicacin accede a un objeto al que no tiene permiso para
acceder.
Gua de desarrollo
Agregar un servicio de escucha al almacn de mensajes

1.

import net.rim.blackberry.api.mail.NoSuchServiceException;
import net.rim.blackberry.api.mail.Session;
import net.rim.blackberry.api.mail.Store;
2.
Cree un bloque try-catch para administrar una NoSuchServiceException.

try
{
}
catch (NoSuchServiceException e)
{
System.out.println(e.toString());
}
3.
Dentro del bloque try-catch, invoque Session.waitForDefaultSession().getStore() para recuperar el

objeto Store.
try
{
Store store = Session.waitForDefaultSession().getStore();
}
{
}
4.
Despus del bloque try-catch, invoque store.addStoreListener() para aadir una instancia
StoreListener al objeto Store.
store.addStoreListener(this);

para actualizaciones por lotes
1.

import net.rim.blackberry.api.mail.event.StoreListener;
2.
Implemente la interfaz StoreListener.

void batchOperation(StoreEvent e)
{
// Perform action when messages added or removed in batch operation.
}
41
Agregar un servicio de escucha a una carpeta
Gua de desarrollo
Agregar un servicio de escucha a una carpeta

1.

import net.rim.blackberry.api.mail.event.FolderListener;
import net.rim.blackberry.api.mail.Folder;
2.
Implemente FolderListener.messagesAdded() y FolderListener.messagesRemoved().

void messagesAdded(FolderEvent e)
{
// Perform processing on added messages.
}
void messagesRemoved(FolderEvent e)
{
// Perform processing on removed messages.
}
3.
Recupere el objeto Folder para el que desea recibir notificaciones de nuevos mensajes.
Folder[] folders = store.list(Folder.INBOX);
Folder inbox = folders[0];
4.
Registre la clase que implementa FolderListener con la carpeta.

inbox.addFolderListener(this);
Recuperar el nmero total de mensajes de correo

electrnico sin leer de todas las carpetas del almacn
1.
Importe la clase necesaria.

2.
Invoque Store.getUnreadMessageCount().
int numUnread = store.getUnreadMessageCount();
Abrir un mensaje
1.

import
import
import
import
import
import
2.
42
java.util.Date;
net.rim.blackberry.api.mail.Folder;
net.rim.blackberry.api.mail.Session;
net.rim.blackberry.api.mail.Store;
Invoque Session.waitForDefaultSession.getStore() para recuperar el almacn de mensajes.
Gua de desarrollo
Recuperar el cuerpo de un mensaje de correo electrnico
Store store = Session.waitForDefaultSession.getStore();
3.
Invoque Store.getFolder() para recuperar la carpeta que contiene el mensaje.

Folder folder = Store.getFolder("SampleFolder");
4.
Invoque folder.getMessages() para recuperar los objetos de mensaje y almacenarlos en una matriz
Message. Itere sobre la matriz y recupere informacin, como el remitente y el asunto, para mostrarla al usuario
del dispositivo BlackBerry.
Message[] msgs = folder.getMessages();
5.
Cuando un usuario selecciona un mensaje de la lista, invoque mtodos en el objeto Message para recuperar el
contenido pertinente de campos y cuerpo que mostrar al usuario.
Message msg = msgs[0]; // Retrieve the first message
Address[] recipients = msg.getRecipients(Message.RecipientType.TO);
Date sent = msg.getSentDate();
Address from = msg.getFrom();
String subject = msg.getSubject();
Object o = msg.getContent();
// Verify that the message is not multipart
if ( o instanceof String )
{
String body = (String)o;
}
//...
6.
Invoque Message.getBodyText() en un mensaje para recuperar el contenido de texto sin formato como una
String. Si el mensaje no contiene texto sin formato, el mtodo devuelve null.

Un mensaje de correo electrnico puede contener texto sin formato, HTML o ambos. El contenido y el orden del
contenido en el mensaje de correo electrnico pueden variar.
Una aplicacin del dispositivo BlackBerry puede utilizar la clase MimeBodyPart para recuperar el contenido HTML
o utilizar la clase TextBodyPart para recuperar el contenido de texto sin formato. Puede utilizar un objeto
MultiPart para recuperar objetos de la clase MimeBodyPart y la clase TextBodyPart.
Por ejemplo, podra recuperar el contenido de un mensaje de correo electrnico para traducir el contenido a un
idioma diferente.
La compatibilidad con texto y HTML se introdujo en BlackBerry Device Software 4.5 para dispositivos BlackBerry
asociados con BlackBerry Enterprise Server 4.1 Service Pack 6 (4.1.6) o BlackBerry Internet Service 2.5.
43
Gua de desarrollo
Recuperar el texto sin formato y el contenido HTML del cuerpo de un

mensaje de correo electrnico utilizando un mtodo recursivo
Cree un mtodo recursivo para recuperar todas las partes del cuerpo de un mensaje de correo electrnico,
incluido el texto sin formato y HTML.
1.

import
import
import
import
import
2.
net.rim.blackberry.api.mail.MimeBodyPart;
net.rim.blackberry.api.mail.Multipart;
net.rim.blackberry.api.mail.SupportedAttachmentPart;
net.rim.blackberry.api.mail.TextBodyPart;
net.rim.blackberry.api.mail.UnsupportedAttachmentPart;
Cree la firma del mtodo para el mtodo recursivo.

void findEmailBody(Object obj) {...}
3.
Cree las variables locales que indican si BlackBerry Attachment Service es compatible con el tipo de archivo
adjunto del mensaje.
boolean _hasSupportedAttachment;
boolean _hasUnsupportedAttachment;
4.
Inicialice las variables locales.

_hasSupportedAttachment = false;
_hasUnsupportedAttachment = false;
5.
Si el parmetro del mtodo es un objeto Multipart, el objeto tiene varios objetos BodyPart. En cada objeto
BodyPart, invoque el mtodo recursivo que busca en el cuerpo de un mensaje de correo electrnico.
if(obj instanceof Multipart)
{
_Multipart mp = (Multipart)obj;
//Extract all of the parts within the Multipart message.
for(int count=0; count < mp.getCount(); ++count)
{
findEmailBody(mp.getBodyPart(count));
}
}
6.
Si el objeto BodyPart es un TextBodyPart, recupere el cuerpo de texto sin formato del mensaje.
else if (obj instanceof TextBodyPart)
{
//This message only has a text body.
TextBodyPart tbp = (TextBodyPart) obj;
readEmailBody(tbp);
}
7.
Compruebe si el objeto BodyPart es un MimeBodyPart.

else if (obj instanceof MimeBodyPart) {...}
44
Gua de desarrollo
8.
Si el objeto BodyPart es un MimeBodyPart, lleve a cabo las acciones siguientes:

a.
Asigne el objeto BodyPart como un MimeBodyPart.

MimeBodyPart mbp = (MimeBodyPart) obj;
b.
Si el objeto MimeBodyPart no contiene archivos adjuntos, recupere el cuerpo del mensaje utilizando el
objeto MimeBodyPart como un parmetro.
if (mbp.getContentType().indexOf(ContentType.TYPE_TEXT_HTML_STRING) != -1)
{
readEmailBody(mbp);
}
c.
Si el objeto MimeBodyPart contiene archivos adjuntos, invoque un mtodo que recupere el cuerpo del
mensaje.
else if
(mbp.getContentType().equals(ContentType.TYPE_MULTIPART_MIXED_STRING) ||
mbp.getContentType().equals(ContentType.TYPE_MULTIPART_ALTERNATIVE_STRING))
{
findEmailBody(mbp.getContent());
}
9.
Si el BodyPart es un archivo adjunto compatible con BlackBerry Attachment Service, cambie la variable local
pertinente a true.
else if (obj instanceof SupportedAttachmentPart)
{
_hasSupportedAttachment = true;
}
10. Si el BodyPart es un archivo adjunto no compatible con BlackBerry Attachment Service, cambie la variable local
pertinente a true.
else if (obj instanceof UnsupportedAttachmentPart)
{
_hasUnsupportedAttachment = true;
}
Ejemplo de cdigo: Recuperar el contenido de un mensaje de correo electrnico

private void findEmailBody(Object obj)
{
//Reset the attachment flags.
_hasSupportedAttachment = false;
_hasUnsupportedAttachment = false;
if(obj instanceof Multipart)
{
Multipart mp = (Multipart)obj;
for(int count=0; count < mp.getCount(); ++count)
{
findEmailBody(mp.getBodyPart(count));
}
45
Gua de desarrollo
}
else if (obj instanceof TextBodyPart)
{
TextBodyPart tbp = (TextBodyPart) obj;
readEmailBody(tbp);
}
else if (obj instanceof MimeBodyPart)
{
MimeBodyPart mbp = (MimeBodyPart)obj;
if (mbp.getContentType().indexOf(ContentType.TYPE_TEXT_HTML_STRING) != -1)
{
readEmailBody(mbp);
}
}
else if (mbp.getContentType().equals(ContentType.TYPE_MULTIPART_MIXED_STRING) ||
mbp.getContentType().equals(ContentType.TYPE_MULTIPART_ALTERNATIVE_STRING))
{
//The message has attachments or we are at the top level of the message.
//Extract all of the parts within the MimeBodyPart message.
findEmailBody(mbp.getContent());
}
else if (obj instanceof SupportedAttachmentPart)
{
_hasSupportedAttachment = true;
}
else if (obj instanceof UnsupportedAttachmentPart)
{
_hasUnsupportedAttachment = true;
}
Recuperar el contenido de texto sin formato de un mensaje de correo

electrnico
En la tarea siguiente, puede aparecer una excepcin al invocar el mtodo Transport.more().
1.

import
import
import
import
2.
net.rim.blackberry.api.mail.BodyPart;
net.rim.blackberry.api.mail.TextBodyPart;
net.rim.blackberry.api.mail.Transport;
net.rim.device.api.ui.component.Dialog;
Cree un mtodo que tome un objeto TextBodyPart como parmetro.

void readEmailBody(TextBodyPart tbp);
3.
Asigne el valor que devuelve TextBodyPart.getContent()como un String para obtener la parte de texto
sin formato del cuerpo del mensaje.
_plainTextMessage = (String)tbp.getContent();
4.
46
Invoque TextBodyPart.hasMore() y TextBodyPart.moreRequestSent() para identificar si hay

disponible ms objeto TextBodyPart en el servidor.
Gua de desarrollo
if (tbp.hasMore() && !tbp.moreRequestSent())

{
5.
Si hay ms datos disponibles para el objeto TextBodyPart, invoque Transport.more() para recuperar el
resto del objeto TextBodyPart.
Transport.more((BodyPart)tbp, true);
Ejemplo de cdigo: Recuperar el contenido de texto sin formato de un mensaje de correo electrnico
private void readEmailBody(TextBodyPart tbp)
{
_plainTextMessage = (String)tbp.getContent();
if (tbp.hasMore() && !tbp.moreRequestSent())
{
try
{
Transport.more((BodyPart)tbp, true);
}
catch (Exception ex)
{
Dialog.alert("Exception: " + ex.toString());
}
}
}
Recuperar contenido HTML de un mensaje de correo electrnico

En la tarea siguiente, puede aparecer una excepcin al invocar el mtodo Transport.more().
1.

import
import
import
import
2.
net.rim.blackberry.api.mail.BodyPart;
net.rim.blackberry.api.mail.MimeBodyPart;
net.rim.device.api.ui.component.Dialog;
Cree un mtodo que tome un objeto MimeBodyPart como parmetro.

void readEmailBody(MimeBodyPart mbp)
{
3.
Invoque MimeBodyPart.getContent() y MimeBodyPart.getContentType() para recuperar el contenido

del objeto MimeBodyPart.
Object obj = mbp.getContent();
String mimeType = mbp.getContentType();
4.
Cree una variable String para mantener la representacin de String del objeto MimeBodyPart.
String body = null;
47
Gua de desarrollo
5.
Si el dispositivo BlackBerry puede convertir el cuerpo HTML de un mensaje en una String, el objeto
MimeBodyPart ser una String. Asigne el objeto MimeBodyPart como una String y asgnelo a la
representacin String del cuerpo del mensaje.
if (obj instanceof String)
{
body = (String)obj;
}
6.
Si el dispositivo BlackBerry no puede convertir el cuerpo HTML de un mensaje en una String, el objeto
MimeBodyPart ser una matriz de bytes. Cree una instancia nueva de String utilizando como parmetro el
objeto MimeBodyPart asignado como una matriz de bytes. Asigne la String a la representacin de String
del cuerpo del mensaje.
else if (obj instanceof byte[])
{
body = new String((byte[])obj);
}
7.
Compruebe si la representacin de String del contenido del objeto MimeBodyPart contiene

ContentType.TYPE_TEXT_PLAIN_STRING para determinar si el objeto MimeBodyPart es el cuerpo de texto
sin formato del mensaje.
if (mimeType.indexOf(ContentType.TYPE_TEXT_PLAIN_STRING) != -1)
{
8.
Invoque MimeBodyPart.hasMore() y MimeBodyPart.moreRequestSent() para determinar si todo el

cuerpo de texto est presente en el objeto MimeBodyPart.
if (mbp.hasMore() && !mbp.moreRequestSent())
{
9.
Si hay ms datos disponibles para el objeto MimeBodyPart, invoque Transport.more() para recuperar el
resto de los datos del objeto MimeBodyPart.
Transport.more((BodyPart)mbp, true);
10. Compruebe si la representacin de String del contenido del objeto MimeBodyPart contiene
ContentType.TYPE_TEXT_HTML_STRING para determinar si el objeto MimeBodyPart es el cuerpo HTML del
mensaje.
else if (mimeType.indexOf(ContentType.TYPE_TEXT_HTML_STRING) != -1)
{
11. Invoque MimeBodyPart.hasMore() y MimeBodyPart.moreRequestSent() para determinar si todo el

cuerpo HTML est presente en el objeto MimeBodyPart.
{
12. Si hay ms datos disponibles para el objeto MimeBodyPart, invoque Transport.more() para recuperar el
resto del objeto MimeBodyPart.
48
Gua de desarrollo
Ejemplo de cdigo: Recuperar el contenido HTML de un mensaje de correo electrnico

private void readEmailBody(MimeBodyPart mbp)
{
//Extract the content of the message.
Object obj = mbp.getContent();
String mimeType = mbp.getContentType();
String body = null;
if (obj instanceof String)
{
body = (String)body;
}
else if (obj instanceof byte[])
{
body = new String((byte[])obj);
}
if (mimeType.indexOf(ContentType.TYPE_TEXT_PLAIN_STRING) != -1)
{
_plainTextMessage = body;
//Determine if all of the text body part is present.
{
try
{
}
{
}
}
}
else if (mimeType.indexOf(ContentType.TYPE_TEXT_HTML_STRING) != -1)
{
_htmlMessage = body;
//Determine if all of the HTML body part is present.
{
try
{
}
{
}
}
}
}
49
Gua de desarrollo
Notificar a una aplicacin del dispositivo BlackBerry que est a punto de enviarse un mensaje de
correo electrnico
Notificar a una aplicacin del dispositivo BlackBerry que

est a punto de enviarse un mensaje de correo electrnico
1.

import
import
import
import
2.
net.rim.blackberry.api.mail.NoSuchServiceException;
net.rim.blackberry.api.mail.SendListener;
Implemente la interfaz SendListener.

public class MailSendListener implements SendListener{...}
3.
Cree una instancia de la clase que implemente la interfaz SendListener.

MailSendListener mailSL = new mailSendListener();
4.
En un bloque try, invoque Session.waitForDefaultSession().getStore() para recuperar el objeto

Store.
try
{
}
5.
En un bloque catch, administre una NoSuchServiceException.

{
}
6.
Invoque Store.addSendListener(MailSendListener) para aadir una instancia SendListener.

store.addSendListener(mailSL);

est a punto de enviarse un mensaje MMS
1.

import net.rim.blackberry.api.mms.SendListener;
import net.rim.blackberry.api.mms.MMS;
2.
Implemente la interfaz SendListener.

public class MMSSendListener implements SendListener{...}
3.

MMSSendListener mmsSL = new mmsSendListener();
50
Notificar a una aplicacin del dispositivo BlackBerry que est a punto de enviarse un mensaje SMS
Gua de desarrollo
4.
Aada una instancia SendListener.

MMS.addSendListener(mmsSL);

est a punto de enviarse un mensaje SMS
1.

import net.rim.blackberry.api.sms.SendListener;
import net.rim.blackberry.api.sms.SMS;
2.
Cree una clase que implemente la interfaz SendListener.

public class smsSendListener implements SendListener{...}
3.

smsSendListener smsSL = new smsSendListener();
4.
Aada un SendListener.
SMS.addSendListener(smsSL);
Enviar un mensaje
1.

import
import
import
import
import
import
import
import
2.
net.rim.blackberry.api.mail.AddressException;
net.rim.blackberry.api.mail.MessagingException;
Declare un objeto Message.

Message msg;
3.
Especifique una carpeta en la que guardar una copia del mensaje enviado.
Store store = Session.getDefaultInstance().getStore();
Folder[] folders = store.list(Folder.SENT);
Folder sentfolder = folders[0];
msg = new Message(sentfolder);
4.
Cree una matriz de objetos Address.

Address toList[] = new Address[1];
5.
En un bloque try, agregue cada direccin a la matriz.

51
Gua de desarrollo
Enviar un mensaje
try
{
toList[0]= new Address("ming.li@example.com", "Ming Li");
}
6.
En un bloque catch, administre una AddressException, que se muestra si una direccin es no vlida.
catch(AddressException e)
{
}
7.
8.
Invoque Message.addRecipients() y proporcione el tipo de destinatario (PARA, CC o CCO) y la matriz de

direcciones que se agregarn como parmetros al mtodo.
Si el mensaje tiene varios tipos de destinatarios, invoque Message.addRecipients() una vez para cada de
tipo destinatario.
msg.addRecipients(Message.RecipientType.TO, toList);
9.
Invoque Message.setFrom(Address).
Address from = new Address("ming.li@example.com", "Ming Li");
msg.setFrom(from);
10. Invoque Message.setSubject(String).

msg.setSubject("Test Message");
11. Invoque Message.setContent(String). (Normalmente, la aplicacin del dispositivo BlackBerry recupera el

contenido de texto que escribe un usuario del dispositivo BlackBerry en un campo).
try
{
msg.setContent("This is a test message.");

}
catch(MessagingException e)
{
System.out.println(e.getMessage());
}
12. Invoque Session.getTransport() y almacene el objeto devuelto en una variable de tipo Transport. El
objeto Transport representa el protocolo de transporte de mensajes.
Transport trans = Session.getTransport();
13. Invoque Transport.send(Message) para enviar el mensaje.

try
{
trans.send(msg);
}
{
}
52
Responder a un mensaje
Gua de desarrollo
Responder a un mensaje
1.

import
import
import
import
import
2.
Invoque Session.getTransport() y almacene el objeto devuelto en una variable de tipo Transport. El

3.
Invoque Session.waitForDefaultSession().getStore() para recuperar el objeto Store.

4.
Invoque Store.list(INBOX) para recuperar todas las carpetas en la carpeta INBOX. Almacene las carpetas
en una matriz Folder.
Folder[] folders = store.list(INBOX);
5.
Especifique un elemento de matriz especfico para recuperar la carpeta bandeja de entrada.

6.
Invoque Folder.getMessages() para recuperar los mensajes de la carpeta Bandeja de entrada. Almacene
los mensajes en una matriz Message.
Message[] messages = inbox.getMessages();
7.
Invoque Message.reply(Boolean) y especifique true para responder a todos los destinatarios del mensaje
o false para responder slo al remitente.
if( messages.length > 0 )
{
Message msg = messages[0];
}
Message reply = msg.reply(true);
8.
Invoque Transport.send(Message) para enviar la respuesta.

try
{
trans.send(reply);
}
{
}
53
Reenviar un mensaje
Gua de desarrollo
Reenviar un mensaje
1.

import
import
import
import
import
2.
Invoque Message.forward() en un objeto Message existente. La lnea del asunto de un mensaje reenviado
se establece automticamente como RV:asunto_original.
Message fwdmsg = msg.forward();
3.
Cree una matriz de direcciones.

Address toList[] = new Address[1];
4.
Agregue un objeto Address nuevo a la matriz.

toList[0]= new Address("ming.li@example.com", "Ming Li");
5.
Invoque Message.addRecipients(int, Address[]) para agregar destinatarios al Message.

fwdmsg.addRecipients(Message.RecipientType.TO, toList);
6.
Invoque Message,setContent(String) para establecer el contenido del mensaje que aparece antes del
mensaje original.
try
{
fwdmsg.setContent("This is a forwarded message.");

}
{
}
7.

8.
Invoque Transport.send(Message).
try
{
trans.send(fwdmsg);
}
{
}
54
Trabajar con carpetas de mensajes
Gua de desarrollo

1.

import
import
import
import
import
import
import
2.
net.rim.blackberry.api.mail.FolderNotFoundException;
Recupere el almacn.
3.
Realice una de las siguientes acciones:

Tarea
Abrir una vista de carpeta
Pasos
a.
Recupere una lista de carpetas.

Store store = null;
store =
Session.waitForDefaultSession().getStore();
Folder[] folders = store.list();
b.
Invoque Invoke.invokeApplication() para ver una carpeta

de la lista.
Invoke.invokeApplication(Invoke.APP_TYPE_MESSAGE
S,
new MessageArguments( folders[0]));
Enumerar las carpetas de un

almacn de buzn
Invoque Store.list().
Recupere una matriz de carpetas

por tipo
Invoque Store.list(int) y proporcione como parmetro el tipo

de carpeta.
Folder[] folders = store.list(INBOX);

Recuperar una matriz de carpetas

a travs de una bsqueda
Recuperar una carpeta por su
nombre
Invoque Store.findFolder(String).
Folder[] folders = store.findFolder("Inbox");
a.
Invoque Store.getFolder(String) y proporcione como

parmetro la ruta de acceso absoluta a la carpeta.
55
Gua de desarrollo
Tarea
Pasos
Folder folder =
store.getFolder("Mailbox - Yan Wang/Inbox/
Projects");
b.
Si la carpeta no existe, cree cdigo para administrar una excepcin

FolderNotFoundException.
Recuperar una carpeta por su ID
a.
Invoque Folder.getID() para recuperar el identificador de la

carpeta.
b.
Invoque Store.getFolder() con el ID como parmetro.

long id = folders[0].getId();
Folder f2 = store.getFolder(id);
Archivar un mensaje
Invoque Folder.appendMessage(Message) en un objeto

Folder.
Message msg = new Message();
// populate the message
Folder folder = store.getFolder("Inbox");
folder.appendMessage(msg);
56
Gua de desarrollo
Mensajes personalizados
Utilizar mensajes y carpetas personalizados en la lista de

mensajes
Puede utilizar el paquete net.rim.blackberry.api.messagelist para crear mensajes y carpetas
personalizados para una aplicacin del dispositivo BlackBerry.
Para utilizar carpetas y mensajes personalizados en una aplicacin, debe crear una aplicacin con los mdulos
siguientes:
Un mdulo de IU para interactuar con el usuario del dispositivo BlackBerry

Un mdulo de servicio para interactuar con el servidor de aplicaciones y realizar otras acciones en segundo plano
Ambos mdulos forman parte de la misma aplicacin pero tienen puntos de entrada diferentes.
Debe determinar la funcionalidad que forma parte de cada mdulo. Por ejemplo, un elemento del men que
permite al usuario eliminar un mensaje o marcarlo como ledo debe formar parte del mdulo de servicio. Un
elemento del men que permite al usuario abrir o responder a un mensaje debe formar parte del mdulo de IU.
Consulte la aplicacin de ejemplo Demostracin de lista de mensajes que se incluye en el BlackBerry Java SDK para
ver una demostracin sobre cmo utilizar esta API.
Crear un mdulo para procesos en segundo plano

Un mdulo de servicio interacta con un servidor de aplicaciones y realiza otras acciones en segundo plano. Se
inicia automticamente cuando se inicia el dispositivo BlackBerry y se ejecuta sin que el usuario realice ninguna
accin. El mdulo de servicio puede enviar y recibir mensajes de un servidor de aplicaciones y puede agregar
mensajes a la lista de mensajes. Para los mensajes que enva puede utilizar cualquier protocolo que desee (por
ejemplo, un protocolo nativo, un protocolo de mensaje de correo electrnico o un protocolo de mensaje de texto
SMS). El usuario no puede detener el mdulo de servicio.
Cuando se inicia el dispositivo, el mdulo de servicio debe registrar una carpeta de aplicaciones y rastrear las
actualizaciones hechas a la carpeta, como cuando el usuario elimina un mensaje o marca un mensaje como ledo o
no ledo.
Crear un mdulo para la IU

El mdulo de la IU contiene los componentes de la IU y se utiliza para interactuar con los usuarios del dispositivo
BlackBerry. Normalmente, el mdulo de la IU se inicia automticamente cuando el usuario interacta con un
mensaje personalizado. Por ejemplo, si el usuario selecciona un mensaje personalizado en la aplicacin Mensajes y
hace clic en el panel tctil o toca la pantalla tctil, se debe iniciar el mdulo de la IU y se debe mostrar el contenido
del mensaje. Si el mdulo de la IU no se est ejecutando y el usuario intenta abrir un mensaje personalizado, el
mdulo de la IU se inicia automticamente. El mdulo de la IU tambin puede permitir que los usuarios respondan
a un mensaje y compongan un mensaje nuevo.
57
Gua de desarrollo

1.
2.
3.
4.
Cree un proyecto con la configuracin que inicia la aplicacin automticamente. En el BlackBerry Java Plug-in
para Eclipse, seleccione la casilla de verificacin Auto-run on startup que est en el Descriptor de aplicacin de
BlackBerry. Para obtener ms informacin, consulte la Gua de desarrollo de BlackBerry Java Plug-in para Eclipse .
Cree una clase con los campos y mtodos para el mdulo.
Compile el proyecto en un archivo .jad.
Incluya el archivo .jad con los archivos .jad del mdulo IU y la parte principal de la aplicacin.
Iniciar el mdulo para procesos en segundo plano o el

mdulo para la IU
1.

import net.rim.blackberry.api.messagelist.*;
2.
Cree un mtodo principal para la aplicacin del dispositivo BlackBerry.

public static void main( String[] args )
{
try {
3.
En main(), compruebe si el valor del parmetro args indica que la aplicacin debe iniciar el mdulo del servicio
o el mdulo de la IU.
if( args.length == 1 && args[ 0 ].equals( "service" ) )
{
}
} else if( args.length == 1 && args[ 0 ].equals( "gui" ) )
{
}
4.
Si la aplicacin debe iniciar el mdulo del servicio, en la primera declaracin de if, cree una instancia de una
clase que contenga la funcionalidad y elementos del servicio. Obtenga una referencia a un objeto
ApplicationMessageFolderRegistry.
MLSampleService service = new MLSampleService();
ApplicationMessageFolderRegistry reg =
ApplicationMessageFolderRegistry.getInstance();
5.
58
Si la aplicacin debe iniciar el mdulo de la IU, en la primera declaracin de else if, cree una instancia de una
clase que contenga la funcionalidad y elementos de la IU. Por ejemplo, el mdulo de la IU debe iniciarse si el
usuario del dispositivo BlackBerry hace clic en el icono de la aplicacin en la pantalla Inicio o abre un mensaje
personalizado en la aplicacin Mensajes. Muestre la IU de la aplicacin y agregue la aplicacin al distribuidor de
eventos.
Gua de desarrollo
Crear un icono para un mensaje personalizado
MLSampleGui gui = new MLSampleGui();

gui.showGui();
gui.enterEventDispatcher();
Ejemplo de cdigo: Iniciar el mdulo para procesos en segundo plano o el mdulo para la IU
public static void main( String[] args )
{
try
{
if( args.length == 1 && args[ 0 ].equals( "service" ) )
{
MLSampleService service = new MLSampleService();
}
else if( args.length == 1 && args[ 0 ].equals( "gui" ) )
{
MLSampleGui gui = new MLSampleGui();
gui.showGui();
gui.enterEventDispatcher();
}
}
}

Puede asociar iconos con mensajes personalizados. Un icono se asocia con un tipo y un estado de mensaje
personalizado. Por ejemplo, puede asociar un icono con los mensajes sin abrir y un icono diferente con los
mensajes abiertos. El icono aparece en el lado izquierdo del mensaje en la aplicacin Mensajes.
1.

import net.rim.device.api.system.EncodedImage;
2.
Invoque EncodedImage.getEncodedImageResource() para crear un icono basado en una imagen

codificada. Pase el nombre de archivo como un argumento.
ApplicationIcon newIcon =
new
ApplicationIcon( EncodedImage.getEncodedImageResource( "ml_sample_new.png" ) );
ApplicationIcon openedIcon =
new
ApplicationIcon( EncodedImage.getEncodedImageResource( "ml_sample_opened.png" ) );
3.
Invoque ApplicationMessageFolderRegistry.registerMessageIcon() para asignar un estado y un

icono a un mensaje personalizado. Especifique lo siguiente como argumentos: un valor para el tipo de mensaje
para una aplicacin del dispositivo BlackBerry, un estado del mensaje utilizando campo de la interfaz
ApplicationMessage.Status y una instancia de la clase ApplicationIcon.
59
Gua de desarrollo
Crear una carpeta personalizada en la lista de mensajes
int MESSAGE_TYPE = 0;
int STATUS_NEW = ApplicationMessage.Status.UNOPENED;
int STATUS_OPENED = ApplicationMessage.Status.OPENED;
reg.registerMessageIcon( MESSAGE_TYPE, STATUS_NEW, newIcon );
reg.registerMessageIcon( MESSAGE_TYPE, STATUS_OPENED, openedIcon );

Los mensajes personalizados se guardan en las carpetas personalizadas. Para realizar operaciones en mensajes
personalizados, su aplicacin de dispositivo BlackBerry debe registrar por lo menos una carpeta personalizada.
1.

import net.rim.device.api.collection.ReadableList;
2.
Cree una clase que implemente la interfaz ApplicationMessage.

public class MLSampleMessage implements ApplicationMessage
3.
Obtenga una referencia a un objeto ApplicationMessageFolderRegistry.

4.
Invoque ApplicationMessageFolderRegistry.registerFolder() para registrar una carpeta

personalizada para cada recopilacin de mensajes.
// collections of MLSampleMessage instances
ReadableList inboxMessages = messages.getInboxMessages();
ReadableList deletedMessages = messages.getDeletedMessages();
ApplicationMessageFolder inboxFolder = reg.registerFolder(
INBOX_FOLDER_ID,
"Inbox",
inboxMessages );
ApplicationMessageFolder deletedFolder = reg.registerFolder(
DELETED_FOLDER_ID,
"Deleted Messages",
deletedMessages,
false );
5.
Invoque ApplicationMessageFolder.addListener() para agregar un servicio de escucha de forma que

se pueda notificar a su aplicacin cuando se produzcan eventos especficos de carpeta. En el siguiente ejemplo
de cdigo, la aplicacin rastrea los mensajes eliminados. Para obtener una lista de todas las acciones que puede
escuchar, consulte la documentacin de la clase ApplicationMessageFolderListener en la referencia de
la API para BlackBerry Java SDK.
deletedFolder.addListener( this,
ApplicationMessageFolderListener.MESSAGE_DELETED );
6.
Cree una clase que implemente la interfaz ApplicationMessageFolderListener.

public class AppFolderListener implements ApplicationMessageFolderListener
60
Gua de desarrollo
7.
Enviar una notificacin cuando una carpeta personalizada cambie
Implemente ApplicationMessageFolderListener.actionPerformed() para realizar acciones cuando

ocurra un evento de carpeta.
public void actionPerformed( int action, ApplicationMessage[] messages,
ApplicationMessageFolder folder )
{
// check if action was performed on multiple messages
if( messages.length == 1 )
{
switch( action )
{
case ApplicationMessageFolderListener.MESSAGE_DELETED:
messageStore.deleteInboxMessage( message );
...
8.
Invoque ApplicationMessageFolderRegistry.setRootFolderName() para especificar el nombre de la

carpeta raz de las carpetas personalizadas de su aplicacin. El nombre de la carpeta raz aparece en el cuadro
de dilogo Ver carpeta de la aplicacin Mensajes cuando una aplicacin registra ms de una carpeta de mensajes
de aplicacin.
reg.setRootFolderName( "ML Sample" );
Enviar una notificacin cuando una carpeta personalizada

cambie
Despus de que su aplicacin de dispositivo BlackBerry agregue los mensajes personalizados a la lista de mensajes,
debe administrar los mensajes. Por ejemplo, un usuario de dispositivo BlackBerry puede abrir la aplicacin y
eliminar un mensaje o la aplicacin puede sincronizarse con un servidor y obtener ms mensajes para mostrar en
la lista.
Para mantener la lista de mensajes sincronizada con los mensajes personalizados de una carpeta personalizada, la
aplicacin debe ser notificada cuando una carpeta personalizada cambia.
1.

2.
Invoque ApplicationMessageFolder.fireElementAdded() para notificar a una aplicacin cuando un

mensaje se agregue a una carpeta personalizada.
inboxFolder.fireElementAdded( newMessage );
3.
Invoque ApplicationMessageFolder.fireElementRemoved() para notificar a una aplicacin cuando se

elimine un mensaje de una carpeta personalizada.
inboxFolder.fireElementRemoved( deletedMessage );
4.
Invoque ApplicationMessageFolder.fireElementUpdated() para notificar a una aplicacin cuando se

actualice un mensaje en una carpeta personalizada.
inboxFolder.fireElementUpdated( updatedMessage );
61
Gua de desarrollo
5.
Crear un indicador personalizado
Invoque ApplicationMessageFolder.fireReset() para notificar a una aplicacin cuando cambie ms de

un mensaje en una carpeta personalizada.
inboxFolder.fireReset();

Los indicadores personalizados aparecen en la pantalla Inicio junto con otros indicadores, como el indicador de
mensajes nuevos y los avisos del calendario. Puede utilizar la clase ApplicationIndicator para crear y
administrar un indicador para mensajes personalizados. Por ejemplo, puede crear un indicador para mostrar el
nmero de mensajes personalizados sin leer que hay la lista de mensajes. Los indicadores son visibles an cuando
el dispositivo BlackBerry est bloqueado. Su aplicacin puede registrar slo un indicador y debe registrarlo cada
vez que se inicia el dispositivo BlackBerry. El tamao del indicador puede variar segn el dispositivo y el tema. Para
obtener ms informacin sobre el tamao de un indicador, consulte las Directrices sobre IU paraBlackBerry
BlackBerry.
1.

import net.rim.device.api.system.EncodedImage;
2.
Obtenga una referencia a un objeto ApplicationIndicatorRegistry.

ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry.getInstance();
3.
Cree un indicador basado en una imagen codificada invocando

EncodedImage.getEncodedImageResource() y pasando el nombre de archivo como un argumento.
Guarde una referencia a la imagen codificada en una variable EncodedImage. Cree una instancia de la clase
ApplicationIcon utilizando EncodedImage como un argumento.
EncodedImage image = EncodedImage.getEncodedImageResource( "clowds.gif" );
ApplicationIcon icon = new ApplicationIcon( image );
4.
Registre el icono como un indicador de aplicacin invocando
ApplicationIndicatorRegistry.register(). En el siguiente ejemplo de cdigo, el segundo parmetro
especifica que el indicador puede tener un valor numrico asociado (por ejemplo, un nuevo recuento de
mensajes). El tercer parmetro especifica que el indicador debe ser visible.
ApplicationIndicator indicator = reg.register( icon, false, true);
5.
Recupere el indicador registrado invocando
ApplicationIndicatorRegistry.getApplicationIndicator(). Guarde el valor devuelto en una

variable ApplicationIndicator.
ApplicationIndicator appIndicator = reg.getApplicationIndicator();
6.
Establezca el icono y el valor para el indicador invocando ApplicationIndicator.set(). Considere mostrar

el valor slo si es mayor que 0.
appIndicator.set( newIcon, newValue );
62
Gua de desarrollo
Ocultar un indicador
1.

2.
Para ocultar temporalmente un indicador, invoque ApplicationIndicator.setVisible() y proporcione
false como el argumento.
appIndicator.setVisible( false );
Eliminar indicadores personalizados

Puede eliminar un indicador personalizado de la pantalla de inicio anulando su registro.
1.

2.
Elimine el indicador personalizado invocando ApplicationIndicatorRegistry.unregister().

reg.unregister();
63
Gua de desarrollo
Archivos adjuntos
Archivos adjuntos
Puede utilizar la API de correo del paquete net.rim.blackberry.api.mail para administrar archivos adjuntos
de mensajes de correo electrnico entrantes e incluir archivos adjuntos en mensajes de correo electrnico
salientes de un dispositivo BlackBerry. Un archivo adjunto se representa como un objeto BodyPart separado en
un mensaje Multipart.
Crear un gestor de archivos adjuntos

Puede utilizar la interfaz AttachmentHandler para gestionar un archivo adjunto a un mensaje de correo
electrnico que aparezca en la lista de mensajes del dispositivo BlackBerry.
Nota: BlackBerry Attachment Service recibe todos los archivos adjuntos en primer lugar. Los gestores de archivos
adjuntos de terceros no pueden anular este comportamiento predeterminado. Para obtener ms informacin
acerca de BlackBerry Attachment Service, consulte la Gua de administracin de BlackBerry Enterprise Server .
1.

import net.rim.blackberry.api.mail.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.component.*;
2.
Implemente la interfaz AttachmentHandler para crear un gestor personalizado de archivos adjuntos.

public class AttachTest implements AttachmentHandler {...}
3.
Implemente el mtodo supports(String) para especificar el tipo de contenido del archivo adjunto
compatible con el gestor.
public boolean supports(String contentType)
{
return (contentType.toLowerCase().indexOf("contenttype") != -1 ? true : false);
}
4.
Implemente el mtodo menuString() para especificar el texto del elemento del men que aparece cuando
un usuario selecciona un archivo adjunto.
public String menuString()
{
return "Custom Attachment Viewer";
}
5.
Implemente el mtodo run() para especificar lo que debe suceder cuando un usuario hace clic en el elemento
del men. En el ejemplo de cdigo siguiente, una pantalla nueva utiliza la clase RichTextField para mostrar
una representacin String del contenido del archivo adjunto.
public void run(Message m, SupportedAttachmentPart p)
{
MainScreen view = new MainScreen();
view.setTitle("Attachment Viewer");
view.add(new RichTextField(new String((byte[])p.getContent())));
}
64
Recuperar el contenido de un archivo adjunto
Gua de desarrollo
6.
Invoque AttachmentHandlerManager.addAttachmentHandler() para registrar el gestor de archivos

adjuntos con el administrador. Tenga en cuenta que el nombre del archivo adjunto debe llevar el prefijo "xrimdevice" para que el archivo adjunto sea enviado y almacenado en el dispositivo BlackBerry.
AttachmentHandlerManager m = AttachmentHandlerManager.getInstance();
CustomAttachmentHandler ah = new CustomAttachmentHandler();
m.addAttachmentHandler(ah);
Recuperar el contenido de un archivo adjunto

1.
2.
Importe la clase net.rim.blackberry.api.mail.SupportedAttachmentPart.

Invoque SupportedAttachmentPart.getContent().
String s = new String((byte[])p.getContent());
Recuperar informacin sobre un archivo adjunto

1.
2.
Importe la clase net.rim.blackberry.api.mail.SupportedAttachmentPart.

Invoque los mtodos de la clase SupportedAttachmentPart. La clase SupportedAttachmentPart
representa un archivo adjunto con un visor correspondiente en el dispositivo BlackBerry. La clase
UnsupportedAttachmentPart representa un archivo adjunto que no tiene ningn visor en el dispositivo
BlackBerry.
Enviar un mensaje con un archivo adjunto

1.

import
import
import
import
import
import
2.
net.rim.blackberry.api.mail.Multipart;
net.rim.blackberry.api.mail.SupportedAttachmentPart;
Cree un objeto Multipart nuevo para crear un mensaje multiparte.

byte[] data = new byte[256];
MultiPart multipart = new MultiPart();
3.
Cree un objeto SupportedAttachmentPart, designando el objeto Multipart como su padre, para crear
cada componente de la pantalla.
SupportedAttachmentPart attach = new SupportedAttachmentPart( multipart,
"application/x-example", "filename", data);
4.
Invoque MultiPart.addBodyPart(SupportedAttachmentPart) para aadir cada uno de los objetos

supportedAttachmentPart al objeto multiparte.
65
Gua de desarrollo
Descargar automticamente archivos adjuntos
multipart.addBodyPart(attach);
5.
Invoque Message.setContent(Multipart) y proporcione como parmetro el objeto Multipart para

establecer el contenido del archivo adjunto.
msg.setContent(multipart);
6.

7.
Invoque Transport.send(Message).
try
{
trans.send(msg);
}
{
}

Cuando llega un mensaje a la aplicacin de mensajes del dispositivo BlackBerry con un archivo adjunto, puede
descargar automticamente el archivo adjunto y almacenarlo en el dispositivo BlackBerry.
Antes de descargar archivos adjuntos, la clase AttachmentDownloadManager valida el archivo adjunto.
AttachmentDownloadManager muestra excepciones si se produce alguna de las condiciones siguientes.
la aplicacin intenta invocar la descarga mientras ya hay una descarga en curso

la aplicacin intenta descargar archivos de longitud cero
el tamao del archivo adjunto es mayor de lo permitido por los libros de servicios o la poltica de TI de la aplicacin
los archivos adjuntos estn cifrados
no hay espacio suficiente disponible en el dispositivo BlackBerry ni en la tarjeta SD
El mtodo AttachmentDownloadManager.download() realiza una verificacin durante el proceso de descarga.

Si se encuentran errores de verificacin, el mtodo muestra una excepcin. Para ver una lista de posibles errores
de verificacin, consulte la referencia de API para BlackBerry Java Development Environment.
Nota: BlackBerry Attachment Service recibe todos los archivos adjuntos en primer lugar. Los gestores de archivos
adjuntos de terceros no pueden anular este comportamiento predeterminado. Para obtener ms informacin
acerca de BlackBerry Attachment Service, consulte la Gua de administracin de BlackBerry Enterprise Server .
1.

import java.io.IOException;
import net.rim.blackberry.api.mail.*;
66
Gua de desarrollo
2.
Implemente la interfaz DownloadProgressListener. Cree una instancia de la clase

AttachmentDownloadManager.
public class AutoAttachTest implements DownloadProgressListener
{
AttachmentDownloadManager _adm = new AttachmentDownloadManager();
3.
Utilice los mtodos disponibles en AttachmentDownloadManager para determinar informacin sobre el

archivo adjunto.
public
public
public
public
4.
String
String
String
String
fileSize
fileName
fileType
filePath
=
=
=
=
getFileSize(BodyPart bodyPart);
getFileName(BodyPart bodyPart);
getFileContentType(BodyPart bodyPart);
getDownloadedFileName(BodyPart bodyPart);
Invoque AttachmentDownloadManager.download() para descargar el archivo adjunto.

_adm.download(bodyParts, null, this);
5.
Anule los mtodos de devolucin de llamada de DownloadProgressListener para ofrecer actualizaciones

acerca del estado de la descarga del archivo adjunto.
private void downloadCancelled(String msg)
{
BodyPart bodyPart = (BodyPart) element;
_screen.displayProgress("Failed to download " + _adm.getFileName(bodyPart));
}
private void downloadCompleted(Object element)
{
BodyPart bodyPart = (BodyPart) element;
_screen.displayProgress(_adm.getFileName(bodyPart) + " downloaded.");
}
public void updateProgress(Object element, int current, int total)
{
}
67
Calendario
Gua de desarrollo
Calendario
Abrir el calendario
1.

import net.rim.blackberry.api.invoke.CalendarArguments;
2.
3.
Invoque Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments).

Si su aplicacin no tiene permiso para acceder la aplicacin que invoca, busque una
ControlledAccessException.
Ver o cambiar una entrada del calendario

1.

import
import
import
import
import
import
import
2.
java.util.Enumeration;
javax.microedition.pim.PIM;
javax.microedition.pim.Event;
javax.microedition.pim.EventList;
net.rim.blackberry.api.invoke.CalendarArguments;
net.rim.device.api.system.ControlledAccessException;
Recupere un Event de la lista de eventos.

Event e = null;
EventList el =
(EventList)PIM.getInstance().openPIMList( PIM.EVENT_LIST, PIM.READ_WRITE );
Enumeration events = el.items();
e = (Event)events.nextElement();
3.
Invoque Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments) mediante el objeto

CalendarArguments creado utilizando el campo ARG_VIEW_DEFAULT y el Event recuperado.
Invoke.invokeApplication( Invoke.APP_TYPE_CALENDAR, new
CalendarArguments( CalendarArguments.ARG_VIEW_DEFAULT, e ) );
4.
Abrir una nueva entrada de calendario rellenada

1.

import javax.microedition.pim.PIM;
import javax.microedition.pim.Event;
import javax.microedition.pim.EventList;
68
Actualizar informacin de entradas del calendario
Gua de desarrollo
import net.rim.blackberry.api.invoke.CalendarArguments;
2.
Cree un nuevo Event mediante un objeto EventList.

EventList el = (EventList)PIM.getInstance().openPIMList( PIM.EVENT_LIST,
PIM.READ_WRITE );
Event e = el.createEvent();
3.
Agregue informacin al objeto Event.

e.addString( Event.SUMMARY, 0, "Go For A Walk" );
e.addString( Event.LOCATION, 0, "The Park" );
long start = System.currentTimeMillis() + 8640000;
e.addDate( Event.START, 0, start );
e.addDate( Event.END, 0, start + 72000000 );
4.
Invoque Invoke.invokeApplication(APP_TYPE_CALENDAR, CalendarArguments) mediante el objeto

CalendarArguments creado utilizando el campo ARG_NEW y Event.
Invoke.invokeApplication( Invoke.APP_TYPE_CALENDAR, new
CalendarArguments( CalendarArguments.ARG_NEW, e ) );

1.

import
import
import
import
import
2.
java.util.Date;
javax.microedition.pim.RepeatRule;
Invoque openPIMList() para abrir una lista de entradas del calendario. Proporcione lo siguiente como
parmetros: el tipo de lista que se va a abrir (PIM.EVENT_LIST) y el modo en el que se debe abrir la lista.
READ_WRITE
READ_ONLY
WRITE_ONLY
EventList eventList = null;
try
{
eventList = (EventList)PIM.getInstance().openPIMList(PIM.EVENT_LIST,
PIM.READ_WRITE);
}
catch (PimException e)
{
// Handle exception.
}
3.
Para actualizar informacin del calendario, realice cualquiera de las tareas siguientes:
69
Gua de desarrollo
Tarea
Crear una cita
Pasos
Invoque createEvent() en una lista de eventos.
Event event = eventList.createEvent();
Agregar informacin de citas
Invoque Event.isSupportedField(int) para comprobar que un

elemento admite un campo.
if (event.isSupportedField(Event.SUMMARY))
{
event.addString(Event.SUMMARY, Event.ATTR_NONE,
"Meet with customer");
}
if (event.isSupportedField(Event.LOCATION))
{
event.addString(Event.LOCATION, Event.ATTR_NONE,
"Conference Center");
}
Date start = new Date(System.currentTimeMillis() +
8640000);
if (event.isSupportedField(Event.START))
{
event.addDate(Event.START, Event.ATTR_NONE,
start);
}
if (event.isSupportedField(Event.END))
{
event.addDate(Event.END, Event.ATTR_NONE, start +
72000000);
}
if (event.isSupportedField(Event.ALARM))
{
if (event.countValues(Event.ALARM) > 0)
{
event.removeValue(Event.ALARM,0);
event.setInt(Event.ALARM, 0, Event.ATTR_NONE,
396000);
}
}
Crear una cita peridica
a.
Cree un objeto RepeatRule. La clase RepeatRule define campos

para las propiedades y valores que puede definir, como COUNT,
FREQUENCY e INTERVAL.
b.
Invoque RepeatRule.getFields() para recuperar una matriz

de campos compatibles.
c.
Invoque RepeatRule.setInt(int, int) o

RepeatRule.setDate (int, int, int, long) en un objeto
RepeatRule nuevo para definir una pauta peridica.
70
Recuperar informacin de entradas de calendario
Gua de desarrollo
Tarea
Pasos
RepeatRule recurring = new RepeatRule();
recurring.setInt(RepeatRule.FREQUENCY,
RepeatRule.MONTHLY);
recurring.setInt(RepeatRule.DAY_IN_MONTH, 14);
d.
Invoque Event.setRepeat(RepeatRule) en un evento para

asignar un patrn de repeticin a una cita.
EventList eventList =
(EventList)PIM.getInstance().openPIMList
(PIM.EVENT_LIST, PIM.READ_WRITE);
Event event = eventList.createEvent();
event.setRepeat(recurring);
Cambiar informacin de citas
a.
Invoque el mtodo de configuracin pertinente, como

setString() para sustituir un valor existente por uno nuevo.
b.
Invoque Event.countValues() para determinar si ya se ha

definido un valor para el campo.
c.
Utilice el mtodo de configuracin correspondiente, como

setString() para cambiar un valor existente.
if (event.countValues(Event.LOCATION) > 0)
{
event.setString(Event.LOCATION, 0,
Event.ATTR_NONE, "Board Room");
}
Guardar una cita
a.
Antes de guardar la cita, para identificar campos de la cita que han

cambiado desde que sta se guard por ltima vez, invoque
Event.isModified().
b.
Invoque Event.commit().
if(event.isModified())
{
event.commit();
}
Recuperar informacin de entradas de calendario

1.

javax.microedition.pim.Event
javax.microedition.pim.EventList
javax.microedition.pim.PIM
2.
Invoque EventList.items() para recuperar una enumeracin de citas.
71
Exportar una entrada de calendario
Gua de desarrollo
(EventList)PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_ONLY);
Enumeration e = eventList.items();
3.
Invoque PIMItem.getFields() para recuperar una matriz de ID de campos que tengan datos relativos a una
tarea particular. Invoque PIMItem.getString() para recuperar los valores del campo.
while (e.hasMoreElements())
{
Event event = (Event)e.nextElement();
int[] fieldIds = event.getFields();
int id;
for(int index = 0; index < fieldIds.length; ++index)
{
id = fieldIds[index];
if(e.getPIMList().getFieldDataType(id) == STRING)
{
for(int j=0; j < event.countValues(id); ++j)
{
String value = event.getString(id, j);
System.out.println(event.getFieldLable(id) + "=" + value);
}
}
}
}
Exportar una entrada de calendario

1.

import
import
import
import
import
2.
java.io.ByteArrayOutputStream;
Invoque PIM.supportedSerialFormats() especificando el de tipo lista (PIM.EVENT_LIST), para

recuperar una matriz de String de los formatos de serie compatibles.
String[] dataFormats = PIM.supportedSerialFormats(PIM.EVENT_LIST);
3.
4.
Utilice un redactor de flujo de salida para exportar entradas de calendario del dispositivo BlackBerry a un formato
de serie compatible, como iCal.
Invoque toSerialFormat() para escribir un elemento en el formato de serie. El parmetro enc especifica la
codificacin de caracteres para utilizar al programar en el flujo de salida. Las codificaciones de caracteres
compatibles incluyen "UTF8", "ISO-8859-1" y "UTF-16BE". Este parmetro no puede ser nulo.
(EventList)PIM.getInstance().openPIMList( PIM.EVENT_LIST, PIM.READ_ONLY );
ByteArrayOutputStream bytestream = new ByteArrayOutputStream();
Enumeration e = eventList.items();
{
72
Importar una entrada de calendario
Gua de desarrollo
Event event = (Event)e.nextElement();

PIM.getInstance().toSerialFormat(event, bytestream, "UTF8", dataFormats[0]);
Importar una entrada de calendario

1.

import
import
import
import
import
2.
3.
java.io.ByteArrayInputStream;
Invoque PIM.getInstance().fromSerialFormat() para devolver una matriz de objetos PIMItem.

Invoque EventList.importEvent() para agregar una entrada de calendario nueva.
// Convert an existing entry into a iCal and then
// import the iCal as a new entry
String[] dataFormats = PIM.supportedSerialFormats();
// Write entry to iCal
ByteArrayOutputStream os = new ByteArrayOutputStream();
PIM.getInstance().toSerialFormat(event, os, "UTF8", dataFormats[0]);
// Import entry from iCal
ByteArrayInputStream is = new ByteArrayInputStream(os.toByteArray());
PIMItem[] pi = PIM.getInstance().fromSerialFormat(is, "UTF8");
(EventList)PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);
Event event2 = eventList.importEvent((Event)pi[0]);
Recuperar varias listas de entradas de calendario

El primer elemento de la matriz de listas es la lista predeterminada.
1.
2.
Importe la clase javax.microedition.pim.PIM.

Invoque PIM.listPIMLists(int pimListType).
String[] allLists = PIM.listPIMLists(PIM.EVENT_LIST);
Notificar a una aplicacin del dispositivo BlackBerry

cuando cambie una lista de entradas de calendario
1.

import
import
import
import
net.rim.blackberry.api.pdap.BlackBerryPIMList;
net.rim.blackberry.api.pdap.PIMListListener;
73
Gua de desarrollo
2.
Notificar a una aplicacin del dispositivo BlackBerry cuando cambie la lista predeterminada de
entradas de calendario
Implemente la interfaz PIMListListener.

public class MyEventListListener implements PIMListListener {...}
3.
Invoque BlackBerryPIMList.addListener() para registrar la recepcin de notificaciones de cambios en

una lista de entradas de calendario.
BlackBerryPIMList eventList =
(BlackBerryPIMList)PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);
eventList.addListener(new MyEventListListener());

cuando cambie la lista predeterminada de entradas de
calendario
Cuando se produce una actualizacin de la lista de servicios de un dispositivo BlackBerry, la lista de bases de datos
PIM de un dispositivo puede cambiar. Esta accin puede tener como resultado la creacin de una nueva lista
predeterminada de entradas de calendario.
1.

import net.rim.blackberry.api.pdap.BlackBerryPIM;
import net.rim.blackberry.api.pdap.ListChangeListener;
2.
Implemente la interfaz ListChangeListener.

public class MyListChangeListener implements ListChangeListener {...}
3.
Invoque BlackBerryPIM.addListChangeListener() para registrar la recepcin de notificaciones de

cambios en una lista PIM predeterminada.
ListChangeListener listener = new MyListChangeListener();
((BlackBerryPIM) PIM.getInstance()).addListChangeListener(listener);
4.
Para que la aplicacin utilice siempre la PIMList predeterminada, almacene una referencia a la PIMList
deseada y disee el mtodo ListChangeListener.defaultListChanged() para actualizar la referencia
cuando cambie la lista predeterminada.
Actualizar una entrada del calendario sin ninguna

notificacin
Puede actualizar entradas del calendario de un dispositivo BlackBerry sin enviar notificaciones a los participantes
de la entrada.
1.
74
Actualizar una entrada del calendario sin ninguna notificacin
Gua de desarrollo
import
import
import
import
import
2.
java.util.*;
javax.microedition.pim.*;
net.rim.blackberry.api.pdap.BlackBerryEvent;
net.rim.blackberry.api.pdap.BlackBerryEventList;
net.rim.blackberry.api.pdap.BlackBerryPIMItem;
Invoque PIM.openPIMList() para abrir una lista de entradas del calendario como un objeto
BlackBerryEventList.
BlackBerryEventList eventList = null;
try
{
eventList = (BlackBerryEventList)
PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);
}
catch (PIMException e)
{
// Handle exception
}
3.
Recupere un objeto BlackBerryEvent de la lista de entradas.

Enumeration events = eventList.items();
BlackBerryEvent event = (BlackBerryEvent) events.nextElement();
4.
Modifique la entrada.
if (eventList.isSupportedField(Event.SUMMARY))
{
event.addString(Event.NOTE, Event.ATTR_NONE, "Remember to bring food");
}
5.
Invoque BlackBerryPIMItem.commit() y especifique la marca

BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES para guardar los cambios.
{
try
{
int result;
result =
((BlackBerryPIMItem) event).commit(BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES);
}
{
// Handle exception
}
}
Si especifica BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES al confirmar los cambios de una entrada del

calendario, la notificacin no se enva a menos que la entrada del calendario sea una reunin nueva o se hayan
agregado nuevos participantes de la reunin desde la ltima actualizacin (los participantes de la reunin deben
ser notificados acerca de la reunin para poder aceptar la invitacin a la misma). Si la notificacin se ha enviado,
BlackBerryPIMItem.commit() devuelve BlackBerryEvent.MEETING_RECORD_NOT_FOUND o
BlackBerryEvent.INVITEE_LIST_CHANGED.
75
Eliminar una entrada del calendario sin ninguna notificacin
Gua de desarrollo
Ejemplo de cdigo
try
{
if (eventList.isSupportedField(Event.SUMMARY))
{
event.addString(Event.NOTE, Event.ATTR_NONE, "Remember to bring food");
}
{
int result;
result =
((BlackBerryPIMItem) event).commit(BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES);
}
}
{
// Handle exception
}
Eliminar una entrada del calendario sin ninguna

notificacin
Puede eliminar entradas del calendario de un dispositivo BlackBerry sin enviar notificaciones a los participantes de
la entrada.
1.

import
import
import
import
2.
java.util.*;
javax.microedition.pim.*;
net.rim.blackberry.api.pdap.BlackBerryEvent;
net.rim.blackberry.api.pdap.BlackBerryEventList;
Invoque PIM.openPIMList() para abrir una lista de entradas del calendario como un objeto
BlackBerryEventList.
try
{
}
{
// Handle exception
}
76
Gua de desarrollo
3.
Recupere un objeto BlackBerryEvent de la lista de entradas.

4.
Invoque BlackBerryEventList.removeElement() y especifique la marca

BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES para eliminar la entrada sin la notificacin.
try
{
eventList.removeEvent(event, BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES);
}
{
// handle exception
{
Si se produce un error cuando intenta eliminar el evento, el mtodo devuelve PIMException.

Ejemplo de cdigo
try
{
eventList.removeEvent(event, BlackBerryEvent.DO_NOT_NOTIFY_ATTENDEES);
}
{
// Handle exception
}
77
Gua de desarrollo
Lista de contactos
Lista de contactos
Puede utilizar una instancia de la clase ContactList o de la clase BlackBerryContactList en su aplicacin

para agregar y ver informacin de contactos en la aplicacin de contactos del dispositivo BlackBerry. Puede crear
los objetos Contact o BlackBerryContact para almacenar informacin de contactos individuales, como el
nombre, el nmero de telfono, la direccin de correo electrnico y la direccin de la calle.
Su aplicacin puede realizar tareas como agregar, borrar y cambiar las entradas de la lista de contactos.
Compatibilidad con diversas listas de contactos

En BlackBerry Java Development Environment 5.0 o posterior, se encuentra disponible la compatibilidad con
varias listas de contactos. Cada lista de contactos tiene un nombre de lista asignado por el sistema y un UID que
puede utilizar para recuperar la lista. Puede cambiar el nombre de la lista de contactos utilizando BlackBerry
Desktop Manager para cambiar el nombre del servicio asociado al nombre de la lista de contactos. No puede
cambiar el UID.
Al decidir cmo desea abrir una lista de contactos, debe considerar la persistencia en el dispositivo BlackBerry. Si
su aplicacin exige que se mantenga el nombre de lista de contactos en todas las actualizaciones del sistema
operativo, utilice el UID para abrir la lista de contactos. Si su aplicacin exige que se mantenga el nombre de lista
de contactos slo en los reinicios del dispositivo BlackBerry, puede utilizar el nombre de la lista de contactos. Dado
que un nombre de lista de contactos puede cambiar, puede registrar un servicio de escucha para eventos de
cambio de nombre invocando BlackBerryPIM.addListChangeListener(ListChangeListener
listener).
Puede recuperar los nombres de las listas de contactos que estn instaladas en un dispositivo BlackBerry
invocando PIM.listPIMLists(int pimListType) y pasando PIM.CONTACT_LIST como pimListType. La
matriz String que se devuelve ofrece los nombres asignados por el sistema a las listas de contactos del
dispositivo. El nombre de la lista de contactos que est en el ndice 0 de la matriz String devuelta es la lista de
contactos predeterminada. Puede recuperar el UID de una lista de contactos de un dispositivo BlackBerry
invocando BlackBerryPIMList.getPIMListUID().
Puede abrir una lista de contactos por su nombre invocando PIM.openPIMList(int pimListType, int
mode, String name). Puede abrir una lista del contacto por su UID invocando
BlackBerryPIM.openPIMList(int pimListType, int mode, long uid). Puede abrir una lista que
combine mltiples listas de contactos de un dispositivo invocando uno de los mtodos
BlackBerryPIM.openUnifiedPIMList().
Abrir la aplicacin de contactos

Puede abrir la aplicacin Contactos del dispositivo BlackBerry utilizando el mtodo
Invoke.invokeApplication() y pasando los argumentos pertinentes.
1.
78
Abrir la aplicacin de contactos utilizando los datos de contacto
Gua de desarrollo
import net.rim.blackberry.api.invoke.AddressBookArguments;
2.
Invoque Invoke.invokeApplication(APP_TYPE_ADDRESSBOOK, AddressBookArguments).

AddressBookArguments abArg = new AddressBookArguments();
Invoke.invokeApplication(Invoke.APP_TYPE_ADDRESSBOOK, abArg);
3.
Abrir la aplicacin de contactos utilizando los datos de

contacto
Puede abrir la aplicacin Contactos de un dispositivo BlackBerry y mostrar un contacto utilizando el mtodo
Invoke.invokeApplication() y pasando los datos de contacto como un parmetro de un objeto
AddressBookArguments.
1.

import
import
import
import
import
import
import
2.
net.rim.blackberry.api.invoke.AddressBookArguments;
net.rim.blackberry.api.pdap.BlackBerryContact;
net.rim.blackberry.api.pdap.BlackBerryContactList;
javax.microedition.pim.PIMException;
Invoque PIM.getInstance() para recuperar una instancia PIM, e invocar PIM.openPIMList(int, int)
para abrir la lista de contactos predeterminada, pasando como parmetros el tipo de lista que se va a abrir
(PIM.CONTACT_LIST) y el modo de acceso con el que se va a abrir la lista (PIM.READ_WRITE,
PIM.READ_ONLY, o PIM.WRITE_ONLY). Para abrir una lista de contactos con nombre, puede invocar en su lugar
PIM.openPIMList(int, int, String).
BlackBerryContactList contactList = (BlackBerryContactList)
PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
3.
Invoque BlackBerryContactList.getByUID(String uid) para recuperar un contacto de la lista de

contactos.
BlackBerryContact contact = contactList.getByUID("1XKIOD898");
4.
Cree una instancia de la clase AddressBookArguments, pasando un objeto Contact como parmetro.
AddressBookArguments abArg = new AddressBookArguments("ARG_VIEW", contact);
5.
Invoque Invoke.invokeApplication(APP_TYPE_ADDRESSBOOK, AddressBookArguments) y utilice el

objeto AddressBookArguments para el contacto.
Invoke.invokeApplication(Invoke.APP_TYPE_ADDRESSBOOK, abArg);
79
Abrir la aplicacin de contactos con una lista de contactos especfica
Gua de desarrollo
6.
Busque PIMException y ControlledAccessException si su aplicacin no tiene permiso para acceder a la

aplicacin que invoca.
Abrir la aplicacin de contactos con una lista de contactos

especfica
Puede abrir la aplicacin de contactos de un dispositivo BlackBerry y mostrar una lista de contactos especfica
invocando el mtodo BlackBerryContactList.choose().
1.

import
import
import
import
import
import
import
import
import
2.
net.rim.blackberry.api.pdap.BlackBerryContactGroup;
net.rim.blackberry.api.pdap.BlackBerryPIM;
javax.microedition.pim.PIMItem;
Invoque PIM.listPIMLists(int pimListType) para devolver una matriz de objetos String. La matriz
devuelta ofrece los nombres asignados por el sistema, uno para cada lista PIM del tipo especificado. La lista
predeterminada del tipo especificado se devuelve en el ndice 0 de la matriz.
String[] lists = PIM.listPIMLists(PIM.CONTACT_LIST);
3.
4.
Itere sobre la matriz que devuelve PIM.listPIMLists() para buscar el nombre asignado por el sistema a la
lista de contactos que desea mostrar.
Invoque BlackBerryPIMList.getPIMListUID() para obtener el UID de la lista de contactos.
long uid = cl.getPIMListUID();
5.
Invoque PIM.getInstance() para recuperar una instancia PIM, e invocar PIM.openPIMList(int, int,
long) para abrir la lista de contactos, pasando como parmetros el tipo de lista que se va a abrir
(PIM.CONTACT_LIST), el modo de acceso con el que se va a abrir la lista (PIM.READ_WRITE, PIM.READ_ONLY, o
PIM.WRITE_ONLY) y el UID.
BlackBerryContactList list = (BlackBerryContactList)
PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, uid);
6.
Invoque BlackBerryContactList.choose() para devolver un BlackBerryContact o un

BlackBerryContactGroup PIMItem.
PIMItem item = list.choose();
if (item instanceof BlackBerryContact)
{
BlackBerryContact contact = (BlackBerryContact) item;
int values = contact.countValues(BlackBerryContact.EMAIL);
String email = contact.getString(BlackBerryContact.EMAIL, 0);
System.out.println("Email is: " + email);
80
Crear un contacto y asignarlo a una lista de contactos
Gua de desarrollo
}
else if (item instanceof BlackBerryContactGroup)
{
...
}
7.

Crear un contacto y asignarlo a una lista de contactos

Puede crear un contacto y asignarlo a la lista de contactos predeterminada o bien a otra lista de contactos de un
dispositivo BlackBerry.
1.

import
import
import
import
import
import
import
import
2.
javax.microedition.pim.PIMList;
javax.microedition.pim.ContactList;
Para agregar el contacto nuevo a la lista de contactos predeterminada, invoque PIM.openPIMList(int, int)
para abrir una instancia de la lista de contactos predeterminada, pasando como parmetros el tipo de lista que
se va a abrir (PIM.CONTACT_LIST) y el modo de acceso PIM.READ_WRITE. Avance hasta el paso 4.
3.
Para agregar el contacto nuevo a una lista de contactos que no sea la lista de contactos predeterminada, realice
las acciones siguientes:
a. Invoque PIM.listPIMLists(int), pasando como parmetro el tipo de lista (PIM.CONTACT_LIST), para
devolver una matriz de objetos String. La matriz devuelta ofrece los nombres asignados por el sistema a
cada lista de contactos. La lista de contactos predeterminada se devuelve en el ndice 0 de la matriz.
b.
c.
Itere sobre la matriz que devuelve PIM.listPIMLists() para buscar el nombre asignado por el sistema
a la lista de contactos que desea abrir.
Invoque PIM.openPIMList(int, int, String) para abrir la instancia de la lista de contactos, pasando
como parmetro el tipo de lista que se va a abrir (PIM.CONTACT_LIST), el modo de acceso
PIM.READ_WRITE y el nombre de la lista de contactos.
PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, name);
4.
Invoque ContactList.createContact() para agregar el contacto nuevo a la lista de contactos.

BlackBerryContact contact = contactList.createContact();
81
Recuperar informacin de contacto
Gua de desarrollo
5.
Invoque uno o ms de los mtodos siguientes para agregar informacin referente al contacto nuevo. Para
obtener ms informacin acerca de mtodos PIMItem, consulte la referencia de API para BlackBerry Java
Development Environment.
addString()
addStringArray()
addDate()
addInt()
addBoolean()
addBinary()
6.
Invoque los mtodos siguientes para comprobar que la informacin cumple los requisitos de tamao y de tipo
del campo especificado del contacto.
Invoque ContactList.isSupportedField(int) para comprobar que el elemento es compatible con el
tipo de campo.
Invoque ContactList.isSupportedAttribute(int, int) para comprobar que el campo es
compatible con el atributo especificado.
Invoque PIMList.maxValues(int field) para comprobar el nmero de valores con los que es
compatible el campo.
7.
Invoque Contact.commit() para acometer los cambios.

if(contact.isModified())
{
contact.commit();
}
8.

Recuperar informacin de contacto

Puede recuperar informacin de una lista de contactos de un dispositivo BlackBerry invocando uno de los
mtodos PIMList.items(). Estos mtodos devuelven una enumeracin de todos los contactos de una lista de
contactos especfica. Puede invocar los mtodos BlackBerryContactList.items() para devolver grupos de
contactos.
1.

import
import
import
import
import
import
import
82
Gua de desarrollo
2.
Recuperar un UID de listas de contactos
Invoque PIM.getInstance() para recuperar una instancia PIM e invocar PIM.openPIMList() para abrir
una instancia de la lista de contactos, pasando como parmetros el tipo de lista que se va a abrir
(PIM.CONTACT_LIST), el modo de acceso con el que abrir la lista (PIM.READ_WRITE, PIM.READ_ONLY, o
PIM.WRITE_ONLY), y el nombre si no va a abrir la lista de contactos predeterminada.
3.
Invoque PIMList.items() para recuperar una enumeracin de elementos de una lista de contactos.
Enumeration _enum = contactList.items();
4.
Invoque uno de los mtodos getter de PIMItem para recuperar informacin de contacto.
Para recuperar una matriz de campos que contengan los datos de un contacto especificado, invoque
PIMItem.getFields().
Para recuperar un String que represente el valor para un campo de contactos especificado, invoque
PIMItem.getString(int field, int index).
Para recuperar una fecha que represente el valor para un campo de contactos especificado, invoque
PIMItem.getDate(int field, int index).
while (_enum.hasMoreElements())
{
BlackBerryContact c = (BlackBerryContact)_enum.nextElement();
int[] fieldIds = c.getFields();
int id;
{
if(c.getPIMList().getFieldDataType(id) == BlackBerryContact.STRING)
{
for(int j=0; j < c.countValues(id); ++j)
{
String value = c.getString(id, j);
System.out.println(c.getPIMList().getFieldLabel(id) + "="
+ value);
}
}
}
}
Recuperar un UID de listas de contactos

Puede abrir una lista de contactos de un dispositivo BlackBerry especificando un nombre asignado por el sistema o
un UID. El UID est asociado a una cuenta de BlackBerry Enterprise Server y se mantiene durante todos los
cambios del dispositivo BlackBerry, incluyendo las actualizaciones del sistema operativo. Puede abrir la lista de
contactos por su UID invocando BlackBerryPIM.openPIMList(int pimListType, int mode, long
uid).
1.
83
Exportar un contacto
Gua de desarrollo
import
import
import
import
import
2.
3.
Acceda a la lista de contactos con la que desee trabajar.

Invoque BlackBerryPIMList.getPIMListUID() para recuperar el UID de la lista de contactos.
long uid = list.getPIMListUID();
Exportar un contacto
Puede exportar informacin de contacto de una lista de contactos de un dispositivo BlackBerry a un flujo de salida.
El proceso de exportacin convierte un elemento PIM en un flujo de salida de bytes que pueda importar otra
aplicacin. Puede exportar datos PIM a un formato de serie compatible invocando
PIM.toSerialFormat(PIMItem, OutputStream, String, String) y pasando como argumentos
PIMItem, el OutputStream en el que se programa el PIMItem serializado, el formato de codificacin de
caracteres que se va a utilizar al programar en el flujo de salida y el formato de serie compatible al que convertir,
como por ejemplo vCard.
1.

import
import
import
import
import
import
2.
java.io.UnsupportedEncodingException;
javax.microedition.pim.Contact;
Invoque PIM.supportedSerialFormats() y especifique el tipo de lista (PIM.CONTACT_LIST) para

recuperar una matriz de cadena de los formatos de serie compatibles.
ContactList contactList = (ContactList)
String[] dataFormats = PIM.getInstance().supportedSerialFormats(PIM.CONTACT_LIST);
3.
Invoque PIM.getInstance().toSerialFormat(item, stream, enc, dataFormat) para escribir un

elemento en un formato de serie compatible. Utilice el parmetro enc para especificar el formato de codificacin
de caracteres que se va a utilizar al programar en el flujo de salida. Los formatos de codificacin de caracteres
compatibles incluyen UTF8, ISO-8859-1 y UTF-16BE. Si el parmetro enc es nulo, el mtodo utiliza UTF-8.
ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
Enumeration e = contactList.items();
{
try
{
Contact c = (Contact)e.nextElement();
PIM.getInstance().toSerialFormat(c, byteStream, "UTF8", dataFormats[0]);
}
84
Importar un contacto
Gua de desarrollo
catch (UnsupportedEncodingException ex)

{
System.out.println(ex.toString());
}
Importar un contacto
Puede importar informacin de contactos de un flujo de entrada compatible a una lista de contactos de un
dispositivo BlackBerry. Puede importar informacin de contacto invocando fromSerialFormat(InputStream,
String) y pasando como argumentos el PIMItem desde el que se programa el InputStream y el formato de
codificacin de caracteres que se va a utilizar. Los formatos de codificacin de caracteres compatibles incluyen
UTF8, ISO-8859-1 y UTF-16BE.
1.

import
import
import
import
import
2.
Invoque PIM.getInstance().fromSerialFormat() para devolver una matriz de elementos de PIM.

ByteArrayInputStream istream =
new ByteArrayInputStream(outputStream.toByteArray());
PIMItem[] pi = PIM.getInstance().fromSerialFormat(istream, "UTF8");
3.
Abra una lista de contactos e invoque ContactList.importContact() para crear un contacto nuevo
utilizando un elemento PIM.
ContactList contactList = (ContactList)
Contact contact2 = contactList.importContact((Contact) pi[0]);
contact2.commit();
Eliminar un contacto
Puede eliminar un contacto de la lista de contactos predeterminada o bien de otra lista de contactos de un
1.

import
import
import
import
import
import
import
85
Gua de desarrollo
2.
Notificar a una aplicacin cuando una lista de contactos cambia
Para eliminar un contacto de la lista de contactos predeterminada, invoque PIM.openPIMList(int, int)

para abrir la instancia de la lista de contactos predeterminada, pasando como parmetros el tipo de la lista que
se va a abrir (PIM.CONTACT_LIST) y el modo de acceso con el que abrir la lista (PIM.READ_WRITE,
PIM.READ_ONLY, o PIM.WRITE_ONLY). Avance hasta el paso 4.
3.
Para eliminar un contacto de una lista de contactos que no sea la lista de contactos predeterminada, realice las
acciones siguientes:
a. Invoque listPIMLists(int pimListType) para devolver una matriz de objetos String. La matriz
devuelta ofrece el nombre asignado por el sistema a cada lista de contactos. La lista de contactos
predeterminada se devuelve en el ndice 0 de la matriz.
b.
c.
a la lista de contactos que desea eliminar.
como parmetros el tipo de lista que se va a abrir (PIM.CONTACT_LIST), el modo de acceso con el que
abrir la lista (PIM.READ_WRITE, PIM.READ_ONLY, o PIM.WRITE_ONLY) y el nombre de la lista de
contactos.
4.
Invoque BlackBerryContactList.removeContact() para eliminar el contacto de la lista de contactos.

contactList.removeContact(contact);
5.

Notificar a una aplicacin cuando una lista de contactos

cambia
Puede registrar su aplicacin para recibir la notificacin de cambios en las listas de contactos de un dispositivo
BlackBerry implementando la interfaz PIMListListener. La interfaz PIMListListener ofrece los mtodos
siguientes:
itemAdded(PIMItem item), que se invoca cuando se agrega un elemento a una lista de contactos
itemUpdated(PIMItem oldItem, PIMItem newItem), que se invoca cuando un elemento cambia
itemRemoved(PIMItem item), que se invoca cuando se elimina un elemento de una lista de contactos
1.

import net.rim.blackberry.api.pdap.BlackBerrryContact;
import net.rim.blackberry.api.pdap.BlackBerryContactList;
import net.rim.blackberry.api.pdap.BlackBerryPIMList;
86
Gua de desarrollo
import
import
import
import
2.
Notificar a una aplicacin cuando una lista de contactos cambia
net.rim.blackberry.api.pdap.PIMListListener;
Para recibir notificaciones de cambios de la lista de contactos predeterminada, invoque
PIM.openPIMList(int, int) para abrir la instancia de la lista de contactos predeterminada, pasando como
parmetros el tipo de la lista que se va a abrir (PIM.CONTACT_LIST) y el modo de acceso con el que abrir la
lista (PIM.READ_WRITE, PIM.READ_ONLY, o PIM.WRITE_ONLY). Avance hasta el paso 4.
3.
Para recibir notificaciones de cambios de una lista de contactos que no sea la lista de contactos predeterminada,
realice las acciones siguientes:
a. Invoque listPIMLists(int), pasando como parmetro el tipo de lista que se va a abrir
(PIM.CONTACT_LIST), para devolver una matriz de objetos String. La matriz devuelta ofrece el nombre
asignado por el sistema a cada lista de contactos. La lista de contactos predeterminada se devuelve en el
ndice 0 de la matriz.
b.
c.
a la lista de contactos respecto a la que desea recibir notificaciones de cambios.
como parmetros el tipo de lista que se va a abrir (PIM.CONTACT_LIST), el modo de acceso con el que
abrir la lista (PIM.READ_WRITE, PIM.READ_ONLY, o PIM.WRITE_ONLY) y el nombre de la lista de
contactos.
4.
Invoque BlackBerryPIMList.addListener() para registrar un servicio de escucha para la lista de

contactos.
(BlackBerryPIMList) contactList.addListener(new PIMListListener());
5.
Omita lo mtodos PIMListListener.itemAdded(), PIMListListener.itemUpdated() y

PIMListListener.itemRemoved() para configurar el comportamiento de notificacin.
public void itemAdded(PIMItem item)
{
System.out.println("ITEM ADDED: " +
(BlackBerryContact) item.getString(BlackBerryContact.UID, 0));
}
public void itemUpdated(PIMItem oldItem, PIMItem newItem)
{
System.out.println("ITEM UPDATED: " + (BlackBerryContact)
oldItem.getString(BlackBerryContact.UID, 0) + " to " +
(BlackBerryContact) newItem.getString(Contact.UID, 0));
}
public void itemRemoved(PIMItem item)
{
87
Crear y eliminar listas de contactos
Gua de desarrollo
6.
System.out.println("ITEM REMOVED: " +

(BlackBerryContact) item.getString(BlackBerryContact.UID, 0));


Puede crear listas de contactos en un dispositivo BlackBerry invocando BlackBerryPIM.createPIMList().
Actualmente, el tipo de lista PIM que especifique cuando invoque createPIMList() debe ser
PIM.CONTACT_LIST o se devolver PIMException.
Tambin puede eliminar listas de contactos invocando BlackBerryPIM.removePIMList(). Actualmente, este
mtodo admite listas PIM slo de tipo PIM.CONTACT_LIST.
Crear una lista de contactos

Puede crear listas de contactos en un dispositivo BlackBerry. Tenga en cuenta lo siguiente acerca de las listas de
contactos que cree:
Cada lista de contactos tiene un identificador nico, que es el valor que devuelve createPIMList().
Las listas de contactos no tienen registros de servicio y no admiten la sincronizacin inalmbrica.
Las aplicaciones pueden registrarse para escuchar los cambios en la lista de contactos invocando
BlackBerryPIMList.addListener().
1.

import
import
import
import
import
import
import
import
2.
net.rim.blackberry.api.pdap.BlackBerryPIM;
Recupere un objeto BlackBerryPIM.

BlackBerryPIM myPIM = (BlackBerryPIM) PIM.getInstance();
3.
Cree la lista de contactos.

long listUID = myPIM.createPIMList(PIM.CONTACT_LIST, "test");
4.
88
El nombre de la lista de contactos es el que usted proporciona ("prueba" en el ejemplo anterior), a menos que
haya otra lista de contactos con ese nombre en el dispositivo, en cuyo caso se agrega un nmero al nombre para
hacerlo nico. Para hacer referencia a la lista de contactos ms tarde, debe utilizar el UID de la lista, que es el
valor que devuelve createPIMList().
Opcionalmente, rellene la lista de contactos.
Gua de desarrollo
BlackBerryContactList contactList =
(BlackBerryContactList) myPIM.openPIMList(PIM.CONTACT_LIST,
PIM.READ_WRITE, listUID);
Contact contact = contactList.createContact();
String[] name = new String[contactList.stringArraySize(Contact.NAME)];
name[Contact.NAME_GIVEN] = "Noha";
name[Contact.NAME_FAMILY] = "Toma";
contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, name);
contact.commit();
5.
Cierre la lista de contactos.

contactList.close();
Ejemplo de cdigo
try
{
// create a contact list
long listUID = myPIM.createPIMList(PIM.CONTACT_LIST, "test");
// add a contact to the list
BlackBerryContactList contactList =
(BlackBerryContactList) myPIM.openPIMList(PIM.CONTACT_LIST,
PIM.READ_WRITE, listUID);
Contact contact = contactList.createContact();
String[] name = new String[contactList.stringArraySize(Contact.NAME)];
name[Contact.NAME_GIVEN] = "Noha";
name[Contact.NAME_FAMILY] = "Toma";
contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, name);
contact.addString(Contact.TEL, Contact.ATTR_HOME, "519-555-0151");
contact.addString(Contact.TEL, Contact.ATTR_WORK, "519-555-0199");
contact.commit();
// close the contact list
contactList.close();
}
{
}
Eliminar listas de contactos

Puede eliminar listas contactos de un dispositivo BlackBerry. Tenga en cuenta lo siguiente acerca de eliminar listas
de contactos:
No se pueden eliminar las listas de contactos que tienen registros de servicio.

No se puede eliminar la ltima lista de contactos de un dispositivo.
No se puede eliminar la lista de contactos predeterminada (la que tiene el UID -1).
89
Gua de desarrollo
Recuperar el contacto asociado con una llamada activa
Se devuelve BlackBerryPIMRemovalException si se produce un error cuando intenta eliminar una lista de

contactos.
1.

import net.rim.blackberry.api.pdap.BlackBerryPIM;
import net.rim.blackberry.api.pdap.BlackBerryPIMRemovalException;
2.
Recupere un objeto BlackBerryPIM.

3.
4.
Si sabe el nombre o el UID de la lista de contactos que quiere eliminar, vaya al paso 6.
Recupere la matriz de listas de contactos.
String[] lists = myPIM.listPIMLists(PIM.CONTACT_LIST);
5.
6.
La matriz devuelta proporciona los nombres asignados a cada lista de contactos.

Repase toda la matriz para buscar la lista de contactos que quiere eliminar.
Elimine la lista de contactos invocando BlackBerryPIM.removePIMList(). Puede proporcionar tanto el
nombre como el UID de la lista de contactos. De forma predeterminada, el mtodo elimina una lista de contactos
slo si est vaca. Si quiere eliminar una lista de contactos que no est vaca, debe proporcionar el parmetro
BlackBerryPIM.REMOVE_NON_EMPTY_LIST.
try
{
myPIM.removePIMList(PIM.CONTACT_LIST, "test",
BlackBerryPIM.REMOVE_NON_EMPTY_LIST);
}
catch (BlackBerryPIMRemovalException e)
{
// handle the exception
}
Ejemplo de cdigo
try
{
myPIM.removePIMList(PIM.CONTACT_LIST, "test",
BlackBerryPIM.REMOVE_NON_EMPTY_LIST);
}
catch (BlackBerryPIMRemovalException e)
{
}

1.
90
Gua de desarrollo
import net.rim.blackberry.api.pdap.BlackBerryContact;
import net.rim.blackberry.api.phone.*;
2.
Implemente un oyente de telfono.

class MyPhoneListener extends AbstractPhoneListener
{
}
3.
Invoque PhoneCall.getContact() en un mtodo de devolucin de llamada en el servicio de escucha de

telfono (por ejemplo, en callIncoming() para una llamada nueva). El mtodo getContact() busca en
todas las listas de contactos del dispositivo BlackBerry y devuelve un BlackBerryContact que est asociado
con el nmero de telfono actual o null si no hay contacto que coincida.
public void callIncoming(int callId)
{
PhoneCall call = Phone.getCall(callId);
BlackBerryContact contact = call.getContact();
}
4.
Utilice la informacin de contacto recuperada.
Ejemplo de cdigo
public void callIncoming(int callID) // in a phone listener
{
StringBuffer strBuffer = new StringBuffer();
PhoneCall call = Phone.getCall(callID);
BlackBerryContact contact = call.getContact();
if(contact != null)
{
if(contact.countValues(BlackBerryContact.ADDR) > 0)
{
String[] strArray = contact.getStringArray(BlackBerryContact.ADDR, 0);
String city = strArray[BlackBerryContact.ADDR_LOCALITY];
if(city != null && city.length() > 0)
{
strBuffer.append(city);
}
String country = strArray[BlackBerryContact.ADDR_COUNTRY];
if(country != null && country.length() > 0)
{
if(city != null && city.length() > 0)
{
strBuffer.append(", ");
}
strBuffer.append(country);
}
}
}
// use the contact info, for example,
// display it on the incoming phone screen
}
Informacin relacionada
91
Recuperar el contacto asociado con una llamada finalizada
Gua de desarrollo
Mostrar contenido en una pantalla de telfono, 114
Recuperar el contacto asociado con una llamada

finalizada
Puede recuperar el contacto asociado con una llamada finalizada del registro de llamadas de un dispositivo
BlackBerry.
1.

import javax.microedition.pim.Contact;
import net.rim.blackberry.api.pdap.BlackBerryContact;
import net.rim.blackberry.api.phone.phonelogs.PhoneCallLogID;
2.
Recupere la informacin de ID de llamada de una llamada del registro de llamadas.

PhoneCallLogID callLog = new PhoneCallLogID(phoneNum);
3.
Recupere el contacto asociado invocando PhoneCallLogID.getContact(). El mtodo getContact() busca

en todas las listas de contactos del dispositivo BlackBerry un contacto que coincida con la informacin de ID de
llamada. El mtodo devuelve null si ningn contacto coincide.
BlackBerryContact contact = callLog.getContact();
Ejemplo de cdigo
String phoneNum = "519-555-0151";
PhoneCallLogID callLog = new PhoneCallLogID(phoneNum);
BlackBerryContact contact = callLog.getContact();
if (contact != null)
{
String[] name = contact.getStringArray(Contact.NAME, 0);
add(new RichTextField("The matching contact is " + name[Contact.NAME_GIVEN]
+ " " + name[Contact.NAME_FAMILY]));
}
else
{
add(new RichTextField("There is no matching contact"));
}
Recuperar contactos por nmero de telfono

Puede buscar en todas las listas de contactos o en una lista especfica de un dispositivo BlackBerry para encontrar
los contactos que coincidan con un nmero de telfono especificado.
1.

import
import
import
import
92
net.rim.blackberry.api.phone.Phone;
Gua de desarrollo
import
import
import
import
2.
java.util.*;
Lleve a cabo una de las acciones siguientes:

a. Para buscar en todas las listas de contactos, invoque Phone.getContactsByPhoneNumber(), que
devuelve un objeto Vector que contiene los contactos que coinciden con el nmero de telfono
especificado. El Vector est vaco si no hay contactos que coincidan.
Vector contacts = Phone.getContactsByPhoneNumber(phoneNum);
b.
Para buscar en una lista de contactos especificada, invoque

BlackBerryContactList.itemsByPhoneNumber(), que devuelve un objeto Enumeration de todos
los contactos que coinciden con el nmero de telfono especificado. Cada uno de los elementos de
Enumeration es un objeto PIMItem que puede asignar a un objeto BlackBerryContactList.
PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, "test");
Enumeration myEnum = list.itemsByPhoneNumber(phoneNum);
Ejemplo de cdigo
try
{

PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, "test");
Enumeration myEnum = list.itemsByPhoneNumber(phoneNum);
while (myEnum.hasMoreElements())
{
Object o = myEnum.nextElement();
if (o instanceof BlackBerryContact)
{
BlackBerryContact c = (BlackBerryContact) o;
String[] name = c.getStringArray(Contact.NAME, 0);
add(new RichTextField("A matching contact is " +
name[Contact.NAME_GIVEN] + " " + name[Contact.NAME_FAMILY]));
}
}
}
catch (Exception e)
{
}
93
Gua de desarrollo
Vincular contactos de terceros con contactos de la aplicacin Contactos
Vincular contactos de terceros con contactos de la

aplicacin Contactos
Puede permitir que los usuarios de dispositivos BlackBerry vinculen datos de contacto de su aplicacin con
contactos de la aplicacin de contactos del dispositivo BlackBerry utilizando la API de vinculacin de contactos del
paquete net.rim.blackberry.api.pdap.contactlinking. Por ejemplo, puede permitir que los usuarios
vinculen un contacto de su aplicacin de administracin de las relaciones con el cliente (CRM) con un contacto de
la aplicacin Contactos.
Un contacto de una aplicacin de terceros puede vincularse slo con un contacto de la aplicacin Contactos. Sin
embargo, un contacto de la aplicacin Contactos puede vincularse con contactos de varias aplicaciones de
terceros. Cuando un usuario trata de vincular un contacto de su aplicacin con un contacto de la aplicacin
Contactos, usted puede utilizar la API de vinculacin de contactos para realizar algunas tareas automticamente,
como buscar un contacto coincidente y comprobar si el contacto ya est vinculado.
Puede crear elementos del men que aparezcan en la aplicacin Contactos cuando un usuario vea un contacto
vinculado con uno de sus contactos. Los elementos del men pueden realizar cualquier accin que desee. Por
ejemplo, puede permitir que un usuario agregue notas a la aplicacin Contactos acerca del contacto de su
aplicacin.
Puede definir la informacin que se mostrar en la aplicacin Contactos cuando el usuario vea un contacto
vinculado a uno de sus contactos.
La aplicacin de ejemplo de vinculacin de contactos se incluye en el BlackBerry Java SDK. La aplicacin demuestra
cmo utilizar la API de vinculacin de contactos.
Vincular un contacto
Puede vincular un contacto de su aplicacin con un contacto de la aplicacin Contactos del dispositivo BlackBerry.
Puede decidir cmo interactuar con el usuario del dispositivo BlackBerry cuando vincula un contacto. Los pasos
siguientes describen un enfoque posible.
Antes de comenzar:
Cree los contactos en su aplicacin creando una clase que implemente la interfaz LinkableContact y tambin
una instancia de la misma.
Defina una clase que ample LinkedContactInfoProvider y registre la clase con su aplicacin. Para obtener
ms informacin, consulte Crear un proveedor de informacin para un contacto vinculado.
1.

import net.rim.blackberry.api.pdap.*;
import net.rim.blackberry.api.pdap.contactlinking.*;
import javax.microedition.pim.*;
2.
94
Compruebe si hay un contacto en la aplicacin de contactos (un objeto BlackBerryContact) que sea un
candidato para la vinculacin de su contacto. El mtodo
LinkedContactUtilities.getContactLinkCandidate() devuelve BlackBerryContact si encuentra
Gua de desarrollo
un contacto en la aplicacin de contactos que tenga la misma direccin de correo electrnico o el mismo nmero
de telfono que el LinkableContact que se le ha pasado. Si no hay ningn contacto coincidente, el mtodo
devuelve null.
BlackBerryContact bbContact =
LinkedContactUtilities.getContactLinkCandidate(linkableContact);
3.
Si se encuentra una coincidencia, vincule su contacto con BlackBerryContact.

bbContact = LinkedContactUtilities.linkContact(bbContact, linkableContact);
4.
Si no se encuentra ninguna coincidencia, haga que el usuario seleccione un contacto de la aplicacin Contactos
para vincularlo con el contacto seleccionado.
BlackBerryContactList contacts = null;
try
{
contacts = (BlackBerryContactList) PIM.getInstance().
openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
}
catch(PIMException e)
{
ContactLinkingDemo.errorDialog("Couldn't open contacts list.");
return;
}
Object choice = contacts.choose();
if(choice instanceof BlackBerryContact)
{
bbContact = (BlackBerryContact)choice;
}
5.
Compruebe si el contacto seleccionado de la aplicacin Contactos ya est vinculado con un contacto de su

aplicacin.
LinkedContactUtilities.isContactLinked(bbContact,
linkableContact.getApplicationID())
6.
Si el contacto seleccionado en la aplicacin Contactos an no est vinculado, vinclelo con el contacto de su

aplicacin.
bbContact = LinkedContactUtilities.linkContact(bbContact, linkableContact);
Ejemplo de cdigo: Vincular un contacto

Para consultar un ejemplo de este planteamiento para vincular un contacto, consulte linkContact() en la
aplicacin de ejemplo de demostracin de vinculacin de contactos que se incluye en BlackBerry Java SDK.
Eliminar un vnculo
Puede eliminar un vnculo entre un contacto de su aplicacin y un contacto de la aplicacin Contactos del
1.

95
Gua de desarrollo
2.
Recupere el contacto de la aplicacin Contactos vinculado con su contacto.

BlackBerryContact contact =
LinkedContactUtilities.getLinkedContact(linkableContact);
3.
Elimine el vnculo entre los contactos.

LinkedContactUtilities.unlinkContact(contact, linkableContact.getApplicationID());
Ejemplo de cdigo: Eliminar un vnculo

private void unlinkContact(LinkableContact linkableContact)
{
BlackBerryContact contact =
LinkedContactUtilities.getLinkedContact(linkableContact);
if(contact != null)
{
LinkedContactUtilities.unlinkContact(contact,
linkableContact.getApplicationID());
}
}
Crear elementos del men para contactos vinculados

Puede crear elementos del men que estn disponibles en la aplicacin Contactos en el dispositivo BlackBerry
cuando un usuario vea un contacto que est vinculado con un contacto en su aplicacin invocando
LinkedContactUtilities.registerMenuItems(). Debe asignar elementos del men a un grupo de
aplicaciones utilizando la interfaz LinkedContactConstants.
Grupo de aplicaciones
COMPOSE_SN_MENU_GROUP
COMPOSE_IM_MENU_GROUP
COMPOSE_OTHER_MENU_GROUP
Descripcin
aplicaciones de redes sociales
aplicaciones de mensajera instantnea
aplicaciones que no son aplicaciones de redes sociales ni aplicaciones
de mensajera instantnea
Si un contacto de la aplicacin Contactos est vinculado con contactos de varias aplicaciones de terceros, los
elementos del men de la aplicacin de contactos se agrupan con otras aplicaciones del mismo grupo.
Los elementos del men de redes sociales se agrupan dentro del elemento del men Redes sociales.
Los elementos del men de mensajera instantnea se agrupan dentro el elemento del men Mensajera
instantnea.
Los elementos del men de otros tipos de aplicaciones se agrupan dentro del elemento del men Contactar
mediante.
Los elementos del men de aplicaciones de terceros con contactos vinculados se integran con el men de la
aplicacin Contactos.
96
Gua de desarrollo
Situacin
Resultado
Un grupo contiene una aplicacin con
El elemento del men de la aplicacin aparece en el men de la
contactos vinculados. La aplicacin
aplicacin Contactos.
contiene un elemento del men.
Un grupo contiene una aplicacin con
El nombre de la aplicacin aparece en el men. Al seleccionar el
contactos vinculados. La aplicacin
nombre aparece un cuadro de dilogo que contiene un botn para
contiene varios elementos del men.
cada elemento del men.
Un grupo contiene varias aplicaciones con El elemento del men del grupo (como Redes sociales) aparece en el
contactos vinculados.
men. Al seleccionar el elemento del men del grupo, se muestra un
cuadro de dilogo con un botn para cada aplicacin con contactos
vinculados en el grupo.
Crear elementos del men para contactos vinculados

Puede crear elementos del men disponibles en la aplicacin Contactos del dispositivo BlackBerry cuando un
usuario vea un contacto que vinculado con un contacto de su aplicacin.
1.

import
import
import
import
2.
net.rim.blackberry.api.menuitem.ApplicationMenuItem;
net.rim.blackberry.api.pdap.contactlinking.LinkedContactConstants;
net.rim.blackberry.api.pdap.contactlinking.LinkedContactUtilities;
net.rim.device.api.system.ApplicationDescriptor;
Cree una clase que ample la clase ApplicationMenuItem.

public class LinkedMenuItem extends ApplicationMenuItem {...}
3.
Cree un descriptor de aplicacin para su aplicacin.

ApplicationDescriptor appdesc = new
ApplicationDescriptor(ApplicationDescriptor.currentApplicationDescriptor(),
"Linking Application", null);
4.
Cree una variable para almacenar el ID nico de su aplicacin.

public static final long APPLICATION_ID = 0x1eredfe71d34760fdL;
5.
Cree una matriz con una o ms instancias del elemento del men.
ApplicationMenuItem[] items = new ApplicationMenuItem[1];
items[0] = new LinkedMenuItem();
6.
Invoque LinkedContactUtilities.registerMenuItems() para agregar los elementos del men para el

contacto vinculado al men. Pase la matriz de elementos del men, el ID nico de su aplicacin, el grupo de
aplicaciones y el descriptor de la aplicacin.
LinkedContactUtilities.registerMenuItems(items, APPLICATION_ID,
LinkedContactConstants.COMPOSE_SN_MENU_GROUP, appdesc);
97
Gua de desarrollo
Ejemplo de cdigo: Crear elementos del men para contactos vinculados

Para consultar un ejemplo de creacin de elementos de men para contactos vinculados, consulte la clase
SampleMenuItem y main() en la aplicacin de ejemplo de demostracin de vinculacin de contactos que se
incluye en BlackBerry Java SDK.
Crear un proveedor de informacin para un contacto vinculado

Puede crear una clase que ample la clase LinkedContactInfoProvider abstracta para definir informacin
sobre un contacto vinculado. Esta informacin aparece en la aplicacin Contactos del dispositivo BlackBerry
cuando un usuario ve un contacto vinculado a un contacto de su aplicacin.
1.

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
2.
Cree una clase que ample LinkedContactInfoProvider.

public class SampleLinkedContactInfoProvider extends LinkedContactInfoProvider
{
private Image _image;
private String _appName;
public SampleLinkedContactInfoProvider(Image image, String appName)
{
_image = image;
_appName = appName;
}
3.
Implemente getAppImage() y devuelva el icono que representa su aplicacin. El mtodo debe devolver una
imagen para que aparezca cualquier informacin sobre su contacto vinculado cuando un usuario vea un contacto
en la aplicacin de Contactos.
public Image getAppImage()
{
return _image;
}
4.
Implemente getAppName() y devuelva el nombre de su aplicacin. El mtodo debe devolver un nombre para
que aparezca la informacin sobre el contacto vinculado cuando un usuario edite un contacto en la aplicacin
Contactos.
public String getAppName()
{
return _appName;
}
5.
98
Para indicar los campos LinkedContactInfoProvider (nombre de usuario, disponibilidad o estado) que
admite su aplicacin, implemente isSupported(). De forma predeterminada, los campos no se admiten. Debe
implementar isSupported() slo si su aplicacin admite cualquiera de los campos.
Gua de desarrollo
public boolean isSupported(int capability)

{
switch(capability)
{
case LinkedContactInfoProvider.STATUS:
case LinkedContactInfoProvider.AVAILABILITY:
case LinkedContactInfoProvider.USER_NAME:
return true;
default:
return false;
}
}
6.
Implemente requestFields() para especificar la informacin para mostrar para el contacto en la aplicacin
Contactos. El mtodo es invocado por el marco cuando necesita mostrar informacin para el contacto vinculado
en la aplicacin Contactos. Especifique el nombre del contacto, el estado y la disponibilidad actual, en funcin
de los campos que haya definido como admitidos en isSupported().
public void requestFields(String contactID, final LinkedContactCallback callback,
int fields)
{
LinkableContact contact = ContactListScreen.getUserForID(contactID);
if((fields & LinkedContactInfoProvider.AVAILABILITY) != 0)
{
callback.setAvailability(LinkedContactInfoProvider.AVAILABILITY_ONLINE);
}
if((fields & LinkedContactInfoProvider.STATUS) != 0)
{
callback.setStatusString("<Sample contact status>");
}
if((fields & LinkedContactInfoProvider.USER_NAME) != 0)
{
callback.setUserName(contact.toString());
}
}
7.
Registre al proveedor de informacin con su aplicacin.

LinkedContactUtilities.registerLinkedContactInfoProvider(
new SampleLinkedContactInfoProvider(imageBlue, "Demo App 1"),
APPLICATION_ID,
LinkedContactConstants.COMPOSE_SN_MENU_GROUP);
Este ejemplo registra la aplicacin como una aplicacin de redes sociales utilizando el campo
COMPOSE_SN_MENU_GROUP en LinkedContactConstants.
Cuando un usuario muestra un contacto de la aplicacin Contactos vinculado a uno de los suyos, la informacin
que defini en el proveedor de informacin se visualiza en la pantalla del contacto. El marco determina la
disposicin de la informacin. En este ejemplo, dado que la aplicacin fue definida como una aplicacin de red
social, la informacin se muestra en la seccin de Redes sociales del contacto.
Ejemplo de cdigo: Crear un proveedor de informacin para un contacto vinculado
99
Gua de desarrollo
Para consultar un ejemplo de creacin de un proveedor de informacin para un contacto vinculado, consulte la
clase SampleLinkedContactInfoProvider en la aplicacin de ejemplo de demostracin de vinculacin de
contactos que se incluye enBlackBerry Java SDK.
100
Lista de tareas
Gua de desarrollo
Lista de tareas
Ver o cambiar una tarea

1.

import
import
import
import
import
import
2.
javax.microedition.pim.ToDo;
javax.microedition.pim.ToDoList;
net.rim.blackberry.api.invoke.TaskArguments;
Cree una instancia de una ToDoList y almacnela en una Enumeration.

ToDoList tdl = (ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST,
PIM.READ_WRITE);
Enumeration todos = tdl.items();
3.
Cree un objeto ToDo utilizando un elemento de la Enumeration.

ToDo todo = (ToDo)todos.nextElement();
4.
Invoque Invoke.invokeApplication() mediante el campo APP_TYPE_TASKS y un objeto TaskArguments

nuevo creado mediante el campo ARG_VIEW y el objeto ToDo.
Invoke.invokeApplication(Invoke.APP_TYPE_TASKS,
new TaskArguments(TaskArguments.ARG_VIEW, todo));
Crear una tarea nueva en blanco

1.

import net.rim.blackberry.api.invoke.TaskArguments;
2.

nuevo creado utilizando el campo ARG_NEW.
new TaskArguments( TaskArguments.ARG_NEW));
Crear una tarea nueva rellenada

1.

import java.util.Enumeration;
import javax.microedition.pim.ToDo;
101
Gua de desarrollo
Abrir una lista de tareas
import javax.microedition.pim.ToDoList;
import net.rim.blackberry.api.invoke.TaskArguments;
2.
Cree una instancia de ToDoList.

ToDoList tdl = (ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST,
PIM.READ_WRITE);
3.
Invoque createToDo() para crear un objeto ToDo nuevo y agregue informacin al nuevo objeto ToDo.
ToDo todo = tdl.createToDo();
todo.addString(ToDo.SUMMARY, 0, "Walk the Dog");
4.

nuevo creado mediante el campo ARG_NEW y el objeto ToDo nuevo.
new TaskArguments( TaskArguments.ARG_NEW, todo));
Abrir una lista de tareas

1.

import javax.microedition.pim.PIMException;
2.
Invoque PIM.openPIMList() y proporcione como parmetros el tipo de la lista que se va a abrir

(PIM.TODO_LIST) y el modo de acceso con el que abrir la lista (READ_WRITE, READ_ONLY, o WRITE_ONLY).
ToDoList todoList = null;
try
{
todoList = (ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST,
PIM.READ_WRITE);
}
catch (PimException e)
{
// handle exception here
}
Creacin de una tarea

1.

2.
Invoque ToDoList.createToDo() en una lista de tareas.

ToDo task = todoList.createToDo();
102
Agregar informacin de tareas
Gua de desarrollo
Agregar informacin de tareas

1.

import
import
import
import
2.
3.
4.
java.util.Date;
Antes de definir o recuperar un valor de campo, verifique que el elemento admite el campo llamando a
ToDoList.isSupportedField(int).
Invoque PIMList.getFieldDataType(int) para recuperar el tipo de datos del campo.
Invoque uno de los mtodos siguientes para establecer los datos de campo:
addString()
addDate()
addInt()
addBoolean()
addBinary()
if (todoList.isSupportedField(ToDo.SUMMARY))
{
task.addString(ToDo.SUMMARY, ToDo.ATTR_NONE, "Create project plan");
}
if (todoList.isSupportedField(ToDo.DUE))
{
Date date = new Date();
task.addDate(ToDo.DUE, ToDo.ATTR_NONE, (date + 17280000));
}
if (todoList.isSupportedField(ToDo.NOTE))
{
task.addString(ToDo.NOTE, ToDo.ATTR_NONE, "Required for meeting");
}
if (todoList.isSupportedField(ToDo.PRIORITY))
{
task.addInt(Todo.PRIORITY, ToDo.ATTR_NONE, 2);
}
Cambiar informacin de tareas

1.

2.
3.
Para sustituir un valor existente por un valor nuevo, invoque el mtodo de configuracin pertinente, como por
ejemplo ToDo.setString().
Para determinar si ya se ha definido un valor para el campo, invoque ToDo.countValues().
103
Guardar una tarea
Gua de desarrollo
if (task.countValues(ToDo.SUMMARY) > 0)
{
task.setString(ToDo.SUMMARY, 0, ToDo.ATTR_NONE, "Review notes");
}
4.
Cree cdigo para administrar una FieldFullException que lance un mtodo como addString() cuando
ya exista un valor.
Guardar una tarea

1.

2.
3.
Antes de realizar cambios, invoque isModified() para determinar si algn campo de la tarea ha cambiado
desde que la tarea se guard por ltima vez.
Invoque commit().
if(task.isModified())
{
task.commit();
}
Recuperar informacin de tareas

1.

import
import
import
import
2.
Invoque ToDoList.items() en la lista de tareas para recuperar una enumeracin.

ToDoList todoList =
(ToDoList)PIM.getInstance().openToDoList(PIM.TODO_LIST, PIM.READ_ONLY);
Enumeration enum = todoList.items();
3.
4.
Invoque ToDo.getFields() para recuperar una matriz de ID de campos que tienen datos correspondientes
a un elemento ToDo concreto.
Invoque PIMItem.getString() para recuperar los valores del campo.
while (enum.hasMoreElements())
{
ToDo task = (ToDo)enum.nextElement();
int[] fieldIds = task.getFields();
int id;
{
104
Exportar una tarea
Gua de desarrollo
if(task.getPIMList().getFieldDataType(id) == STRING)
{
for(int j=0; j < task.countValues(id); ++j)
{
String value = task.getString(id, j);
System.out.println(task.getFieldLable(id) + "=" + value);
}
}
Exportar una tarea

1.

import
import
import
import
import
2.
Utilice un redactor de flujo de salida para exportar tareas del dispositivo BlackBerry a un formato de serie
compatible.
3.
Para recuperar una matriz de cadena de formatos de serie compatibles, invoque

PIM.supportedSerialFormats() y, a continuacin, especifique el tipo lista (PIM.TODO_List).
Para escribir un elemento en un formato en serie, invoque PIM.getInstance().toSerialFormat. El
parmetro enc especifica la codificacin de caracteres para utilizar al programar en el flujo de salida. Las
codificaciones de caracteres compatibles incluyen "UTF8", "ISO-8859-1" y "UTF-16BE". Este parmetro no puede
ser nulo.
4.
ToDoList todoList =
(ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST, PIM.READ_ONLY);
ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
String[] dataFormats = PIM.getInstance().supportedSerialFormats(PIM.TODO_LIST);
Enumeration e = todoList.items();
{
ToDo task = (ToDo)e.nextElement();
PIM.getInstance().toSerialFormat(task, byteStream, "UTF8", dataFormats[0]);
}
Importar una tarea

1.

import
import
import
import
import
java.io.ByteArrayInputStream;
105
Eliminar una tarea
Gua de desarrollo
2.
3.
Invoque PIM.getInstance().fromSerialFormat() para devolver una matriz de objetos PIMItem. El

parmetro enc especifica la codificacin de caracteres para utilizar al programar en el flujo de salida. Las
codificaciones de caracteres compatibles incluyen "UTF8", "ISO-8859-1" y "UTF-16BE". Este parmetro no puede
ser nulo.
Invoque ToDoList.importToDo() para crear una tarea nueva usando los elementos PIM.
String[] dataFormats = PIM.toDoSerialFormats();
// Write task to serial format
ByteArrayOutputStream os = new ByteArrayOutputStream();
PIM.getInstance().toSerialFormat(task, os, "UTF8", dataFormats[0]);
// Import task from serial format
ByteArrayInputStream is = new ByteArrayInputStream(outputStream.toByteArray());
PIMItem[] pi = PIM.getInstance().fromSerialFormat(is, "UTF8");
ToDoList todoList =
(ToDoList)PIM.getInstance().openPIMList(PIM.TODO_LIST, PIM.READ_WRITE);
ToDo task2 = todoList.importToDo((ToDo)pi[0]);
task2.commit();
Eliminar una tarea

1.

import
import
import
import
2.
Invoque PIM.getInstance para crear un objeto ToDoList.

ToDoList todoList = (ToDoList)PIM.getInstance().openToDoList(PIM.TODO_LIST,
PIM.READ_ONLY);
3.
Invoque ToDoList.removeToDo() para eliminar la tarea.

todoList.removeToDo(task);
Cerrar la lista de tareas

1.

import javax.microedition.pim.PIMException;
2.
3.
Invoque ToDoList.close().
Cree cdigo que administre excepciones.
try
{
todoList.close();
}
106
Gua de desarrollo
{
}
Notificar a una aplicacin del dispositivo BlackBerry cuando una lista de tareas cambia
// Handle exception

cuando una lista de tareas cambia
1.

import net.rim.blackberry.api.pdap.PIMListListener;
import net.rim.blackberry.api.pdap.BlackBeryPIMList;
2.
Implemente la interfaz PIMListListener.

class MyTaskListListener implements PIMListListener {...}
3.
Invoque BlackBerryPIMList.addListener() para registrar la recepcin de notificaciones de cambios en

una lista de tareas.
BlackBerryPIMList taskList =
(BlackBerryPIMList)PIM.getInstance().openPIMList(PIM.TODO_LIST,
PIM.READ_WRITE);
taskList.addListener(new MyTaskListListener());
107
Gua de desarrollo
Telfono
Telfono
10
El paquete net.rim.blackberry.api.phone contiene las API que puede utilizar para acceder la aplicacin en
el dispositivo BlackBerry. Puede utilizar este paquete para hacer llamadas, cambiar entre las lneas de telfono
disponibles, recibir eventos de notificacin y cambiar las opciones del telfono.
Realizar una llamada desde una aplicacin del dispositivo

BlackBerry
Los dispositivos BlackBerry pueden admitir mltiples tipos de lneas de telfono, incluyendo las lneas celulares
que ofrece un proveedor de servicios inalmbricos y lneas de trabajo integradas con un sistema de telfono PBX
de una empresa. Puede crear una aplicacin que interacte con las lneas de telfono que estn disponibles en un
dispositivo. Puede comprobar los tipos de lneas de telfono que estn disponibles y utilizar una lnea de telfono
especfica para hacer una llamada saliente.
Hacer una llamada desde una aplicacin del dispositivo

BlackBerry (entorno de una sola lnea)
1.

import net.rim.blackberry.api.invoke.PhoneArguments;
2.
Cree una instancia de la clase PhoneArguments, pasando el campo ARG_CALL y el nmero de telfono de
destino.
PhoneArguments call = new PhoneArguments(PhoneArguments.ARG_CALL, "519-555-0100");
3.
Invoque Invoke.invokeApplication() para abrir la aplicacin Telfono desde su aplicacin,

proporcionando el campo APP_TYPE_PHONE y la instancia PhoneArguments.
Invoke.invokeApplication(Invoke.APP_TYPE_PHONE, call);
4.
Busque IllegalArgumentException.
Realizar una llamada desde una aplicacin del dispositivo

BlackBerry (entorno de varias lneas)
1.

import net.rim.blackberry.api.phone.Phone;
import net.rim.device.api.system.RadioException;
2.
108
Invoque initiateCall() para utilizar una lnea de telfono especfica para hacer una llamada. Para el nmero
de destino, pase un texto de usuario o nmero no modificable. En el ejemplo de cdigo siguiente, la aplicacin
hace una llamada al nmero de destino 519-555-0100 y utiliza el ID de lnea que devuelve al ndice 0.
Agregar tonos DTMF a la cola de envo
Gua de desarrollo
Phone.initiateCall(Phone.getLineIds()[0], "519-555-0100");
Agregar tonos DTMF a la cola de envo

1.

import net.rim.blackberry.api.phone.PhoneCall;
2.
Para agregar un solo tono DTMF a la cola de envo, invoque PhoneCall.sendDTMFTone().

PhoneCall pc = new PhoneCall();
boolean added = pc.sendDTMFTone('7');
Para agregar varios tonos DTMF a la cola de envo, invoque PhoneCall.sendDTMFTones().

PhoneCall ph = new PhoneCall();
boolean added = ph.sendDTMFTones("72");
Tonos DTMF de BlackBerry

Tecla
1
2
3
4
5
6
7
8
9
0
*
#
Tono bajo (Hz)

697
697
697
770
770
770
852
852
852
941
941
941
Tono alto (Hz)

1209
1336
1477
1209
1336
1477
1209
1336
1477
1209
1336
1477
Escuchar y administrar eventos del telfono

Puede configurar la aplicacin de su dispositivo BlackBerry para escuchar y administrar automticamente varios
eventos de telfono implementando la interfaz PhoneListener. La interfaz PhoneListener proporciona un
conjunto de mtodos de devolucin de llamada que puede utilizar para recibir una notificacin de eventos del
telfono.
1.

import net.rim.blackberry.api.phone.*;
109
Gua de desarrollo
2.
3.
Escuchar y administrar eventos de varias lneas
Cree una clase que implemente la interfaz PhoneListener.

Registre la clase que implementa PhoneListener invocando addPhoneListener().
Phone.addPhoneListener(this);
4.
5.
Administre eventos entrantes del telfono utilizando los mtodos de devolucin de llamada de
PhoneListener. Por ejemplo, para recibir la notificacin de que una llamada se ha desconectado, implemente
la notificacin en callDisconnected(int); para recibir la notificacin de que ha llegado una llamada nueva,
implemente la notificacin en callIncoming(int); y para recibir la notificacin de que hay una llamada en
espera, implemente la notificacin en callWaiting(int).
Para ver una lista completa de mtodos de devolucin de llamadas de PhoneListener, consulte la referencia
de API para BlackBerry Java Development Environment
Para anular el registro de PhoneListener, invoque Phone.removePhoneListener().
Phone.removePhoneListener(this);
Escuchar y administrar eventos de varias lneas

En los dispositivos BlackBerry que son compatibles con varias lneas de telfono, puede configurar su aplicacin
para escuchar y administrar automticamente eventos de varias lneas de telfono utilizando la clase
MultiLineListener. La clase MultiLineListener es una clase de helper que implementa la interfaz
PhoneListener y ofrece un conjunto de los mtodos de devolucin de llamada que puede utilizar para recibir
una notificacin de eventos de varias lneas de telfono.
1.

import net.rim.blackberry.api.phone.MultiLineListener;
2.
3.
Cree una clase que ample MultiLineListener.

Registre la clase como un PhoneListener invocando Phone.addPhoneListener().
Phone.addPhoneListener(this);
4.
Para administrar eventos de conmutacin de lnea, realice las acciones siguientes:

a. Anule los mtodos de devolucin de llamada de MultiLineListener para notificar a la aplicacin cuando
se produce un evento de conmutacin de lnea. Esto es especialmente importante cuando se usa esta
caracterstica en dispositivos que funcionan en redes CDMA, ya que podra producirse una demora cuando
la aplicacin cambie entre lneas de telfono.
public void setPreferredLineFailure(int lineId)
{
_screen.popupMessage("switching failed.");
}
public void setPreferredLineSuccess(int lineId)
{
110
Recuperar informacin de llamadas utilizando registros de llamadas
Gua de desarrollo
b.
_screen.popupMessage("Switching succeeded to " +

Phone.getLineNumber(lineId) + " completed." );
Invoque Phone.setPreferredLine(), pasando el ID de lnea de la lnea de telfono a la que conmutar.

En el siguiente ejemplo de cdigo, la aplicacin selecciona la lnea que vuelve al ndice 0.
Phone.setPreferredLine( Phone.getLineIds()[0]);
Recuperar informacin de llamadas utilizando registros de

llamadas
La informacin de las llamadas de un dispositivo BlackBerry se graba en los registros de llamadas a los que se
puede acceder desde la lista de mensajes. Los registros de llamadas se almacenan en carpetas de registro de
llamadas a las que se puede acceder utilizando las constantes PhoneLogs.FOLDER_NORMAL_CALLS o
PhoneLogs.FOLDER_MISSED_CALLS.
1.

import net.rim.blackberry.api.phone.phonelogs.*;
2.
Invoque getInstance() para recuperar una instancia del registro de llamadas.

PhoneLogs _logs = PhoneLogs.getInstance();
3.
Invoque numberOfCalls() para recuperar el nmero total de llamadas de una carpeta especificada de registro
de llamadas (FOLDER_MISSED_CALLS o FOLDER_NORMAL_CALLS).
int numberOfCalls = _logs.numberOfCalls(PhoneLogs.FOLDER_NORMAL_CALLS);
4.
Invoque PhoneLogs.callAt() para recuperar informacin de llamadas de un registro de llamadas, pasando

el ndice del registro de llamadas y la carpeta de registro de llamadas.
PhoneCallLog phoneLog =
(PhoneCallLog)_logs.callAt(0,PhoneLogs.FOLDER_NORMAL_CALLS);
5.
Invoque PhoneCallLog.getType() para recuperar el tipo de llamada. Los valores devueltos posibles son
TYPE_MISSED_CALL_OPENED, TYPE_MISSED_CALL_UNOPENED, TYPE_PLACED_CALL o
TYPE_RECEIVED_CALL.
int phoneType = phoneLog.getType();
Recuperar a un participante de una llamada

Puede utilizar las clases PhoneCallLogID y ConferencePhoneCallLog para recuperar a un participante de una
llamada de un registro de llamadas.
1.

import net.rim.blackberry.api.phone.phonelogs.*;
111
Gua de desarrollo
2.
Recuperar informacin de llamadas
Invoque PhoneCallLog.getParticipant() o ConferencePhoneCallLog.getParticipantAt() para

recuperar la informacin del participante de la llamada.
PhoneCallLogID participant = myPhoneCallLog.getParticipant();
PhoneCallLogID participant = myConferencePhoneCallLog.getParticipantAt(0);
Recuperar informacin de llamadas

1.

2.
Invoque PhoneCall.getElapsedTime() para recuperar la duracin de la llamada actual. Invoque

PhoneCall.getStatus() para recuperar el estado de la conexin de la llamada. Invoque
PhoneCall.getDisplayPhoneNumber() para recuperar el nmero de telfono de la llamada. En el ejemplo
de cdigo siguiente, aparece un mensaje de estado en la pantalla cuando la llamada telefnica ha durado ms
de 120 segundos.
int threshold = 120;
int elapsedTime = call.getElapsedTime();
int status = call.getStatus();
if ((status == PhoneCall.STATUS_CONNECTED
|| status == PhoneCall.STATUS_CONNECTING)
&& call.isOutGoing() && elapsedTime > threshold)
{
String phoneNumber = call.getDisplayPhoneNumber();
Status.show("Your call to " + call.getDisplayPhoneNumber() + " has lasted more
than " +
(String)threshold + ".");
}
Recuperar el nmero de telfono de un dispositivo

BlackBerry
1.

2.
Invoque Phone.getDevicePhoneNumber(), pasando true para devolver el nmero de telfono en su

formato regional.
String phNumber = Phone.getDevicePhoneNumber(true);
3.
112
Busque ControlledAccessException para obtener instancias en las que su aplicacin no tiene permiso para
acceder a la informacin de nmero de telfono.
Gua de desarrollo
Recuperar una llamada por el ID de llamada
Recuperar una llamada por el ID de llamada

1.

2.
Invoque Phone.getCall(), pasando el ID de la llamada que se va a recuperar.

PhoneCall ph = Phone.getCall(5);
Visualizar contenido en una pantalla de llamada

En dispositivosBlackBerry que ejecutan BlackBerry Device Software 5.0 o posterior, puede personalizar la pantalla
de llamada entrante y la pantalla de llamada activa para que muestren contenido utilizando la API de pantalla de
telfono que se suministra en el paquete net.rim.blackberry.api.phone.phonegui. Por ejemplo, puede
mostrar informacin proporcionada por su aplicacin cuando un usuario del dispositivo BlackBerry reciba una
llamada de una persona especfica.
El dispositivo muestra el contenido en la parte inferior de la pantalla de llamada. Si hay mltiples aplicaciones que
ofrecen contenido para una pantalla de llamada, el dispositivo muestra el contenido de cada aplicacin en
secuencia durante aproximadamente dos segundos hasta que aparece la siguiente pantalla de llamada. Por
ejemplo, si muestra contenido en la pantalla de llamada entrante, el dispositivo muestra el contenido hasta que el
usuario conteste la llamada y aparece la pantalla de llamada activa.
La aplicacin de muestra de Pantalla de telfono incluida en el BlackBerry Java SDK demuestra cmo utilizar esta
API.
113
Gua de desarrollo
Mostrar contenido en una pantalla de telfono

En el ejemplo de cdigo siguiente, se agreg contenido personalizado a la pantalla de llamada entrante anulando
AbstractPhoneListener.callIncoming(). Puede mostrar el contenido en otras pantallas de llamada
anulando callWaiting(), callInitiated() y callAnswered().
Antes de comenzar: Asegrese de que la siguiente aplicacin de ejemplo se ejecute en segundo plano cuando se
inicie el dispositivo BlackBerry. En el BlackBerry Java Plug-in para Eclipse, cambie el descriptor de aplicacin de
BlackBerry para la aplicacin de ejemplo. Para obtener ms informacin, consulte la Gua de desarrollo de
BlackBerry Java Plug-in para Eclipse .
1.

import
import
import
import
import
2.
net.rim.blackberry.api.phone.*;
net.rim.blackberry.api.phone.phonegui.*;
net.rim.device.api.system.*;
net.rim.device.api.ui.*;
net.rim.device.api.ui.component.*;
Cree el marco de la aplicacin ampliando la clase Application. En el constructor, invoque

Phone.addPhoneListener() para registrar el servicio de escucha que se cre en el paso 3. En main(),
invoque enterEventDispatcher() para activar la aplicacin para recibir eventos.
public final class MyPhoneScreen extends Application
{
public MyPhoneScreen()
{
Phone.addPhoneListener(new MyPhoneScreenContent());
}
{
new MyPhoneScreen().enterEventDispatcher();
}
}
3.
Cree una clase que ample la clase AbstractPhoneListener. Cree a un constructor para esta nueva clase.
final class MyPhoneScreenContent extends AbstractPhoneListener
{
public MyPhoneScreenContent()
{
}
}
4.
114
En la clase que ampla AbstractPhoneListener, anule AbstractPhoneListener.callIncoming(). Cree

una instancia de la clase ScreenModel. Obtenga una instancia de la pantalla de llamada entrante invocando
ScreenModel.getPhoneScreen(). Pase los parmetros para especificar la orientacin y tipo de pantalla de
llamada que quiere obtener. En el siguiente ejemplo de cdigo, se obtiene la orientacin vertical de la pantalla
de llamada entrante. Debido a que los dispositivos con pantallas tctiles admiten la orientacin vertical y
horizontal, pase el parmetro PhoneScreen.LANDSCAPE para obtener la orientacin horizontal de la pantalla
de llamada entrante.
Gua de desarrollo

{
ScreenModel screenModel = new ScreenModel(callId);
PhoneScreen phoneScreenPortrait =
screenModel.getPhoneScreen(PhoneScreen.PORTRAIT, PhoneScreen.INCOMING);
}
5.
En callIncoming(), cree contenido personalizado para agregar a la pantalla de llamada. En el ejemplo de

cdigo siguiente, el texto se agreg a la pantalla de llamada entrante utilizando campos de etiqueta. Anule
LabelField.paint() para cambiar el color del campo de etiqueta.
LabelField labelField1 = new LabelField("Hello")
{
public void paint(Graphics g)
{
g.setColor(Color.GREEN);
super.paint(g);
}
};
LabelField labelField2 = new LabelField(" to the World.")
{
{
g.setColor(Color.RED);
super.paint(g);
}
};
6.
En callIncoming(), especifique el tipo de letra para el contenido personalizado. En el siguiente ejemplo de

cdigo, se utiliza el tipo de letra de la pantalla de llamada. Invoque PhoneScreen.getCallerInfoFont()
para obtener el tipo de letra que se utilizar en la pantalla de llamada. Invoque Field.setFont() y pase el
tipo de letra de la pantalla de llamada para especificar el tipo de letra para los campos de etiqueta que se crearon
en el paso 5. Invoque PhoneScreen.add() para agregar los campos de etiqueta a la pantalla de llamada.
labelField1.setFont(phoneScreenPortrait.getCallerInfoFont());
phoneScreenPortrait.add(labelField1);
7.
En callIncoming(), invoque ScreenModel.sendAllDataToScreen() para agregar el contenido

personalizado a la pantalla de llamada entrante.
screenModel.sendAllDataToScreen();
Ejemplo de cdigo: Mostrar contenido en una pantalla de telfono

import
import
import
import
import
public
{
net.rim.blackberry.api.phone.*;
net.rim.blackberry.api.phone.phonegui.*;
net.rim.device.api.ui.component.*;
final class MyPhoneScreen extends Application
115
Gua de desarrollo
public MyPhoneScreen()
{
Phone.addPhoneListener(new MyPhoneScreenContent());
}
{
new MyPhoneScreen().enterEventDispatcher();
}
}
final class MyPhoneScreenContent extends AbstractPhoneListener
{
public MyPhoneScreenContent()
{
}
{
screenModel.getPhoneScreen(PhoneScreen.PORTRAIT, PhoneScreen.INCOMING);
LabelField labelField1 = new LabelField("Hello")
{
{
g.setColor(Color.GREEN);
super.paint(g);
}
};
LabelField labelField2 = new LabelField(" to the World.")
{
{
g.setColor(Color.RED);
super.paint(g);
}
};
screenModel.sendAllDataToScreen();
}
}
Visualizar contenido en dispositivos que operan en una red CDMA

La aplicacin Telfono de un dispositivo BlackBerry muestra la pantalla de llamada activa cuando un usuario
contesta o hace una llamada. Despus de que el usuario conteste una llamada, puede recibir y contestar una
segunda llamada. En dispositivos que operan en una red CDMA, la segunda llamada no invoca los mismos eventos
que la llamada original. En cuanto a estos dispositivos, para mostrar contenido personalizado en la pantalla
Llamada activa, debe omitir los mtodos AbstractPhoneListener.callAnswered() y
AbstractPhoneListener.callWaiting().
116
Gua de desarrollo
Mtodo
callAnswered()
callWaiting()
Descripcin
Para mostrar contenido en la primera pantalla de llamada activa, anule
AbstractPhoneListener.callAnswered() y obtenga los objetos de
pantalla de llamada para la llamada activa. La aplicacin Telfono invoca
este mtodo cuando el usuario contesta la primera llamada. En dispositivos
que funcionan en una red GSM, la aplicacin Telfono invoca este mtodo
cuando el usuario contesta tanto la primera llamada como la segunda.
Para mostrar contenido en la segunda pantalla de llamada activa, anule
AbstractPhoneListener.callWaiting() y obtenga los objetos de
pantalla de llamada para la llamada activa. La aplicacin Telfono invoca
este mtodo cuando el usuario contesta la segunda llamada.
Ejemplo de cdigo: Visualizar el contenido en dispositivos que funcionan en una red CDMA
El ejemplo de cdigo siguiente demuestra cmo anular AbstractPhoneListener.callWaiting(). Puede
comprobar si el dispositivo opera en una red CDMA utilizando la clase RadioInfo. Obtiene las instancias de la
pantalla de llamada activa invocando ScreenModel.getPhoneScreen() y pasando PhoneScreen.ACTIVE de
forma que slo especifique el contenido de la segunda llamada.
public void callWaiting(int callId)
{
// For CDMA devices, specify the content for the active call screen
if((RadioInfo.getSupportedWAFs() & RadioInfo.WAF_CDMA) != 0)
{
screenModel.getPhoneScreen(PhoneScreen.PORTRAIT, PhoneScreen.ACTIVE);
PhoneScreen phoneScreenLandscape =
screenModel.getPhoneScreen(PhoneScreen.LANDSCAPE, PhoneScreen.ACTIVE);
}
// For GSM and CDMA devices, specify the content for the incoming call screen
}
117
Gua de desarrollo
BlackBerry Browser
BlackBerry Browser
11
Recuperar una sesin de BlackBerry Browser

Al recuperar la sesin predeterminada se anula cualquier sesin abierta en el dispositivo BlackBerry.
1.
2.
Importe la clase net.rim.blackberry.api.browser.Browser.

Recupere el objeto predeterminado BrowserSession invocando el mtodo esttico
Browser.getDefaultSession().
Recuperar una sesin no predeterminada de BlackBerry

Browser
1.
2.
Importe la clase net.rim.blackberry.api.browser.Browser.

Invoque Browser.getSession(uid), donde uid es el UID de registro de servicio del explorador.
Solicitar una pgina Web

1.
2.
Importe la clase net.rim.blackberry.api.browser.BrowserSession.

Invoque BrowserSession.displayPage(String url), especificando la URL que contiene el contenido
Web.
El siguiente ejemplo crea un elemento del men que muestra una pgina Web en BlackBerry Browser.
private MenuItem browserItem =
new MenuItem(_resources.getString(MENUITEM_BROWSER), 110, 12)
{
public void run()
{
BrowserSession visit = Browser.getDefaultSession();
visit.displayPage("http://www.blackberry.com");
}
};
Compatibilidad mejorada para contenido Web en

aplicaciones del dispositivo BlackBerry
En BlackBerry Java Development Environment 5.0, el paquete net.rim.device.api.browser.field2
proporciona un conjunto nuevo de API que puede utilizar para incrustar contenido Web en aplicaciones del
118
Gua de desarrollo
Compatibilidad mejorada para contenido Web en aplicaciones del dispositivo BlackBerry
En versiones anteriores del BlackBerry JDE, el paquete net.rim.device.api.browser.field proporcionaba

una funcionalidad para agregar contenido Web a una aplicacin del dispositivo BlackBerry. Para obtener ms
informacin acerca de cmo utilizar este campo de explorador, consulte la aplicacin de ejemplo
BrowserFieldDemo que se ofrece con BlackBerry JDE.
Las API que son nuevas en BlackBerry JDE 5.0 le permiten realizar las acciones siguientes:
cargar y configurar los ajustes de visualizacin para contenido Web en objetos Field de cualquier aplicacin
acceda al DOM del contenido Web cargado
controle la gestin HTTP para conexiones, SSL, cookies y almacenamiento en cach
ajuste los servicios de escucha de devolucin de llamadas para controlar el progreso de carga de pginas Web
Puede crear aplicaciones que incluyan objetos Java y mtodos que puedan acceder e invocar cdigo JavaScript y
recibir acceso e invocacin del cdigo JavaScriptutilizando las API del paquete net.rim.device.api.script,
que es nuevo en BlackBerry JDE.
Mostrar contenido HTML en un campo de navegador

1.

import net.rim.device.api.browser.field2.*;
2.
Cree el marco de la aplicacin ampliando la clase UiApplication. En main(), cree una instancia de la clase
nueva e invoque enterEventDispatcher() para activar la aplicacin para recibir eventos. En el constructor
de la aplicacin, invoque pushScreen() para mostrar la pantalla personalizada para la aplicacin. La clase
BrowserFieldDemoScreen, descrita en el paso 3, representa la pantalla personalizada.
public class BrowserFieldDemo extends UiApplication
{
{
BrowserFieldDemo app = new BrowserFieldDemo();
}
public BrowserFieldDemo()
{
pushScreen(new BrowserFieldDemoScreen());
}
}
3.
Cree la pantalla personalizada ampliando la clase MainScreen.

class BrowserFieldDemoScreen extends MainScreen
{
public BrowserFieldDemoScreen()
{
}
}
4.
En el constructor de pantalla, cree una instancia de la clase BrowserField.
119
Gua de desarrollo
BrowserField myBrowserField = new BrowserField();
5.
En el constructor de pantalla, invoque add() para agregar el objeto BrowserField a la pantalla.

add(myBrowserField);
6.
En el constructor de pantalla, invoque BrowserField.displayContent() para especificar y mostrar el

contenido HTML.
myBrowserField.displayContent("<html><body><h1>Hello World!</h1></body></html>",
"http://localhost");
Mostrar contenido HTML de una pgina Web en un campo de navegador

1.

import
import
import
import
2.
net.rim.device.api.browser.field2.*;
net.rim.device.api.ui.container.*;
{
{
}
{
}
}
3.
Cree el marco para la pantalla personalizada ampliando la clase MainScreen.

{
{
}
}
4.

5.

120
Gua de desarrollo
6.
En el constructor de pantalla, invoque BrowserField.requestContent() para especificar la ubicacin del

contenido HTML y mostrarlo.
myBrowserField.requestContent("http://www.blackberry.com");
Mostrar contenido HTML de un recurso en su aplicacin

1.

import
import
import
import
2.
{
{
}
{
}
}
3.

{
{
}
}
4.

5.

6.
En el constructor de pantalla, invoque BrowserField.requestContent() para especificar la ubicacin del

recurso en su aplicacin y mostrar el contenido HTML.
myBrowserField.requestContent("local:///test.html");
121
Gua de desarrollo
Nota: La clase BrowserField no accede a los recursos utilizando una estructura de carpetas. La clase
BrowserField muestra el primer recurso encontrado que coincide con el nombre de archivo especificado.
Configurar un campo de navegador

1.

import net.rim.device.api.browser.field2.*;
2.
{
{
}
{
}
}
3.
Cree el marco de la pantalla personalizada ampliando la clase MainScreen.

{
{
}
}
4.
En el constructor de pantalla, cree una instancia de la clase BrowserFieldConfig.

BrowserFieldConfig myBrowserFieldConfig = new BrowserFieldConfig();
5.
En el constructor de pantalla, invoque BrowserFieldConfig.setProperty() para especificar una

propiedad de BrowserField. El primer parmetro de setProperty() especifica la propiedad, y el segundo
especifica el valor de la propiedad. Por ejemplo, el ejemplo de cdigo siguiente especifica la propiedad
NAVIGATION_MODE de un objeto BrowserField:
myBrowserFieldConfig.setProperty(BrowserFieldConfig.NAVIGATION_MODE,
BrowserFieldConfig.NAVIGATION_MODE_POINTER);
6.
En el constructor de pantalla, cree una instancia de la clase BrowserField que utilice la configuracin que ha
definido.
BrowserField browserField = new BrowserField(myBrowserFieldConfig);
122
Gua de desarrollo
Enviar datos de formularios a una direccin Web en un campo de

navegador
1.

import
import
import
import
import
import
import
2.
net.rim.device.api.io.http.*;
java.lang.*;
java.util.*;
{
{
}
{
}
}
3.

{
{
}
}
4.

BrowserField browserField = new BrowserField();
5.

add(browserField);
6.
En el constructor de pantalla, cree un objeto String que contenga la direccin Web bsica de la pgina Web
a la que va a enviar los datos de formularios.
String baseURL = "http://www.blackberry.com";
7.
En el constructor de pantalla, cree un objeto String que especifique los datos de formularios que la aplicacin
enva a la pgina Web.
123
Gua de desarrollo
String postData = "fieldname1=value1&fieldname2=value2";
8.
En el constructor de pantalla, cree un objeto Hashtable para almacenar la informacin de encabezado para
los datos de formulario.
Hashtable header = new Hashtable();
9.
En el constructor de pantalla, invoque Hashtable.put() para especificar la informacin de encabezado para

los datos de formulario.
header.put("Content-Length", "" + postData.length());
header.put("Content-Type", "application/x-www-form-urlencoded");
10. En el constructor de pantalla, invoque BrowserField.requestContent() para enviar los datos de formulario
a la pgina Web y mostrar la pgina Web.
browserField.requestContent(baseURL, postData.getBytes(), new
HttpHeaders(header));
124
Opciones de men
Gua de desarrollo
Opciones de men
12
Aadir elementos del men a aplicaciones de BlackBerry

Device Software
La API de elementos del men de aplicacin, del paquete net.rim.blackberry.api.menuitem, le permite
definir elementos del men para que aparezcan en aplicaciones de BlackBerry Device Software. La clase
ApplicationMenuItemRepository le permite agregar o eliminar elementos del men de aplicaciones de
BlackBerry Device Software.
Crear y registrar un elemento del men

Ample la clase ApplicationMenuItem para definir un elemento del men y que aparezca en aplicaciones de
BlackBerry Device Software.
1.

import java.lang.IllegalStateException;
import net.rim.blackberry.api.menuitem.ApplicationMenuItem;
import net.rim.blackberry.api.menuitem.ApplicationMenuItemRepository;
2.
Para crear y registrar un elemento del men, realice las tareas siguientes:
Tarea
Definir un elemento del men
Pasos
Ample la clase ApplicationMenuItem.
public class SampleMenuItem extends
ApplicationMenuItem { ... }
Especificar la posicin del

elemento del men en el men
Construya el ApplicationMenuItem. Cuanto ms alto es el

nmero del constructor, ms abajo en el men aparecer el
elemento del men.
SampleMenuItem()
{
super(0x350100);
}
Especificar el texto del elemento

del men
Implemente toString().
Especificar el comportamiento del

elemento del men
Implemente run().
public String toString()

{
return "My menu item";
}
125
Send Menu API
Gua de desarrollo
Tarea
Pasos
public Object run(Object context)
{
// the menu's action here
return null;
}
Registrar el elemento del men
Invoque
ApplicationMenuItemRepository.addMenuItem().
ApplicationMenuItemRepository amir =
ApplicationMenuItemRepository.getInstance();
amir.addMenuItem(
ApplicationMenuItemRepository.MENUITEM_PHONE,
mySampleMenuItem);
Ejemplo de cdigo: Crear y registrar un elemento del men

// Create menu item
int placement = 0x350100;
ApplicationMenuItem ami = new ApplicationMenuItem(placement)
{
public Object run(Object context)
{
// do something
return null;
}
public String toString()
{
return "My menu item";
}
};
// Register menu item to display when user views a contact
ApplicationMenuItemRepository amir = ApplicationMenuItemRepository.getInstance();
amir.addMenuItem(ApplicationMenuItemRepository.MENUITEM_ADDRESSCARD_VIEW, ami);
Para obtener ms informacin, consulte la descripcin general de las categoras de integracin de aplicaciones en
la referencia de la API para BlackBerry Java Development Environment.
Send Menu API

You can use the Send Menu API to allow BlackBerry device users to send content from your application to a
recipient by using a core application on the BlackBerry device. For example, you can create an application that
allows users to send content using an email message, an SMS text message, a PIN message, or a social networking
application such as Twitter for BlackBerry smartphones. You can allow users to send text from your application, or
files from the file system on the device. The classes that make up the Send Menu API are included in the
net.rim.blackberry.api.sendmenu package.
126
Gua de desarrollo
Send Menu API
The Send Menu API allows your application to interact with other BlackBerry Device Software applications, such as
the Messages application and social networking applications, and makes it easy for users to navigate between
applications. By using the Send Menu API, you can create an application with a user experience that is consistent
with other core applications on the device.
You can use the Send Menu API to add a Send menu item to the menu of your application. When a user clicks the
Send menu item, a submenu appears with a list of applications that the user can use to send content from your
application to a recipient. When the user clicks the name of an application in the Send submenu, that application
opens with certain fields prepopulated with the content to send. For example, if the user chooses to send text
from your application by using an email message, the Messages application opens and the body of a new email
message is populated with the text. Only applications that are developed by Research In Motion can appear in the
Send menu of your application.
127
Retrieving Send commands
Gua de desarrollo
Retrieving Send commands

To create a Send menu in your application, you must retrieve a set of commands to include in the menu. Each
command corresponds to an application that BlackBerry device users can use to send content from your
application. For example, you can retrieve commands that correspond to sending an email message, an SMS text
message, and so on.
You can use the SendCommandRepository class to retrieve commands to use in a Send menu. The
SendCommandRepository class contains all of the commands that are registered on the device, and you can
include these commands in the Send menu. The SendCommandRepository class is a singleton class, and you can
retrieve the singleton instance of this class by invoking the static SendCommandRepository.getInstance().
You can then retrieve an array of commands by invoking get(). Commands are represented by SendCommand
objects, and so invoking get() returns an array of SendCommand objects.
When you invoke get() to retrieve commands, you must provide a set of parameters that defines the types of
commands that you want this method to return. The following table describes the parameters that you must
provide and how each parameter affects the types of commands that you receive.
Parameter
type
Description
This parameter is an int value that represents the type of content that your
application allows users to send using the Send menu. You can specify two
values for this parameter, both of which are constants that are included in
SendCommand:
context
availability
SendCommand.TYPE_TEXT: This constant indicates that your
application allows users to send text, and that the context parameter
contains information that is related to the text to send.
SendCommand.TYPE_PATH: This constant indicates that your
application allows users to send files, and that the context parameter
contains information that is related to the file to send.
This parameter is a JSONObject object that represents the content to send.
This object contains a set of key-value pairs that determine what content
is sent and what fields are populated in the application that sends the
content. For example, the JSONObject object might contain the path of
the file to send, or the subject and body of a message to create. You can
use the constants that are included in the SendCommandContextKeys
class as keys for the content.
This parameter is a boolean value that indicates whether get() returns
all commands regardless of whether their associated applications can be
opened.
This parameter is optional.
128
Creating a Send menu
Gua de desarrollo
The get() method returns SendCommand objects that support both the type and the context that you specify.
For example, if you specify a type of SendCommand.TYPE_PATH, the array of SendCommand objects that you
receive from get() will not include a command that is associated with sending an SMS text message because files
cannot be sent using SMS text messages.
You can use the following code snippet to retrieve a set of commands from a SendCommandRepository. These
commands are associated with applications that support sending text content to a recipient, such as the Messages
application, and do not include commands that are associated with applications that cannot be opened.
SendCommand[] sendCommands =
SendCommandRepository.getInstance().get(SendCommand.TYPE_TEXT, context, false);

You can use the SendCommandMenu class to create a Send menu in your application. This class is a subclass of the
SubMenu class and is designed to create a menu that represents a set of SendCommand objects. Each
SendCommand object is represented in the Send menu by a SendCommandMenuItem object. When a BlackBerry
device user clicks one of the Send menu items, the run() method of the associated SendCommand object is
invoked.
When you create a SendCommandMenu object, you can provide either an array of SendCommandMenuItem
objects or an array of SendCommand objects. You can specify both the ordering of the items in the menu, and
what text appears as the label of the menu. For example, the default label is "Send," but you can provide different
text that is appropriate for your application.
As an alternative to creating a Send menu, you can use the SendCommandScreen class to create a pop-up screen
that displays SendCommand objects. For example, your application might contain a toolbar button called "Send",
and when a user clicks this button, a list of available Send commands is displayed.
You can also create your own UI components to display SendCommand objects if neither SendCommandMenu or
SendCommandScreen suit your needs. For example, you might create a drop-down list that contains
SendCommand objects that a user can choose from.
Create a Send menu

In this task, an edit field is created that accepts text that a BlackBerry device user types. This text is stored in a
context object, and this context object is used to retrieve a list of Send menu commands whose associated
applications can accept the text. A Send menu is created with these Send menu commands.
1.

import net.rim.blackberry.api.sendmenu.*;
import
import
import
import
import
import
net.rim.device.api.ui.Field;
net.rim.device.api.ui.XYEdges;
net.rim.device.api.ui.component.EditField;
net.rim.device.api.ui.component.Menu;
net.rim.device.api.ui.container.MainScreen;
net.rim.device.api.ui.decor.BorderFactory;
129
Gua de desarrollo
import org.json.me.JSONException;
import org.json.me.JSONObject;
2.
In the screen class, declare instance variables to represent an edit field and the text that the user types in this
field.
private EditField _textToSend;
private String _textString;
3.
In the screen constructor, create a new EditField object to represent the field that the user types in.
_textToSend = new EditField("Send: ", "Type the text to send here", 255,
Field.USE_ALL_WIDTH);
4.
To specify the appearance of the EditField object, invoke setBorder(), setPadding(), and
setMargin(). In this task, a bevel border is created for the EditField object, and a padding area and margin
area are added.
_textToSend.setBorder(BorderFactory.createBevelBorder(new XYEdges(3, 3, 3, 3)));
_textToSend.setPadding(8, 8, 8, 8);
_textToSend.setMargin(15, 15, 15, 15);
5.
Add the EditField object to the screen.

add(_textToSend);
6.
Override makeMenu() of the MainScreen class.

protected void makeMenu(Menu menu, int instance)
{
7.
Invoke super.makeMenu() to add the default menu items for BlackBerry device applications to the menu.
super.makeMenu(menu, instance);
8.
Invoke getText() of the EditField class to retrieve the text that the user typed in the edit field.
_textString = _textToSend.getText();
9.
Create a new JSONObject object to represent the context information for the Send menu.
JSONObject context = new JSONObject();
10. In a try/catch block, invoke put() of the JSONObject object to populate the context information using keyvalue pairs. Use the constants that are defined in the SendCommandContextKeys class as keys. Catch a
JSONException, which indicates that the specified key is null.
try
{
context.put(SendCommandContextKeys.TEXT, _textString);
context.put(SendCommandContextKeys.SUBJECT, "Your Text");
}
catch (JSONException e)
{
}
130
Gua de desarrollo
11. Create an array of SendCommand objects to represent the Send menu commands that you want to include in
the Send menu. Invoke SendCommandRepository.getInstance() to retrieve the singleton instance of the
SendCommandRepository. Invoke get() and specify as parameters the type of content to send, the context
information for the content, and a boolean value that indicates whether all of the commands should be
retrieved regardless of whether their associated applications can be opened.
SendCommand[] sendCommands = SendCommandRepository.getInstance().get(
SendCommand.TYPE_TEXT, context, false);
12. Determine whether the array of SendCommand objects is not null and contains commands, and if so, create a
new SendCommandMenu object to represent these commands and add it to the menu.
if (sendCommands != null && sendCommands.length > 0)

{
menu.add(new SendCommandMenu(sendCommands, 0, 0));
}
Code sample: Creating a Send menu

import
import
import
import
import
import
import
net.rim.device.api.ui.UiApplication;
public class SendMenuAPIDemo extends UiApplication
{
{
SendMenuAPIDemo theApp = new SendMenuAPIDemo();
theApp.enterEventDispatcher();
}
public SendMenuAPIDemo()
{
pushScreen(new SendCommandDemoScreen());
}
class SendCommandDemoScreen extends MainScreen

{
public SendCommandDemoScreen()
131
Gua de desarrollo
Creating a context object
setTitle("Send Menu API Demo");

_textToSend = new EditField("Send: ", "Type the text to send here",
255, Field.USE_ALL_WIDTH);
_textToSend.setBorder(BorderFactory.createBevelBorder(
new XYEdges(3, 3, 3, 3)));
add(_textToSend);

{
try
{
}
{
}
false);

SendCommand.TYPE_TEXT, context,
{
}
Creating a context object

When you use the SendCommandRepository class to retrieve a set of commands to include in a Send menu, you
must provide a context object. A context object contains information that is required to send content from your
application to a recipient. For example, if your application allows a BlackBerry device user to send text and the
user chooses to send the text in an email message, the context object might contain the subject and body of the
email message to send.
The Send Menu API uses a JSONObject object to represent context information. A JSONObject is an unordered
collection of key-value pairs. The keys are String objects, and the values can include several types, such as
boolean, int, Hashtable, or Vector.
132
Using context keys
Gua de desarrollo
You can invoke put() of the JSONObject class to add context information to a JSONObject. The Send Menu API
provides a set of predefined keys, which are constants in the SendCommandContextKeys class, that you can use
to add context information to a JSONObject.
The following code sample demonstrates how to create a JSONObject and add text to it using the
SendCommandContextKeys.TEXT key. The put() method can throw a JSONException to indicate that the key
that you specify is null, so it's important to catch this exception.
try
{
context.put(SendCommandContextKeys.TEXT, "This is some text to send.");
}
{
}
Using context keys

When you add context information for a Send command to a JSONObject object, you must specify a context key.
The key in a JSONObject must be a String value. You can use the constants in the SendCommandContextKeys
class as keys for the information in a JSONObject. You aren't required to use the keys that are defined in
SendCommandContextKeys, but they are defined to standardize the keys that the Send Menu API uses.
The following table describes the constants that are defined in SendCommandContextKeys.
Constant
PATH
SUBJECT
Description
You can use this constant as a key to store a String object that represents
a path. This path is the location of a file in the file system of the BlackBerry
device, such as /SDCard/photo.jpg. The file that this path refers to does not
need to exist on the device.
If a SendCommand object has a type of SendCommand.TYPE_PATH, then
this constant is required as a key in the associated JSONObject.
the subject of a message. For example, if your application allows a
BlackBerry device user to send text and the user chooses to send the text
in an email message, then the value that is associated with this key in the
JSONObject is used as the subject of the email message.
If a SendCommand object has a type of SendCommand.TYPE_TEXT, then
this constant is optional as a key in the associated JSONObject.
133
Using context filters
Gua de desarrollo
Constant
Description
the text of a message. For example, if your application allows a user to send
text and the user chooses to send the text in an email message, then the
value that is associated with this key in the JSONObject is used as the text
of the email message.
TEXT
If a SendCommand object has a type of SendCommand.TYPE_TEXT, then

this constant is optional as a key in the assocated JSONObject.

You can use the SendCommandContextFilter interface to define a context filter for the context object that is
associated with a SendCommand object. Filters are useful if the application that you're using to send content has
restrictions on the size or type of content that it receives. For example, if an application can accept text of a
certain length only, you can define a filter that shortens strings in the context object if they exceed a specific
character limit so that the application can accept and send the content.
You can create a class that acts as a filter by implementing the SendCommandContextFilter interface and
implementing filterContext(). This method changes the context object of a specified SendCommand object
according to filtering criteria that you specify, and returns the altered context object. The run() method of the
SendCommand object uses the altered context object to send the content from your application. You can register a
context filter for a SendCommand object by invoking setSendCommandContextFilter().
Create a context filter

In this task, a context filter is created that replaces the subject in the JSONObject context object with different
text.
1.

import net.rim.blackberry.api.sendmenu.SendCommandContextFilter;
2.
Override makeMenu() of the MainScreen class to create the menu for your application. Add the required code
to set up a Send menu, such as invoking super.makeMenu(), creating and populating a context object, and
retrieving a list of SendCommand objects.
{
}
3.
Before you invoke add() to add the Send menu to the menu of your application, perform the following steps:
a.
134
// add the required code to set up a Send menu here
Create a new object to represent a context filter. In this task, the MyContextFilter class is defined as a
context filter for SendCommand objects.
Gua de desarrollo
MyContextFilter filter = new MyContextFilter();
b.
Invoke setSendCommandContextFilter() of the SendCommand class to set the MyContextFilter

object as the context filter for a SendCommand. In this task, the emailSendCommand variable represents
a SendCommand object to send content using an email message.
emailSendCommand.setSendCommandContextFilter(filter);
4.
Define the MyContextFilter class and implement the SendCommandContextFilter interface.

class MyContextFilter implements SendCommandContextFilter
{
5.
Implement filterContext(). This method is invoked when a BlackBerry device user clicks a Send menu item
that has this context filter set.
public JSONObject filterContext(SendCommand sendCommand)
{
6.
Create a new JSONObject object. Invoke getContext() to retrieve the context object of the SendCommand
object that the user clicked, and store it in the JSONObject.
JSONObject newContext = sendCommand.getContext();
7.
In a try/catch block, alter the context object as appropriate. In this task, invoke put() of the JSONObject object
to replace the subject text in the JSONObject. Catch a JSONException, which indicates that the specified key
is null.
try
{
newContext.put(SendCommandContextKeys.SUBJECT,
"Subject replaced by filter");
}
{
}
Code sample: Creating a context filter

import
import
import
import
import
import
import
net.rim.device.api.ui.UiApplication;
public class ContextFilterDemo extends UiApplication
135
Gua de desarrollo

{
ContextFilterDemo theApp = new ContextFilterDemo();
theApp.enterEventDispatcher();
}
public ContextFilterDemo()
{
pushScreen(new ContextFilterDemoScreen());
}
class ContextFilterDemoScreen extends MainScreen

{
public ContextFilterDemoScreen()
{
setTitle("Context Filter Demo");
_textToSend = new EditField("Send: ", "Type the text to send here",
255, Field.USE_ALL_WIDTH);
_textToSend.setBorder(BorderFactory.createBevelBorder(
new XYEdges(3, 3, 3, 3)));
}
add(_textToSend);

{
try
{
}
{
}
SendCommand.TYPE_TEXT, context, false);
{
MyContextFilter filter = new MyContextFilter();
for (int i = 0; i < sendCommands.length; i++)
{
136
Gua de desarrollo
sendCommands[i].setSendCommandContextFilter(filter);
}
class MyContextFilter implements SendCommandContextFilter

{
public JSONObject filterContext(SendCommand sendCommand)
{
JSONObject newContext = sendCommand.getContext();
try
{
newContext.put(SendCommandContextKeys.SUBJECT,
"Subject replaced by filter");
}
{
}
return newContext;
137
Gua de desarrollo
Obtener ms informacin
138
Obtener ms informacin
13
www.blackberry.com/go/apiref: vea la ltima versin de la referencia de la API para BlackBerry Java SDK.
www.blackberry.com/go/devguides: encuentre las guas de desarrollo, notas de la versin y las descripciones
generales de la aplicacin de ejemplo para BlackBerry Java SDK.
www.blackberry.com/go/uiguidelines: encuentre las directrices de IU para smartphones BlackBerry.
www.blackberry.com/developers: visite BlackBerry Developer Zone si desea conocer recursos sobre desarrollo
de aplicaciones de dispositivos BlackBerry.
www.blackberry.com/go/developerkb: consulte los artculos de la base de conocimientos en la Base de
conocimientos de desarrollo de BlackBerry.
www.blackberry.com/developers/downloads: encuentre las ltimas herramientas de desarrollo y descargas
para desarrollar aplicaciones de dispositivos BlackBerry.
Gua de desarrollo
Glosario
Glosario
14
API
Application Programming Interface (Interfaz de programacin de aplicaciones)
BCC (CCO)
blind carbon copy (copia oculta)
CC
carbon copy (copia)
CRM
Customer relationship management (Gestin de las relaciones con el cliente)
DTMF
Dual Tone Multi-Frequency (Multifrecuencia de doble tono)
JSR
Java Specification Request
MIME
Multipurpose Internet Mail Extensions (Extensiones multiuso del correo de Internet)
MEID
Mobile Equipment Identifier (Identificador de equipos mviles)
MMS
Multimedia Messaging Service (Servicio de mensajera multimedia)
PIM
personal information management (administracin de informacin personal)
PIN
personal identification number (nmero de identificacin personal)
SMS
Short Message Service (Servicio de mensajes cortos)
SVG
Scalable Vector Graphics (Grficos vectoriales escalables)
UCS
Universal Content Stream (Flujo de contenido universal)
139
Gua de desarrollo
UID
unique identifier (identificador nico)
UTF
UCS Transformation Format (Formato de transformacin UCS)
140
Glosario
Gua de desarrollo
Comentarios
Comentarios
15
Para ofrecer comentarios acerca de esta entrega, visite www.blackberry.com/docsfeedback.
141
Historial de revisin del documento
Gua de desarrollo

Fecha
24 de septiembre de 2010
16
Descripcin
Se cambiaron los temas siguientes:
10 de septiembre de 2010

Iniciar el mdulo para procesos en segundo plano o el mdulo para la
IU
Utilizar mensajes y carpetas personalizados en la lista de mensajes
Se agregaron los temas siguientes:
Buscar un sensor en el dispositivo

Comprobar el estado de un sensor
Detectar el soporte
Gestionar soportes
API de capacidad de dispositivo
Notificar a una aplicacin cuando cambie el estado de un sensor
Eliminar indicadores personalizados
Iniciar el mdulo para procesos en segundo plano o el mdulo para la
IU
Utilizar mensajes y carpetas personalizados en la lista de mensajes
Se aadi el siguiente ejemplo de cdigo:
142
Ejemplo de cdigo: Trabajar con un sensor
Gua de desarrollo
Fecha
16 de agosto de 2010
Descripcin
Se aadi el tema siguiente:
Crear un proveedor de informacin para un contacto vinculado

Vincular un contacto
Se elimin el tema siguiente:

3 de agosto de 2010
Crear un campo personalizado para los contactos vinculados

Se agregaron los temas siguientes:
Configurar e iniciar una bsqueda

Crear una lista de contactos
Personalizar la apariencia de sus datos en los resultados de la bsqueda
Definir una clase EntityBasedSearchable para sus objetos
SearchableEntity.
Visualizar contenido en dispositivos que operan en una red CDMA
Exponer los datos de sus aplicaciones
Rastrear las respuestas del Servicio de bsqueda unificada
Notificar al Servicio de bsqueda unificada acerca de los cambios
hechos a sus datos
Pasar consultas a otros motores de bsqueda
Procesar los resultados de la bsqueda
Registrar su objeto EntityBasedSearchable en el Servicio de bsqueda
unificada
Eliminar listas de contactos
Recuperar el contacto asociado con una llamada finalizada
Bsquedas
Especificar un icono en EntityBasedSearchable o en la clase
SearchableEntity
143
Gua de desarrollo
Fecha
Descripcin
Bsqueda unificada
Actualizar una entrada del calendario sin ninguna notificacin
Se agregaron los siguientes ejemplos de cdigo:
Ejemplo de cdigo: Mostrar contenido en una pantalla de telfono
144

Mostrar contenido en una pantalla de telfono
Gua de desarrollo
Aviso legal
Aviso legal
17
2011 Research In Motion Limited. Reservados todos los derechos. BlackBerry, RIM, Research In Motion y las
marcas comerciales, nombres y logotipos relacionados son propiedad de Research In Motion Limited y estn
registrados y/o se usan en EE. UU. y en diferentes pases del mundo.
Eclipse es una marca comercial de Eclipse Foundation, Inc. Google y YouTube son marcas comerciales de Google
Inc. Java y JavaScript son marcas comerciales de Oracle America, Inc. iCal es una marca comercial de Apple Inc.
vCard es una marca comercial de Internet Mail Consortium. Wi-Fi es una marca comercial de Wi-Fi Alliance.. Todas
las dems marcas comerciales son propiedad de sus respectivos propietarios.
Esta documentacin, incluida cualquier documentacin que se incorpore mediante referencia como documento
proporcionado o disponible en www.blackberry.com/go/docs, se proporciona o se pone a disposicin "TAL CUAL"
y "SEGN SU DISPONIBILIDAD" sin ninguna condicin, responsabilidad o garanta de ningn tipo por Research In
Motion Limited y sus empresas afiliadas ("RIM") y RIM no asume ninguna responsabilidad por los errores
tipogrficos, tcnicos o cualquier otra imprecisin, error u omisin contenidos en esta documentacin. Con el fin
de proteger la informacin confidencial y propia de RIM, as como los secretos comerciales, la presente
documentacin describe algunos aspectos de la tecnologa de RIM en lneas generales. RIM se reserva el derecho
a modificar peridicamente la informacin que contiene esta documentacin, si bien tampoco se compromete en
modo alguno a proporcionar cambios, actualizaciones, ampliaciones o cualquier otro tipo de informacin que se
pueda agregar a esta documentacin.
Esta documentacin puede contener referencias a fuentes de informacin, hardware o software, productos o
servicios, incluidos componentes y contenido como, por ejemplo, el contenido protegido por copyright y/o sitios
Web de terceros (conjuntamente, los "Productos y servicios de terceros"). RIM no controla ni es responsable de
ningn tipo de Productos y servicios de terceros, incluido, sin restricciones, el contenido, la exactitud, el
cumplimiento de copyright, la compatibilidad, el rendimiento, la honradez, la legalidad, la decencia, los vnculos o
cualquier otro aspecto de los Productos y servicios de terceros. La inclusin de una referencia a los Productos y
servicios de terceros en esta documentacin no implica que RIM se haga responsable de dichos Productos y
servicios de terceros o de dichos terceros en modo alguno.
EXCEPTO EN LA MEDIDA EN QUE LO PROHBA ESPECFICAMENTE LA LEY DE SU JURISDICCIN, QUEDAN EXCLUIDAS
POR LA PRESENTE TODAS LAS CONDICIONES, APROBACIONES O GARANTAS DE CUALQUIER TIPO, EXPLCITAS O
IMPLCITAS, INCLUIDA, SIN NINGN TIPO DE LIMITACIN, CUALQUIER CONDICIN, APROBACIN, GARANTA,
DECLARACIN DE GARANTA DE DURABILIDAD, IDONEIDAD PARA UN FIN O USO DETERMINADO,
COMERCIABILIDAD, CALIDAD COMERCIAL, ESTADO DE NO INFRACCIN, CALIDAD SATISFACTORIA O TITULARIDAD,
O QUE SE DERIVE DE UNA LEY O COSTUMBRE O UN CURSO DE LAS NEGOCIACIONES O USO DEL COMERCIO, O
RELACIONADO CON LA DOCUMENTACIN O SU USO O RENDIMIENTO O NO RENDIMIENTO DE CUALQUIER
SOFTWARE, HARDWARE, SERVICIO O CUALQUIER PRODUCTO O SERVICIO DE TERCEROS MENCIONADOS AQU.
TAMBIN PODRA TENER OTROS DERECHOS QUE VARAN SEGN EL ESTADO O PROVINCIA. ES POSIBLE QUE
ALGUNAS JURISDICCIONES NO PERMITAN LA EXCLUSIN O LA LIMITACIN DE GARANTAS IMPLCITAS Y
CONDICIONES. EN LA MEDIDA EN QUE LO PERMITA LA LEY, CUALQUIER GARANTA IMPLCITA O CONDICIONES EN
RELACIN CON LA DOCUMENTACIN NO SE PUEDEN EXCLUIR TAL Y COMO SE HA EXPUESTO ANTERIORMENTE,
PERO PUEDEN SER LIMITADAS, Y POR LA PRESENTE ESTN LIMITADAS A NOVENTA (90) DAS DESDE DE LA FECHA
QUE ADQUIRI LA DOCUMENTACIN O EL ELEMENTO QUE ES SUJETO DE LA RECLAMACIN.
145
Gua de desarrollo
Aviso legal
EN LA MEDIDA MXIMA EN QUE LO PERMITA LA LEY DE SU JURISDICCIN, EN NINGN CASO RIM ASUMIR
RESPONSABILIDAD ALGUNA POR CUALQUIER TIPO DE DAOS RELACIONADOS CON ESTA DOCUMENTACIN O SU
USO, O RENDIMIENTO O NO RENDIMIENTO DE CUALQUIER SOFTWARE, HARDWARE, SERVICIO O PRODUCTOS Y
SERVICIOS DE TERCEROS AQU MENCIONADOS INCLUIDOS SIN NINGN TIPO DE LIMITACIN CUALQUIERA DE LOS
SIGUIENTES DAOS: DIRECTOS, RESULTANTES, EJEMPLARES, INCIDENTALES, INDIRECTOS, ESPECIALES, PUNITIVOS
O AGRAVADOS, DAOS POR PRDIDA DE BENEFICIOS O INGRESOS, IMPOSIBILIDAD DE CONSEGUIR LOS AHORROS
ESPERADOS, INTERRUPCIN DE LA ACTIVIDAD COMERCIAL, PRDIDA DE INFORMACIN COMERCIAL, PRDIDA DE
LA OPORTUNIDAD DE NEGOCIO O CORRUPCIN O PRDIDA DE DATOS, IMPOSIBILIDAD DE TRANSMITIR O RECIBIR
CUALQUIER DATO, PROBLEMAS ASOCIADOS CON CUALQUIER APLICACIN QUE SE UTILICE JUNTO CON
PRODUCTOS Y SERVICIOS DE RIM, COSTES DEBIDOS AL TIEMPO DE INACTIVIDAD, PRDIDA DE USO DE LOS
PRODUCTOS Y SERVICIOS DE RIM O PARTE DE L O DE CUALQUIER SERVICIO DE USO, COSTE DE SERVICIOS
SUSTITUTIVOS, COSTES DE COBERTURA, INSTALACIONES O SERVICIOS, COSTE DEL CAPITAL O CUALQUIER OTRA
PRDIDA MONETARIA SIMILAR, TANTO SI DICHOS DAOS SE HAN PREVISTO O NO, Y AUNQUE SE HAYA AVISADO A
RIM DE LA POSIBILIDAD DE DICHOS DAOS.
EN LA MEDIDA MXIMA EN QUE LO PERMITA LA LEY DE SU JURISDICCIN, RIM NO TENDR NINGN OTRO TIPO
DE OBLIGACIN O RESPONSABILIDAD CONTRACTUAL, EXTRACONTRACTUAL O CUALQUIER OTRA, INCLUIDA
CUALQUIER RESPONSABILIDAD POR NEGLIGENCIA O RESPONSABILIDAD ESTRICTA.
LAS LIMITACIONES, EXCLUSIONES Y DESCARGOS DE RESPONSABILIDAD SE APLICARN: (A) INDEPENDIENTEMENTE
DE LA NATURALEZA DE LA CAUSA DE LA ACCIN, DEMANDA O ACCIN SUYA, INCLUIDA PERO NO LIMITADA AL
INCUMPLIMIENTO DEL CONTRATO, NEGLIGENCIA, AGRAVIO, EXTRACONTRACTUAL, RESPONSABILIDAD ESTRICTA
O CUALQUIER OTRA TEORA DEL DERECHO Y DEBERN SOBREVIVIR A UNO O MS INCUMPLIMIENTOS ESENCIALES
O AL INCUMPLIMIENTO DEL PROPSITO ESENCIAL DE ESTE CONTRATO O CUALQUIER SOLUCIN CONTENIDA
AQU; Y (B) A RIM Y A SUS EMPRESAS AFILIADAS, SUS SUCESORES, CESIONARIOS, AGENTES, PROVEEDORES
(INCLUIDOS LOS PROVEEDORES DE SERVICIOS DE USO), DISTRIBUIDORES AUTORIZADOS POR RIM (INCLUIDOS
TAMBIN LOS PROVEEDORES DE SERVICIOS DE USO) Y SUS RESPECTIVOS DIRECTORES, EMPLEADOS Y
CONTRATISTAS INDEPENDIENTES.
ADEMS DE LAS LIMITACIONES Y EXCLUSIONES MENCIONADAS ANTERIORMENTE, EN NINGN CASO NINGN
DIRECTOR, EMPLEADO, AGENTE, DISTRIBUIDOR, PROVEEDOR, CONTRATISTA INDEPENDIENTE DE RIM O
CUALQUIER AFILIADO DE RIM ASUMIR NINGUNA RESPONSABILIDAD DERIVADA DE O RELACIONADA CON LA
DOCUMENTACIN.
Antes de instalar, usar o suscribirse a cualquiera de los Productos y servicios de terceros, es su responsabilidad
asegurarse de que su proveedor de servicios de uso ofrezca compatibilidad con todas sus funciones. Puede que
algunos proveedores de servicios de uso no ofrezcan las funciones de exploracin de Internet con una suscripcin
al servicio BlackBerry Internet Service. Consulte con su proveedor de servicios acerca de la disponibilidad,
arreglos de itinerancia, planes de servicio y funciones. La instalacin o el uso de los Productos y servicios de
terceros con productos y servicios de RIM puede precisar la obtencin de una o ms patentes, marcas
comerciales, derechos de autor u otras licencias para evitar que se vulneren o violen derechos de terceros. Usted
es el nico responsable de determinar si desea utilizar Productos y servicios de terceros y si se necesita para ello
cualquier otra licencia de terceros. En caso de necesitarlas, usted es el nico responsable de su adquisicin. No
instale o utilice Productos y servicios de terceros hasta que se hayan adquirido todas las licencias necesarias.
Cualquier tipo de Productos y servicios de terceros que se proporcione con los productos y servicios de RIM se le
146
Gua de desarrollo
Aviso legal
facilita para su comodidad "TAL CUAL" sin ninguna condicin expresa e implcita, aprobacin, garanta de
cualquier tipo por RIM y RIM no sume ninguna responsabilidad en relacin con ello. El uso de los Productos y
servicios de terceros se regir y estar sujeto a la aceptacin de los trminos de licencias independientes
aplicables en este caso con terceros, excepto en los casos cubiertos expresamente por una licencia u otro acuerdo
con RIM.
Algunas funciones mencionadas en esta documentacin requieren una versin mnima del software de
BlackBerry Enterprise Server, BlackBerry Desktop Software y/o BlackBerry Device Software.
Los trminos de uso de cualquier producto o servicio de RIM se presentan en una licencia independiente o en otro
acuerdo con RIM que se aplica en este caso. NINGUNA PARTE DE LA PRESENTE DOCUMENTACIN EST PENSADA
PARA PREVALECER SOBRE CUALQUIER ACUERDO EXPRESO POR ESCRITO O GARANTA PROPORCIONADA POR RIM
PARA PARTES DE CUALQUIER PRODUCTO O SERVICIO DE RIM QUE NO SEA ESTA DOCUMENTACIN.
Research In Motion Limited
295 Phillip Street
Waterloo, ON N2L 3W8
Canad
Research In Motion UK Limited
Centrum House
36 Station Road
Egham, Surrey TW20 9LF
Reino Unido
Publicado en Canad
147

BlackBerry - Java - SDK 1638866 1219123258 005 7.0 ES

Cargado por

Información del documento

Título original

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

BlackBerry - Java - SDK 1638866 1219123258 005 7.0 ES

Cargado por

Copyright:

Formatos disponibles

BlackBerry Java SDK

3 Compatibilidad de interaccin de dispositivo...................................................................................................

Crear un mensaje de texto rellenado nuevo....................................................................................................

Recuperar contactos por nmero de telfono.................................................................................................

Ejemplo de cdigo: Mostrar contenido en una pantalla de telfono........................................................ 115

13 Obtener ms informacin................................................................................................................................. 138

Integracin con aplicaciones de BlackBerry Device Software

Integracin con aplicaciones de BlackBerry

Invocar una aplicacin de BlackBerry Device Software

Importe las clases y las interfaces necesarias.

Invoque el mtodo Invoke.invokeApplication() y utilice los parmetros pertinentes. Por ejemplo:

Para iniciar el calendario, invoque Invoke.invokeApplication(APP_TYPE_CALENDAR,

Para obtener ms informacin acerca del uso de la clase net.rim.blackberry.api.invoke.Invoke, consulte

Hacer que los datos puedan ser encontrados

Exponer los datos de sus aplicaciones

Hacer que los datos puedan ser encontrados

Servicio de bsqueda unificada.

Notifique al Servicio de bsqueda

Despus de que notifique al Servicio de bsqueda unificada que sus datos

Hacer que los datos puedan ser encontrados

Pasar consultas a otros motores de bsqueda

UnifiedSearchServices.getSearchProviders() devuelve una lista de todos los proveedores externos de

Definir una clase EntityBasedSearchable para sus objetos SearchableEntity.

Definir una clase EntityBasedSearchable para sus objetos

Importe las clases y las interfaces necesarias.

MySearchableEntity[] _myEntities; // You will need this in steps 8 and 11

Asigne un nombre significativo a cada SearchField.

Definir una clase EntityBasedSearchable para sus objetos SearchableEntity.

_searchFields[0] = new SearchField("Title");

Compruebe si el servicio de bsqueda unificada ha enviado un comando pause. Si es as, detenga la

Definir una clase EntityBasedSearchable para sus objetos SearchableEntity.

MyObject dataObject = (MyObject) objects.nextElement();

El servicio de bsqueda unificada invoca getSearchableEntities() a continuacin para recuperar la matriz

11. En getSearchableEntities(), devuelva la matriz _myEntities que cre en el paso 8.

Personalizar la apariencia de sus datos en los resultados de la bsqueda

Definir una clase EntityBasedSearchable para sus objetos SearchableEntity.

Especificar un icono en EntityBasedSearchable o en la clase

Importe las clases necesarias.

Cree una variable de instancia para almacenar el icono.

Importe el grfico a su aplicacin desde su carpeta de recursos.

Compruebe si la importacin fue correcta y a continuacin cree un icono.

En getIcon(), devuelva la imagen.

Encapsular datos en la clase SearchableEntity

Encapsular datos en la clase SearchableEntity

Importe las clases y las interfaces necesarias.

Recupere una matriz de objetos SearchField de EntityBasedSearchable.

Implemente getSearchCriteria() para devolver SearchFieldCriteriaList.

Specifying what users can do with your data in search results

public String getTitle() {

Implemente getSearchable(). Recupere el EntityBasedSearchable que su aplicacin crea para

Specifying what users can do with your data in search

Specifying what users can do with your data in search results

Specify an operation for a selected search result

Import the required classes and interfaces.

Declare a class that extends UiAction, and create an empty constructor.

Invoke pushScreen() to make the new screen object visible.

public Image getIcon() {

Specifying what users can do with your data in search results

Provide an alternate entry point for your application

Import the required classes and interfaces.

Create the application framework by extending the UiApplication class.

public MyApp(String entryPoint)

Create an application object. Provide the entry point type as a parameter.