/core/externals/update-engine/Core/KSPlistServer.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 "KSServer.h"
 17
 18
 19// KSPlistServer
 20//
 21// This concrete KSServer subclass is designed to read a specially formatted
 22// XML Plist, and based on the "rules" in that plist, will create the necessary
 23// KSUpdateInfo objects (KSUpdateInfo instances describe an update that needs to
 24// be installed). 
 25//
 26// The "trick" to this class is that each Rule contains an NSPredicate-
 27// compatible "Predicate" string. Each predicate will be evaluated against a
 28// specific object that provides access to useful system/product version info.
 29// If the Predicate evaluates to true, then the update in the rule is applied, 
 30// otherwise, it's discarded.
 31//
 32// == Plist Format ==
 33//
 34// The fetched plist must have a top-level key named "Rules" with a value that
 35// is a array of individual rules. Each Rule itself must be a dictionary with 
 36// the following required keys and value types (IMPORTANT: case *is* important):
 37//
 38//   - ProductID (string) : The unique identifier for the product (same as the
 39//                          product ID used in the ticket).
 40//   - Predicate (string) : Any NSPredicate compatible string that determines 
 41//                          whether the update described by the current rule
 42//                          should be applied. More details below.
 43//   - Codebase  (string) : The URL where the update should be downloaded from.
 44//                          This URL must reference a disk image (DMG).
 45//   - Hash      (string) : The Base64-encoded SHA-1 hash of the file at 
 46//                          the "Codebase" URL.
 47//                          An easy way to calculate this is with the command:
 48//                          openssl sha1 -binary dmg-filename | openssl base64
 49//   - Size      (string) : The size in bytes of the file at the "Codebase" URL.
 50//
 51// The Predicate enables lots of flexibility and configurability. The string
 52// specified for the predicate will be converted into an NSPredicate and run 
 53// against an NSDictionary with two attributes: 
 54// 
 55//   - SystemVersion : This gives the predicate access to version information
 56//                     about the current OS. The value of this key is the
 57//                     contents of the file:
 58//                     /System/Library/CoreServices/SystemVersion.plist
 59//   - Ticket        : This gives the predicate access to the product's
 60//                     (determined by the ProductID key) currently installed 
 61//                     version information via its corresponding KSTicket.
 62//
 63// == Example Plist 1 ==
 64// 
 65// This plist contains one rule whose predicate says to install the update at
 66// "Codebase" if the currently installed version is not version 1.1. This rule
 67// may work for a product whose current version is 1.1 and all versions that are
 68// not 1.1 should be "upgraded" to version 1.1.
 69//
 70// <?xml version="1.0" encoding="UTF-8"?>
 71// <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
 72//                        "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
 73// <plist version="1.0">
 74// <dict>
 75//   <key>Rules</key>
 76//   <array>
 77//     <dict>
 78//       <key>ProductID</key>
 79//       <string>com.google.Foo</string>
 80//       <key>Predicate</key>
 81//       <string>Ticket.version != '1.1'</string>
 82//       <key>Codebase</key>
 83//       <string>https://www.google.com/engine/Foo.dmg</string>
 84//       <key>Hash</key>
 85//       <string>somehash=</string>
 86//       <key>Size</key>
 87//       <string>123456</string>
 88//     </dict>
 89//   </array>
 90// </dict>
 91// </plist>
 92//
 93//
 94// == Example Plist 2 ==
 95//
 96// This plist lists two rules for two different products (Foo and Bar). The
 97// Foo product will only ever apply to Tiger machines because the predicate
 98// looks for "SystemVersion.ProductVersion beginswith '10.4'". The Bar product
 99// only targets Leopard systems because its predicate includes a similar check
100// for a system version beginning with '10.5'. The rest of this plist should be
101// pretty straight forward.
102//
103// <?xml version="1.0" encoding="UTF-8"?>
104// <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
105//                        "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
106// <plist version="1.0">
107// <dict>
108//   <key>Rules</key>
109//   <array>
110//     <dict>
111//       <key>ProductID</key>
112//       <string>com.google.Foo</string>
113//       <key>Predicate</key>
114//       <string>SystemVersion.ProductVersion beginswith '10.4' AND Ticket.version != '1.1'</string>
115//       <key>Codebase</key>
116//       <string>https://www.google.com/engine/Foo.dmg</string>
117//       <key>Hash</key>
118//       <string>somehash=</string>
119//       <key>Size</key>
120//       <string>123456</string>
121//     </dict>
122//     <dict>
123//       <key>ProductID</key>
124//       <string>com.google.Bar</string>
125//       <key>Predicate</key>
126//       <string>SystemVersion.ProductVersion beginswith '10.5' AND Ticket.version != '1.1'</string>
127//       <key>Codebase</key>
128//       <string>https://www.google.com/engine/Bar.dmg</string>
129//       <key>Hash</key>
130//       <string>somehash=</string>
131//       <key>Size</key>
132//       <string>123456</string>
133//     </dict>
134//   </array>
135// </dict>
136// </plist>
137//
138@interface KSPlistServer : KSServer {
139 @private
140  NSArray *tickets_;
141  NSDictionary *systemVersion_;
142}
143
144// Returns an autoreleased instance that will create requests to the given URL.
145+ (id)serverWithURL:(NSURL *)url;
146
147// Returns the tickets that were last passed to -requestsForTickets:. Because 
148// this class retains the tickets passed to -requestsForTickets:, it's not safe
149// to reuse this class--only use each instance once.
150- (NSArray *)tickets;
151
152@end