OpenStep 4.2/Openstep-4.2-Intel-User.iso/NextLibrary/Documentation/NextAdmin/ReleaseNotes/Terminal.rtfd/Terminal.h

C/C++ Source or Header | 1994-07-25 | 5.2 KB | 174 lines

//
// Copyright (C) 1994 by NeXT Computer, Inc.  All rights reserved
// 940413 sam streeper created
//

#if 0

    This protocol allows applications to request that the Terminal
application perform commands on their behalf.  This is useful if
a program wants to open up a shell window for the user to interact
with, and it may be easier than setting up pipes and doing a
fork/exec of a program yourself.  The commands may be run in a window,
in which case a window handle is returned to allow a window to be
reused for subsequent commands, or they may be performed in the
background.  Additionally, you can pass in an NXData object whose
data will be fed to the command's stdin, and if you pass in a pointer
to an NXData, Terminal can hand you back the output of the commands
stdout and/or stderr.

    Terminal cannot provide services if it is not running.  It may
be necessary to use the workspace request protocol to launch
Terminal if the connection to Terminal fails.

    The following protocol is accessed through distributed objects.
For security reasons, the Terminal service is registered with the
bootstrap server rather than the netname server.

Terminal's distributed service may be disabled as follows:
    dwrite Terminal DisableDOServices YES
        (or)
    touch /NextApps/Terminal.app/.DisableDOServices

You can only get the stdout and stderr of a command if it is run in
the background.  If you pass a pointer to get these back, the data
at the pointer should be nil before invoking the command.  Upon
completion, the pointer will point to an newly created
NXData containing the output.

The following example shows how Terminal may be asked to perform a service:

//------------------------------
#import <appkit/appkit.h>
#import <mach/mach.h>
#import <mach/mach_error.h>
#import <mach/task_special_ports.h>
#import <servers/bootstrap.h>
#import <machkit/NXPort.h>
#import "/NextDeveloper/Headers/apps/Terminal.h"

main()
{
    int i, ret;
    int handle;
    NXData *myOutput=nil, *myEnv=nil;
    id <TSTerminalDOServices> terminal;
    port_t    sport;
    int err = bootstrap_look_up(bootstrap_port, "TerminalDO", &sport);
    NXPort *terminalPort;
    char *cp;

    if (err != KERN_SUCCESS) exit(-1);
    terminalPort = [NXPort newFromMachPort:sport];
    terminal = [NXConnection connectToPort:terminalPort];
    if (!terminal) exit(-1);

    for (i=0; i<8; i++)
    {
        [terminal runCommand:"echo \"Hello world.\""
            windowType: TSWindowDedicated
            windowHandle: &handle
            shellType:TSShellFastC
            windowTitle:"Echo Test"
            returnCode:&ret];
        sleep(1);
    }

    [terminal runCommand:"cd /bin; ls -la"
        windowTitle:"Listing of /bin"];

    // the following is bogus; you should compute the size
    // of the environment if you pass it in.  If you pass
    // NULL, however, the env is inherited.
    myEnv = [[NXData alloc] initWithSize:(8192)];
    cp = [myEnv data];
    strcpy(cp,"MESSAGE=Terminal is my friend!");
    while (*cp++);
    strcpy(cp,"PATH=/usr/local/bin:/usr/ucb:/usr/bin:/bin");
    while (*cp++);
    strcpy(cp,"");

    myOutput=nil;    // we only want data copied back to us
    [terminal runCommand:"ls -la; echo 'the environment:'; printenv"
        inputData:NULL
        outputData:&myOutput
        errorData:NULL
        waitForReturn:YES            // doesn't matter since there is out data
        windowType: TSWindowNone
        windowHandle: NULL
        exitAction: TSCloseOnExit    // doesn't matter, no window...
        shellType:TSShellBourne
        windowTitle:NULL
        directory:"/etc"
        environment:myEnv
        returnCode:&ret];
    printf("length:%d result is:\n%s\n",[myOutput size],[myOutput data]);
}
//------------------------------

#endif

#import <objc/Object.h>

typedef enum {
    TSWindowNone = 0,
    TSWindowIdle = 2,
    TSWindowNew = 4,
    TSWindowDedicated = 8
    } TSWindowType;

typedef enum {
    TSShellNone = 1,
    TSShellBourne = 2,
    TSShellDefault = 4,
    TSShellFastC = 8
    } TSShellType;

typedef enum {
    TSCloseOnExit = 0,
    TSCloseUnlessError = 1,
    TSDontCloseOnExit = 2
    } TSExitAction;

@protocol TSTerminalDOServices

// indicates the version implemented
- (int) protocolVersion;

// run in a new window, using fast c shell
- runCommand:(const char *)cmdString
    windowTitle:(const char *)winTitle;

// run command in a specified window
- runCommand:(const char *)cmdString
    windowType: (TSWindowType)winType
    windowHandle: (inout int *)myHandle
    shellType:(TSShellType)shellType
    windowTitle:(const char *)winTitle
    returnCode:(out int *)retCode;

// run in background using fast c shell, return stdout
- runCommand:(const char *)cmdString
    inputData:inputData                    // an NXData object for stdin
    outputData:(id *)outputData            // a pointer to an NXData object
    waitForReturn:(int)shouldWait        // synchronous even if no out data?
    directory:(const char *)workingDir    // where to cd before execution
    returnCode:(out int *)retCode;

// the full form, all others invoke this
- runCommand:(const char *)cmdString
    inputData:(id)inputData
    outputData:(id *)outputData
    errorData:(id *)errorData
    waitForReturn:(int)shouldWait        // synchronous even if no out data?
    windowType: (TSWindowType)winType
    windowHandle: (inout int *)myHandle
    exitAction: (TSExitAction)exitAction
    shellType:(TSShellType)shellType
    windowTitle:(const char *)winTitle
    directory:(const char *)workingDir
    environment:(id)environmentData        // null separated in an NXData
    returnCode:(out int *)retCode;

@end