PageRenderTime 19ms CodeModel.GetById 1ms app.highlight 14ms RepoModel.GetById 1ms app.codeStats 0ms

/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
 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