package-summary.html

JAVA CODE ,NOKIA JAVA SMS API接口函数包！主要是针对Java编程

</td>
</tr>

<tr>
<td>
71...132 chars
</td>
<td>
2
</td>
<td>
67...126 chars
</td>
<td>
2
</td>
</tr>

<tr>
<td>
133...198 chars
</td>
<td>
3
</td>
<td>
127...189 chars
</td>
<td>
3
</td>
</tr>

</table>

<h3>Addressing</h3>

<p>The URL strings that specify the address use the following syntax:
</p>
<p>
<code>
<table>
<tr>
<td>
smsurl
</td>
<td>               ::== "com.nokia.sms://" address_part
</td>
</tr>
<tr>
<td>
address_part
</td>
<td>         ::== foreign_host_address | local_host_address
</td>
</tr>
<tr>
<td>
local_host_address 
</td>
<td>  ::== port_number_part
</td>
</tr>
<tr>
<td>
port_number_part
</td>
<td>     ::== ":" digits
</td>
</tr>
<tr>
<td>
foreign_host_address 
</td>
<td>::== msisdn | msisdn port_number_part
</td>
</tr>
<tr>
<td>
msisdn
</td>
<td>               ::== "+" digits | digits
</td>
</tr>
<tr>
<td>
digit 
</td>
<td>    ::== "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
</td>
</tr>
<tr>
<td>
digits
</td>
<td>        ::== digit | digit digits
</td>
</tr>
</table>
</code>
</p>
<p>Examples of valid URLs are:
</p>
<p>
<code>
com.nokia.sms://[phone]<br/>
com.nokia.sms://[phone]:6578<br/>
com.nokia.sms://:3381<br/>
</code>
</p>
<p>In the address, the MSISDN part identifies the recipient phone number and the port number part the application port number address as specified in the GSM 3.40 SMS specification (sections 9.2.3.24.3 and 9.2.3.24.4). The same mechanism is used e.g. for the WAP WDP messages.</p>
<p>When the port number is present in the address, the TP-User Data of the SMS shall contain a User-Data-Header with the Application port addressing scheme information element.</p>
<p>When the recipient address does not contain a port number, the TP-User Data shall not contain the Application port addressing header. It is not possible for Java applications to receive this kind of messages, but they will be handled as normally in the recipient device, e.g. text messages will be displayed to the end user.</p>
<p>Messages can be sent using this API via 'client' or 'server' type MessageConnections. When a message identifying a port number is sent from a 'server' type MessageConnection, the originating port number in the message is set to the port number of the MessageConnection and thus the recipient can send a response to the message that will be received by this MessageConnection. </p>
<p>However, when a 'client' type MessageConnection is used for sending a message with a port number, the originating port number is set to an implementation specific value and any possible messages received to this port number are not delivered to the MessageConnection. </p>
<p>Thus, only the 'server' mode MessageConnections can be used for receiving messages and any messages to which the other party is expected to respond should be sent using the appropriate 'server' mode MessageConnection.</p>
<p>When SMS messages are received by an application, they are removed from the SIM / ME memory where they may have been stored. If an application wishes to save the message information more persistently, the application should handle the saving of the information itself e.g. using the RMS facility of the MIDP API or any other available mechanism.</p>

<h3>Using port numbers</h3>

<p>The receiving application in a device is identified with the port number included in the message. When opening the 'server' mode MessageConnection, the application specifies the port number that it will use for receiving messages.</p>
<p>The first application to allocate a given port number will get it and if subsequently other applications try to allocate the same port number while it is being used by the first application, the other applications will get an exception thrown when trying to open the MessageConnection. The same rule applies if some port number is being used by a system application in the device; in this case, the Java applications will not be able to use that port number.</p>
<p>As specified in the GSM 03.40 standard [1], the port numbers are split into ranges and there is a range that is controlled by IANA (the Internet Assigned Numbers Authority). If an application author wants to be sure that his application can always use some port number value, he can register a port number with IANA. Otherwise, he can just pick a number at random from the freely usable range and hope that the same number is not used by other applications at least such that would be installed in the same device as his application. This is exactly the same way as port numbers are used with TCP and UDP in the Internet currently.</p>

<h3>Message types</h3>

<p>SMS messages can be sent using the TextMessage or the BinaryMessage message type of the API. The encodings used in the SMS protocol are defined in the GSM 03.38 standard [2].</p>
<p>When the application uses the TextMessage, the TP-Data-Coding-Scheme in the SMS shall indicate the GSM default 7-bit alphabet or UCS-2 and the TP-User-Data shall be encoded appropriately using the chosen alphabet. The 7-bit alphabet shall be used for encoding if the String that is given by the application only contains characters that are present in the GSM 7-bit alphabet. If the String given by the application contains at least one character that is not present in the GSM 7-bit alphabet, the UCS-2 encoding shall be used.</p>
<p>When the application uses the BinaryMessage, the TP-Data-Coding-Scheme in the SMS shall indicate 8-bit data.</p>
<p>The application is responsible to keep the message payload such that it fits in an SMS message when encoded as defined in this specification. If the application tries to send a message with a too long payload, the MessageConnection.send() method will throw an exception and the message is not sent. This specification contains the necessary information for applications to be able to determine what is the maximum payload for the kind of message they are trying to send.</p>
<p>All messages sent via this API shall be sent as Class 1 messages.</p>


<h2>Handling Received Messages when the MIDlet Is Not Running</h2>

