Home | History | Annotate | Download | only in cocoa 
      1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 
      5 #ifndef CHROME_BROWSER_COCOA_KEYSTONE_GLUE_H_
      6 #define CHROME_BROWSER_COCOA_KEYSTONE_GLUE_H_
      7 #pragma once
      8 
      9 #include "base/string16.h"
     10 
     11 #if defined(__OBJC__)
     12 
     13 #import <Foundation/Foundation.h>
     14 
     15 #import "base/memory/scoped_nsobject.h"
     16 #include "chrome/browser/cocoa/scoped_authorizationref.h"
     17 
     18 // Possible outcomes of various operations.  A version may accompany some of
     19 // these, but beware: a version is never required.  For statuses that can be
     20 // accompanied by a version, the comment indicates what version is referenced.
     21 // A notification posted containing an asynchronous status will always be
     22 // followed by a notification with a terminal status.
     23 enum AutoupdateStatus {
     24   kAutoupdateNone = 0,        // no version (initial state only)
     25   kAutoupdateRegistering,     // no version (asynchronous operation in progress)
     26   kAutoupdateRegistered,      // no version
     27   kAutoupdateChecking,        // no version (asynchronous operation in progress)
     28   kAutoupdateCurrent,         // version of the running application
     29   kAutoupdateAvailable,       // version of the update that is available
     30   kAutoupdateInstalling,      // no version (asynchronous operation in progress)
     31   kAutoupdateInstalled,       // version of the update that was installed
     32   kAutoupdatePromoting,       // no version (asynchronous operation in progress)
     33   kAutoupdatePromoted,        // no version
     34   kAutoupdateRegisterFailed,  // no version
     35   kAutoupdateCheckFailed,     // no version
     36   kAutoupdateInstallFailed,   // no version
     37   kAutoupdatePromoteFailed,   // no version
     38 };
     39 
     40 // kAutoupdateStatusNotification is the name of the notification posted when
     41 // -checkForUpdate and -installUpdate complete.  This notification will be
     42 // sent with with its sender object set to the KeystoneGlue instance sending
     43 // the notification.  Its userInfo dictionary will contain an AutoupdateStatus
     44 // value as an intValue at key kAutoupdateStatusStatus.  If a version is
     45 // available (see AutoupdateStatus), it will be present at key
     46 // kAutoupdateStatusVersion.
     47 extern NSString* const kAutoupdateStatusNotification;
     48 extern NSString* const kAutoupdateStatusStatus;
     49 extern NSString* const kAutoupdateStatusVersion;
     50 
     51 namespace {
     52 
     53 enum BrandFileType {
     54   kBrandFileTypeNotDetermined = 0,
     55   kBrandFileTypeNone,
     56   kBrandFileTypeUser,
     57   kBrandFileTypeSystem,
     58 };
     59 
     60 } // namespace
     61 
     62 // KeystoneGlue is an adapter around the KSRegistration class, allowing it to
     63 // be used without linking directly against its containing KeystoneRegistration
     64 // framework.  This is used in an environment where most builds (such as
     65 // developer builds) don't want or need Keystone support and might not even
     66 // have the framework available.  Enabling Keystone support in an application
     67 // that uses KeystoneGlue is as simple as dropping
     68 // KeystoneRegistration.framework in the application's Frameworks directory
     69 // and providing the relevant information in its Info.plist.  KeystoneGlue
     70 // requires that the KSUpdateURL key be set in the application's Info.plist,
     71 // and that it contain a string identifying the update URL to be used by
     72 // Keystone.
     73 
     74 @class KSRegistration;
     75 
     76 @interface KeystoneGlue : NSObject {
     77  @protected
     78 
     79   // Data for Keystone registration
     80   NSString* productID_;
     81   NSString* appPath_;
     82   NSString* url_;
     83   NSString* version_;
     84   NSString* channel_;  // Logically: Dev, Beta, or Stable.
     85   BrandFileType brandFileType_;
     86 
     87   // And the Keystone registration itself, with the active timer
     88   KSRegistration* registration_;  // strong
     89   NSTimer* timer_;  // strong
     90 
     91   // The most recent kAutoupdateStatusNotification notification posted.
     92   scoped_nsobject<NSNotification> recentNotification_;
     93 
     94   // The authorization object, when it needs to persist because it's being
     95   // carried across threads.
     96   scoped_AuthorizationRef authorization_;
     97 
     98   // YES if a synchronous promotion operation is in progress (promotion during
     99   // installation).
    100   BOOL synchronousPromotion_;
    101 
    102   // YES if an update was ever successfully installed by -installUpdate.
    103   BOOL updateSuccessfullyInstalled_;
    104 }
    105 
    106 // Return the default Keystone Glue object.
    107 + (id)defaultKeystoneGlue;
    108 
    109 // Load KeystoneRegistration.framework if present, call into it to register
    110 // with Keystone, and set up periodic activity pings.
    111 - (void)registerWithKeystone;
    112 
    113 // -checkForUpdate launches a check for updates, and -installUpdate begins
    114 // installing an available update.  For each, status will be communicated via
    115 // a kAutoupdateStatusNotification notification, and will also be available
    116 // through -recentNotification.
    117 - (void)checkForUpdate;
    118 - (void)installUpdate;
    119 
    120 // Accessor for recentNotification_.  Returns an autoreleased NSNotification.
    121 - (NSNotification*)recentNotification;
    122 
    123 // Accessor for the kAutoupdateStatusStatus field of recentNotification_'s
    124 // userInfo dictionary.
    125 - (AutoupdateStatus)recentStatus;
    126 
    127 // Returns YES if an asynchronous operation is pending: if an update check or
    128 // installation attempt is currently in progress.
    129 - (BOOL)asyncOperationPending;
    130 
    131 // Returns YES if the application is running from a read-only filesystem,
    132 // such as a disk image.
    133 - (BOOL)isOnReadOnlyFilesystem;
    134 
    135 // -needsPromotion is YES if the application needs its ticket promoted to
    136 // a system ticket.  This will be YES when the application is on a user
    137 // ticket and determines that the current user does not have sufficient
    138 // permission to perform the update.
    139 //
    140 // -wantsPromotion is YES if the application wants its ticket promoted to
    141 // a system ticket, even if it doesn't need it as determined by
    142 // -needsPromotion.  -wantsPromotion will always be YES if -needsPromotion is,
    143 // and it will additionally be YES when the application is on a user ticket
    144 // and appears to be installed in a system-wide location such as
    145 // /Applications.
    146 //
    147 // Use -needsPromotion to decide whether to show any update UI at all.  If
    148 // it's YES, there's no sense in asking the user to "update now" because it
    149 // will fail given the rights and permissions involved.  On the other hand,
    150 // when -needsPromotion is YES, the application can encourage the user to
    151 // promote the ticket so that updates will work properly.
    152 //
    153 // Use -wantsPromotion to decide whether to allow the user to promote.  The
    154 // user shouldn't be nagged about promotion on the basis of -wantsPromotion,
    155 // but if it's YES, the user should be allowed to promote the ticket.
    156 - (BOOL)needsPromotion;
    157 - (BOOL)wantsPromotion;
    158 
    159 // Promotes the Keystone ticket into the system store.  System Keystone will
    160 // be installed if necessary.  If synchronous is NO, the promotion may occur
    161 // in the background.  synchronous should be YES for promotion during
    162 // installation. The KeystoneGlue object assumes ownership of
    163 // authorization_arg.
    164 - (void)promoteTicketWithAuthorization:(AuthorizationRef)authorization_arg
    165                            synchronous:(BOOL)synchronous;
    166 
    167 // Requests authorization and calls -promoteTicketWithAuthorization: in
    168 // asynchronous mode.
    169 - (void)promoteTicket;
    170 
    171 // Sets a new value for appPath.  Used during installation to point a ticket
    172 // at the installed copy.
    173 - (void)setAppPath:(NSString*)appPath;
    174 
    175 @end  // @interface KeystoneGlue
    176 
    177 @interface KeystoneGlue(ExposedForTesting)
    178 
    179 // Load any params we need for configuring Keystone.
    180 - (void)loadParameters;
    181 
    182 // Load the Keystone registration object.
    183 // Return NO on failure.
    184 - (BOOL)loadKeystoneRegistration;
    185 
    186 - (void)stopTimer;
    187 
    188 // Called when a checkForUpdate: notification completes.
    189 - (void)checkForUpdateComplete:(NSNotification*)notification;
    190 
    191 // Called when an installUpdate: notification completes.
    192 - (void)installUpdateComplete:(NSNotification*)notification;
    193 
    194 @end  // @interface KeystoneGlue(ExposedForTesting)
    195 
    196 #endif  // __OBJC__
    197 
    198 // Functions that may be accessed from non-Objective-C C/C++ code.
    199 namespace keystone_glue {
    200 
    201 // True if Keystone is enabled.
    202 bool KeystoneEnabled();
    203 
    204 // The version of the application currently installed on disk.
    205 string16 CurrentlyInstalledVersion();
    206 
    207 }  // namespace keystone_glue
    208 
    209 #endif  // CHROME_BROWSER_COCOA_KEYSTONE_GLUE_H_
    210