liblinphone  3.6.1
Typedefs | Enumerations | Functions
Chat room and Messaging

Typedefs

typedef struct _LinphoneChatMessage LinphoneChatMessage
typedef struct _LinphoneChatRoom LinphoneChatRoom
typedef enum
_LinphoneChatMessageStates 
LinphoneChatMessageState
typedef void(* LinphoneChatMessageStateChangeCb )(LinphoneChatMessage *msg, LinphoneChatMessageState state, void *ud)

Enumerations

enum  _LinphoneChatMessageStates {
  LinphoneChatMessageStateIdle,
  LinphoneChatMessageStateInProgress,
  LinphoneChatMessageStateDelivered,
  LinphoneChatMessageStateNotDelivered
}

Functions

LinphoneChatRoomlinphone_core_create_chat_room (LinphoneCore *lc, const char *to)
void linphone_chat_room_destroy (LinphoneChatRoom *cr)
void linphone_chat_room_send_message (LinphoneChatRoom *cr, const char *msg)
LinphoneChatRoomlinphone_core_get_chat_room (LinphoneCore *lc, const LinphoneAddress *addr)
LinphoneCorelinphone_chat_room_get_lc (LinphoneChatRoom *cr)
void linphone_chat_room_set_user_data (LinphoneChatRoom *cr, void *ud)
void * linphone_chat_room_get_user_data (LinphoneChatRoom *cr)
const LinphoneAddresslinphone_chat_room_get_peer_address (LinphoneChatRoom *cr)
LinphoneChatMessagelinphone_chat_room_create_message (LinphoneChatRoom *cr, const char *message)
void linphone_chat_room_send_message2 (LinphoneChatRoom *cr, LinphoneChatMessage *msg, LinphoneChatMessageStateChangeCb status_cb, void *ud)
const char * linphone_chat_message_state_to_string (const LinphoneChatMessageState state)
LinphoneChatRoomlinphone_chat_message_get_chat_room (LinphoneChatMessage *msg)
const LinphoneAddresslinphone_chat_message_get_peer_address (LinphoneChatMessage *msg)
void linphone_chat_message_set_user_data (LinphoneChatMessage *message, void *ud)
void * linphone_chat_message_get_user_data (const LinphoneChatMessage *message)
const char * linphone_chat_message_get_external_body_url (const LinphoneChatMessage *message)
void linphone_chat_message_set_external_body_url (LinphoneChatMessage *message, const char *url)
void linphone_chat_message_set_from (LinphoneChatMessage *message, const LinphoneAddress *from)
const LinphoneAddresslinphone_chat_message_get_from (const LinphoneChatMessage *message)
const LinphoneAddresslinphone_chat_message_get_to (const LinphoneChatMessage *message)
LinphoneAddresslinphone_chat_message_get_local_address (const LinphoneChatMessage *message)
time_t linphone_chat_message_get_time (const LinphoneChatMessage *message)
LinphoneChatMessageState linphone_chat_message_get_state (const LinphoneChatMessage *message)
const char * linphone_chat_message_get_text (const LinphoneChatMessage *message)
void linphone_chat_message_add_custom_header (LinphoneChatMessage *message, const char *header_name, const char *header_value)
const char * linphone_chat_message_get_custom_header (LinphoneChatMessage *message, const char *header_name)
LinphoneChatMessagelinphone_chat_message_clone (const LinphoneChatMessage *msg)
void linphone_chat_message_destroy (LinphoneChatMessage *msg)
void linphone_core_set_chat_database_path (LinphoneCore *lc, const char *path)

Detailed Description

Exchanging text messages
Messages are sent using LinphoneChatRoom object. First step is to create a chat room from a peer sip uri.

LinphoneChatRoom* chat_room = linphone_core_create_chat_room(lc,"sip:joe@sip.linphone.org");


Once created, messages are sent using function linphone_chat_room_send_message() .

linphone_chat_room_send_message(chat_room,"Hello world"); /*sending message*/


Incoming message are received from call back LinphoneCoreVTable.text_received

void text_received(LinphoneCore *lc, LinphoneChatRoom *room, const LinphoneAddress *from, const char *message) {
        printf(" Message [%s] received from [%s] \n",message,linphone_address_as_string (from));
}


A complete tutorial can be found at : Chat room tutorial


Typedef Documentation

typedef struct _LinphoneChatMessage LinphoneChatMessage

A chat room message to old content to be sent.
Can be created by linphone_chat_room_create_message().

typedef struct _LinphoneChatRoom LinphoneChatRoom

A chat room is the place where text messages are exchanged.
Can be created by linphone_core_create_chat_room().

