browser/cocoa/keystone_glue.h

// Copyright (c) 2009 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef CHROME_BROWSER_COCOA_KEYSTONE_GLUE_H_
#define CHROME_BROWSER_COCOA_KEYSTONE_GLUE_H_

#include "base/string16.h"

#if defined(__OBJC__)

#import <Foundation/Foundation.h>

#import "base/scoped_nsobject.h"
#include "chrome/browser/cocoa/scoped_authorizationref.h"

// Possible outcomes of various operations.  A version may accompany some of
// these, but beware: a version is never required.  For statuses that can be
// accompanied by a version, the comment indicates what version is referenced.
// A notification posted containing an asynchronous status will always be
// followed by a notification with a terminal status.
enum AutoupdateStatus {
  kAutoupdateNone = 0,        // no version (initial state only)
  kAutoupdateRegistering,     // no version (asynchronous operation in progress)
  kAutoupdateRegistered,      // no version
  kAutoupdateChecking,        // no version (asynchronous operation in progress)
  kAutoupdateCurrent,         // version of the running application
  kAutoupdateAvailable,       // version of the update that is available
  kAutoupdateInstalling,      // no version (asynchronous operation in progress)
  kAutoupdateInstalled,       // version of the update that was installed
  kAutoupdatePromoting,       // no version (asynchronous operation in progress)
  kAutoupdatePromoted,        // no version
  kAutoupdateRegisterFailed,  // no version
  kAutoupdateCheckFailed,     // no version
  kAutoupdateInstallFailed,   // no version
  kAutoupdatePromoteFailed,   // no version
};

// kAutoupdateStatusNotification is the name of the notification posted when
// -checkForUpdate and -installUpdate complete.  This notification will be
// sent with with its sender object set to the KeystoneGlue instance sending
// the notification.  Its userInfo dictionary will contain an AutoupdateStatus
// value as an intValue at key kAutoupdateStatusStatus.  If a version is
// available (see AutoupdateStatus), it will be present at key
// kAutoupdateStatusVersion.
extern NSString* const kAutoupdateStatusNotification;
extern NSString* const kAutoupdateStatusStatus;
extern NSString* const kAutoupdateStatusVersion;

namespace {

enum BrandFileType {
  kBrandFileTypeNotDetermined = 0,
  kBrandFileTypeNone,
  kBrandFileTypeUser,
  kBrandFileTypeSystem,
};

} // namespace

// KeystoneGlue is an adapter around the KSRegistration class, allowing it to
// be used without linking directly against its containing KeystoneRegistration
// framework.  This is used in an environment where most builds (such as
// developer builds) don't want or need Keystone support and might not even
// have the framework available.  Enabling Keystone support in an application
// that uses KeystoneGlue is as simple as dropping
// KeystoneRegistration.framework in the application's Frameworks directory
// and providing the relevant information in its Info.plist.  KeystoneGlue
// requires that the KSUpdateURL key be set in the application's Info.plist,
// and that it contain a string identifying the update URL to be used by
// Keystone.

@class KSRegistration;

@interface KeystoneGlue : NSObject {
 @protected

  // Data for Keystone registration
  NSString* productID_;
  NSString* appPath_;
  NSString* url_;
  NSString* version_;
  NSString* channel_;  // Logically: Dev, Beta, or Stable.
  BrandFileType brandFileType_;

  // And the Keystone registration itself, with the active timer
  KSRegistration* registration_;  // strong
  NSTimer* timer_;  // strong

  // The most recent kAutoupdateStatusNotification notification posted.
  scoped_nsobject<NSNotification> recentNotification_;

  // The authorization object, when it needs to persist because it's being
  // carried across threads.
  scoped_AuthorizationRef authorization_;

  // YES if a synchronous promotion operation is in progress (promotion during
  // installation).
  BOOL synchronousPromotion_;

  // YES if an update was ever successfully installed by -installUpdate.
  BOOL updateSuccessfullyInstalled_;
}

// Return the default Keystone Glue object.
+ (id)defaultKeystoneGlue;

// Load KeystoneRegistration.framework if present, call into it to register
// with Keystone, and set up periodic activity pings.
- (void)registerWithKeystone;

// -checkForUpdate launches a check for updates, and -installUpdate begins
// installing an available update.  For each, status will be communicated via
// a kAutoupdateStatusNotification notification, and will also be available
// through -recentNotification.
- (void)checkForUpdate;
- (void)installUpdate;

// Accessor for recentNotification_.  Returns an autoreleased NSNotification.
- (NSNotification*)recentNotification;

// Accessor for the kAutoupdateStatusStatus field of recentNotification_'s
// userInfo dictionary.
- (AutoupdateStatus)recentStatus;

// Returns YES if an asynchronous operation is pending: if an update check or
// installation attempt is currently in progress.
- (BOOL)asyncOperationPending;

// Returns YES if the application is running from a read-only filesystem,
// such as a disk image.
- (BOOL)isOnReadOnlyFilesystem;

// -needsPromotion is YES if the application needs its ticket promoted to
// a system ticket.  This will be YES when the application is on a user
// ticket and determines that the current user does not have sufficient
// permission to perform the update.
//
// -wantsPromotion is YES if the application wants its ticket promoted to
// a system ticket, even if it doesn't need it as determined by
// -needsPromotion.  -wantsPromotion will always be YES if -needsPromotion is,
// and it will additionally be YES when the application is on a user ticket
// and appears to be installed in a system-wide location such as
// /Applications.
//
// Use -needsPromotion to decide whether to show any update UI at all.  If
// it's YES, there's no sense in asking the user to "update now" because it
// will fail given the rights and permissions involved.  On the other hand,
// when -needsPromotion is YES, the application can encourage the user to
// promote the ticket so that updates will work properly.
//
// Use -wantsPromotion to decide whether to allow the user to promote.  The
// user shouldn't be nagged about promotion on the basis of -wantsPromotion,
// but if it's YES, the user should be allowed to promote the ticket.
- (BOOL)needsPromotion;
- (BOOL)wantsPromotion;

// Promotes the Keystone ticket into the system store.  System Keystone will
// be installed if necessary.  If synchronous is NO, the promotion may occur
// in the background.  synchronous should be YES for promotion during
// installation. The KeystoneGlue object assumes ownership of
// authorization_arg.
- (void)promoteTicketWithAuthorization:(AuthorizationRef)authorization_arg
                           synchronous:(BOOL)synchronous;

// Requests authorization and calls -promoteTicketWithAuthorization: in
// asynchronous mode.
- (void)promoteTicket;

// Sets a new value for appPath.  Used during installation to point a ticket
// at the installed copy.
- (void)setAppPath:(NSString*)appPath;

@end  // @interface KeystoneGlue

@interface KeystoneGlue(ExposedForTesting)

// Load any params we need for configuring Keystone.
- (void)loadParameters;

// Load the Keystone registration object.
// Return NO on failure.
- (BOOL)loadKeystoneRegistration;

- (void)stopTimer;

// Called when a checkForUpdate: notification completes.
- (void)checkForUpdateComplete:(NSNotification*)notification;

// Called when an installUpdate: notification completes.
- (void)installUpdateComplete:(NSNotification*)notification;

@end  // @interface KeystoneGlue(ExposedForTesting)

#endif  // __OBJC__

// Functions that may be accessed from non-Objective-C C/C++ code.
namespace keystone_glue {

// True if Keystone is enabled.
bool KeystoneEnabled();

// The version of the application currently installed on disk.
string16 CurrentlyInstalledVersion();

}  // namespace keystone_glue

#endif  // CHROME_BROWSER_COCOA_KEYSTONE_GLUE_H_