/core/externals/update-engine/Core/KSTicket.h

  1// Copyright 2008 Google Inc.
  2//
  3// Licensed under the Apache License, Version 2.0 (the "License");
  4// you may not use this file except in compliance with the License.
  5// You may obtain a copy of the License at
  6//
  7//     http://www.apache.org/licenses/LICENSE-2.0
  8//
  9// Unless required by applicable law or agreed to in writing, software
 10// distributed under the License is distributed on an "AS IS" BASIS,
 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12// See the License for the specific language governing permissions and
 13// limitations under the License.
 14
 15#import <Foundation/Foundation.h>
 16
 17// Keys for the parameters dictionary.  The values should be an NSString unless
 18// otherwise noted.
 19#define KSTicketProductIDKey          @"ProductID"
 20#define KSTicketVersionKey            @"Version"
 21#define KSTicketExistenceCheckerKey   @"ExistenceChecker"  // KSExistenceChecker
 22#define KSTicketServerURLKey          @"URL"               // NSURL
 23#define KSTicketTrustedTesterTokenKey @"TTToken"
 24#define KSTicketCreationDateKey       @"CreationDate"      // NSDate
 25#define KSTicketTagKey                @"Tag"
 26#define KSTicketTagPathKey            @"TagPath"
 27#define KSTicketTagKeyKey             @"TagKey"
 28#define KSTicketBrandPathKey          @"BrandPath"
 29#define KSTicketBrandKeyKey           @"BrandKey"
 30#define KSTicketVersionPathKey        @"VersionPath"
 31#define KSTicketVersionKeyKey         @"VersionKey"
 32
 33@class KSExistenceChecker;
 34
 35// Object that encapsulates information that an application provides when
 36// "registering" with UpdateEngine. Tickets are a central part of UpdateEngine.
 37// UpdateEngine maintains one ticket for each registered application. Tickets
 38// are how UpdateEngine knows what's installed.
 39//
 40// The creation date simply records the date the ticket was created. If a ticket
 41// is unarchived (from a KSTicketStore), the creationDate_ will be the date the
 42// ticket was originally created, not the date it was unarchived.  You can use
 43// the creation date to see how long the ticket has been registered.  You should
 44// preserve the creation date when you update a ticket.
 45//
 46@interface KSTicket : NSObject <NSCoding> {
 47 @private
 48  NSString *productID_;  // guid or bundleID
 49  NSString *version_;
 50  KSExistenceChecker *existenceChecker_;
 51  NSURL *serverURL_;
 52  NSDate *creationDate_;
 53  NSString *trustedTesterToken_;
 54  NSString *tag_;
 55  NSString *tagPath_;
 56  NSString *tagKey_;
 57  NSString *brandPath_;
 58  NSString *brandKey_;
 59  NSString *versionPath_;
 60  NSString *versionKey_;
 61}
 62
 63// Returns an autorelased KSTicket instance initialized with the
 64// values contained in the parameter directory.
 65+ (KSTicket *)ticketWithParameters:(NSDictionary *)args;
 66
 67// Returns an autoreleased KSTicket instance initialized with the specified
 68// arguments. All arguments are required; if any are nil, then nil is returned.
 69+ (id)ticketWithProductID:(NSString *)productid
 70                  version:(NSString *)version
 71         existenceChecker:(KSExistenceChecker *)xc
 72                serverURL:(NSURL *)serverURL;
 73
 74// Returns an autoreleased KSTicket instance initialized with the
 75// specified arguments, also allowing a trusted tester token to be
 76// specified.  All arguments other than the trusted tester token are
 77// required; if any others are nil, then nil is returned.
 78+ (id)ticketWithProductID:(NSString *)productid
 79                  version:(NSString *)version
 80         existenceChecker:(KSExistenceChecker *)xc
 81                serverURL:(NSURL *)serverURL
 82       trustedTesterToken:(NSString *)trustedTesterToken;
 83
 84// Returns an autoreleased KSTicket instance initialized with the
 85// specified arguments, also allowing a trusted tester token and a
 86// creation date to be specified.  All arguments other than the
 87// trusted tester token and creation date are required; if any others
 88// are nil, then nil is returned.
 89+ (id)ticketWithProductID:(NSString *)productid
 90                  version:(NSString *)version
 91         existenceChecker:(KSExistenceChecker *)xc
 92                serverURL:(NSURL *)serverURL
 93       trustedTesterToken:(NSString *)trustedTesterToken
 94             creationDate:(NSDate *)creationDate;
 95
 96// Returns an autoreleased KSTicket instance initialized with the
 97// specified arguments, also allowing a trusted tester token, a
 98// creation date, and a tag to be specified.  All arguments other than
 99// the trusted tester token, creation date, and tag are required; if