LinphoneChatMessageState is used to notify if messages have been succesfully delivered or not.

Call back used to notify message delivery status

Parameters:
msgLinphoneChatMessage object
statusLinphoneChatMessageState
udapplication user data

Enumeration Type Documentation

LinphoneChatMessageState is used to notify if messages have been succesfully delivered or not.

Enumerator:
LinphoneChatMessageStateIdle 

initial state

LinphoneChatMessageStateInProgress 

delivery in progress

LinphoneChatMessageStateDelivered 

message succesffully delivered an acknoleged by remote end point

LinphoneChatMessageStateNotDelivered 

message was not delivered


Function Documentation

Create a new chat room for messaging from a sip uri like sip:joe@sip.linphone.org

Parameters:
lcLinphoneCore object
todestination address for messages
Returns:
LinphoneChatRoom where messaging can take place.

Destroy a LinphoneChatRoom.

Parameters:
crLinphoneChatRoom object
void linphone_chat_room_send_message ( LinphoneChatRoom cr,
const char *  msg 
)

Send a message to peer member of this chat room.

Deprecated:
linphone_chat_room_send_message2() gives more control on the message expedition.
Parameters:
crLinphoneChatRoom object
msgmessage to be sent

Retrieve an existing chat room whose peer is the supplied address, if exists.

Parameters:
lcthe linphone core
adda linphone address.
Returns:
the matching chatroom, or NULL if no such chatroom exists.

Returns back pointer to LinphoneCore object.

void linphone_chat_room_set_user_data ( LinphoneChatRoom cr,
void *  ud 
)

Assign a user pointer to the chat room.

Retrieve the user pointer associated with the chat room.

get peer address associated to this LinphoneChatRoom

Parameters:
crLinphoneChatRoom object
Returns:
LinphoneAddress peer address

Create a message attached to a dedicated chat room;

Parameters:
crthe chat room.
messagetext message, NULL if absent.
Returns:
a new LinphoneChatMessage

Send a message to peer member of this chat room.

Parameters:
crLinphoneChatRoom object
msgLinphoneChatMessage message to be sent
status_cbLinphoneChatMessageStateChangeCb status callback invoked when message is delivered or could not be delivered. May be NULL
uduser data for the status cb.
Note:
The LinphoneChatMessage must not be destroyed until the the callback is called.

Returns a LinphoneChatMessageState as a string.

Returns the chatroom this message belongs to.

Returns the peer (remote) address for the message.

void linphone_chat_message_set_user_data ( LinphoneChatMessage message,
void *  ud 
)

User pointer set function

User pointer get function

Linphone message can carry external body as defined by rfc2017

Parameters:
messageLinphoneChatMessage
Returns:
external body url or NULL if not present.
void linphone_chat_message_set_external_body_url ( LinphoneChatMessage message,
const char *  url 
)

Linphone message can carry external body as defined by rfc2017

Parameters:
messagea LinphoneChatMessage
urlex: access-type=URL; URL="http://www.foo.com/file"
void linphone_chat_message_set_from ( LinphoneChatMessage message,
const LinphoneAddress from 
)

Set origin of the message

Parameters:
messageLinphoneChatMessage obj
fromLinphoneAddress origin of this message (copied)

Get origin of the message

Parameters:
messageLinphoneChatMessage obj
Returns:
LinphoneAddress

Get destination of the message

Parameters:
messageLinphoneChatMessage obj
Returns:
LinphoneAddress

Returns the origin address of a message if it was a outgoing message, or the destination address if it was an incoming message.

Parameters:
messageLinphoneChatMessage obj
Returns:
LinphoneAddress

Get the time the message was sent.

Get the state of the message

Parameters:
messageLinphoneChatMessage obj
Returns:
LinphoneChatMessageState
const char * linphone_chat_message_get_text ( const LinphoneChatMessage message)

Get text part of this message

Returns:
text or NULL if no text.
void linphone_chat_message_add_custom_header ( LinphoneChatMessage message,
const char *  header_name,
const char *  header_value 
)

Add custom headers to the message.

Parameters:
messagethe message
header_namename of the header_name
header_valueheader value
const char * linphone_chat_message_get_custom_header ( LinphoneChatMessage message,
const char *  header_name 
)

Retrieve a custom header value given its name.

Parameters:
messagethe message
header_nameheader name searched

Duplicate a LinphoneChatMessage

Destroys a LinphoneChatMessage.

void linphone_core_set_chat_database_path ( LinphoneCore lc,
const char *  path 
)

Sets the database filename where chat messages will be stored. If the file does not exist, it will be created.

Parameters:
lcthe linphone core
pathfilesystem path