/core/externals/update-engine/Core/KSCommandRunner.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
17
18// KSCommandRunner
19//
20// Protocol that defines the methods that must be implemented by any object that
21// can act as a "command runner". A command runner object is an object that can
22// run a command for you, and return you the results.
23@protocol KSCommandRunner <NSObject>
24
25// This method runs the command at |path|, with the specified |args| and |env|,
26// and return the commands output in |*output| and the command's return code as
27// the return value of this method.
28//
29// Args:
30//   path - the full path of the command to be executed
31//   args - an array of arguments to give to the command; may be nil
32//   env - a dictionary of environment variables to be set; may be nil
33//   output - returns the command's output; may not be nil.  Don't even try it.
34//            Why?  Tiger gets confused sending a nil NSString **.
35//            Passing nil on the server side leads to the client
36//            actually getting passed a non-nil pointer to an
37//            NSString.  This **pointer gets an NSString assigned
38//            to it, which then causes DO to crash deep in its guts
39//            on the client side trying to return the value.
40//   stdError - returns text emitted from standard error.  Like for output,
41//              don't pass nil.
42//
43// Returns:
44//   The return code is the return code from the command, and |output| will be
45//   filled in with the command's output.  |stderror| will be filled in with 
46//   the command's standard error.
47- (int)runCommand:(NSString *)path
48         withArgs:(NSArray *)args
49      environment:(NSDictionary *)env
50           output:(NSString **)output
51         stdError:(NSString **)stderror;
52
53// Simpler version that doesn't return standard error.
54- (int)runCommand:(NSString *)path
55         withArgs:(NSArray *)args
56      environment:(NSDictionary *)env
57           output:(NSString **)output;
58@end
59
60
61// KSTaskCommandRunner
62//
63// This class is used to run external commands (via NSTask) with given args and
64// environment, and will return the standard output of the command along with
65// the command's return code.
66@interface KSTaskCommandRunner : NSObject <KSCommandRunner>
67
68// Returns an autoreleased KSCommandRunner instance
69+ (id)commandRunner;
70
71@end