/core/externals/update-engine/Core/KSCheckAction.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#import "KSMultiAction.h"
17
18@class KSUpdateEngine;
19
20// KSCheckAction
21//
22// This KSMultiAction runs one KSUpdateCheckAction for each unique server URL
23// found in a ticket. The output of all the sub-KSUpdateCheckActions is
24// collected and the aggregate output is set as this action's output (via its
25// outPipe).
26//
27// Sample usage:
28//   KSActionProcessor *ap = ...
29//   NSArray *tickets = ... tickets that could be for any arbitrary URLs ...
30//
31//   KSAction *checker = [KSCheckAction actionWithTickets:tickets];
32//
33//   [ap enqueueAction:checker];
34//   [ap startProcessing];
35//
36//   ... spin runloop until done ...
37//   NSArray *agg = [[checker outPipe] contents];
38//
39// That last line will return an array with the aggregate output from all the
40// sub-KSUpdateCheckActions.
41//
42// A KSCheckAction completes "successfully" if *any* of its
43// sub-KSUpdateCheckActions complete successfully. They do not all need to be
44// successfull in order for this class to be successful. This handles the case
45// where one of the URLs for one of the KSUpdateCheckActions is bad but the
46// rest are fine. In this case, we shouldn't fail the whole operation just from
47// one bad URL. But in the case where the user has no internet connetion and
48// ALL the sub-KSUpdateCheckActions fail, we do want to report that this multi-
49// action failed.
50//
51@interface KSCheckAction : KSMultiAction {
52 @private
53  NSArray *tickets_;
54  NSMutableArray *updateInfos_;  // Output for next action
55  NSMutableDictionary *outOfBandData_;  // Output for next action
56  NSDictionary *params_;
57  KSUpdateEngine *engine_;
58  BOOL wasSuccessful_;
59}
60
61// Returns an autoreleased KSCheckAction. See the designated initializer for
62// more details.
63+ (id)actionWithTickets:(NSArray *)tickets params:(NSDictionary *)params
64                 engine:(KSUpdateEngine *)engine;
65+ (id)actionWithTickets:(NSArray *)tickets params:(NSDictionary *)params;
66+ (id)actionWithTickets:(NSArray *)tickets;
67
68// Designated initializer. Returns a KSCheckAction that will create
69// sub-KSUpdateCheckActions for each group of tickets to each unique server URL.
70// |tickets| must be an array of KSTicket objects. The tickets do not need to
71// point to the same server URL. A nil or empty array of tickets is allowed;
72// this action will just immediately finish running and will return an empty
73// output array as if no updates were available.
74// If specified, |params| is an NSDictionary indexed by the keys in
75// KSUpdateEngineParameters.h.  These paramaters are passed down to
76// objects which may be created by this class.
77- (id)initWithTickets:(NSArray *)tickets params:(NSDictionary *)params
78               engine:(KSUpdateEngine *)engine;
79- (id)initWithTickets:(NSArray *)tickets params:(NSDictionary *)params;
80- (id)initWithTickets:(NSArray *)tickets;
81
82@end
83
84
85// API to configure KSCheckAction instances.
86@interface KSCheckAction (Configuration)
87
88// Returns the KSServer Class that will be used by KSCheckAction instances. The
89// returned Class is guaranteed to be a subclass of KSServer. This method never
90// returns nil. By default, the returned class is KSPlistServer.
91+ (Class)serverClass;
92
93// Sets the KSServer Class that KSCheckAction instances should use.
94// |serverClass| MUST be a subclass of the KSServer abstract class. It will be
95// ignored if it is not. Passing a value of nil will reset things back to its
96// default value.
97+ (void)setServerClass:(Class)serverClass;
98
99@end