Documentation »  ACCESS Linux Platform Native Development »  Messaging Guide »  IMPS

The IMPS Postal Plug-in provides services for Instant Messaging and Presence Services (IMPS). This service IMPS defines a set of universal specifications for mobile instant messaging. The specifications describe the exchange of messages and presence information between mobile devices, mobile services, and Internet-based instant messaging services while leveraging existing web technologies.

The IMPS plug-in provides OMA IMPS 1.2 and 1.3 features to the Postal Framework. It implements all the mandatory interfaces that the framework provides and exposes a set of APIs for an IMPS client. The plug-in also takes advantage of the Postal Framework flexibility.

The IMPS plug-in implements CSP 1.3 (Client Server Protocol) and maintains compliance with 1.2.

Supported Services ^TOP^

The IMPS Postal Plug-in provides several services, described below.

Messaging:

The Messaging service element provides functionality for sending and receiving instant messages. An instant message may be sent to, or received from, a specific IMPS-user, or users of other instant messaging systems. It is also possible to send instant messages to a group of IMPS users. Applications use Postal Framework APIs to access the Messaging service, which is part of the common behavior between all Postal Services plug-ins.

Presence:

The Presence service element provides functionality for presence information management. This includes updating, retrieving, setting, and storing presence and location information. Presence information can be manipulated implicitly by the system, or explicitly by the user. A user can subscribe to receive the presence information of other users, as specified in a contact list. Contact List Management is also a part of the presence service.

Group:

The Group service element provides functionality for use and management of groups. The groups can be private or public. A common usage of the Group service is a chat room.

CSP Connection:

The CSP Connection provides functionality for formatting and sending CSP primitives. This includes sessions and transactions management.

CSP Access:

The CSP Access provides functionality for authenticating and authorizing the client to the IMPS server. It also provides common functions.

IMPS Transport

The transport layer, which can be HTTP, HTTPS or SMS.

All the CSP Messages are converted into XML form. If the encoding is WBXML or PTS, an encoder/decoder is in charge to process the conversion.

IMPS Feature Provisions ^TOP^

CSP Access:

Login; 4W Login; Logout; Capability; Negotiation

Messaging:

Send to buddy; Send to group

Presence:

Add/Remove buddy; Create/Remove list;
Update my presence; Update my public profile (1.3);
Get buddy presence; Get list presence;
Subscribe presence to a buddy; Subscribe presence to a list

Group:

Create; Join

Search:

Execute a query

Implementation Details ^TOP^

• Data can be encoded in XML, WBXML or PTS (Plain Text Syntax)
• The transport layer can be HTTP, HTTPS or SMS
• CIR (Communication Initiation Request) can be done by WAP PUSH SMS or by a TCP link

Usage Examples ^TOP^

The IMPS Service is provided by the postal IMPS plug-in. It implements the generic APIs of the Postal Services framework and exposes specific IMPS features.

The main basics features provided by the generic APIs are:

• Manage accounts
• Manage sessions
• Send/Receive messages

IMPS service is an implementation of the OMA Wireless Village (WV) IMPS protocol. It supports a set of features of 1.1, 1.2 and 1.3 versions. The version used is automatically negotiated when the plug-in logs into the IMPS Server.

In order to provide the specific IMPS features (such as buddy management and presence management), the IMPS plug-in provides the following specific services:

• IMPS Contact
• IMPS Contact List
• IMPS Buddy
• IMPS Presence
• IMPS Search

The IMPS plug-in also extends the Session generic services.

The goal of this section is to provide an overview of the specifics IMPS features and to provide sample code.

Table 3.1  Specific IMPS Objects

Logging Into an IMPS Server ^TOP^

To login to an IMPS server, the IMPS service relies on the generic Postal APIs.

First, create an IMPS account for the IMPS service. The IMPS account service exposes a set of specifics IMPS_ACCOUNT properties in postal_imps_account.h.

The IMPS account must contain the following information, shown here with description and property:

• Server address: a string:
  "http://service_ip" or "http://domain.address".
  ALP_POSTAL_IMPS_PROPERTY_ACCOUNT_SERVER_ADDRESS
• Server port: an integer representing a port number
  ALP_POSTAL_IMPS_PROPERTY_ACCOUNT_SERVER_PORT
• Username: the WV UserID of the client
  ALP_POSTAL_IMPS_PROPERTY_ACCOUNT_SERVER_LOGIN
• Password: the password associated with the WV user ID
  ALP_POSTAL_IMPS_PROPERTY_ACCOUNT_SERVER_PASSWORD

Creating and Connecting to a Session ^TOP^

This example assumes that the application has a defined account. The (asynchronous) call to connect the session starts the login procedure of the IMPS service.

