liblinphone 3.6.1

- Main Page
- Related Pages
- Modules
- Data Structures

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