100// any others are nil, then nil is returned.
101// TODO(mdalrymple): There's too damn many of these initializers.
102//    Pare it down to the Big Four (prodID, version, xc, url), and then
103//    another one with all the args - either as individual arguments, or
104//    a dict/struct packed with the extra values.
105+ (id)ticketWithProductID:(NSString *)productid
106                  version:(NSString *)version
107         existenceChecker:(KSExistenceChecker *)xc
108                serverURL:(NSURL *)serverURL
109       trustedTesterToken:(NSString *)trustedTesterToken
110             creationDate:(NSDate *)creationDate
111                      tag:(NSString *)tag;
112
113// Designated initializer.  Returns a KSTicket initialized with the
114// specified argument directory.
115- (id)initWithParameters:(NSDictionary *)args;
116
117// Returns a KSTicket initialized with the specified arguments. All
118// arguments are required; if any are nil, then nil is returned.
119- (id)initWithProductID:(NSString *)productid
120                version:(NSString *)version
121       existenceChecker:(KSExistenceChecker *)xc
122              serverURL:(NSURL *)serverURL;
123
124// Returns a KSTicket initialized with the specified arguments, also
125// allowing a trusted tester token.  All arguments other than the
126// trusted tester token are required; if any are nil, then nil is
127// returned.
128- (id)initWithProductID:(NSString *)productid
129                version:(NSString *)version
130       existenceChecker:(KSExistenceChecker *)xc
131              serverURL:(NSURL *)serverURL
132     trustedTesterToken:(NSString *)trustedTesterToken;
133
134// Returns a KSTicket initialized with the specified arguments, also
135// allowing a trusted tester token and a creation date.  All arguments
136// other than the trusted tester token and creation date are required;
137// if any are nil, then nil is returned. If no creation date is
138// supplied, the current date and time is used.
139- (id)initWithProductID:(NSString *)productid
140                version:(NSString *)version
141       existenceChecker:(KSExistenceChecker *)xc
142              serverURL:(NSURL *)serverURL
143     trustedTesterToken:(NSString *)trustedTesterToken
144           creationDate:(NSDate *)creationDate;
145
146// Returns a KSTicket initialized with the
147// specified arguments, also allowing a trusted tester token,
148// a creation date, and a tag.  All arguments other than the trusted tester
149// token, creation date, and tag are required; if any are nil, then nil is
150// returned.  If no creation date is supplied, the current date and
151// time is used.
152- (id)initWithProductID:(NSString *)productid
153                version:(NSString *)version
154       existenceChecker:(KSExistenceChecker *)xc
155              serverURL:(NSURL *)serverURL
156     trustedTesterToken:(NSString *)trustedTesterToken
157           creationDate:(NSDate *)creationDate
158                    tag:(NSString *)tag;
159
160// Returns YES if ticket is equal to the ticket identified by self.
161- (BOOL)isEqualToTicket:(KSTicket *)ticket;
162
163// Returns the productID for this ticket.
164// We don't know or care if it's a GUID or BundleID
165- (NSString *)productID;
166
167// Returns the version stored in the ticket.  You may want to use
168// -determineVersion if all you're interested in is "what version do I
169// report to the server for an update?"
170- (NSString *)version;
171
172// Returns the existence checker object for this ticket. This object can be used
173// to determine if the application represented by this ticket is still
174// installed.
175- (KSExistenceChecker *)existenceChecker;
176
177// Returns the server URL to check for updates to the application represented by
178// this ticket.
179- (NSURL *)serverURL;
180
181// Returns the date this ticket was created.
182- (NSDate *)creationDate;
183
184// Returns the trusted tester token, or nil if the ticket does not have one.
185- (NSString *)trustedTesterToken;
186
187// Returns the tag, or nil if the ticket does not have one.
188- (NSString *)tag;
189
190// Returns the tag path, or nil if the ticket does not have one.
191- (NSString *)tagPath;
192
193// Returns the tag key, or nil if the ticket does not have one.
194- (NSString *)tagKey;
195
196// Uses -tag, -tagPath, and -tagKey to determine what the ticket's tag is.
197// If -tagPath is not-nil, and points to a valid plist file, look up
198// a value with the -tagKey.  If that exists, its description is returned.
199// If -tagPath is not-nil, and points to an invalid plist file, returns the
200// value of -tag.
201// If there is no tagPath, returns the value of -tag.
202- (NSString *)determineTag;
203
204// Returns the brand path, or nil if the ticket does not have one.
205- (NSString *)brandPath;
206
207// Returns the brand key, or nil if the ticket does not have one.
208- (NSString *)brandKey;
209
210// Uses -brandPath and -brandKey to determine what the ticket's brand code is.
211// If -brandPath is not-nil, and points to a valid plist file, look up
212// a value using the -brandKey.  If that exists, its description is returned.
213// Returns nil if there is no brand code.
214- (NSString *)determineBrand;
215
216// Returns the version path, or nil if the ticket does not have one.
217- (NSString *)versionPath;
218
219// Returns the version key, or nil if the ticket does not have one.
220- (NSString *)versionKey;
221
222// Uses -version, -versionPath, and -versionKey to determine what the
223// ticket's version is.
224// If -versionPath is not-nil, and points to a valid plist file, look up
225// a value with the -versionKey.  If that exists, its description is returned.
226// If it doesn't exist, -version is returned.
227// If -versionPath is not-nil, and points to an invalid plist file, returns
228// -version.
229// If there is no versionPath, returns -version.
230- (NSString *)determineVersion;
231
232@end