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