001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: //-----------------------------------------------------------------------------
028: // PACKAGE DEFINITION
029: //-----------------------------------------------------------------------------
030: package sim.toolkit;
031:
032: import javacard.framework.*;
033:
034: //-----------------------------------------------------------------------------
035: // IMPORTS
036: //-----------------------------------------------------------------------------
037:
038: /**
039: *
040: * The <code>ToolkitRegistry</code> class offers basic services and methods
041: * to allow
042: * any Toolkit applet to register its configuration (supported events) during
043: * the install phase and possibly to change it during all the applet life time.
044: * Each toolkit applet will get a reference to its registry entry with the
045: * static
046: * method <code>getEntry</code>. The initial state of all the events
047: * is cleared.<p>
048: *
049: * Note: the constants related to the events are defined in the
050: * <code>ToolkitConstants </code> interface.<p>
051: *
052: * Example of use:<pre><code>
053: * public class MyToolkitApplet extends Applet implements
054: * ToolkitInterface, ToolkitConstants {
055: * // data fields
056: * private ToolkitRegistry reg;
057: * private byte[] menuEntry = { ... };
058: * private byte menuId;
059: * //
060: * // Constructor of applet
061: * //
062: * public MyToolkitApplet() {
063: * // get the reference of the applet ToolkitRegistry object ...
064: * reg = ToolkitRegistry.getEntry();
065: * // ...and initialize it according to the applet characteristics
066: * menuId = reg.initMenuEntry(menuEntry, (short)0,
067: * (short)menuEntry.length,
068: * PRO_CMD_SET_UP_CALL, false, 0, 0);
069: * reg.disableMenuEntry(menuId);
070: * reg.setEvent(EVENT_FORMATTED_SMS_PP_ENV);
071: * reg.setEvent(EVENT_CALL_CONTROL_BY_SIM);
072: * }
073: * //
074: * // Install method
075: * // *param bArray the array containing installation parameters
076: * // *param bOffset the starting offset in bArray
077: * // *param bLength the length in bytes of the parameter data in bArray
078: * //
079: * public static void install(byte bArray[], short bOffset, byte bLength)
080: * throws ISOException {
081: * // create and register applet
082: * MyToolkitApplet applet = new MyToolkitApplet();
083: * applet.register();
084: * }
085: * //
086: * // Process toolkit events
087: * // *param event the type of event to be processed
088: * // *exception ToolkitException
089: * //
090: * public void processToolkit(byte event) throws ToolkitException {
091: * if (event == EVENT_FORMATTED_SMS_PP_ENV) {
092: * reg.enableMenuEntry(menuId);
093: * } else if (event == EVENT_MENU_SELECTION) {
094: * //...
095: * }
096: * }
097: * }
098: * </code></pre>
099: *
100: * @version 8.3.0
101: *
102: * @see ToolkitInterface
103: * @see ToolkitException
104: * @see ToolkitConstants
105: */
106: public final class ToolkitRegistry {
107:
108: // ------------------------------- Constructors ---------------------------
109: /**
110: * Constructor
111: */
112: private ToolkitRegistry() {
113: }
114:
115: // ------------------------------- Public methods -------------------------
116: /**
117: * This method is used by the Toolkit applet to get a reference to its
118: * Toolkit Registry entry, so that it can handle its registration state to
119: * the toolkit events.
120: *
121: * @return reference to the applet ToolkitRegistry object
122: *
123: * @exception ToolkitException with the following reason codes: <ul>
124: * <li>REGISTRY_ERROR in case of register error</ul>
125: */
126: public static ToolkitRegistry getEntry() throws ToolkitException {
127: return new ToolkitRegistry();
128: }
129:
130: /**
131: * Sets an event in the Toolkit Registry entry of the applet.
132: * No exception shall be thrown if the applet registers more than once to
133: * the same event.
134: *
135: * @param event value of the new event to register (between -128 and 127)
136: *
137: * @exception ToolkitException with the following reason codes: <ul>
138: * <li>EVENT_NOT_SUPPORTED if the event is not supported
139: * <li>EVENT_ALREADY_REGISTERED if the event has already been
140: * registered (for limited event like Call Control)
141: * <li>EVENT_NOT_ALLOWED if event is EVENT_MENU_SELECTION,
142: * EVENT_MENU_SELECTION_HELP_REQUEST,
143: * EVENT_TIMER_EXPIRATION,
144: * EVENT_STATUS_COMMAND</ul>
145: */
146: public void setEvent(byte event) throws ToolkitException {
147: if (event != ToolkitConstants.EVENT_UNFORMATTED_SMS_PP_ENV) {
148: ToolkitException
149: .throwIt(ToolkitException.EVENT_NOT_SUPPORTED);
150: }
151: AID aid = JCSystem.getAID();
152: ViewHandler.SATAccessor.setEventListener(aid);
153: }
154:
155: /**
156: * Sets an event list in the Toolkit Registry entry of the applet.
157: * In case of any exception the state of the registry is undefined.
158: * The toolkit applet has to include this call within a transaction
159: * if necessary.
160: *
161: * <p>
162: * Notes:<ul>
163: * <li><em>If </em><code>offset</code><em> or
164: * </em><code>length</code><em> parameter is negative an
165: * </em><code>ArrayIndexOutOfBoundsException</code>
166: * <em> exception is thrown and no event list is set.</em>
167: * <li><em>If </em><code>offset+length</code><em> is greater than
168: * </em><code>eventList.length</code><em>, the length
169: * of the </em><code>eventList</code><em> array an
170: * </em><code>ArrayIndexOutOfBoundsException</code><em> exception is
171: * thrown and no event list is set.</em>
172: * </ul>
173: *
174: * @param eventList buffer containing the list of the new events to
175: * register
176: * @param offset offset in the eventlist buffer for event registration
177: * @param length length in the eventlist buffer for event registration
178: *
179: * @exception NullPointerException if <code>eventlist</code>
180: * is <code>null</code>
181: * @exception ArrayIndexOutOfBoundsException if setEventList would cause
182: * access of data outside array bounds.
183: * @exception ToolkitException with the following reason codes: <ul>
184: * <li>EVENT_NOT_SUPPORTED if one event is not supported
185: * <li>EVENT_ALREADY_REGISTERED if one event has already been
186: * registered
187: * (for limited event like Call Control)
188: * <li>EVENT_NOT_ALLOWED if eventList contains EVENT_MENU_SELECTION,
189: * EVENT_MENU_SELECTION_HELP_REQUEST, EVENT_TIMER_EXPIRATION,
190: * EVENT_STATUS_COMMAND</ul>
191: */
192: public void setEventList(byte[] eventList, short offset,
193: short length) throws NullPointerException,
194: ArrayIndexOutOfBoundsException, ToolkitException {
195: boolean alreadyRegistered = false;
196: for (short i = 0; i < eventList.length; i++) {
197: if (eventList[i] != ToolkitConstants.EVENT_UNFORMATTED_SMS_PP_ENV) {
198: ToolkitException
199: .throwIt(ToolkitException.EVENT_NOT_SUPPORTED);
200: }
201: if (!alreadyRegistered) {
202: AID aid = JCSystem.getAID();
203: ViewHandler.SATAccessor.setEventListener(aid);
204: alreadyRegistered = true;
205: }
206: }
207:
208: }
209:
210: /**
211: * Clears an event in the Toolkit Registry entry of the applet.
212: *
213: * @param event the value of the event to unregister (between -128 and 127)
214: * @exception ToolkitException with the following reason codes: <ul>
215: * <li>EVENT_NOT_ALLOWED if event is EVENT_MENU_SELECTION,
216: * EVENT_MENU_SELECTION_HELP_REQUEST, EVENT_TIMER_EXPIRATION,
217: * EVENT_STATUS_COMMAND</ul>
218: */
219: public void clearEvent(byte event) throws ToolkitException {
220: if (event != ToolkitConstants.EVENT_UNFORMATTED_SMS_PP_ENV) {
221: // no other events are supported
222: return;
223: }
224: AID aid = JCSystem.getAID();
225: ViewHandler.SATAccessor.clearEventListener(aid);
226: }
227:
228: /**
229: * Allows to know if an event is set in the Toolkit Registry entry of the
230: * applet.
231: *
232: * @param event the value of the event (between -128 and 127)
233: *
234: * @return true if the event is set in the Toolkit Registry entry of
235: * the applet, false otherwise
236: */
237: public boolean isEventSet(byte event) {
238: if (event != ToolkitConstants.EVENT_UNFORMATTED_SMS_PP_ENV)
239: return false;
240:
241: AID aid = JCSystem.getAID();
242: return ViewHandler.SATAccessor.isEventListenerSet(aid);
243: }
244:
245: /**
246: * Disables a menu entry.
247: * This method doesn't modify the registration state to the
248: * EVENT_MENU_SELECTION
249: * and EVENT_MENU_SELECTION_HELP_REQUEST. After invocation of this method,
250: * during the current card session, the SIM
251: * Toolkit Framework shall dynamically update the menu stored in the ME.
252: *
253: * @param id the menu entry identifier supplied by the
254: * <code>initMenuEntry()</code> method
255: *
256: * @exception ToolkitException with the following reason codes: <ul>
257: * <li>MENU_ENTRY_NOT_FOUND if the menu entry does not exist
258: * for this applet</ul>
259: */
260: public void disableMenuEntry(byte id) throws ToolkitException {
261: ToolkitException.throwIt(ToolkitException.MENU_ENTRY_NOT_FOUND);
262: }
263:
264: /**
265: * Enables a menu entry.
266: * This method doesn't modify the registration state to the
267: * EVENT_MENU_SELECTION
268: * and EVENT_MENU_SELECTION_HELP_REQUEST. After invocation of this method,
269: * during the current card session, the SIM
270: * Toolkit Framework shall dynamically update the menu stored in the ME.
271: *
272: * @param id the menu entry identifier supplied by the
273: * <code>initMenuEntry()</code> method
274: *
275: * @exception ToolkitException with the following reason codes: <ul>
276: * <li>MENU_ENTRY_NOT_FOUND if the menu entry does not exist for
277: * this applet</ul>
278: */
279: public void enableMenuEntry(byte id) throws ToolkitException {
280: ToolkitException.throwIt(ToolkitException.MENU_ENTRY_NOT_FOUND);
281: }
282:
283: /**
284: * Initialises the next menu entry allocated at loading.
285: * The default state of the menu entry is
286: * 'enabled'. The value of the <code>helpSupported</code> boolean
287: * parameter defines the registration status of the applet to the event
288: * EVENT_MENU_SELECTION_HELP_REQUEST. The applet is registered to
289: * the EVENT_MENU_SELECTION. The icon identifier provided will be added to
290: * the icon identifier list of the item icon identifier list Simple TLV if
291: * all the applets registered to the EVENT_MENU_SELECTION provide it.
292: * The Icon list qualifier transmitted to the ME will be 'icon is not self
293: * explanatory' if one of the applet registered prefers this qualifier.
294: * This method shall be called by the applet in the same order than the
295: * order of the item parameters defined at the applet loading if the applet
296: * has several menu entries. The applet shall initialise all its loaded
297: * menu entries during its installation.
298: *
299: * <p>
300: * Notes:<ul>
301: * <li><em>If </em><code>offset</code><em> or </em><code>length</code><em>
302: * parameter is negative an
303: * </em><code>ArrayIndexOutOfBoundsException</code>
304: * <em> exception is thrown and no menu entry is initialised.</em>
305: * <li><em>If </em><code>offset+length</code><em> is greater than
306: * </em><code>menuEntry.length</code><em>, the length
307: * of the </em><code>menuEntry</code><em> array a
308: * </em><code>ArrayIndexOutOfBoundsException</code><em> exception is thrown
309: * and no menu entry is initialised.</em>
310: * </ul>
311: *
312: * @param menuEntry a reference on a byte array, containing the menu entry
313: * string
314: * @param offset offset of the menu entry string in the buffer
315: * @param length length of the menu entry string
316: * @param nextAction a byte coding the next action indicator for the menu
317: * entry (or 0)
318: * @param helpSupported equals true if help is available for the menu entry
319: * @param iconQualifier the preferred value for the icon list qualifier
320: * @param iconIdentifier the icon identifier for the menu entry
321: * (0 means no icon)
322: *
323: * @return the identifier attached to the initialised menu entry
324: *
325: * @exception NullPointerException if <code>menuEntry</code> is
326: * <code>null</code>
327: * @exception ArrayIndexOutOfBoundsException if initMenuEntry would
328: * cause access of data outside array bounds.
329: * @exception ToolkitException with the following reason codes: <ul>
330: * <li>REGISTRY_ERROR if the menu entry cannot be initialised
331: * (eg no more item data in applet loading parameter)
332: * <li>ALLOWED_LENGTH_EXCEEDED if the menu entry string is
333: * bigger than the alloacted space</ul>
334: */
335: public byte initMenuEntry(byte[] menuEntry, short offset,
336: short length, byte nextAction, boolean helpSupported,
337: byte iconQualifier, short iconIdentifier)
338: throws NullPointerException,
339: ArrayIndexOutOfBoundsException, ToolkitException {
340: ToolkitException.throwIt(ToolkitException.REGISTRY_ERROR);
341: return 0;
342: }
343:
344: /**
345: * Changes the value of a menu entry. The default state of the changed
346: * menu
347: * entry is 'enabled'. The value of the <code>helpSupported</code> boolean
348: * parameter defines the registration status of the
349: * EVENT_MENU_SELECTION_HELP_REQUEST
350: * event. The icon identifier provided will be added to the icon
351: * identifier list
352: * of the item icon identifier list Simple TLV if all the applets
353: * registered
354: * to the EVENT_MENU_SELECTION provide it.
355: * The Icon list qualifier transmitted to the ME will be 'icon is not self
356: * explanatory' if one of the applet registered prefers this qualifier.
357: * After the invocation of this method, during the current card session,
358: * the SIM Toolkit Framework
359: * shall dynamically update the menu stored in the ME.
360: *
361: * <p>
362: * Notes:<ul>
363: * <li><em>If </em><code>offset</code><em> or </em><code>length</code><em>
364: * parameter is negative an
365: * </em><code>ArrayIndexOutOfBoundsException</code>
366: * <em> exception is thrown and no menu entry is changed.</em>
367: * <li><em>If </em><code>offset+length</code><em> is greater than
368: * </em><code>menuEntry.length</code><em>, the length
369: * of the </em><code>menuEntry</code><em> array an
370: * </em><code>ArrayIndexOutOfBoundsException</code><em> exception is thrown
371: * and no menu entry is changed.</em>
372: * </ul>
373: *
374: * @param id the menu entry identifier supplied by the
375: * <code>initMenuEntry()</code> method
376: * @param menuEntry a reference on a byte array, containing the
377: * menu entry string
378: * @param offset the position of the menu entry string in the buffer
379: * @param length the length of the menu entry string
380: * @param nextAction a byte coding the next action indicator for the
381: * menu entry (or 0)
382: * @param helpSupported equals true if help is available for the menu entry
383: * @param iconQualifier the preferred value for the icon list qualifier
384: * @param iconIdentifier the icon identifier for the menu entry
385: * (0 means no icon)
386: *
387: * @exception NullPointerException if <code>menuEntry</code>
388: * is <code>null</code>
389: * @exception ArrayIndexOutOfBoundsException if changeMenuEntry would
390: * cause access of data outside array bounds.
391: * @exception ToolkitException with the following reason codes: <ul>
392: * <li>MENU_ENTRY_NOT_FOUND if the menu entry does not exist for
393: * this applet
394: * <li>ALLOWED_LENGTH_EXCEEDED if the menu entry string is bigger
395: * than the alloacted space</ul>
396: */
397: public void changeMenuEntry(byte id, byte[] menuEntry,
398: short offset, short length, byte nextAction,
399: boolean helpSupported, byte iconQualifier,
400: short iconIdentifier) throws NullPointerException,
401: ArrayIndexOutOfBoundsException, ToolkitException {
402: ToolkitException.throwIt(ToolkitException.MENU_ENTRY_NOT_FOUND);
403: }
404:
405: /**
406: * Asks the Toolkit framework to allocate a Timer that the applet
407: * can manage.
408: * By calling this method the applet is registered to the
409: * EVENT_TIMER_EXPIRATION of the allocated timer.
410: * The timer is allocated by the applet until it explicitly releases it.
411: * So it can then issue the Timer Management proactive command to start,
412: * stop or get the value of its allocated timer.
413: *
414: * @return the identifier of the Timer allocated to the applet
415: *
416: * @exception ToolkitException with the following reason codes: <ul>
417: * <li>NO_TIMER_AVAILABLE if all the timers are allocated or the
418: * maximum number
419: * of timers have been allocated to this applet</ul>
420: */
421: public byte allocateTimer() throws ToolkitException {
422: ToolkitException.throwIt(ToolkitException.NO_TIMER_AVAILABLE);
423: return 0;
424: }
425:
426: /**
427: * Release a Timer that has been allocated to the calling applet.
428: * The applet is deregistered of the EVENT_TIMER_EXPIRATION
429: * for the indicated Timer Identifier.
430: *
431: * @param timerIdentifier the identifier of the Timer to be released
432: *
433: * @exception ToolkitException with the following reason codes: <ul>
434: * <li>INVALID_TIMER_ID if the timerIdentifierd is not allocated
435: * to this applet.</ul>
436: */
437: public void releaseTimer(byte timerIdentifier)
438: throws ToolkitException {
439: ToolkitException.throwIt(ToolkitException.INVALID_TIMER_ID);
440: }
441:
442: /**
443: * Requests a duration for the EVENT_STATUS_COMMAND event of the
444: * registering
445: * toolkit applet. Due to different duration requested by other
446: * toolkit
447: * applets or due to restriction of the ME, the SIM Toolkit
448: * Framework may adjust another duration.
449: * This method can be used at every time to request a new duration.
450: *
451: * @param duration specifies the number of seconds requested for
452: * proactive polling.
453: * The maximum value of <code>duration</code> is
454: * <code>15300</code> (255 minutes).
455: * If <code>duration<code> is equal to
456: * <code>POLL_NO_DURATION</code>,
457: * the calling applet deregisters from EVENT_STATUS_COMMAND, and
458: * the SIM Toolkit Framework may issue the POLLING OFF proactive
459: * command.
460: * If <code>duration<code> is equal to
461: * <code>POLL_SYSTEM_DURATION</code>,
462: * the calling applet registers to the
463: * EVENT_STATUS_COMMAND and let
464: * the SIM Toolkit Framework define the duration.
465: *
466: * @exception ToolkitException with the following reason codes: <ul>
467: * <li>REGISTRY_ERROR if <code>duration</code> is greater than
468: * the maximum value.</ul>
469: */
470: public void requestPollInterval(short duration)
471: throws ToolkitException {
472: ToolkitException.throwIt(ToolkitException.REGISTRY_ERROR);
473: }
474:
475: /**
476: * Returns the number of seconds of the adjusted duration for the calling
477: * toolkit applet.
478: * If the returned duration is equal to <code>POLL_NO_DURATION<code>, the
479: * toolkit applet is not registered to EVENT_STATUS_COMMAND event.
480: * The returned duration may :
481: * - be a multiple of the real adjusted poll interval time at the ME.
482: * - differ from the requested duration due to request of
483: * other toolkit applets or due to restrictions of the current ME.
484: * - be changed during the card session due requests from other toolkit
485: * applets.
486: * - be wrong due to direct generation of the proactive command POLL
487: * INTERVAL or POLLING OFF.
488: * - not correspond to the ellasped time due to additional STATUS
489: * commands send by the ME.
490: *
491: * @return the number of seconds of the adjusted duration for the applet
492: */
493: public short getPollInterval() {
494: return 0;
495: }
496:
497: }
|