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 Symbian 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 Symbian implementation does not support SipConnectionNotifier to
act in the dedicated mode. Symbian implementation throws IOException if MIDlet
passes "dedicated mode" URI as argument to the Connertor.open() operation.
Note: There
is one special case where Symbian implementation throws IllegalArgumentException instead
of IOException if MIDlet passes "dedicated mode" URI
as argument to the Connector.open() operation. This special
URI is "sip:".
Symbian 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 Symbian implementation does not
pass 401 or 407 responses to the MIDlet. The Symbian 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 Symbian 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 Symbian implementation does not support this operation. This operation always returns null.
void send()
The Symbian
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 Symbian 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 Symbian 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.