<p>The MIDP 2.0 (JSR118) will define the so-called "Push" mechanism that can be used to register the application so that it will be started when a message for it has been received.</p>
<p>Because this SMS API will be used in MIDP 1.0 based products, we define a similar mechanism based on an attribute in the JAD file for this purpose.</p>

<h3>Syntax of the JAD file extension</h3>

<p>The following extension may be placed in the JAD file to indicate that this MIDlet should be started when an SMS to the indicated port number is received.</p>
<p>Using the symbols defined in the BNF for application descriptors in section 8.5 of the MIDP 1.0 specification:</p>
<code>
attrname: "Nokia-SMS-Handler-" n
</code>
<p>where n shall be 1 for the first such attribute in the JAD file and the following such attributes in the same JAD file shall be numbered using consecutive ordinals.</p>

<code>
attrvalue: SMS_URL WSP "," WSP description WSP "," WSP MIDlet_class
</code>
<p>where SMS_URL is the URL as specified above, including the port number but not an MSISDN number (i.e. a URL for "server mode" connection).<br/>
description is descriptive text describing this connection (i.e. text suitable to be presented to the end user in some configuration / debugging cases)<br/>
MIDlet_class is the name of the MIDlet class that will be started to handle the messages to the indicated port number. This class name shall be such that the same class appears in one of the "MIDlet-<n>" attributes in the same JAD file.<br>
WSP is possible whitespace as defined in section 8.5 of the MIDP 1.0 specification.</p>
<p>The following line provides an example of the attribute line that could be included in the JAD file:</p>
<code>
Nokia-SMS-Handler-1: com.nokia.sms://:7685, Chess move SMS, com.nokia.chess.Chess
</code>


<h3>Behaviour for receiving SMS messages for application</h3>
<p>When the application is running and has opened the MessageConnection with the appropriate URL, the application will receive the incoming messages immediately as specified for the API.</p>
<p>When the application is not running and an SMS is received where the port number matches one of the port numbers indicated in a JAD file for a MIDlet, the implementation shall start the MIDlet indicated in the JAD file. </p>
<p>It is implementation specific how exactly this happens and it is not required to immediately pre-empt the application the user is currently using. The behaviour is intended to be similar to when a normal SMS arrives to the user (i.e. this notification is shown to the user at an appropriate time, but does not necessarily immediately pre-empt the application that the user is currently using). The implementation is also allowed to show a notification to the user asking for user confirmation before actually starting the MIDlet. The exact details how this happens are to be defined in the appropriate UI specification.</p>
<p>When the MIDlet is started, it is the responsibility of the MIDlet to open the MessageConnection with the same URL. When it does so, the messages that have been queued for it are delivered as defined in the API documentation.</p>
<p>If the application does not retrieve the messages (e.g. because the user denied starting the application or the application just does not call the API methods to receive the messages even after having been started), the implementation is allowed to delete the queued messages at an implementation-determined time. However, the implementation naturally needs to give the application reasonable time to retrieve the messages when it has been started.</p>


<h2>Examples of Usage</h2>

<p>This section provides some examples how the API can be used:</p>

<h3>Sending a text message to an end user</h3>

<p>The following example code sends the string "Hello World!" to an end user as a normal SMS.</p>

<code>
<pre>
try {
    String addr = "com.nokia.sms://[phone]";
    MessageConnection conn = (MessageConnection)Connector.open(addr);
    TextMessage msg =   
       (TextMessage)conn.newMessage(MessageConnection.TEXT_MESSAGE);
    msg.setPayloadText("Hello World!");
    conn.send(msg);
} catch (Exception e) {
  ...
}
</pre>
</code>

<h3>A server that responds to received messages</h3>

<P>The following example code illustrates a server application that waits for messages sent to port 5432 and responds to them.</p>

<code>
<pre>
try {
    String addr = "com.nokia.sms://:5432";
    MessageConnection conn = (MessageConnection)Connector.open(addr);
    Message msg = null;
    while (someExitCondition) {
        // wait for incoming messages
        msg = conn.receive();
        // received a message
        if (msg instanceof TextMessage) {
            TextMessage tmsg = (TextMessage)msg;
            String receivedText = tmsg.getPayloadText();
            // respond with the same text with "Received:" inserted
            // in the beginning
            tmsg.setPayloadText("Received:" + receivedText);
            // Note that the recipient address in the message is
            // already correct as we are reusing the same object
            conn.send(tmsg);
        }
        else {
           // Received message was not a text message, but e.g. binary
           ... 
        }
    }
} catch (Exception e) {
   ...
}
</pre>
</code>






<!-- Put @see and @since tags down here. -->
<P>

<P>
<HR>

<!-- ========== START OF NAVBAR ========== -->
<A NAME="navbar_bottom"><!-- --></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
<a href=http://forum.nokia.com/java target=_top>forum.nokia.com/java</a></EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;PREV PACKAGE&nbsp;
&nbsp;NEXT PACKAGE</FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="package-summary.html" TARGET="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;
<SCRIPT>
  <!--
  if(window==top) {
    document.writeln('<A HREF="../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>');
  }
  //-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
</TABLE>
<!-- =========== END OF NAVBAR =========== -->

<HR>
<font size=-1>Copyright (c) 2002 Nokia Mobile Phones. All Rights Reserved.<br/>Java is a trademark or registered trademark of Sun Microsystems, Inc.
</BODY>
</HTML>