2
0
MasterPassword/External/google-plus-ios-sdk/OpenSource/GTL/GTLObject.h
Maarten Billemont a6e3b83ebb Dumped Google+ SDK.
[UPDATED]   Google+ SDK.
2013-04-27 17:14:05 -04:00

209 lines
6.8 KiB
Objective-C

/* Copyright (c) 2011 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
//
// GTLObject.h
//
// GTLObject documentation:
// https://code.google.com/p/google-api-objectivec-client/wiki/Introduction#Objects_and_Queries
#import <Foundation/Foundation.h>
#import "GTLDefines.h"
#import "GTLUtilities.h"
#import "GTLDateTime.h"
#undef _EXTERN
#undef _INITIALIZE_AS
#ifdef GTLOBJECT_DEFINE_GLOBALS
#define _EXTERN
#define _INITIALIZE_AS(x) =x
#else
#define _EXTERN extern
#define _INITIALIZE_AS(x)
#endif
@protocol GTLCollectionProtocol
@optional
@property (retain) NSArray *items;
@end
@protocol GTLBatchItemCreationProtocol
- (void)createItemsWithClassMap:(NSDictionary *)batchClassMap;
@end
@interface GTLObject : NSObject <NSCopying> {
@private
NSMutableDictionary *json_;
// Used when creating the subobjects from this one.
NSDictionary *surrogates_;
// Any complex object hung off this object goes into the cache so the
// next fetch will get the same object back instead of having to recreate
// it.
NSMutableDictionary *childCache_;
// Anything defined by the client; retained but not used internally; not
// copied by copyWithZone:
NSMutableDictionary *userProperties_;
}
@property (nonatomic, retain) NSMutableDictionary *JSON;
@property (nonatomic, retain) NSDictionary *surrogates;
@property (nonatomic, retain) NSMutableDictionary *userProperties;
///////////////////////////////////////////////////////////////////////////////
//
// Public methods
//
// These methods are intended for users of the library
//
+ (id)object;
+ (id)objectWithJSON:(NSMutableDictionary *)dict;
- (id)copyWithZone:(NSZone *)zone;
- (NSString *)JSONString;
// generic access to json; also creates it if necessary
- (void)setJSONValue:(id)obj forKey:(NSString *)key GTL_NONNULL((2));
- (id)JSONValueForKey:(NSString *)key;
// Returns the list of keys in this object's JSON that aren't listed as
// properties on the object.
- (NSArray *)additionalJSONKeys;
// Any keys in the JSON that aren't listed as @properties on the object
// are counted as "additional properties". These allow you to get/set them.
- (id)additionalPropertyForName:(NSString *)name;
- (void)setAdditionalProperty:(id)obj forName:(NSString *)name GTL_NONNULL((2));
- (NSDictionary *)additionalProperties;
// User properties are supported for client convenience, but are not copied by
// copyWithZone. User Properties keys beginning with _ are reserved by the library.
//
// Set nil for obj to remove the property.
- (void)setProperty:(id)obj forKey:(NSString *)key GTL_NONNULL((2));
- (id)propertyForKey:(NSString *)key GTL_NONNULL((1));
// userData is stored as a property with key "_userData"
- (void)setUserData:(id)obj;
- (id)userData;
// Makes a partial query-compatible string describing the fields present
// in this object. (Note: only the first element of any array is examined.)
//
// http://code.google.com/apis/tasks/v1/performance.html#partial
//
- (NSString *)fieldsDescription;
// Makes an object containing only the changes needed to do a partial update
// (patch), where the patch would be to change an object from the original
// to the receiver, such as
//
// GTLSomeObject *patchObject = [newVersion patchObjectFromOriginal:oldVersion];
//
// http://code.google.com/apis/tasks/v1/performance.html#patch
//
// NOTE: this method returns nil if there are no changes between the original
// and the receiver.
- (id)patchObjectFromOriginal:(GTLObject *)original;
// Method creating a null value to set object properties for patch queries that
// delete fields. Do not use this except when setting an object property for
// a patch query.
+ (id)nullValue;
///////////////////////////////////////////////////////////////////////////////
//
// Protected methods
//
// These methods are intended for subclasses of GTLObject
//
// class registration ("kind" strings) for subclasses
+ (Class)registeredObjectClassForKind:(NSString *)kind;
+ (void)registerObjectClassForKind:(NSString *)kind;
// creation of objects from a JSON dictionary
+ (GTLObject *)objectForJSON:(NSMutableDictionary *)json
defaultClass:(Class)defaultClass
surrogates:(NSDictionary *)surrogates
batchClassMap:(NSDictionary *)batchClassMap;
// property-to-key mapping (for JSON keys which are not used as method names)
+ (NSDictionary *)propertyToJSONKeyMap;
// property-to-Class mapping for array properties (to say what is in the array)
+ (NSDictionary *)arrayPropertyToClassMap;
// The default class for additional JSON keys
+ (Class)classForAdditionalProperties;
@end
// Collection objects with an "items" property should derive from GTLCollection
// object. This provides support for fast object enumeration, the
// itemAtIndex: convenience method, and indexed subscripts.
//
// Subclasses must implement the items method dynamically.
@interface GTLCollectionObject : GTLObject <GTLCollectionProtocol, NSFastEnumeration> {
@private
NSDictionary *identifierMap_;
}
// itemAtIndex: and objectAtIndexedSubscript: return nil when the index exceeds
// the bounds of the items array.
- (id)itemAtIndex:(NSUInteger)idx;
- (id)objectAtIndexedSubscript:(NSInteger)idx;
// itemForIdentifier: looks up items from the collection object by identifier,
// and returns the first one.
//
// Typically, items will have a unique identifier (with key "id" in the
// object's JSON). This method returns the first item found in the collection
// with the specified identifier.
//
// The first time this method is used, the collection will cache a map of
// identifiers to items. If the items list for the instance somehow changes,
// use the reset method below to force a new cache to be created for this
// collection.
- (id)itemForIdentifier:(NSString *)key GTL_NONNULL((1));
// Identifiers for all items are cached when the first one is obtained.
// This method resets the cache. It is needed only if the item list has
// changed.
- (void)resetIdentifierMap;
@end
@interface GTLCollectionObject (DynamicMethods)
- (NSArray *)items;
@end
// Base object use for when an service method directly returns an array instead
// of an object. Normally methods should return an object with an 'items'
// property, but this exists for the methods not up to spec.
@interface GTLResultArray : GTLCollectionObject
// This method should only be called by subclasses.
- (NSArray *)itemsWithItemClass:(Class)itemClass;
@end