// Define the callback that will be called when the 
asynchronous connect 
// function ends 
static void on_AlpPostalSessionConnectAsyncReplyCallback 
        (alp_postal_service_id_t iServiceId,  
         alp_postal_session_id_t iSessionId,  
         alp_status_t iRequestResult) 
{ 
        printf("Session %d connect status code is %x\n", 
iSessionId, iRequestResult); 
} 
 
// Declare the account 
AlpPostalAccount    postalAccount; 
 
alp_postal_session_id_t     sessionId = 
ALP_POSTAL_SESSION_INVALID_ID; 
alp_postal_account_id_t     accountId = 
ALP_POSTAL_ACCOUNT_INVALID_ID; 
 
// Intialize the account 
alp_postal_account_init (&postalAccount); 
 
// Set the account name (generic property) 
alp_postal_account_set_property (&postalAccount, 
ALP_POSTAL_PROPERTY_ACCOUNT_NAME, 
(alp_postal_property_value_t)"myIMPSaccount", 0); 
 
// Set the server address (specific property) 
alp_postal_account_set_property (&postalAccount, 
ALP_POSTAL_IMPS_PROPERTY_ACCOUNT_SERVER_ADDRESS, 
(alp_postal_property_value_t)"http://0.0.0.0", 0); 
 
// Set the User ID (specific propery) 
alp_postal_account_set_property (&postalAccount, 
ALP_POSTAL_IMPS_PROPERTY_ACCOUNT_LOGIN, 
(alp_postal_property_value_t)"wv:bob", 0); 
 
// Set the Password of User ID 
alp_postal_account_set_property (&postalAccount, 
ALP_POSTAL_IMPS_PROPERTY_ACCOUNT_PASSWORD, 
(alp_postal_property_value_t)"0000", 0); 
 
// Create (save) the account 
alp_postal_service_create_account 
(ALP_POSTAL_SERVICE_ID_IMPS, &postalAccount, &accountId); 
 
// Create the session 
alp_postal_service_create_session 
(ALP_POSTAL_SERVICE_ID_IMPS, accountId, &sessionId); 
 
// Connect the session 
alp_postal_session_connect(ALP_POSTAL_SERVICE_ID_IMPS, 
sessionId, NULL, NULL, 
on_AlpPostalSessionConnectAsyncReplyCallback); 

Note that the code sample uses the generic Postal Services function, alp_postal_session_connect(). You can also connect an IMPS session using alp_postal_imps_session_connect(), which is specific to the IMPS plug-in library. This function's callback result is an asynchronous response that includes the string iResultDescription. The string returns the IMPS server's response to the "connect" request. Likewise, you can use alp_postal_imps_session_disconnect() to disconnect a session.

Adding or Removing a List Contact ^TOP^

This request is sent to the IMPS server. Therefore, the call must occur on a connected session.

The API only operates on contact lists, which means you can only add or remove a list contacts, even if the list contains only one contact.

Because using a "ContactList" to store a list of contacts might be confusing, the object used to store a list of contacts is a NickList (AlpPostalImpsNickList).

To fill a list of contacts, fill an AlpPostalImpsNickList as shown in the following example:

// Declare a contact to add 
AlpPostalImpsContact      newContact; 
// Declare the nicklist 
AlpPostalImpsNickList     nickList; 
 
// Initialize objects 
alp_postal_imps_contact_init (&newContact);						 
alp_postal_imps_contact_init_nick_list (&nickList); 
 
// Set property on Contact 
alp_postal_imps_contact_set_property (&newContact, 
ALP_POSTAL_IMPS_PROPERTY_CONTACT_NICKNAME, 
(alp_postal_property_value_t)"nick", 0); 
 
// Set property on Contact 
alp_postal_imps_contact_set_property (&newContact, 
ALP_POSTAL_IMPS_PROPERTY_CONTACT_USERID, 
(alp_postal_property_value_t)"wv:user", 0); 
 
// Add the contact to the nickList 
alp_postal_imps_contact_add_to_list(&nickList, &newContact); 
[OK] 
 
// Use the nickList 

To add a contact, declare and set the properties on the contact. The USER_ID property is important: it must refer to a UserID that exists on the IMPS server.

Declare and fill a list of contacts (a NickList). Then call the IMPS_CONTACT_MANAGE API that adds or removes the list of contacts according to the operationType flag: IMPS_CONTACT_MANAGE_ADD or IMPS_CONTACT_MANAGE_REMOVE.

The second parameter is the ContactListID, which specifies where to add or remove the user. If an empty string is passed, the user will be added into the default list, if one exists.

alp_postal_imps_contact_manage (ALP_POSTAL_SERVICE_ID_IMPS, 
"", &nickList, IMPS_CONTACT_MANAGE_ADD, callbackPtr); 
 
// Free the nickList (also free the contacts that have been 
added) 
alp_postal_imps_contact_free_nick_list(&nickList); 

Adding a Contact List ^TOP^

Use the following function to add a contact list:

alp_postal_imps_contact_list_create; 

