File	Doc	Category	Size	Date	Package
ToolkitRegistry.java	API Doc	phoneME MR2 API (J2ME)	21787	Wed May 02 18:00:40 BST 2007	sim.toolkit

ToolkitRegistry

• java.lang.Object

public class MyToolkitApplet extends Applet implements
ToolkitInterface, ToolkitConstants {
// data fields
private ToolkitRegistry reg;
private byte[] menuEntry = { ... };
private byte menuId;
//
// Constructor of applet
//
public MyToolkitApplet() {
// get the reference of the applet ToolkitRegistry object ...
reg = ToolkitRegistry.getEntry();
// ...and initialize it according to the applet characteristics
menuId = reg.initMenuEntry(menuEntry, (short)0,
(short)menuEntry.length,
PRO_CMD_SET_UP_CALL, false, 0, 0);
reg.disableMenuEntry(menuId);
reg.setEvent(EVENT_FORMATTED_SMS_PP_ENV);
reg.setEvent(EVENT_CALL_CONTROL_BY_SIM);
}
//
// Install method
// *param bArray the array containing installation parameters
// *param bOffset the starting offset in bArray
// *param bLength the length in bytes of the parameter data in bArray
//
public static void install(byte bArray[], short bOffset, byte bLength)
throws ISOException {
// create and register applet
MyToolkitApplet applet = new MyToolkitApplet();
applet.register();
}
//
// Process toolkit events
// *param event the type of event to be processed
// *exception ToolkitException
//
public void processToolkit(byte event) throws ToolkitException {
if (event == EVENT_FORMATTED_SMS_PP_ENV) {
reg.enableMenuEntry(menuId);
} else if (event == EVENT_MENU_SELECTION) {
//...
}
}
}

Fields Summary

Constructors Summary
private ToolkitRegistry() Constructor

