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
LinphoneChatRoom *	linphone_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)
LinphoneChatRoom *	linphone_core_get_chat_room (LinphoneCore *lc, const LinphoneAddress *addr)
LinphoneCore *	linphone_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 LinphoneAddress *	linphone_chat_room_get_peer_address (LinphoneChatRoom *cr)
LinphoneChatMessage *	linphone_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)
LinphoneChatRoom *	linphone_chat_message_get_chat_room (LinphoneChatMessage *msg)
const LinphoneAddress *	linphone_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 LinphoneAddress *	linphone_chat_message_get_from (const LinphoneChatMessage *message)
const LinphoneAddress *	linphone_chat_message_get_to (const LinphoneChatMessage *message)
LinphoneAddress *	linphone_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)
LinphoneChatMessage *	linphone_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().

typedef enum _LinphoneChatMessageStates LinphoneChatMessageState

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

msg	LinphoneChatMessage object
status	LinphoneChatMessageState
ud	application user data

Enumeration Type Documentation

enum _LinphoneChatMessageStates

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

lc	LinphoneCore object
to	destination address for messages

Returns

LinphoneChatRoom where messaging can take place.

void linphone_chat_room_destroy

(

LinphoneChatRoom *

cr

)

Destroy a LinphoneChatRoom.

Parameters

cr	LinphoneChatRoom 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

cr	LinphoneChatRoom object
msg	message 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

lc	the linphone core
add	a 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

cr	LinphoneChatRoom 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

cr	the chat room.
message	text 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

cr	LinphoneChatRoom object
msg	LinphoneChatMessage message to be sent
status_cb	LinphoneChatMessageStateChangeCb status callback invoked when message is delivered or could not be delivered. May be NULL
ud	user 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

message

LinphoneChatMessage

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

message	a LinphoneChatMessage
url	ex: 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

message	LinphoneChatMessage obj
from	LinphoneAddress origin of this message (copied)

const LinphoneAddress * linphone_chat_message_get_from

(

const LinphoneChatMessage *

message

)

Get origin of the message

Parameters

message

LinphoneChatMessage obj

Returns

LinphoneAddress

const LinphoneAddress * linphone_chat_message_get_to

(

const LinphoneChatMessage *

message

)

Get destination of the message

Parameters

message

LinphoneChatMessage 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

message

LinphoneChatMessage 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

message

LinphoneChatMessage 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

message	the message
header_name	name of the header_name
header_value	header value

const char * linphone_chat_message_get_custom_header	(	LinphoneChatMessage *	message,
		const char *	header_name
	)

Retrieve a custom header value given its name.

Parameters

message	the message
header_name	header 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

lc	the linphone core
path	filesystem path