Updating Presence Status ^TOP^

To update and broadcast presence status, simply build a Presence object with the presence properties:

// Declare the presence object 
AlpPostalImpsPresence         impsPresence; 
 
// Initialize the object 
alp_postal_imps_presence_init (&impsPresence); 
 
// Set presence properties 
alp_postal_imps_presence_set_property (&impsPresence,  
              
ALP_POSTAL_IMPS_PROPERTY_PRESENCE_ONLINE_STATUS, 
              ((alp_postal_property_value_t) TRUE), 0); 
alp_postal_imps_presence_set_property (&impsPresence,  
              ALP_POSTAL_IMPS_PROPERTY_PRESENCE_AVAILABILITY,  
              ((alp_postal_property_value_t) 
gUserPresenceStatus), 0); 
alp_postal_imps_presence_set_property (&impsPresence, 
              ALP_POSTAL_IMPS_PROPERTY_PRESENCE_STATUS_TEXT, 
              ((alp_postal_property_value_t) gMessage), 0); 
alp_postal_imps_presence_set_property (&impsPresence, 
              ALP_POSTAL_IMPS_PROPERTY_PRESENCE_MOOD, 
              ((alp_postal_property_value_t) gMood), 0); 
 
// Send the request 
alp_postal_imps_presence_update (a_connected_session_id, 
&impsPresence, callbackPtr); 

Managing Buddies ^TOP^

A Buddy is an object that contains a single Contact, one ContactList, and one Presence.

The buddy is only an object that you can retrieve from the postal server. When you get a buddy, it has information about the Contact (UserID, etc.), it may have information about the ContactList it belongs to (ContactListID, ContactListName), and it may have information about presence.

To get properties relative to the Contact, use the following function:

alp_postal_imps_buddy_get_contact(AlpPostalImpsBuddy* iBuddyP,
   AlpPostalImpsContact** oContactP);  

 To get properties relative to the ContactList, use:

alp_postal_imps_buddy_get_contact_list(AlpPostalImpsBuddy* iBuddyP,
   AlpPostalImpsContactList** oContactListP); 

 To get properties relative to the Presence, use the following: 

alp_postal_imps_buddy_get_presence (AlpPostalImpsBuddy* iBuddyP,
   AlpPostalImpsPresence** oPresenceP); 


    NOTE:  Do not free the pointers oContactP, oContactListP, or oPresenceP. Use alp_postal_imps_buddy_free instead.



   Retrieving the List of Buddies ^TOP^



 The following example illustrates how to retrieve a buddy list: 

AlpPostalEnumerator     enumerator; 
AlpPostalProperty*      propP; 
AlpPostalImpsBuddy      buddy; 
AlpPostalImpsContact*   contactP; 
AlpPostalImpsPresence*  presenceP 
char*                   str; 
bool                    online; 
 
// Initialize enumerator 
alp_postal_imps_session_buddy_init_enumerator(&enumerator); 
// Get buddy enumerator 
alp_postal_imps_session_get_buddy_enumerator(iSessionId, 
      NULL, NULL, &enumerator); 
// Enumerate buddy list 
while(alp_postal_imps_session_get_next_buddy(&enumerator, 
&buddy) == POSTAL_STATUS_OK) 
{ 
        // Use the buddy 
        // Get the buddy's userId 
         alp_postal_imps_buddy_get_contact(buddy, &contactP); 
         alp_postal_imps_contact_get_property(contactP,
         ALP_POSTAL_IMPS_PROPERTY_CONTACT_USERID, &propP); 
	 alp_postal_property_get_string(prop, &str); 
       // Get the buddy's online status 
         alp_postal_imps_buddy_get_presence(buddy,
         &presenceP); 
         alp_postal_imps_presence_get_property(presenceP,
    ALP_POSTAL_IMPS_PROPERTY_PRESENCE_ONLINE_STATUS, &propP); 
         alp_postal_property_get_bool(prop, &bool); 
 
} 
alp_postal_imps_session_buddy_release_enumerator(&enumerator)
; 



   Sending and Receiving Presence Notifications ^TOP^



 On a connected session, when the presence status of a buddy changes, a postal notification is sent.

 To receive plug-in specific notifications, the postal client must call:

alp_postal_imps_service_initialize(); 



 To register for the presence notification, use:

alp_postal_notification_add_observer
      (ALP_POSTAL_IMPS_NOTIFICATION_PRESENCE_UPDATE, (void*)callbackPtr); 



 To remove the notification, use: 

alp_postal_notification_remove_observer
      (ALP_POSTAL_IMPS_NOTIFICATION_PRESENCE_UPDATE); 



 
 

	1. Written by This e-mail address is being protected from spam bots, you need JavaScript enabled to view it on 06-06-2008 21:31 - Guest
	How to build IMPS server i want to build my own IMPS server, what must i do to do that? http://ibnumaksum.cn Report