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

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.

typedef void(* LinphoneChatMessageStateChangeCb) (LinphoneChatMessage *msg, LinphoneChatMessageState state, void *ud)

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

LinphoneChatRoom * linphone_core_create_chat_room ( LinphoneCore lc,
const char *  to 
)

Create a new chat room for messaging from a sip uri like sip:joe@s.nosp@m.ip.l.nosp@m.inpho.nosp@m.ne.o.nosp@m.rg

Parameters
lcLinphoneCore object
todestination address for messages
Returns
LinphoneChatRoom where messaging can take place.
void linphone_chat_room_destroy ( LinphoneChatRoom cr)

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
LinphoneChatRoom * linphone_core_get_chat_room ( LinphoneCore lc,
const LinphoneAddress addr 
)

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.
LinphoneCore * linphone_chat_room_get_lc ( LinphoneChatRoom cr)

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.

void * linphone_chat_room_get_user_data ( LinphoneChatRoom cr)

Retrieve the user pointer associated with the chat room.

const LinphoneAddress * linphone_chat_room_get_peer_address ( LinphoneChatRoom cr)

get peer address associated to this LinphoneChatRoom

Parameters
crLinphoneChatRoom object
Returns
LinphoneAddress peer address
LinphoneChatMessage * linphone_chat_room_create_message ( LinphoneChatRoom cr,
const char *  message 
)

Create a message attached to a dedicated chat room;

Parameters
crthe chat room.
messagetext message, NULL if absent.
Returns
a new LinphoneChatMessage
void linphone_chat_room_send_message2 ( LinphoneChatRoom cr,
LinphoneChatMessage msg,
LinphoneChatMessageStateChangeCb  status_cb,
void *  ud 
)

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.
const char * linphone_chat_message_state_to_string ( const LinphoneChatMessageState  state)

Returns a LinphoneChatMessageState as a string.

LinphoneChatRoom * linphone_chat_message_get_chat_room ( LinphoneChatMessage msg)

Returns the chatroom this message belongs to.

const LinphoneAddress * linphone_chat_message_get_peer_address ( LinphoneChatMessage msg)

Returns the peer (remote) address for the message.

void linphone_chat_message_set_user_data ( LinphoneChatMessage message,
void *  ud 
)

User pointer set function

void * linphone_chat_message_get_user_data ( const LinphoneChatMessage message)

User pointer get function

const char * linphone_chat_message_get_external_body_url ( const LinphoneChatMessage message)

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)
const LinphoneAddress * linphone_chat_message_get_from ( const LinphoneChatMessage message)

Get origin of the message

Parameters
messageLinphoneChatMessage obj
Returns
LinphoneAddress
const LinphoneAddress * linphone_chat_message_get_to ( const LinphoneChatMessage message)

Get destination of the message

Parameters
messageLinphoneChatMessage obj
Returns
LinphoneAddress
LinphoneAddress * linphone_chat_message_get_local_address ( const LinphoneChatMessage message)

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
time_t linphone_chat_message_get_time ( const LinphoneChatMessage message)

Get the time the message was sent.

LinphoneChatMessageState linphone_chat_message_get_state ( const LinphoneChatMessage message)

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
LinphoneChatMessage * linphone_chat_message_clone ( const LinphoneChatMessage msg)

Duplicate a LinphoneChatMessage

void linphone_chat_message_destroy ( LinphoneChatMessage msg)

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