Appendix A. Deploying JSR 180 on MIDP 2.0 Platform

The MIDP 2.0 specification defines a mechanism for granting permissions to use privileged features. This mechanism is based on a policy mechanism enforced in the platform implementation. The following permissions are defined for the JSR 180 functionality, when deployed with a JSR 118 MIDP 2.0 implementation.

To open a connection, a MIDlet suite requires an appropriate permission to access the SIPConnection implementation. If the permission is not granted, then Connector.open methods MUST throw a SecurityException . The following table indicates the permission that must be granted for each protocol.

Note that ideally the permission granted will probably allow all subsequent network connections to be made (open a UDP/TCP/RTP media stream for example). However, this behavior might vary on different platforms.

/**
 * This class represents access rights to connections via the sip protocol.
 * SipProtocolPermission consists of a URI string but no actions list. The URI 
 * string specifies a connection target and used protocol 
 * e.g. sip:[email protected]:5070. 
 * 
 * The URI is specified in RFC3261 [1] and here it takes general form of:
 * {scheme}:[{target}][{params}]
 * where:
 * 
 *	- scheme is SIP scheme supported by the system sip or sips
 *	- target is user network address in form of 
 *    [{user_name}@]{target_host}[:{port}] or {telephone_number}
 * 	- params stands for additional SIP URI parameters like ;transport=udp
 * 
 * The SIP URI may contain quote characters. The application can use either 
 * the quote character or it's escaped version (%22), the API implementation 
 * must support both forms.
 * 
 * @see javax.microedition.io.Connector#open(java.lang.String) in 
 * MIDP 3.0 Specification
 */
public final class SipProtocolPermission extends GCFPermission {

	private static final long serialVersionUID = 1L;
	/**
	 * Creates a new SipProtocolPermission instance with the specified URI 
	 * as its name.
	 * 
	 * @param uri the URI string.
	 * @throws IllegalArgumentException if the uri is malformed
	 * @throws NullPointerException if uri is null
	 * @see Permission#getName()
	 */
	public SipProtocolPermission(String uri){}

	/**
	 * Returns the protocol scheme of this SipProtocolPermission
	 * @see java.security.GCFPermission
	 */
	public String getProtocol(){
		return null;
	}

	/**
	 * Returns the URI of this SipProtocolPermission
	 * @see java.security.GCFPermission
	 */
	public String getURI(){
		return null;
	}

	/**
	 * Checks if this SipProtocolPermission object implies
	 * the specified permission. 
	 * 
	 * Method returns true if:
	 * 
	 *	 - p is an instance of SipProtocolPermission and
	 *	 - p's URI equals this object's URI (Refer to the RFC3261 [1] 
	 *     section 25 how the URIs are constructed.)
	 * 
	 *  are true and if one or more of following condition is met:
	 * 
	 * 	  - If this object has a IP address and p's IP address is equal to 
	 * 		this object's IP address.
	 *    - If this object has a wildcard domain (such as *.amazon.com), and 
	 *		p's absolute name (the name with any preceding * removed) ends with 
	 *   	this object's absolute name. For example, *.amazon.com implies 
	 *		*.uk.amazon.com.  
	 * 	  - If this object's name equals p's name.  
	 *
	 * @param p the permission to check against.
	 * @return true if the specified permission is implied by this object,
	 * false if not.
	 */
	public boolean implies(Permission p) {
		return true;
	}

	/**
	 * Checks two Permission objects for equality
	 * @return true if obj is a HttpsProtocolPermission and 
	 *  has the same URI string as this SipProtocolPermission object.
	 * @see java.security.Permission
	 */
	public boolean equals(Object object) {
		return false;
	}

	/**
	 * Returns the actions as a String. Since the SipProtocolPermission does 
	 * 	  not have actions, method will always return empty string. 
	 * @return the empty string 
	 * @see java.security.Permission
	 */
	public String getActions(){
		return "";
	}

	/**
	 * Returns the hash code value for this Permission object
	 * @return a hash code value for this object
	 * @see java.security.Permission
	 */
	public int hashCode() {
		return -1;
	}
}

Push registrations are either defined in the application descriptor or made dynamically at runtime via PushRegistry. The entry for a SIP protocol will include the connection URI string which identifies the scheme and port number of the inbound message connection. The entry also contains a filter field that designates which senders are permitted to send messages that launch the registered MIDlet. An asterisk ("*") and question mark ("?") can be used in the filter field as a wild cards as specified in the MIDP 2.0 specification.

For the SIP protocol, the filter field is matched against the URI of the From field in the received message.

The URI may also have a media feature tag (MIME type of the application) that associates the MIDlet with the SipConnectionNotifier. See definitions here: "Opening new server connection" and "Routing the incoming request". This media feature tag is compared with the tag included in the received request. This funcionality is based on the SIP Working Group specifications RFC3840 [4] and RFC3841 [5].

As a summary SIP PushRegistry may have following kind of entries:

Furthermore, the MIDlet can register dynamically to the Push Registry when opening the connection by passing the same augmented SIP URI to the Connector. Example:

				String midletName = "com.company.sip.SIPExample2";
				String serverURI = "sip:5080"; SipConnectionNotifier scn
				= (SipConnectionNotifier) Connector.open(sURI);
				PushRegistry.registerConnection(serverURI, midletName,
				"*");
			

Following table defines how the system is routing messages to MIDlets when registered in PushRegistry. It should be noticed that the system requires either port number or at least MIME type for the routing decision.

Unlike the initial push connections defined in MIDP 2.0, the SIP protocol includes an explicit buffering mechanism where messages are held until processed by some application that reads and deletes messages. If a message is delivered to the device and does not pass the specified filter, the message will be deleted by the Application Management Software.

When the application is started in response to a Push request, the application SHOULD read and process all messages that are buffered for it. If an application fails to read and process the messages when started or if starting of the application is denied (for example, by the end user), the platform implementation MAY delete unread messages from the buffer, if it becomes necessary to do so. For example, the platform implementation may delete messages when the buffer becomes full.

Another difference between the JSR180 interface and other protocol handlers in MIDP 2.0, is that JSR180 includes a SipConnectionNotifier which provides asynchronous callbacks when messages become available while the application is running.