PageRenderTime 27ms CodeModel.GetById 17ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

C++ Header | 143 lines | 31 code | 12 blank | 100 comment | 0 complexity | 3c32fd18a1522ebc97bdb06da57d0863 MD5 | raw file
  1// Copyright 2008 Google Inc.
  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
  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.
 15#import <Foundation/Foundation.h>
 16#import "KSAction.h"
 18@class KSActionProcessor;
 20// KSDownloadAction
 22// An action that downloads a URL to a file on disk, and ensures that the
 23// downloaded file matches a known SHA-1 hash value and file size. See the
 24// KSAction.h for more general comments about actions in general. A
 25// KSDownloadAction is created with a URL to be downloaded, a Base64 encoded
 26// SHA-1 hash value that should match the downloaded data (this should be
 27// obtained from a trusted source) and the file size, and a path where the
 28// downloaded file should be saved.
 30// KSDownloadAction never removes files that it downloads. If cleanup is
 31// necessary, that is the responsibility of the caller. KSDownloadAction uses
 32// the fact that a download may already exist at a specified path to short
 33// circuit downloads if the download already exists. Before starting a download,
 34// KSDownloadAction first checks to see if a file alread exists at the
 35// destination path, and if one exists, it checks if that file's hash value
 36// matches the hash value that the KSDownloadAction was created with. If they
 37// match, then the desired file has already been downloaded and the download can
 38// be skipped. If they file does not exist, or the hash values do not match,
 39// then a regular download will be done and the file on disk will be overwritten
 40// if it already existed.
 42// Input-Output
 44// KSDownloadAction does not use its inPipe for anything. However, when a
 45// download finishes successfully, the path (NSString *) to the downloaded file
 46// is stored in its outPipe. It's up to you whether or not you care about this
 47// path.
 49// To use this action you will need to create an instance of KSDownloadAction,
 50// add it to a KSActionProcessor, and tell the action processor to start
 51// processing. Once the processing is finished, the absolute file path to the
 52// downloaded data will be available as an NSString in the downloads |outPipe|
 53// If the download failed, the outPipe's contents will be nil. Here is an
 54// example that downloads the Google logo from the Google homepage.
 56//   NSURL *url = [NSURL URLWithString:
 57//     @""];
 59//   NSString *hash = ... Base64 encoded SHA-1 hash of data from |url| ...
 60//   unsigned long long size = ... the size of the data from |url| ...
 62//   KSDownloadAction *download = [KSDownloadAction actionWithURL:url
 63//                                                           size:size
 64//                                                           hash:hash
 65//                                                           name:@"foo.gif"];
 67//   KSActionProcessor *ap = [[[KSActionProcessor alloc] init] autorelease];
 68//   [ap enqueueAction:download];
 70//   [ap startProcessing];  // This runs starts the download action
 72//   ... spin runloop to let the download complete ...
 74//   NSString *path = nil;
 75//   if (![download isRunning])  // Make sure the download is done
 76//     path = [[download outPipe] contents];
 78//   ... |path| is the path to the downloaded file that matches |hash| ...
 79@interface KSDownloadAction : KSAction {
 80 @private
 81  NSURL *url_;
 82  unsigned long long size_;
 83  NSString *hash_;
 84  NSString *path_;      // See comments at the top of the .m for details about
 85  NSString *tempPath_;  // the difference between path_ and tempPath_.
 86  NSTask *downloadTask_;
 87  NSString *ksurlPath_;
 90// Returns the absolute path to the default directory to be used for downloads.
 91// This path is used when instances are created with the
 92// +actionWithURL:hash:name: convenience method.
 94// Note that we don't use Library/Caches/Google because historically this
 95// directory has been created with a mode of 0777 (note no sticky bit) and this
 96// is too insecure for us. So instead we'll simply use a directory in
 97// Library/Caches/<uid>/Downloads, which has a
 98// mode that we're happy with. This also seems to be the standard way that Apple
 99// apps use Library/Caches.
100+ (NSString *)defaultDownloadDirectory;
102// Returns an autoreleased KSDownloadAction for the specified url, hash, and
103// name. The destination path where the downloaded file will be saved is
104// constructed by appending "name" to the path obtained from
105// +defaultDownloadDirectory.
106+ (id)actionWithURL:(NSURL *)url
107               size:(unsigned long long)size
108               hash:(NSString *)hash
109               name:(NSString *)name;
111// Returns an autoreleased KSDownloadAction for the specified url, hash, and
112// size, that will be saved to |path|.
113+ (id)actionWithURL:(NSURL *)url
114               size:(unsigned long long)size
115               hash:(NSString *)hash
116               path:(NSString *)path;
118// Designated initializer. Returns a KSDownloadAction that will download the
119// data at |url| and save it in a file named |path|. This action will also
120// verify that the downloaded file's SHA-1 hash is equal to |hash|.  All
121// parameters are required and may not be nil.
122- (id)initWithURL:(NSURL *)url
123             size:(unsigned long long)size
124             hash:(NSString *)hash
125             path:(NSString *)path;
127// Returns the URL to be downloaded. The base64 encoded SHA-1 hash value of the
128// data from this URL should match the value of -hash.
129- (NSURL *)url;
131// Returns the size that the data downloaded from the URL should be.
132- (unsigned long long)size;
134// Returns the hash value that downloaded data should have. This returns the
135// hash value that this instance was created with. It is a dumb "getter". It
136// does not actually calculate the hash value.
137- (NSString *)hash;
139// The path where the downloaded file should be placed once it has been
140// succesfully downloaded.
141- (NSString *)path;