/core/externals/update-engine/externals/google-toolbox-for-mac/AddressBook/GTMABAddressBook.h

http://macfuse.googlecode.com/ · C++ Header · 425 lines · 173 code · 77 blank · 175 comment · 0 complexity · da666c90e6ff73196774e84ad3b90de1 MD5 · raw file

  1. //
  2. // GTMABAddressBook.h
  3. //
  4. // Copyright 2008 Google Inc.
  5. //
  6. // Licensed under the Apache License, Version 2.0 (the "License"); you may not
  7. // use this file except in compliance with the License. You may obtain a copy
  8. // of the License at
  9. //
  10. // http://www.apache.org/licenses/LICENSE-2.0
  11. //
  12. // Unless required by applicable law or agreed to in writing, software
  13. // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  14. // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  15. // License for the specific language governing permissions and limitations under
  16. // the License.
  17. //
  18. // These classes wrap up the iPhone AddressBook 'C' API in a manner very
  19. // similar to that found on Mac OS X. They differ only in that none of these
  20. // routines throws, and some of the types are different as necessitated by
  21. // the APIs that they wrap. These wrappers also protect you from a number
  22. // of issues in the AddressBook API (as of iPhone SDK 2.0/2.1)
  23. //
  24. // Note that there is a strings file that you may want to localize
  25. // (GTMABAddressBook.strings).
  26. //
  27. // If things seem strange, it may be due to one of the following radars:
  28. // 6240394 AddressBook framework constants not initialized until
  29. // ABCreateAddressBook called
  30. // -- CLOSED as designed
  31. // 6208390 Integer and real values don't work in ABMultiValueRefs
  32. // (and this isn't part of the title, but dictionaries don't work
  33. // either)
  34. // 6207605 RecordIDs for people and groups are not unique in AddressBook
  35. // -- CLOSED as designed
  36. // 6204021 kABGroupNameProperty and kABPersonFirstNameProperty have the same
  37. // value
  38. // 6203982 ABPersonCopyLocalizedPropertyName returns name for
  39. // kABGroupNameProperty
  40. // 6203961 ABPersonGetTypeOfProperty returns a type for kABGroupNameProperty
  41. // 6203854 ABMultiValues hash to their address
  42. // 6203836 ABRecords hash to their address
  43. // -- CLOSED behaves correctly
  44. // 6203606 Need CFTypeIDs for AddressBook CFTypes
  45. // 6202868 ABPersonSetImageData should validate image data
  46. // 6202860 Passing nil person into ABGroupAddMember crashes
  47. // -- CLOSED behaves correctly
  48. // 6202827 Passing nil info ABMultiValueAddValueAndLabel causes crash
  49. // -- CLOSED behaves correctly
  50. // 6202807 ABMultiValueInsertValueAndLabelAtIndex allows you to insert values
  51. // past end
  52. // 6201276 Removing a NULL record using ABAddressBookRemoveRecord crashes
  53. // -- CLOSED behaves correctly
  54. // 6201258 Adding a NULL record using ABAddressBookAddRecord crashes
  55. // -- CLOSED behaves correctly
  56. // 6201046 ABRecordSetValue returns true even if you pass in a bad type for a
  57. // value
  58. // 6201005 ABRecordRemoveValue returns true for value that aren't in the record
  59. // -- CLOSED behaves correctly
  60. // 6200703 ABAddressBookAddRecord doesn't add an item to the people array until
  61. // it's saved
  62. // 6200638 ABAddressBookHasUnsavedChanges doesn't work
  63. // -- CLOSED fixed in iOS 3.2
  64. #import "GTMDefines.h"
  65. #import <Foundation/Foundation.h>
  66. #if GTM_IPHONE_SDK
  67. #import <AddressBook/AddressBook.h>
  68. @class UIImage;
  69. #else // GTM_IPHONE_SDK
  70. #import <AddressBook/AddressBook.h>
  71. #import <AddressBook/ABAddressBookC.h>
  72. @class NSImage;
  73. #endif // GTM_IPHONE_SDK
  74. @class GTMABPerson;
  75. @class GTMABGroup;
  76. @class GTMABRecord;
  77. GTM_EXTERN NSString *const kGTMABUnknownPropertyName;
  78. #if GTM_IPHONE_SDK
  79. @class UIImage;
  80. typedef ABRecordID GTMABRecordID;
  81. typedef ABPropertyID GTMABPropertyID;
  82. typedef UIImage GTMABImage;
  83. typedef ABPersonCompositeNameFormat GTMABPersonCompositeNameFormat;
  84. typedef ABMultiValueIdentifier GTMABMultiValueIdentifier;
  85. enum _GTMABPropertyType {
  86. kGTMABInvalidPropertyType = kABInvalidPropertyType,
  87. kGTMABStringPropertyType = kABStringPropertyType,
  88. kGTMABIntegerPropertyType = kABIntegerPropertyType,
  89. kGTMABRealPropertyType = kABRealPropertyType,
  90. kGTMABDateTimePropertyType = kABDateTimePropertyType,
  91. kGTMABDictionaryPropertyType = kABDictionaryPropertyType,
  92. kGTMABMultiStringPropertyType = kABMultiStringPropertyType,
  93. kGTMABMultiIntegerPropertyType = kABMultiIntegerPropertyType,
  94. kGTMABMultiRealPropertyType = kABMultiRealPropertyType,
  95. kGTMABMultiDateTimePropertyType = kABMultiDateTimePropertyType,
  96. kGTMABMultiDictionaryPropertyType = kABMultiDictionaryPropertyType,
  97. };
  98. typedef CFIndex GTMABPropertyType;
  99. #define kGTMABPersonFirstNameProperty kABPersonFirstNameProperty
  100. #define kGTMABPersonLastNameProperty kABPersonLastNameProperty
  101. #define kGTMABPersonBirthdayProperty kABPersonBirthdayProperty
  102. #define kGTMABPersonPhoneProperty kABPersonPhoneProperty
  103. #define kGTMABGroupNameProperty kABGroupNameProperty
  104. #define kGTMABPersonPhoneMainLabel ((NSString *)kABPersonPhoneMainLabel)
  105. #define kGTMABPersonPhoneMobileLabel ((NSString *)kABPersonPhoneMobileLabel)
  106. #define kGTMABPersonPhoneHomeLabel ((NSString *)kABHomeLabel)
  107. #define kGTMABPersonPhoneWorkLabel ((NSString *)kABWorkLabel)
  108. #define kGTMABPersonPhoneWorkFaxLabel ((NSString *)kABPersonPhoneWorkFAXLabel)
  109. #define kGTMABPersonPhoneHomeFaxLabel ((NSString *)kABPersonPhoneHomeFAXLabel)
  110. #define kGTMABPersonPhonePagerLabel ((NSString *)kABPersonPhonePagerLabel)
  111. #define kGTMABOtherLabel ((NSString *)kABOtherLabel)
  112. #define kGTMABMultiValueInvalidIdentifier kABMultiValueInvalidIdentifier
  113. #define kGTMABRecordInvalidID kABRecordInvalidID
  114. #else // GTM_IPHONE_SDK
  115. @class NSImage;
  116. typedef NSString* GTMABRecordID;
  117. typedef NSString* GTMABPropertyID;
  118. typedef NSString* GTMABMultiValueIdentifier;
  119. typedef NSImage GTMABImage;
  120. typedef uint32_t GTMABPersonCompositeNameFormat;
  121. enum {
  122. kABPersonCompositeNameFormatFirstNameFirst = 0,
  123. kABPersonCompositeNameFormatLastNameFirst = 1
  124. };
  125. enum _GTMABPropertyType {
  126. kGTMABInvalidPropertyType = kABErrorInProperty,
  127. kGTMABStringPropertyType = kABStringProperty,
  128. kGTMABIntegerPropertyType = kABIntegerProperty,
  129. kGTMABRealPropertyType = kABRealProperty,
  130. kGTMABDateTimePropertyType = kABDateProperty,
  131. kGTMABDictionaryPropertyType = kABDictionaryProperty,
  132. kGTMABMultiStringPropertyType = kABMultiStringProperty,
  133. kGTMABMultiIntegerPropertyType = kABMultiIntegerProperty,
  134. kGTMABMultiRealPropertyType = kABMultiRealProperty,
  135. kGTMABMultiDateTimePropertyType = kABMultiDateProperty,
  136. kGTMABMultiDictionaryPropertyType = kABMultiDictionaryProperty,
  137. };
  138. typedef CFIndex GTMABPropertyType;
  139. #define kGTMABPersonFirstNameProperty kABFirstNameProperty
  140. #define kGTMABPersonLastNameProperty kABLastNameProperty
  141. #define kGTMABPersonBirthdayProperty kABBirthdayProperty
  142. #define kGTMABPersonPhoneProperty kABPhoneProperty
  143. #define kGTMABGroupNameProperty kABGroupNameProperty
  144. #define kGTMABPersonPhoneMainLabel kABPhoneMainLabel
  145. #define kGTMABPersonPhoneMobileLabel kABPhoneMobileLabel
  146. #define kGTMABPersonPhoneHomeLabel kABPhoneHomeLabel
  147. #define kGTMABPersonPhoneWorkLabel kABPhoneWorkLabel
  148. #define kGTMABPersonPhoneWorkFaxLabel kABPhoneWorkFAXLabel
  149. #define kGTMABPersonPhoneHomeFaxLabel kABPhoneHomeFAXLabel
  150. #define kGTMABPersonPhonePagerLabel kABPhonePagerLabel
  151. #define kGTMABOtherLabel kABOtherLabel
  152. #define kGTMABMultiValueInvalidIdentifier @"ABMultiValueInvalidIdentifier"
  153. #define kGTMABRecordInvalidID @"ABRecordInvalidID"
  154. extern NSString* const kABPersonRecordType;
  155. extern NSString* const kABGroupRecordType;
  156. #endif // GTM_IPHONE_SDK
  157. // Wrapper for an AddressBook on iPhone
  158. @interface GTMABAddressBook : NSObject {
  159. @private
  160. ABAddressBookRef addressBook_;
  161. }
  162. // Returns a new instance of an address book.
  163. + (GTMABAddressBook *)addressBook;
  164. // Return the address book reference
  165. - (ABAddressBookRef)addressBookRef;
  166. // Saves changes made since the last save
  167. // Return YES if successful (or there was no change)
  168. - (BOOL)save;
  169. // Returns YES if there are unsaved changes
  170. // The unsaved changes flag is automatically set when changes are made
  171. // As of iPhone 2.1, this does not work, and will always return NO.
  172. // Radar 6200638: ABAddressBookHasUnsavedChanges doesn't work
  173. - (BOOL)hasUnsavedChanges;
  174. // Returns a GTMABPerson matching an ID
  175. // Returns nil if the record could not be found
  176. - (GTMABPerson *)personForId:(GTMABRecordID)uniqueId;
  177. // Returns a GTMABGroup matching an ID
  178. // Returns nil if the record could not be found
  179. - (GTMABGroup *)groupForId:(GTMABRecordID)uniqueId;
  180. // Adds a record (ABPerson or ABGroup) to the AddressBook database
  181. // Be sure to read notes for -people and -group.
  182. - (BOOL)addRecord:(GTMABRecord *)record;
  183. // Removes a record (ABPerson or ABGroup) from the AddressBook database
  184. - (BOOL)removeRecord:(GTMABRecord *)record;
  185. // Returns an array (GTMABPerson) of all the people in the AddressBook database
  186. // As of iPhone 2.1, this array will not contain new entries until you save
  187. // the address book.
  188. // Radar 6200703: ABAddressBookAddRecord doesn't add an item to the people array
  189. // until it's saved
  190. - (NSArray *)people;
  191. // Returns an array of all the groups (GTMABGroup) in the AddressBook database
  192. // As of iPhone 2.1, this array will not contain new entries until you save
  193. // the address book.
  194. // Radar 6200703: ABAddressBookAddRecord doesn't add an item to the people array
  195. // until it's saved
  196. - (NSArray *)groups;
  197. // Performs a prefix search on the composite names of people in an address book
  198. // and returns an array of persons that match the search criteria.
  199. // Ignores case.
  200. - (NSArray *)peopleWithCompositeNameWithPrefix:(NSString *)prefix;
  201. // Performs a prefix search on the composite names of groups in an address book
  202. // and returns an array of groups that match the search criteria.
  203. // Ignores case.
  204. - (NSArray *)groupsWithCompositeNameWithPrefix:(NSString *)prefix;
  205. // Returns a localized name for a given label
  206. + (NSString *)localizedLabel:(NSString *)label;
  207. @end
  208. // Wrapper for a ABRecord on iPhone.
  209. // A abstract class. Instantiate one of the concrete subclasses, GTMABPerson or
  210. // GTMABGroup.
  211. @interface GTMABRecord : NSObject {
  212. @private
  213. ABRecordRef record_;
  214. }
  215. // Create a record with a recordRef.
  216. // Since GTMABRecord is an abstract base class, attempting to create one
  217. // of these directly will throw an exception. Use with one of the concrete
  218. // subclasses.
  219. + (id)recordWithRecord:(ABRecordRef)record;
  220. // Designated initializer
  221. // Since GTMABRecord is an abstract base class, attempting to create one
  222. // of these directly will throw an exception. Use with one of the concrete
  223. // subclasses.
  224. - (id)initWithRecord:(ABRecordRef)record;
  225. // Return our recordRef
  226. - (ABRecordRef)recordRef;
  227. // Return the recordID for the record
  228. - (GTMABRecordID)recordID;
  229. // Returns the value of a given property.
  230. // The type of the value depends on the property type.
  231. - (id)valueForProperty:(GTMABPropertyID)property;
  232. // Set the value of a given property.
  233. // The type of the value must match the property type.
  234. // Returns YES if value set properly
  235. - (BOOL)setValue:(id)value forProperty:(GTMABPropertyID)property;
  236. // Removes the value for the property
  237. // Returns yes if value removed
  238. - (BOOL)removeValueForProperty:(GTMABPropertyID)property;
  239. // returns a human friendly name for the record
  240. - (NSString *)compositeName;
  241. // returns the type of a property
  242. + (GTMABPropertyType)typeOfProperty:(GTMABPropertyID)property;
  243. // returns a human friendly localized name for a property
  244. + (NSString *)localizedPropertyName:(GTMABPropertyID)property;
  245. @end
  246. // Wrapper for an ABPerson on iPhone
  247. @interface GTMABPerson : GTMABRecord
  248. // Creates a person with a first name and a last name.
  249. + (GTMABPerson *)personWithFirstName:(NSString *)first
  250. lastName:(NSString *)last;
  251. // Sets image data for a person. Data must be to a block of data that
  252. // will create a valid GTMABImage.
  253. - (BOOL)setImageData:(NSData *)data;
  254. // Returns the image data.
  255. - (NSData *)imageData;
  256. // Returns the image for a person
  257. - (GTMABImage *)image;
  258. // Sets a the image for a person
  259. - (BOOL)setImage:(GTMABImage *)image;
  260. // Returns the format in with names are composited
  261. + (GTMABPersonCompositeNameFormat)compositeNameFormat;
  262. @end
  263. // Wrapper for a ABGroup on iPhone
  264. @interface GTMABGroup : GTMABRecord
  265. // Create a new group named |name|
  266. + (GTMABGroup *)groupNamed:(NSString *)name;
  267. // Return an array of members (GTMABPerson)
  268. - (NSArray *)members;
  269. // Add a member to a group
  270. - (BOOL)addMember:(GTMABPerson *)person;
  271. // Remove a member from a group
  272. - (BOOL)removeMember:(GTMABPerson *)person;
  273. @end
  274. // GTMABMultiValue does not support NSFastEnumeration because in
  275. // the Apple frameworks it returns identifiers which are already NSStrings.
  276. // In our case identifiers aren't NS types, and it doesn't make sense
  277. // to convert them to NSNumbers just to convert them back so you can
  278. // actually get at the values and labels.
  279. // Instead we supply valueEnumerator and labelEnumerator which you can
  280. // fast enumerate on to get values and labels directly.
  281. @interface GTMABMultiValue : NSObject <NSCopying, NSMutableCopying> {
  282. @protected
  283. ABMultiValueRef multiValue_;
  284. }
  285. // Create a multi value
  286. - (id)initWithMultiValue:(ABMultiValueRef)multiValue;
  287. // return it's ref
  288. - (ABMultiValueRef)multiValueRef;
  289. // Returns the number of value/label pairs
  290. - (NSUInteger)count;
  291. // Returns a value at a given index
  292. // Returns nil if index is out of bounds
  293. - (id)valueAtIndex:(NSUInteger)idx;
  294. // Returns a label at a given index
  295. // Returns nil if index is out of bounds
  296. - (NSString *)labelAtIndex:(NSUInteger)idx;
  297. // Returns an identifier at a given index
  298. // Returns kABMultiValueInvalidIdentifier if index is out of bounds
  299. - (GTMABMultiValueIdentifier)identifierAtIndex:(NSUInteger)idx;
  300. // Returns the index of a given identifier
  301. // Returns NSNotFound if not found
  302. - (NSUInteger)indexForIdentifier:(GTMABMultiValueIdentifier)identifier;
  303. // Type of the contents of this multivalue
  304. - (GTMABPropertyType)propertyType;
  305. // Returns the value for a given identifier
  306. // Returns nil if the identifier is not found
  307. - (id)valueForIdentifier:(GTMABMultiValueIdentifier)identifier;
  308. // Returns the value for a given identifier
  309. // Returns nil if the identifier is not found
  310. - (NSString *)labelForIdentifier:(GTMABMultiValueIdentifier)identifier;
  311. // Returns an enumerator for enumerating through values
  312. - (NSEnumerator *)valueEnumerator;
  313. // Returns an enumerator for enumerating through labels
  314. - (NSEnumerator *)labelEnumerator;
  315. @end
  316. @interface GTMABMutableMultiValue : GTMABMultiValue {
  317. @private
  318. // Use unsigned long here instead of NSUInteger because that's what
  319. // NSFastEnumeration Protocol wants currently (iPhone 2.1)
  320. unsigned long mutations_;
  321. }
  322. // Create a new mutable multivalue with a given type
  323. + (id)valueWithPropertyType:(GTMABPropertyType)type;
  324. // Create a new mutable multivalue with a given type
  325. - (id)initWithPropertyType:(GTMABPropertyType)type;
  326. // Create a new mutable multivalue based on |multiValue|
  327. - (id)initWithMutableMultiValue:(ABMutableMultiValueRef)multiValue;
  328. // Adds a value with its label
  329. // Returns the identifier if successful, kABMultiValueInvalidIdentifier
  330. // otherwise.
  331. - (GTMABMultiValueIdentifier)addValue:(id)value withLabel:(CFStringRef)label;
  332. // Insert a value/label pair at a given index
  333. // Returns the identifier if successful. kABMultiValueInvalidIdentifier
  334. // otherwise
  335. // If index is out of bounds, returns kABMultiValueInvalidIdentifier.
  336. - (GTMABMultiValueIdentifier)insertValue:(id)value
  337. withLabel:(CFStringRef)label
  338. atIndex:(NSUInteger)index;
  339. // Removes a value/label pair at a given index
  340. // Returns NO if index out of bounds
  341. - (BOOL)removeValueAndLabelAtIndex:(NSUInteger)index;
  342. // Replaces a value at a given index
  343. // Returns NO if index out of bounds
  344. - (BOOL)replaceValueAtIndex:(NSUInteger)index withValue:(id)value;
  345. // Replaces a label at a given index
  346. // Returns NO if index out of bounds
  347. - (BOOL)replaceLabelAtIndex:(NSUInteger)index withLabel:(CFStringRef)label;
  348. @end