vcard.h 5.73 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
/*
vcard.h
Copyright (C) 2015  Belledonne Communications SARL

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
*/

20 21 22
#ifndef LINPHONE_VCARD_H
#define LINPHONE_VCARD_H

23 24 25 26 27 28
#include <mediastreamer2/mscommon.h>

#ifndef LINPHONE_PUBLIC
#define LINPHONE_PUBLIC MS2_PUBLIC
#endif

29 30 31 32 33
#ifdef __cplusplus
extern "C"
{
#endif

34
/**
35
 * @addtogroup carddav_vcard
36 37 38
 * @{
 */

39 40
typedef struct _LinphoneVCard LinphoneVCard;

41 42 43
/**
 * Creates a LinphoneVCard object that has a pointer to an empty vCard
 */
44
LINPHONE_PUBLIC LinphoneVCard* linphone_vcard_new(void);
45 46 47

/**
 * Deletes a LinphoneVCard object properly
48
 * @param[in] vCard the LinphoneVCard to destroy
49
 */
50
LINPHONE_PUBLIC void linphone_vcard_free(LinphoneVCard *vCard);
51 52 53 54 55 56

/**
 * Uses belcard to parse the content of a file and returns all the vcards it contains as LinphoneVCards, or NULL if it contains none.
 * @param[in] file the path to the file to parse
 * @return \mslist{LinphoneVCard}
 */
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
LINPHONE_PUBLIC MSList* linphone_vcard_list_from_vcard4_file(const char *file);

/**
 * Uses belcard to parse the content of a buffer and returns all the vcards it contains as LinphoneVCards, or NULL if it contains none.
 * @param[in] buffer the buffer to parse
 * @return \mslist{LinphoneVCard}
 */
LINPHONE_PUBLIC MSList* linphone_vcard_list_from_vcard4_buffer(const char *buffer);

/**
 * Uses belcard to parse the content of a buffer and returns one vCard if possible, or NULL otherwise.
 * @param[in] buffer the buffer to parse
 * @return a LinphoneVCard if one could be parsed, or NULL otherwise
 */
LINPHONE_PUBLIC LinphoneVCard* linphone_vcard_new_from_vcard4_buffer(const char *buffer);
72

73 74
/**
 * Returns the vCard4 representation of the LinphoneVCard.
75 76
 * @param[in] vCard the LinphoneVCard
 * @return a const char * that represents the vCard
77
 */
78
LINPHONE_PUBLIC const char* linphone_vcard_as_vcard4_string(LinphoneVCard *vCard);
79 80 81

/**
 * Sets the FN attribute of the vCard (which is mandatory).
82
 * @param[in] vCard the LinphoneVCard
83 84
 * @param[in] name the display name to set for the vCard
 */
85
LINPHONE_PUBLIC void linphone_vcard_set_full_name(LinphoneVCard *vCard, const char *name);
86 87 88

/**
 * Returns the FN attribute of the vCard, or NULL if it isn't set yet.
89
 * @param[in] vCard the LinphoneVCard
90 91
 * @return the display name of the vCard, or NULL
 */
92 93 94 95 96 97 98 99
LINPHONE_PUBLIC const char* linphone_vcard_get_full_name(const LinphoneVCard *vCard);

/**
 * Adds a SIP address in the vCard, using the IMPP property
 * @param[in] vCard the LinphoneVCard
 * @param[in] sip_address the SIP address to add
 */
LINPHONE_PUBLIC void linphone_vcard_add_sip_address(LinphoneVCard *vCard, const char *sip_address);
100

101 102 103 104 105 106 107 108 109 110 111 112 113 114
/**
 * Removes a SIP address in the vCard (if it exists), using the IMPP property
 * @param[in] vCard the LinphoneVCard
 * @param[in] sip_address the SIP address to remove
 */
LINPHONE_PUBLIC void linphone_vcard_remove_sip_address(LinphoneVCard *vCard, const char *sip_address);

/**
 * Edits the preferred SIP address in the vCard (or the first one), using the IMPP property
 * @param[in] vCard the LinphoneVCard
 * @param[in] sip_address the new SIP address
 */
LINPHONE_PUBLIC void linphone_vcard_edit_main_sip_address(LinphoneVCard *vCard, const char *sip_address);

115 116
/**
 * Returns the list of SIP addresses (as const char *) in the vCard (all the IMPP attributes that has an URI value starting by "sip:") or NULL
117
 * @param[in] vCard the LinphoneVCard
118 119
 * @return \mslist{const char *}
 */
120
LINPHONE_PUBLIC MSList* linphone_vcard_get_sip_addresses(const LinphoneVCard *vCard);
121

122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141
/**
 * Generates a random unique id for the vCard.
 * If is required to be able to synchronize the vCard with a CardDAV server
 * @param[in] vCard the LinphoneVCard
 * @return TRUE if operation is successful, otherwise FALSE (for example if it already has an unique ID)
 */
LINPHONE_PUBLIC bool_t linphone_vcard_generate_unique_id(LinphoneVCard *vCard);

/**
 * Sets the unique ID of the vCard
 * @param[in] vCard the LinphoneVCard
 * @param[in] uid the unique id
 */
void linphone_vcard_set_uid(LinphoneVCard *vCard, const char *uid);

/**
 * Gets the UID of the vCard
 * @param[in] vCard the LinphoneVCard
 * @return the UID of the vCard, otherwise NULL
 */
142 143
const char* linphone_vcard_get_uid(const LinphoneVCard *vCard);

144 145 146 147 148
/**
 * Sets the eTAG of the vCard
 * @param[in] vCard the LinphoneVCard
 * @param[in] etag the eTAG
 */
149
void linphone_vcard_set_etag(LinphoneVCard *vCard, const char * etag);
150 151 152 153 154 155

/**
 * Gets the eTag of the vCard
 * @param[in] vCard the LinphoneVCard
 * @return the eTag of the vCard in the CardDAV server, otherwise NULL
 */
156 157
const char* linphone_vcard_get_etag(const LinphoneVCard *vCard);

158 159 160 161 162
/**
 * Sets the URL of the vCard
 * @param[in] vCard the LinphoneVCard
 * @param[in] url the URL
 */
163
void linphone_vcard_set_url(LinphoneVCard *vCard, const char * url);
164 165 166 167 168 169

/**
 * Gets the URL of the vCard
 * @param[in] vCard the LinphoneVCard
 * @return the URL of the vCard in the CardDAV server, otherwise NULL
 */
170 171
const char* linphone_vcard_get_url(const LinphoneVCard *vCard);

172 173 174 175
/**
 * @}
 */

176 177 178 179 180
#ifdef __cplusplus
}
#endif

#endif