This section lists the implementation specifics of SIP API for J2ME (JSR-180) at package level.
Connection open(String name)
UDP is a default connection protocol in SIP signalling. The S60 implementation
changes the connection protocol to TCP when the transport=tcp parameter
is added to the URI passed as an argument to the Connector.open()
operation. For example, sip:[email protected]:5070;transport=tcp.
Also, when the message to be sent is larger than approximately 1300 bytes
the message will automatically be sent via TCP. Note that the protocol cannot
be changed for example from UDP to TCP in the middle of the dialog.
Restrictions related to the creation of SipClientConnection and SipConnectionNotifier objects:
sips: connection is not supported.
In the creation of SipConnectionNotifier object,
"type" parameter corresponds to the Accept-Contact header value of incoming
request. This is the only supported argument for Connector.open() operation.
SipConnectionNotifier scn = (SipConnectionNotifier) Connector.open ("sip:*;type=\"application/vnd.company.x-game\"");
The S60 implementation does not support SipConnectionNotifier to
act in the dedicated mode. S60 implementation throws IOException if MIDlet
passes "dedicated mode" URI as argument to the Connertor.open() operation.
Note: There is one special case where S60 implementation throws IllegalArgumentException instead
of IOException if MIDlet passes "dedicated mode" URI
as argument to the Connector.open() operation. This special
URI is "sip:".
S60 implementation throws IllegalArgumentException if
MIDlet passes "sip:". URI is passed as argument to the Connector.open() operation.
This interface has been implemented as specified by SIP API for J2ME (JSR-180).
int enableRefresh(SipRefreshListener srl)
This method can be called only for REGISTER and SUBSCRIBE requests.
SipClientConnection initCancel()
The user cannot set headers or content to a CANCEL request.
void initRequest(java.lang.String method,SipConnectionNotifier
scn)
The following requests can be set as an argument method: REGISTER, INVITE, OPTIONS, MESSAGE, SUBSCRIBE, PUBLISH, UPDATE, REFER, and <EXTENSION>.
The following requests cannot be set as an argument method: ACK, CANCEL, BYE, PRACK, UPDATE, and NOTIFY.
An <EXTENSION> request means any arbitrary request
defined by the user.
Section Selecting
registration context and initializing requests contains more information
on how the SipConnectionNotifier argument affects the
values of system headers.
The system headers ‘CSeq’ and ‘Call-ID’ are not available immediately after this operation call. ‘To’, ‘From’ and ‘Contact’ headers are available for a MIDlet after this operation call. More detailed information can be found in section Restrictions on headers.
boolean receive(long timeout)
This operation throws IOException and the state
of the object is set to TERMINATED if an error has occurred
in the sip stack during transaction.
void setCredentials(java.lang.String username,java.lang.String
password,java.lang.String realm)
The MIDlet has to set the credentials before sending a request (See
Example 1 setCredentials() in SIP
API for J2ME (JSR-180) specification). The S60 implementation does
not pass 401 or 407 responses to the MIDlet. The S60 implementation throws IOException if
the registrar server returns 401 or 407 and credentials has not been set by
MIDlet. The user is not asked for the credentials either, in a situation where
the server sends a 401 or a 407 response.
void setRequestURI(java.lang.String URI)
The S60 implementation does not support this operation. This operation
throws SipException with INVALID_OPERATION if
this operation is called in the INITIALIZED state.
void addHeader(java.lang.String name, java.lang.String
value)
Adds a header to the SIP message. See section Headers for detailed information related to them. If multiple header field values exist, the header value is added topmost of this type of headers.
Example 1: Adding single header field row. The message already contains header Route:
<sip:[email protected]>. addHeader("Route", " <sip:[email protected]>"); the result will be Route: <sip:[email protected]> Route: <sip:[email protected]>
Example 2: Adding multiple header field rows as a comma-separated list. The message already contains header Route: <sip:[email protected]>.
addHeader("Route", "<sip:[email protected]>,<sip:[email protected]>");
the result will be:
Route: <sip:[email protected]>
Route: <sip:[email protected]>
Route: <sip:[email protected]>
java.lang.String getHeader()
The top-most header field value, or null if the current message does
not have such a header or the header is for other reasons not available (e.g.
message not initialized). As mentioned in the description of the addHeader() operation,
headers are stored as separate objects and the topmost header is returned.
Example 1: Get top-most Route header from a message that contains three Route headers.
Route: <sip:[email protected]> Route: <sip:[email protected]> Route: <sip:[email protected]> getHeader("Route"); the result is: <sip:[email protected]>
java.lang.String[] getHeaders(java.lang.String name)
Gets the header field value(s) of a specified header type. The method returns the header field-values separated in an array regardless of how they are stored in the message.
Example 1: Get Route headers from a message that contains two Route headers in separate header field rows.
Route: <sip:[email protected]> Route: <sip:[email protected]> getHeaders("Route"); the result is a String array: {"<sip:[email protected]>", "<sip:[email protected]>"}
Example 2: Get Route headers from a message that contains three Route headers in a comma-separated header field value.
Route: <sip:[email protected]>,<sip:[email protected]>,<sip:[email protected]> getHeaders("Route"); the result is a String array: {"<sip:[email protected]>", "<sip:[email protected]>","<sip:[email protected]>"}
void setHeader(java.lang.String name, java.lang.String
value)
Sets the header value in a SIP message. See section Headers for detailed information related to them. If the header does not exist, it will be added to the message, otherwise the existing header is overwritten. If multiple header field values exist, the one on the top is overwritten.
Example 1: Replacing single header field row. The message already contains the following headers:
Route: <sip:[email protected]> Route: <sip:[email protected]> setHeader("Route", " <sip:[email protected]>"); the result will be Route: <sip:[email protected]> Route: <sip:[email protected]>
Example 2: Setting multiple header field rows as a comma-separated list. The message already contains one header:
Route: <sip:[email protected]> setHeader("Route", "<sip:[email protected]>,<sip:[email protected]>"); the result will be: Route: <sip:[email protected]> Route: <sip:[email protected]>
void removeHeader(java.lang.String name)
Removes the header from the message. If multiple header field values exist, the topmost is removed. If the named header is not found, this method does nothing.
Example 1: Removing header from a message that contains two Route headers in separate header field rows.
Route: <sip:[email protected]> Route: <sip:[email protected]> removeHeader("Route"); the result is: Route: <sip:[email protected]>
java.lang.String getRequestURI()
The S60 implementation does not support this operation. This operation always returns null.
void send()
The S60 implementation tries to send request/response for 30 seconds
if e.g. creation of the GPRS connection fails or if the registration of the
SIP Profile takes time. This means that the send() operation
blocks for 30 seconds at the most. IOException is thrown
if sending the request/response still fails after 30 seconds.
The following restrictions/features apply to the UAS side:
A successful response (<= 299) for SUBSCRIBE and REFER
requests are not actually sent until the MIDlet sends the first NOTIFY request
to the UAC side, i.e. when the NOTIFY is sent, first
the successful response is sent followed immediately by the sending of the NOTIFY request.
IOException is thrown if some error
has occurred (e.g. in the sip stack) after the creation of the SipServerConnection object
and before the send() operation call. The state of the SipServerConnection object
is set to TERMINATED in this situation.
This interface has been implemented as specified by SIP API for J2ME (JSR-180).
java.lang.String getDialogID()
In the SUBSCRIBE and REFER cases, dialog ID is available on the UAS after sending a first NOTIFY request.
SipClientConnection getNewClientConnection(java.lang.String
method)
Section Sending a request inside an existing dialog describes the restrictions on this operation.
This interface has been implemented as specified by SIP API for J2ME (JSR-180).
This interface has been implemented as specified by SIP API for J2ME (JSR-180).
java.io.OutputStream update(int refreshID,java.lang.String[]
contact,java.lang.String type,int length,int expires)
Updating a ‘Contact’ header is only allowed in the REGISTER case.
Only one ‘Contact’ header is allowed to set to the ‘contact’ argument.
void refreshEvent(int refreshID,int statusCode,java.lang.String
reasonPhrase)
This callback operation is not called by the S60 implementation when a refreshing occurs. This callback operation is called when a refresh task is started, updated (by MIDlet), cancelled or failed.
The functionality of all other requests except REGISTER request
is supported on the UAS side.
void initResponse(int code)
A 100 response to INVITE is sent automatically
by the sip stack in the S60 implementation. Setting and sending 100 response
to INVITE is ignored on the UAS side. A 100 response is not allowed for other
request methods and IllegalArgumentException is thrown.
void notifyRequest(SipConnectionNotifier scn)
This callback operation is not called if the MIDlet blocks in the SipConnectionNotifier.acceptAndOpen() operation
at the same time. The reason for this functionality is that the acceptAndOpen() operation
returns a SipServerConnection object and the notifyRequest() operation
call is unnecessary in this situation because the acceptAndOpen() operation
has already provided a SipServerConnection object to
the MIDlet.