include/gammu-memory.h

   1 /**
   2  * \file gammu-memory.h
   3  * \author Michal Čihař
   4  *
   5  * Memory data and functions.
   6  */
   7 #ifndef __gammu_memory_h
   8 #define __gammu_memory_h
   9
  10 /**
  11  * \defgroup Memory Memory
  12  * Memory entries manipulations.
  13  */
  14
  15 #include <gammu-datetime.h>
  16 #include <gammu-limits.h>
  17 #include <gammu-bitmap.h>
  18 #include <gammu-debug.h>
  19
  20 /**
  21  * Enum defines ID for various phone and SIM memories.
  22  * Phone modules can translate them to values specific for concrete models.
  23  * Two letter codes (excluding VM and SL) are from GSM 07.07.
  24  *
  25  * \ingroup Memory
  26  */
  27 typedef enum {
  28         /**
  29          * Internal memory of the mobile equipment
  30          */
  31         MEM_ME = 1,
  32         /**
  33          * SIM card memory
  34          */
  35         MEM_SM,
  36         /**
  37          * Own numbers
  38          */
  39         MEM_ON,
  40         /**
  41          * Dialled calls
  42          */
  43         MEM_DC,
  44         /**
  45          * Received calls
  46          */
  47         MEM_RC,
  48         /**
  49          * Missed calls
  50          */
  51         MEM_MC,
  52         /**
  53          * Combined ME and SIM phonebook
  54          */
  55         MEM_MT,
  56         /**
  57          * Fixed dial
  58          */
  59         MEM_FD,
  60
  61         /**
  62          * Voice mailbox
  63          */
  64         MEM_VM,
  65
  66         /**
  67          * Sent SMS logs
  68          */
  69         MEM_SL,
  70
  71         /**
  72          * Quick dialing choices.
  73          */
  74         MEM_QD
  75 } GSM_MemoryType;
  76
  77 /**
  78  * Returns string representation of a memory type.
  79  *
  80  * \param x Memory type to convert
  81  *
  82  * \return Static string.
  83  *
  84  * \ingroup Memory
  85  */
  86 #define GSM_MemoryTypeToString(x) \
  87         ((x) == MEM_ME ? "ME" : \
  88         ((x) == MEM_SM ? "SM" : \
  89         ((x) == MEM_ON ? "ON" : \
  90         ((x) == MEM_DC ? "DC" : \
  91         ((x) == MEM_RC ? "RC" : \
  92         ((x) == MEM_MC ? "MC" : \
  93         ((x) == MEM_MT ? "MT" : \
  94         ((x) == MEM_FD ? "FD" : \
  95         ((x) == MEM_VM ? "VM" : \
  96         ((x) == MEM_QD ? "QD" : \
  97         ((x) == MEM_SL ? "SL" : "XX")))))))))))
  98
  99 /**
 100  * Converts memory type from string.
 101  *
 102  * \param s String with memory type.
 103  *
 104  * \return Parsed memory type or 0 on failure.
 105  */
 106 GSM_MemoryType GSM_StringToMemoryType(const char *s);
 107
 108 /**
 109  * Structure contains info about number of used/free entries in phonebook
 110  * memory.
 111  *
 112  * \ingroup Memory
 113  */
 114 typedef struct {
 115         /**
 116          * Number of used entries
 117          */
 118         int MemoryUsed;
 119         /**
 120          * Memory type
 121          */
 122         GSM_MemoryType MemoryType;
 123         /**
 124          * Number of free entries
 125          */
 126         int MemoryFree;
 127 } GSM_MemoryStatus;
 128
 129 /**
 130  * Type of specific phonebook entry. In parenthesis is specified in which
 131  * member of @ref GSM_SubMemoryEntry value is stored.
 132  *
 133  * \ingroup Memory
 134  */
 135 typedef enum {
 136         /**
 137          * General number. (Text)
 138          */
 139         PBK_Number_General = 1,
 140         /**
 141          * Mobile number. (Text)
 142          */
 143         PBK_Number_Mobile,
 144         /**
 145          * Fax number. (Text)
 146          */
 147         PBK_Number_Fax,
 148         /**
 149          * Pager number. (Text)
 150          */
 151         PBK_Number_Pager,
 152         /**
 153          * Other number. (Text)
 154          */
 155         PBK_Number_Other,
 156         /**
 157          * Note. (Text)
 158          */
 159         PBK_Text_Note,
 160         /**
 161          * Complete postal address. (Text)
 162          */
 163         PBK_Text_Postal,
 164         /**
 165          * Email. (Text)
 166          */
 167         PBK_Text_Email,
 168         /*
 169          * Second email. (Text)
 170          */
 171         PBK_Text_Email2,
 172         /**
 173          * URL (Text)
 174          */
 175         PBK_Text_URL,
 176         /**
 177          * Date and time of last call. (Date)
 178          */
 179         PBK_Date,
 180         /**
 181          * Caller group. (Number)
 182          */
 183         PBK_Caller_Group,
 184         /**
 185          * Name (Text)
 186          */
 187         PBK_Text_Name,
 188         /**
 189          * Last name. (Text)
 190          */
 191         PBK_Text_LastName,
 192         /**
 193          * First name. (Text)
 194          */
 195         PBK_Text_FirstName,
 196         /**
 197          * Company. (Text)
 198          */
 199         PBK_Text_Company,
 200         /**
 201          * Job title. (Text)
 202          */
 203         PBK_Text_JobTitle,
 204         /**
 205          * Category. (Number, if -1 then text)
 206          */
 207         PBK_Category,
 208         /**
 209          * Whether entry is private. (Number)
 210          */
 211         PBK_Private,
 212         /**
 213          * Street address. (Text)
 214          */
 215         PBK_Text_StreetAddress,
 216         /**
 217          * City. (Text)
 218          */
 219         PBK_Text_City,
 220         /**
 221          * State. (Text)
 222          */
 223         PBK_Text_State,
 224         /**
 225          * Zip code. (Text)
 226          */
 227         PBK_Text_Zip,
 228         /**
 229          * Country. (Text)
 230          */
 231         PBK_Text_Country,
 232         /**
 233          * Custom information 1. (Text)
 234          */
 235         PBK_Text_Custom1,
 236         /**
 237          * Custom information 2. (Text)
 238          */
 239         PBK_Text_Custom2,
 240         /**
 241          * Custom information 3. (Text)
 242          */
 243         PBK_Text_Custom3,
 244         /**
 245          * Custom information 4. (Text)
 246          */
 247         PBK_Text_Custom4,
 248         /**
 249          * Ringtone ID. (Number)
 250          */
 251         PBK_RingtoneID,
 252         /**
 253          * Picture ID. (Number)
 254          */
 255         PBK_PictureID,
 256         /**
 257          * User ID. (Text)
 258          */
 259         PBK_Text_UserID,
 260         /**
 261          * Length of call (Number)
 262          */
 263         PBK_CallLength,
 264         /**
 265          * LUID - Unique Identifier used for synchronisation (Text)
 266          */
 267         PBK_Text_LUID,
 268         /**
 269          * Date of last modification (Date)
 270          */
 271         PBK_LastModified,
 272         /**
 273          * Nick name (Text)
 274          */
 275         PBK_Text_NickName,
 276         /**
 277          * Formal name (Text)
 278          */
 279         PBK_Text_FormalName,
 280         /**
 281          * Picture name (on phone filesystem). (Text)
 282          */
 283         PBK_Text_PictureName,
 284         /**
 285          * Push-to-talk ID (Text)
 286          */
 287         PBK_PushToTalkID,
 288         /**
 289          * Favorite messaging number. (Text)
 290          */
 291         PBK_Number_Messaging,
 292         /**
 293          * Photo (Picture).
 294          */
 295         PBK_Photo,
 296         /**
 297          * Second name. (Text)
 298          */
 299         PBK_Text_SecondName,
 300         /**
 301          * VOIP address (Text).
 302          */
 303         PBK_Text_VOIP,
 304         /**
 305          * SIP address (Text).
 306          */
 307         PBK_Text_SIP,
 308         /**
 309          * DTMF (Text).
 310          */
 311         PBK_Text_DTMF,
 312         /**
 313          * Video number. (Text)
 314          */
 315         PBK_Number_Video,
 316         /**
 317          * See What I See address. (Text)
 318          */
 319         PBK_Text_SWIS,
 320         /**
 321          * Wireless Village user ID. (Text)
 322          */
 323         PBK_Text_WVID,
 324         /**
 325          * Name prefix (Text)
 326          */
 327         PBK_Text_NamePrefix,
 328         /**
 329          * Name suffix (Text)
 330          */
 331         PBK_Text_NameSuffix,
 332 } GSM_EntryType;
 333
 334 /**
 335  * Location of memory contact.
 336  *
 337  * \ingroup Memory
 338  */
 339 typedef enum {
 340         /**
 341          * No/Unknown location.
 342          */
 343         PBK_Location_Unknown = 0,
 344         /**
 345          * Home
 346          */
 347         PBK_Location_Home,
 348         /**
 349          * Work
 350          */
 351         PBK_Location_Work,
 352 } GSM_EntryLocation;
 353
 354 /**
 355  * One value of phonebook memory entry.
 356  *
 357  * \ingroup Memory
 358  */
 359 typedef struct {
 360         /**
 361          * Type of entry.
 362          */
 363         GSM_EntryType EntryType;
 364         /**
 365          * Location for the entry.
 366          */
 367         GSM_EntryLocation Location;
 368         /**
 369          * Text of entry (if applicable, see @ref GSM_EntryType).
 370          */
 371         GSM_DateTime Date;
 372         /**
 373          * Number of entry (if applicable, see @ref GSM_EntryType).
 374          */
 375         int Number;
 376         /**
 377          * Voice dialling tag.
 378          */
 379         int VoiceTag;
 380         int SMSList[20];
 381         int CallLength;
 382
 383         /**
 384          * During adding SubEntry Gammu can return here info, if it was done OK
 385          */
 386         GSM_Error AddError;
 387         /**
 388          * Text of entry (if applicable, see @ref GSM_EntryType).
 389          */
 390         unsigned char Text[(GSM_PHONEBOOK_TEXT_LENGTH + 1) * 2];
 391         /**
 392          * Picture data.
 393          */
 394         GSM_BinaryPicture Picture;
 395 } GSM_SubMemoryEntry;
 396
 397 /**
 398  * Structure for saving phonebook entries.
 399  *
 400  * \ingroup Memory
 401  */
 402 typedef struct {
 403         /**
 404          * Used memory for phonebook entry
 405          */
 406         GSM_MemoryType MemoryType;
 407         /**
 408          * Used location for phonebook entry
 409          */
 410         int Location;
 411         /**
 412          * Number of SubEntries in Entries table.
 413          */
 414         int EntriesNum;
 415         /**
 416          * Values of SubEntries.
 417          */
 418         GSM_SubMemoryEntry Entries[GSM_PHONEBOOK_ENTRIES];
 419 } GSM_MemoryEntry;
 420
 421 /**
 422  * Structure for saving speed dials.
 423  *
 424  * \ingroup Memory
 425  */
 426 typedef struct {
 427         /**
 428          * Number of speed dial: 2,3..,8,9
 429          */
 430         int Location;
 431         /**
 432          * ID of phone number used in phonebook entry
 433          */
 434         int MemoryNumberID;
 435         /**
 436          * Memory, where is saved used phonebook entry
 437          */
 438         GSM_MemoryType MemoryType;
 439         /**
 440          * Location in memory, where is saved used phonebook entry
 441          */
 442         int MemoryLocation;
 443 } GSM_SpeedDial;
 444
 445 /**
 446  * Gets memory (phonebooks or calls) status (eg. number of used and
 447  * free entries).
 448  *
 449  * \param s State machine pointer.
 450  * \param status Storage for status information, MemoryType has to be
 451  * set.
 452  *
 453  * \return Error code.
 454  *
 455  * \ingroup Memory
 456  */
 457 GSM_Error GSM_GetMemoryStatus(GSM_StateMachine * s, GSM_MemoryStatus * status);
 458
 459 /**
 460  * Reads entry from memory (phonebooks or calls). Which entry should
 461  * be read is defined in entry.
 462  *
 463  * \param s State machine pointer.
 464  * \param entry Storage for retrieved entry, MemoryType and Location has
 465  * to be set.
 466  *
 467  * \return Error code.
 468  *
 469  * \ingroup Memory
 470  */
 471 GSM_Error GSM_GetMemory(GSM_StateMachine * s, GSM_MemoryEntry * entry);
 472
 473 /**
 474  * Reads entry from memory (phonebooks or calls). Which entry should
 475  * be read is defined in entry. This can be easily used for reading all entries.
 476  *
 477  * \param s State machine pointer.
 478  * \param entry Storage for retrieved entry. MemoryType has to be set
 479  * for first call (with start set to TRUE), for subsequent calls
 480  * Location has to stay intact from previous reading.
 481  * \param start Whether we should start from beginning.
 482  *
 483  * \return Error code.
 484  *
 485  * \ingroup Memory
 486  */
 487 GSM_Error GSM_GetNextMemory(GSM_StateMachine * s, GSM_MemoryEntry * entry,
 488                             gboolean start);
 489
 490 /**
 491  * Sets memory (phonebooks or calls) entry.
 492  *
 493  * \param s State machine pointer.
 494  * \param entry Entry to set, Location and MemoryType has to be set.
 495  *
 496  * \return Error code.
 497  *
 498  * \ingroup Memory
 499  */
 500 GSM_Error GSM_SetMemory(GSM_StateMachine * s, GSM_MemoryEntry * entry);
 501
 502 /**
 503  * Adds memory (phonebooks or calls) entry.
 504  *
 505  * \param s State machine pointer.
 506  * \param entry Entry to add, Location is ignored, MemoryType has to be
 507  * set.
 508  *
 509  * \return Error code.
 510  *
 511  * \ingroup Memory
 512  */
 513 GSM_Error GSM_AddMemory(GSM_StateMachine * s, GSM_MemoryEntry * entry);
 514
 515 /**
 516  * Deletes memory (phonebooks or calls) entry.
 517  *
 518  * \param s State machine pointer.
 519  * \param entry Entry to delete, Location and MemoryType has to be set.
 520  *
 521  * \return Error code.
 522  *
 523  * \ingroup Memory
 524  */
 525 GSM_Error GSM_DeleteMemory(GSM_StateMachine * s, GSM_MemoryEntry * entry);
 526
 527 /**
 528  * Deletes all memory (phonebooks or calls) entries of specified type.
 529  *
 530  * \param s State machine pointer.
 531  * \param MemoryType Where to delete all entries.
 532  *
 533  * \return Error code.
 534  *
 535  * \ingroup Memory
 536  */
 537 GSM_Error GSM_DeleteAllMemory(GSM_StateMachine * s, GSM_MemoryType MemoryType);
 538
 539 /**
 540  * Gets speed dial.
 541  *
 542  * \param s State machine pointer.
 543  * \param Speed Storage for speed dial, Location has to be set.
 544  *
 545  * \return Error code.
 546  *
 547  * \ingroup Memory
 548  */
 549 GSM_Error GSM_GetSpeedDial(GSM_StateMachine * s, GSM_SpeedDial * Speed);
 550
 551 /**
 552  * Sets speed dial.
 553  *
 554  * \param s State machine pointer.
 555  * \param Speed Sspeed dial to set.
 556  *
 557  * \return Error code.
 558  *
 559  * \ingroup Memory
 560  */
 561 GSM_Error GSM_SetSpeedDial(GSM_StateMachine * s, GSM_SpeedDial * Speed);
 562
 563 /**
 564  * Returns name of entry. It might be possibly concatenated from first
 565  * and last names.
 566  *
 567  * \param entry Entry to process.
 568  *
 569  * \return Static unicode string containing name.
 570  *
 571  * \ingroup Memory
 572  */
 573 unsigned char *GSM_PhonebookGetEntryName(const GSM_MemoryEntry * entry);
 574
 575 /**
 576  * Finds default name, number and group for entry.
 577  *
 578  * \param entry Entry to process.
 579  * \param Name Output index of name.
 580  * \param Number Output index of number.
 581  * \param Group Output index of group.
 582  *
 583  * \ingroup Memory
 584  */
 585 void GSM_PhonebookFindDefaultNameNumberGroup(const GSM_MemoryEntry * entry,
 586                                              int *Name, int *Number,
 587                                              int *Group);
 588 /**
 589  * Types of vCard.
 590  *
 591  * \ingroup Memory
 592  */
 593 typedef enum {
 594         /**
 595          * vCard 1.0 hacked for Nokia.
 596          */
 597         Nokia_VCard10 = 1,
 598         /**
 599          * vCard 2.1 hacked for Nokia.
 600          */
 601         Nokia_VCard21,
 602         /**
 603          * vCard 1.0 hacked for Sony-Ericsson (should be standard
 604          * vCard).
 605          */
 606         SonyEricsson_VCard10,
 607         /**
 608          * vCard 2.1 hacked for Sony-Ericsson (should be standard
 609          * vCard).
 610          */
 611         SonyEricsson_VCard21,
 612         /**
 613          * vCard 2.1 hacked for Sony-Ericsson (should be standard
 614          * vCard) from phone (no parsing of location and memory type).
 615          */
 616         SonyEricsson_VCard21_Phone,
 617 } GSM_VCardVersion;
 618
 619 /**
 620  * Encodes memory entry to vCard.
 621  *
 622  * \param di Pointer to debugging description.
 623  * \param[out] Buffer Buffer to store vCard text.
 624  * \param[in] buff_len Size of output buffer.
 625  * \param[in,out] Pos Position in output buffer.
 626  * \param[in,out] pbk Phonebook data, AddError will be set on non
 627  * converted entries.
 628  * \param[in] header Whether to include vCard header in output.
 629  * \param[in] Version What vCard version to create.
 630  *
 631  * \return Error code.
 632  *
 633  * \ingroup Memory
 634  */
 635 GSM_Error GSM_EncodeVCARD(GSM_Debug_Info * di, char *Buffer,
 636                           const size_t buff_len, size_t * Pos,
 637                           GSM_MemoryEntry * pbk, const gboolean header,
 638                           const GSM_VCardVersion Version);
 639
 640 /**
 641  * Decodes memory entry from vCard.
 642  *
 643  * \param di Pointer to debugging description.
 644  * \param[in] Buffer Buffer to readCard text.
 645  * \param[in,out] Pos Position in output buffer.
 646  * \param[out] Pbk Phonebook data read from vCard.
 647  * \param[in] Version What vCard version to parse.
 648  *
 649  * \return Error code.
 650  *
 651  * \ingroup Memory
 652  */
 653 GSM_Error GSM_DecodeVCARD(GSM_Debug_Info * di, char *Buffer, size_t * Pos,
 654                           GSM_MemoryEntry * Pbk,
 655                           const GSM_VCardVersion Version);
 656
 657 /**
 658  * Frees any dynamically allocated memory inside memory
 659  * entry structure.
 660  *
 661  * \param[in] Entry Pointer to memory entry to process.
 662  */
 663 void GSM_FreeMemoryEntry(GSM_MemoryEntry * Entry);
 664 #endif
 665
 666 /* Editor configuration
 667  * vim: noexpandtab sw=8 ts=8 sts=8 tw=72:
 668  */