r_contact.h

Go to the documentation of this file.
00001 ///
00002 /// \file       r_contact.h
00003 ///             Blackberry database record parser class for contact records.
00004 ///
00005 
00006 /*
00007     Copyright (C) 2005-2012, Net Direct Inc. (http://www.netdirect.ca/)
00008 
00009     This program is free software; you can redistribute it and/or modify
00010     it under the terms of the GNU General Public License as published by
00011     the Free Software Foundation; either version 2 of the License, or
00012     (at your option) any later version.
00013 
00014     This program is distributed in the hope that it will be useful,
00015     but WITHOUT ANY WARRANTY; without even the implied warranty of
00016     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
00017 
00018     See the GNU General Public License in the COPYING file at the
00019     root directory of this project for more details.
00020 */
00021 
00022 #ifndef __BARRY_RECORD_CONTACT_H__
00023 #define __BARRY_RECORD_CONTACT_H__
00024 
00025 #include "dll.h"
00026 #include "record.h"
00027 #include <iosfwd>
00028 #include <string>
00029 #include <vector>
00030 #include <map>
00031 #include <stdint.h>
00032 
00033 namespace Barry {
00034 
00035 // forward declarations
00036 class IConverter;
00037 
00038 //
00039 // NOTE:  All classes here must be container-safe!  Perhaps add sorting
00040 //        operators in the future.
00041 //
00042 
00043 struct BXEXPORT ContactGroupLink
00044 {
00045         uint32_t Link;
00046         uint16_t Unknown;
00047 
00048         ContactGroupLink() : Link(0), Unknown(0) {}
00049         ContactGroupLink(uint32_t link, uint16_t unknown)
00050                 : Link(link), Unknown(unknown)
00051         {}
00052 };
00053 
00054 /// \addtogroup RecordParserClasses
00055 /// @{
00056 
00057 //
00058 // Contact record class
00059 //
00060 /// Represents a single record in the Address Book Blackberry database.
00061 ///
00062 class BXEXPORT Contact
00063 {
00064 public:
00065         typedef Barry::CategoryList                     CategoryList;
00066         typedef ContactGroupLink                        GroupLink;
00067         typedef std::vector<GroupLink>                  GroupLinksType;
00068         typedef Barry::UnknownsType                     UnknownsType;
00069         typedef Barry::EmailType                        EmailType;
00070         typedef Barry::EmailList                        EmailList;
00071 
00072         //
00073         // Record fields
00074         //
00075 
00076         // contact specific data
00077         uint8_t RecType;
00078         uint32_t RecordId;
00079         EmailList EmailAddresses;
00080 
00081         /// This field, Phone, is deprecated.  It is possible
00082         /// to write to this field to the Blackberry,
00083         /// but modern devices won't let you add it
00084         /// through their GUIs.  This field only seems
00085         /// to exist on the 7750.  While other devices
00086         /// accept the field and display it, it is
00087         /// not accessible by default.
00088         std::string Phone;
00089 
00090         std::string
00091                 Fax,
00092                 HomeFax,
00093                 WorkPhone,
00094                 HomePhone,
00095                 MobilePhone,
00096                 MobilePhone2,
00097                 Pager,
00098                 PIN,
00099                 Radio,
00100                 WorkPhone2,
00101                 HomePhone2,
00102                 OtherPhone,
00103                 FirstName,
00104                 LastName,
00105                 Company,
00106                 DefaultCommunicationsMethod,
00107                 JobTitle,
00108                 PublicKey,
00109                 URL,
00110                 Prefix,
00111                 Notes,
00112                 UserDefined1,
00113                 UserDefined2,
00114                 UserDefined3,
00115                 UserDefined4,
00116                 Image,
00117                 Nickname;
00118 
00119         Date Birthday;
00120         Date Anniversary;
00121 
00122         PostalAddress WorkAddress;
00123         PostalAddress HomeAddress;
00124 
00125         // Categories are not allowed to have commas in them.
00126         // A category name containing a comma will be split into
00127         // two categories, not only by this library, but by the
00128         // device itself.
00129         CategoryList Categories;
00130 
00131         GroupLinksType GroupLinks;
00132         UnknownsType Unknowns;
00133 
00134 private:
00135         bool m_FirstNameSeen;
00136 
00137 public:
00138         const unsigned char* ParseField(const unsigned char *begin,
00139                 const unsigned char *end, const IConverter *ic = 0);
00140 
00141 public:
00142         Contact();
00143         ~Contact();
00144 
00145         uint32_t GetID() const { return RecordId; }
00146         std::string GetFullName() const;
00147         const std::string& GetEmail(unsigned int index = 0) const;
00148 
00149         // Parser / Builder API (see parser.h / builder.h)
00150         void Validate() const;
00151         uint8_t GetRecType() const { return RecType; }
00152         uint32_t GetUniqueId() const { return RecordId; }
00153         void SetIds(uint8_t Type, uint32_t Id) { RecType = Type; RecordId = Id; }
00154         void ParseHeader(const Data &data, size_t &offset);
00155         void ParseFields(const Data &data, size_t &offset, const IConverter *ic = 0);
00156         void BuildHeader(Data &data, size_t &offset) const;
00157         void BuildFields(Data &data, size_t &offset, const IConverter *ic = 0) const;
00158 
00159         // operations (common among record classes)
00160         void Clear();                   // erase everything
00161         void Dump(std::ostream &os) const;
00162         std::string GetDescription() const;
00163 
00164         // Sorting - use enough data to make the sorting as
00165         //           consistent as possible
00166         bool operator<(const Contact &other) const;
00167 
00168         // database name
00169         static const char * GetDBName() { return "Address Book"; }
00170         static uint8_t GetDefaultRecType() { return 0; }
00171 
00172         // helpers
00173         static void SplitName(const std::string &full, std::string &first, std::string &last);
00174         static std::string Email2CommaString(const EmailList &list);
00175         static void CommaString2Email(const std::string &list, EmailList &result);
00176 
00177         // Generic Field Handle support
00178         static const FieldHandle<Contact>::ListT& GetFieldHandles();
00179 };
00180 
00181 BXEXPORT inline std::ostream& operator<< (std::ostream &os, const Contact &contact) {
00182         contact.Dump(os);
00183         return os;
00184 }
00185 
00186 /// @}
00187 
00188 } // namespace Barry
00189 
00190 #endif
00191