libpurple/protocols/novell/nmcontact.h

   1 /*
   2  * nmcontact.h
   3  *
   4  * Copyright (c) 2004 Novell, Inc. All Rights Reserved.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; version 2 of the License.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA        02111-1301      USA
  18  *
  19  */
  20
  21 #ifndef PURPLE_NOVELL_NMCONTACT_H
  22 #define PURPLE_NOVELL_NMCONTACT_H
  23
  24 #include <glib.h>
  25
  26 typedef struct _NMContact NMContact;
  27 typedef struct _NMContactProperty NMContactProperty;
  28 typedef struct _NMFolder NMFolder;
  29
  30 #include "nmfield.h"
  31 #include "nmuser.h"
  32
  33 /**
  34  * Creates a contact
  35  *
  36  * Should be released by calling nm_release_contact
  37  *
  38  * @return                      The new NMContact
  39  *
  40  */
  41 NMContact *nm_create_contact(void);
  42
  43 /**
  44  * Creates a contact from a field array representing the
  45  * contact
  46  *
  47  * Should be released by calling nm_release_contact
  48  *
  49  * @param       fields  Should be the NM_A_FA_CONTACT for
  50  *                                      the contact
  51  *
  52  * @return      The new contact
  53  *
  54  */
  55 NMContact *nm_create_contact_from_fields(NMField * fields);
  56
  57 /**
  58  * Add a reference to an existing contact
  59  *
  60  * The reference should be released by calling
  61  * nm_release_contact
  62  *
  63  * @param       contact The contact
  64  *
  65  */
  66 void nm_contact_add_ref(NMContact * contact);
  67
  68 /**
  69  * Update the contact list properties of the contact (sequence, parent id, etc.)
  70  *
  71  * @param       contact The contact to update
  72  * @param       fields  The fields to update from (should be a NM_A_FA_CONTACT array)
  73  *
  74  */
  75 void nm_contact_update_list_properties(NMContact * contact, NMField * fields);
  76
  77 /**
  78  * Release a contact reference
  79  *
  80  * @param       contact The contact to release.
  81  *
  82  */
  83 void nm_release_contact(NMContact * contact);
  84
  85 /**
  86  * Get the display name of a contact
  87  *
  88  * @param       contact The contact
  89  *
  90  * @return      The display name of a contact
  91  *
  92  */
  93 const char *nm_contact_get_display_name(NMContact * contact);
  94
  95 /**
  96  * Get the DN of a contact
  97  *
  98  * @param       contact The contact
  99  *
 100  * @return      The DN of the contact
 101  */
 102 const char *nm_contact_get_dn(NMContact * contact);
 103
 104 /**
 105  * Set the display name for a contact. This is called
 106  * by nm_send_rename_contact. It should not be called
 107  * directly (it does not change the display name on the
 108  * server side list -- nm_send_rename_conact does).
 109  *
 110  * @param       contact                 The contact
 111  * @param       display_name    The new display name
 112  *
 113  */
 114 void nm_contact_set_display_name(NMContact * contact, const char * display_name);
 115
 116 /**
 117  * Set the DN for the contact
 118  *
 119  * @param       contact The contact
 120  * @param       dn              The new DN for the contact
 121  *
 122  */
 123 void nm_contact_set_dn(NMContact * contact, const char * dn);
 124
 125 /**
 126  * Return a field array (NM_A_FA_CONTACT) representing the contact
 127  *
 128  * @param       contact The contact
 129  *
 130  * @return      A field array representing the contact
 131  */
 132 NMField *nm_contact_to_fields(NMContact * contact);
 133
 134 /**
 135  * Set the user record for the contact
 136  *
 137  * @param       contact                 The contact
 138  * @param       user_record             The user record
 139  *
 140  */
 141 void nm_contact_set_user_record(NMContact * contact, NMUserRecord * user_record);
 142
 143 /**
 144  * Get the user record for the contact
 145  *
 146  * @param       contact The contact
 147  *
 148  * @return      The user record associated with the contact
 149  *
 150  */
 151 NMUserRecord *nm_contact_get_user_record(NMContact * contact);
 152
 153 /**
 154  * Get the user defined data for the contact
 155  *
 156  * @param       contact The contact
 157  *
 158  * @return      The user defined data for the contact
 159  *
 160  */
 161 gpointer nm_contact_get_data(NMContact * contact);
 162
 163 /**
 164  * Get the Object ID for the contact
 165  *
 166  * @param       contact The contact
 167  *
 168  * @return      The ID for the contact
 169  */
 170 int nm_contact_get_id(NMContact * contact);
 171
 172 /**
 173  * Get the ID for the folder that the contact is in
 174  *
 175  * @param       contact The contact
 176  *
 177  * @return      The ID of the folder that contains the contact
 178  *
 179  */
 180 int nm_contact_get_parent_id(NMContact * contact);
 181
 182 /**
 183  * Get The userid of the contact.
 184  *
 185  * @param       contact The contact
 186  *
 187  * @return      The userid of the contact
 188  *
 189  */
 190 const char *nm_contact_get_userid(NMContact * contact);
 191
 192 /**
 193  * Get the display id of the contact
 194  *
 195  * @param       contact The contact
 196  *
 197  * @return      The display id of the contact
 198  */
 199 const char *nm_contact_get_display_id(NMContact * contact);
 200
 201 /**
 202  * Set the user defined data for the contact
 203  *
 204  * @param       contact The contact
 205  * @param       data    The user defined data
 206  *
 207  */
 208 void nm_contact_set_data(NMContact * contact, gpointer data);
 209
 210 /**
 211  * Create a folder with the given name
 212  *
 213  * @param       name    The name of the folder
 214  *
 215  * @return      The new folder
 216  *
 217  */
 218 NMFolder *nm_create_folder(const char *name);
 219
 220 /**
 221  * Create a folder from a NM_A_FA_FOLDER field array
 222  *
 223  * @param       fields  The NM_A_FA_FOLDER field array
 224  *
 225  * @return      The new folder
 226  *
 227  */
 228 NMFolder *nm_create_folder_from_fields(NMField * fields);
 229
 230 /**
 231  * Add a reference to an existing folder
 232  *
 233  * The reference should be released by calling
 234  * nm_release_folder
 235  *
 236  * @param       folder  The folder
 237  *
 238  */
 239 void nm_folder_add_ref(NMFolder * folder);
 240
 241 /**
 242  * Release a reference to a folder.
 243  *
 244  * @param       folder  The folder to release
 245  *
 246  */
 247 void nm_release_folder(NMFolder * folder);
 248
 249 /**
 250  * Return the number of subfolders for the given
 251  * folder
 252  *
 253  * @param       folder  The folder
 254  *
 255  * @return      The number of subfolders contained by folder
 256  */
 257 int nm_folder_get_subfolder_count(NMFolder * folder);
 258
 259 /**
 260  * Get a subfolder
 261  *
 262  * @param       folder  The root folder
 263  * @param       index   The index of the folder to get
 264  *
 265  * @return      The subfolder at the given index
 266  *
 267  */
 268 NMFolder *nm_folder_get_subfolder(NMFolder * folder, int index);
 269
 270 /**
 271  * Get the number of contacts in the given folder
 272  *
 273  * @param       folder  The folder
 274  *
 275  * @return      The number of contacts contained by folder
 276  *
 277  */
 278 int nm_folder_get_contact_count(NMFolder * folder);
 279
 280 /**
 281  * Get a contact in the given folder
 282  *
 283  * @param       folder  The folder
 284  * @param       index   The index of the contact to get
 285  *
 286  * @return      The contact at the given index
 287  *
 288  */
 289 NMContact *nm_folder_get_contact(NMFolder * folder, int index);
 290
 291 /**
 292  * Get the name of the folder
 293  *
 294  * @param       folder  The folder
 295  *
 296  * @return      The name of the folder.
 297  *
 298  */
 299 const char *nm_folder_get_name(NMFolder * folder);
 300
 301 /**
 302  * Set the name of a folder. Do not call this directly.
 303  * It does not change the name of the folder in the
 304  * server side contact list. You must call
 305  * nm_send_set_folder_name().
 306  *
 307  * @param       folder  The folder
 308  * @param       name    The new name for the folder
 309  *
 310  */
 311 void nm_folder_set_name(NMFolder * folder, const char *name);
 312
 313 /**
 314  * Get Object ID for folder
 315  *
 316  * @param       folder  The folder
 317  *
 318  * @return      The ID of the folder
 319  *
 320  */
 321 int nm_folder_get_id(NMFolder * folder);
 322
 323 /**
 324  * Add contacts and folders from fields into root
 325  *
 326  * @param       user    The logged in user
 327  * @param       root    The root folder
 328  * @param       fields  The contact list field array
 329  *
 330  */
 331 void nm_folder_add_contacts_and_folders(NMUser * user, NMFolder * root,
 332                                                                                 NMField * fields);
 333 /**
 334  * Add a contact to the contact list.
 335  *
 336  * @param       root_folder     The root folder of the contact list
 337  * @param       contact         The contact to add
 338  *
 339  */
 340 void nm_folder_add_contact_to_list(NMFolder * root_folder,
 341                                                                           NMContact * contact);
 342
 343 /**
 344  * Update the contact list properties of the folder (sequence, parent id, etc.)
 345  *
 346  * @param       folder  The folder to update
 347  * @param       fields  The fields to update from (should be a NM_A_FA_FOLDER array)
 348  *
 349  */
 350 void nm_folder_update_list_properties(NMFolder * folder, NMField * fields);
 351
 352 /**
 353  * Add folder to the contact list
 354  *
 355  * @param       root_folder     The root folder of the contact list
 356  * @param       folder          The folder to add to the contact list
 357  *
 358  */
 359 void nm_folder_add_folder_to_list(NMFolder * root_folder, NMFolder * folder);
 360
 361 /**
 362  * Find the object with the given id
 363  *
 364  * @param       root_folder     The root folder of the contact list
 365  * @param       object_id       The object id of the object to find
 366  *
 367  * @return      The object with object id (either a contact or a folder)
 368  */
 369 gpointer nm_folder_find_item_by_object_id(NMFolder * root_folder,
 370                                                                                   int object_id);
 371
 372 /**
 373  * Remove a contact from the folder
 374  *
 375  * @param       folder  The folder
 376  * @param       contact The contact to remove
 377  *
 378  */
 379 void nm_folder_remove_contact(NMFolder * folder, NMContact * contact);
 380
 381 /**
 382  * Find a contact in a folder by DN
 383  *
 384  * @param       folder  The folder to search
 385  * @param       dn              The DN of the contact to find
 386  *
 387  * @return      The contact if found, NULL otherwise
 388  *
 389  */
 390 NMContact *nm_folder_find_contact(NMFolder * folder, const char *dn);
 391
 392 /**
 393  * Find a contact in a folder by userid
 394  *
 395  * @param       folder  The folder to search
 396  * @param       userid  The userid of the contact to find
 397  *
 398  * @return      The contact if found, NULL otherwise
 399  *
 400  */
 401 NMContact *nm_folder_find_contact_by_userid(NMFolder * folder,
 402                                                                                         const char *userid);
 403
 404 /**
 405  * Find a contact in a folder by display id
 406  *
 407  * @param       folder          The folder to search
 408  * @param       display_id      The userid of the contact to find
 409  *
 410  * @return      The contact if found, NULL otherwise
 411  *
 412  */
 413 NMContact *
 414 nm_folder_find_contact_by_display_id(NMFolder * folder, const char *display_id);
 415
 416 /**
 417  * Return a field array (NM_A_FA_FOLDER) representing the folder
 418  *
 419  * @param       folder  The folder
 420  *
 421  * @return      A field array representing the folder
 422  */
 423 NMField *nm_folder_to_fields(NMFolder * folder);
 424
 425 #endif /* PURPLE_NOVELL_NMCONTACT_H */