Methods Summary
public byte	allocateTimer() Asks the Toolkit framework to allocate a Timer that the applet can manage. By calling this method the applet is registered to the EVENT_TIMER_EXPIRATION of the allocated timer. The timer is allocated by the applet until it explicitly releases it. So it can then issue the Timer Management proactive command to start, stop or get the value of its allocated timer. return the identifier of the Timer allocated to the applet exception ToolkitException with the following reason codes: NO_TIMER_AVAILABLE if all the timers are allocated or the maximum number of timers have been allocated to this applet ToolkitException.throwIt(ToolkitException.NO_TIMER_AVAILABLE); return 0;
public void	changeMenuEntry(byte id, byte[] menuEntry, short offset, short length, byte nextAction, boolean helpSupported, byte iconQualifier, short iconIdentifier) Changes the value of a menu entry. The default state of the changed menu entry is 'enabled'. The value of the helpSupported boolean parameter defines the registration status of the EVENT_MENU_SELECTION_HELP_REQUEST event. The icon identifier provided will be added to the icon identifier list of the item icon identifier list Simple TLV if all the applets registered to the EVENT_MENU_SELECTION provide it. The Icon list qualifier transmitted to the ME will be 'icon is not self explanatory' if one of the applet registered prefers this qualifier. After the invocation of this method, during the current card session, the SIM Toolkit Framework shall dynamically update the menu stored in the ME. Notes: If offset or length parameter is negative an ArrayIndexOutOfBoundsException exception is thrown and no menu entry is changed. If offset+length is greater than menuEntry.length, the length of the menuEntry array an ArrayIndexOutOfBoundsException exception is thrown and no menu entry is changed. param id the menu entry identifier supplied by the initMenuEntry() method param menuEntry a reference on a byte array, containing the menu entry string param offset the position of the menu entry string in the buffer param length the length of the menu entry string param nextAction a byte coding the next action indicator for the menu entry (or 0) param helpSupported equals true if help is available for the menu entry param iconQualifier the preferred value for the icon list qualifier param iconIdentifier the icon identifier for the menu entry (0 means no icon) exception NullPointerException if menuEntry is null exception ArrayIndexOutOfBoundsException if changeMenuEntry would cause access of data outside array bounds. exception ToolkitException with the following reason codes: MENU_ENTRY_NOT_FOUND if the menu entry does not exist for this applet ALLOWED_LENGTH_EXCEEDED if the menu entry string is bigger than the alloacted space ToolkitException.throwIt(ToolkitException.MENU_ENTRY_NOT_FOUND);
public void	clearEvent(byte event) Clears an event in the Toolkit Registry entry of the applet. param event the value of the event to unregister (between -128 and 127) exception ToolkitException with the following reason codes: EVENT_NOT_ALLOWED if event is EVENT_MENU_SELECTION, EVENT_MENU_SELECTION_HELP_REQUEST, EVENT_TIMER_EXPIRATION, EVENT_STATUS_COMMAND if (event != ToolkitConstants.EVENT_UNFORMATTED_SMS_PP_ENV) { // no other events are supported return; } AID aid = JCSystem.getAID(); ViewHandler.SATAccessor.clearEventListener(aid);
public void	disableMenuEntry(byte id) Disables a menu entry. This method doesn't modify the registration state to the EVENT_MENU_SELECTION and EVENT_MENU_SELECTION_HELP_REQUEST. After invocation of this method, during the current card session, the SIM Toolkit Framework shall dynamically update the menu stored in the ME. param id the menu entry identifier supplied by the initMenuEntry() method exception ToolkitException with the following reason codes: MENU_ENTRY_NOT_FOUND if the menu entry does not exist for this applet ToolkitException.throwIt(ToolkitException.MENU_ENTRY_NOT_FOUND);
public void	enableMenuEntry(byte id) Enables a menu entry. This method doesn't modify the registration state to the EVENT_MENU_SELECTION and EVENT_MENU_SELECTION_HELP_REQUEST. After invocation of this method, during the current card session, the SIM Toolkit Framework shall dynamically update the menu stored in the ME. param id the menu entry identifier supplied by the initMenuEntry() method exception ToolkitException with the following reason codes: MENU_ENTRY_NOT_FOUND if the menu entry does not exist for this applet ToolkitException.throwIt(ToolkitException.MENU_ENTRY_NOT_FOUND);
public static sim.toolkit.ToolkitRegistry	getEntry() This method is used by the Toolkit applet to get a reference to its Toolkit Registry entry, so that it can handle its registration state to the toolkit events. return reference to the applet ToolkitRegistry object exception ToolkitException with the following reason codes: REGISTRY_ERROR in case of register error return new ToolkitRegistry();
public short	getPollInterval() Returns the number of seconds of the adjusted duration for the calling toolkit applet. If the returned duration is equal to POLL_NO_DURATION, the toolkit applet is not registered to EVENT_STATUS_COMMAND event. The returned duration may : - be a multiple of the real adjusted poll interval time at the ME. - differ from the requested duration due to request of other toolkit applets or due to restrictions of the current ME. - be changed during the card session due requests from other toolkit applets. - be wrong due to direct generation of the proactive command POLL INTERVAL or POLLING OFF. - not correspond to the ellasped time due to additional STATUS commands send by the ME. return the number of seconds of the adjusted duration for the applet return 0;
public byte	initMenuEntry(byte[] menuEntry, short offset, short length, byte nextAction, boolean helpSupported, byte iconQualifier, short iconIdentifier) Initialises the next menu entry allocated at loading. The default state of the menu entry is 'enabled'. The value of the helpSupported boolean parameter defines the registration status of the applet to the event EVENT_MENU_SELECTION_HELP_REQUEST. The applet is registered to the EVENT_MENU_SELECTION. The icon identifier provided will be added to the icon identifier list of the item icon identifier list Simple TLV if all the applets registered to the EVENT_MENU_SELECTION provide it. The Icon list qualifier transmitted to the ME will be 'icon is not self explanatory' if one of the applet registered prefers this qualifier. This method shall be called by the applet in the same order than the order of the item parameters defined at the applet loading if the applet has several menu entries. The applet shall initialise all its loaded menu entries during its installation. Notes: If offset or length parameter is negative an ArrayIndexOutOfBoundsException exception is thrown and no menu entry is initialised. If offset+length is greater than menuEntry.length, the length of the menuEntry array a ArrayIndexOutOfBoundsException exception is thrown and no menu entry is initialised. param menuEntry a reference on a byte array, containing the menu entry string param offset offset of the menu entry string in the buffer param length length of the menu entry string param nextAction a byte coding the next action indicator for the menu entry (or 0) param helpSupported equals true if help is available for the menu entry param iconQualifier the preferred value for the icon list qualifier param iconIdentifier the icon identifier for the menu entry (0 means no icon) return the identifier attached to the initialised menu entry exception NullPointerException if menuEntry is null exception ArrayIndexOutOfBoundsException if initMenuEntry would cause access of data outside array bounds. exception ToolkitException with the following reason codes: REGISTRY_ERROR if the menu entry cannot be initialised (eg no more item data in applet loading parameter) ALLOWED_LENGTH_EXCEEDED if the menu entry string is bigger than the alloacted space ToolkitException.throwIt(ToolkitException.REGISTRY_ERROR); return 0;
public boolean	isEventSet(byte event) Allows to know if an event is set in the Toolkit Registry entry of the applet. param event the value of the event (between -128 and 127) return true if the event is set in the Toolkit Registry entry of the applet, false otherwise if (event != ToolkitConstants.EVENT_UNFORMATTED_SMS_PP_ENV) return false; AID aid = JCSystem.getAID(); return ViewHandler.SATAccessor.isEventListenerSet(aid);
public void	releaseTimer(byte timerIdentifier) Release a Timer that has been allocated to the calling applet. The applet is deregistered of the EVENT_TIMER_EXPIRATION for the indicated Timer Identifier. param timerIdentifier the identifier of the Timer to be released exception ToolkitException with the following reason codes: INVALID_TIMER_ID if the timerIdentifierd is not allocated to this applet. ToolkitException.throwIt(ToolkitException.INVALID_TIMER_ID);
public void	requestPollInterval(short duration) Requests a duration for the EVENT_STATUS_COMMAND event of the registering toolkit applet. Due to different duration requested by other toolkit applets or due to restriction of the ME, the SIM Toolkit Framework may adjust another duration. This method can be used at every time to request a new duration. param duration specifies the number of seconds requested for proactive polling. The maximum value of duration is 15300 (255 minutes). If duration is equal to POLL_NO_DURATION, the calling applet deregisters from EVENT_STATUS_COMMAND, and the SIM Toolkit Framework may issue the POLLING OFF proactive command. If duration is equal to POLL_SYSTEM_DURATION, the calling applet registers to the EVENT_STATUS_COMMAND and let the SIM Toolkit Framework define the duration. exception ToolkitException with the following reason codes: REGISTRY_ERROR if duration is greater than the maximum value. ToolkitException.throwIt(ToolkitException.REGISTRY_ERROR);
public void	setEvent(byte event) Sets an event in the Toolkit Registry entry of the applet. No exception shall be thrown if the applet registers more than once to the same event. param event value of the new event to register (between -128 and 127) exception ToolkitException with the following reason codes: EVENT_NOT_SUPPORTED if the event is not supported EVENT_ALREADY_REGISTERED if the event has already been registered (for limited event like Call Control) EVENT_NOT_ALLOWED if event is EVENT_MENU_SELECTION, EVENT_MENU_SELECTION_HELP_REQUEST, EVENT_TIMER_EXPIRATION, EVENT_STATUS_COMMAND if (event != ToolkitConstants.EVENT_UNFORMATTED_SMS_PP_ENV) { ToolkitException.throwIt(ToolkitException.EVENT_NOT_SUPPORTED); } AID aid = JCSystem.getAID(); ViewHandler.SATAccessor.setEventListener(aid);
public void	setEventList(byte[] eventList, short offset, short length) Sets an event list in the Toolkit Registry entry of the applet. In case of any exception the state of the registry is undefined. The toolkit applet has to include this call within a transaction if necessary. Notes: If offset or length parameter is negative an ArrayIndexOutOfBoundsException exception is thrown and no event list is set. If offset+length is greater than eventList.length, the length of the eventList array an ArrayIndexOutOfBoundsException exception is thrown and no event list is set. param eventList buffer containing the list of the new events to register param offset offset in the eventlist buffer for event registration param length length in the eventlist buffer for event registration exception NullPointerException if eventlist is null exception ArrayIndexOutOfBoundsException if setEventList would cause access of data outside array bounds. exception ToolkitException with the following reason codes: EVENT_NOT_SUPPORTED if one event is not supported EVENT_ALREADY_REGISTERED if one event has already been registered (for limited event like Call Control) EVENT_NOT_ALLOWED if eventList contains EVENT_MENU_SELECTION, EVENT_MENU_SELECTION_HELP_REQUEST, EVENT_TIMER_EXPIRATION, EVENT_STATUS_COMMAND boolean alreadyRegistered = false; for (short i = 0; i < eventList.length; i++) { if (eventList[i] != ToolkitConstants.EVENT_UNFORMATTED_SMS_PP_ENV) { ToolkitException.throwIt(ToolkitException.EVENT_NOT_SUPPORTED); } if (!alreadyRegistered) { AID aid = JCSystem.getAID(); ViewHandler.SATAccessor.setEventListener(aid); alreadyRegistered = true; } }