vcard.h 8.25 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
/*
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
17
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
18 19 20 21 22
*/

#ifndef LINPHONE_VCARD_H
#define LINPHONE_VCARD_H

23
#include "linphone/types.h"
24 25 26 27 28 29 30 31 32 33 34

#ifdef __cplusplus
extern "C"
{
#endif

/**
 * @addtogroup carddav_vcard
 * @{
 */

35 36 37 38 39
/**
 * Cast a belle_sip_object_t into LinphoneVcard.
 */
#define LINPHONE_VCARD BELLE_SIP_CAST(object, LinphoneVcard)

40
/**
41 42
 * Creates a #LinphoneVcard object that has a pointer to an empty vCard
 * @return a new #LinphoneVcard object
43
 * @deprecated Use linphone_factory_create_vcard() instead.
44
 * @donotwrap
45
 */
46
LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneVcard* linphone_vcard_new(void);
47 48

/**
49 50
 * Deletes a #LinphoneVcard object properly
 * @param[in] vCard the #LinphoneVcard to destroy
51
 * @deprecated Use linphone_vcard_unref() or belle_sip_object_unref() instead.
52
 * @donotwrap
53 54 55 56 57
 */
LINPHONE_DEPRECATED LINPHONE_PUBLIC void linphone_vcard_free(LinphoneVcard *vCard);

/**
 * Take a ref on a #LinphoneVcard.
58
 * @param[in] vCard #LinphoneVcard object
59 60 61 62 63
 */
LINPHONE_PUBLIC LinphoneVcard *linphone_vcard_ref(LinphoneVcard *vCard);

/**
 * Release a #LinphoneVcard.
64
 * @param[in] vCard #LinphoneVcard object
65
 */
66
LINPHONE_PUBLIC void linphone_vcard_unref(LinphoneVcard *vCard);
67

Ronan's avatar
Ronan committed
68 69
/**
 * Clone a #LinphoneVcard.
70 71
 * @param[in] vCard #LinphoneVcard object
 * @return a new #LinphoneVcard object
Ronan's avatar
Ronan committed
72 73 74
 */
LINPHONE_PUBLIC LinphoneVcard *linphone_vcard_clone(const LinphoneVcard *vCard);

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

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

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

96 97
/**
 * Sets the skipFieldValidation property of the vcard
98
 * @param[in] vCard the #LinphoneVcard
99 100 101 102 103 104
 * @param[in] skip skipFieldValidation property of the vcard
 */
LINPHONE_PUBLIC void linphone_vcard_set_skip_validation(LinphoneVcard *vCard, bool_t skip);

/**
 * Returns the skipFieldValidation property of the vcard.
105
 * @param[in] vCard the #LinphoneVcard
106 107 108 109
 * @return the skipFieldValidation property of the vcard
 */
LINPHONE_PUBLIC bool_t linphone_vcard_get_skip_validation(const LinphoneVcard *vCard);

110 111
/**
 * Sets the family name in the N attribute of the vCard.
112
 * @param[in] vCard the #LinphoneVcard
113 114 115 116 117 118
 * @param[in] name the family name to set for the vCard
 */
LINPHONE_PUBLIC void linphone_vcard_set_family_name(LinphoneVcard *vCard, const char *name);

/**
 * Returns the family name in the N attribute of the vCard, or NULL if it isn't set yet.
119
 * @param[in] vCard the #LinphoneVcard
120 121 122 123 124 125
 * @return the family name of the vCard, or NULL
 */
LINPHONE_PUBLIC const char* linphone_vcard_get_family_name(const LinphoneVcard *vCard);

/**
 * Sets the given name in the N attribute of the vCard.
126
 * @param[in] vCard the #LinphoneVcard
127 128 129 130 131 132
 * @param[in] name the given name to set for the vCard
 */
LINPHONE_PUBLIC void linphone_vcard_set_given_name(LinphoneVcard *vCard, const char *name);

/**
 * Returns the given name in the N attribute of the vCard, or NULL if it isn't set yet.
133
 * @param[in] vCard the #LinphoneVcard
134 135 136 137 138 139
 * @return the given name of the vCard, or NULL
 */
LINPHONE_PUBLIC const char* linphone_vcard_get_given_name(const LinphoneVcard *vCard);

/**
 * Adds a SIP address in the vCard, using the IMPP property
140
 * @param[in] vCard the #LinphoneVcard
141 142
 * @param[in] sip_address the SIP address to add
 */
143
LINPHONE_PUBLIC void linphone_vcard_add_sip_address(LinphoneVcard *vCard, const char *sip_address);
144 145 146

/**
 * Removes a SIP address in the vCard (if it exists), using the IMPP property
147
 * @param[in] vCard the #LinphoneVcard
148 149
 * @param[in] sip_address the SIP address to remove
 */
150
LINPHONE_PUBLIC void linphone_vcard_remove_sip_address(LinphoneVcard *vCard, const char *sip_address);
151 152 153

/**
 * Edits the preferred SIP address in the vCard (or the first one), using the IMPP property
154
 * @param[in] vCard the #LinphoneVcard
155 156
 * @param[in] sip_address the new SIP address
 */
157
LINPHONE_PUBLIC void linphone_vcard_edit_main_sip_address(LinphoneVcard *vCard, const char *sip_address);
158 159

/**
160
 * Returns the list of SIP addresses (as LinphoneAddress) in the vCard (all the IMPP attributes that has an URI value starting by "sip:") or NULL
161
 * @param[in] vCard the #LinphoneVcard
162
 * @return \bctbx_list{LinphoneAddress}
163
 */
164
LINPHONE_PUBLIC const bctbx_list_t* linphone_vcard_get_sip_addresses(LinphoneVcard *vCard);
165 166 167

/**
 * Adds a phone number in the vCard, using the TEL property
168
 * @param[in] vCard the #LinphoneVcard
169 170
 * @param[in] phone the phone number to add
 */
171
LINPHONE_PUBLIC void linphone_vcard_add_phone_number(LinphoneVcard *vCard, const char *phone);
172 173 174

/**
 * Removes a phone number in the vCard (if it exists), using the TEL property
175
 * @param[in] vCard the #LinphoneVcard
176 177
 * @param[in] phone the phone number to remove
 */
178
LINPHONE_PUBLIC void linphone_vcard_remove_phone_number(LinphoneVcard *vCard, const char *phone);
179 180 181

/**
 * Returns the list of phone numbers (as string) in the vCard (all the TEL attributes) or NULL
182
 * @param[in] vCard the #LinphoneVcard
183
 * @return \bctbx_list{const char *}
184 185 186 187 188
 */
LINPHONE_PUBLIC bctbx_list_t* linphone_vcard_get_phone_numbers(const LinphoneVcard *vCard);

/**
 * Fills the Organization field of the vCard
189
 * @param[in] vCard the #LinphoneVcard
190 191 192 193 194 195
 * @param[in] organization the Organization
 */
LINPHONE_PUBLIC void linphone_vcard_set_organization(LinphoneVcard *vCard, const char *organization);

/**
 * Gets the Organization of the vCard
196
 * @param[in] vCard the #LinphoneVcard
197 198 199 200 201 202 203
 * @return the Organization of the vCard or NULL
 */
LINPHONE_PUBLIC const char* linphone_vcard_get_organization(const LinphoneVcard *vCard);

/**
 * Generates a random unique id for the vCard.
 * If is required to be able to synchronize the vCard with a CardDAV server
204
 * @param[in] vCard the #LinphoneVcard
205 206
 * @return TRUE if operation is successful, otherwise FALSE (for example if it already has an unique ID)
 */
207
LINPHONE_PUBLIC bool_t linphone_vcard_generate_unique_id(LinphoneVcard *vCard);
208 209 210

/**
 * Sets the unique ID of the vCard
211
 * @param[in] vCard the #LinphoneVcard
212 213
 * @param[in] uid the unique id
 */
214
LINPHONE_PUBLIC void linphone_vcard_set_uid(LinphoneVcard *vCard, const char *uid);
215 216 217

/**
 * Gets the UID of the vCard
218
 * @param[in] vCard the #LinphoneVcard
219 220 221 222 223 224
 * @return the UID of the vCard, otherwise NULL
 */
LINPHONE_PUBLIC const char* linphone_vcard_get_uid(const LinphoneVcard *vCard);

/**
 * Sets the eTAG of the vCard
225
 * @param[in] vCard the #LinphoneVcard
226 227 228 229 230 231
 * @param[in] etag the eTAG
 */
LINPHONE_PUBLIC void linphone_vcard_set_etag(LinphoneVcard *vCard, const char * etag);

/**
 * Gets the eTag of the vCard
232
 * @param[in] vCard the #LinphoneVcard
233 234 235 236 237 238
 * @return the eTag of the vCard in the CardDAV server, otherwise NULL
 */
LINPHONE_PUBLIC const char* linphone_vcard_get_etag(const LinphoneVcard *vCard);

/**
 * Sets the URL of the vCard
239
 * @param[in] vCard the #LinphoneVcard
240 241 242 243 244 245
 * @param[in] url the URL
 */
LINPHONE_PUBLIC void linphone_vcard_set_url(LinphoneVcard *vCard, const char *url);

/**
 * Gets the URL of the vCard
246
 * @param[in] vCard the #LinphoneVcard
247 248 249 250 251 252 253 254 255 256 257 258
 * @return the URL of the vCard in the CardDAV server, otherwise NULL
 */
LINPHONE_PUBLIC const char* linphone_vcard_get_url(const LinphoneVcard *vCard);

/**
 * @}
 */

#ifdef __cplusplus
}
#endif

259
#endif