## AnjutaLauncher AnjutaLauncher — External process launcher with async input/output |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libanjuta/anjuta-launcher.h>

    struct              AnjutaLauncher;
    struct              AnjutaLauncherClass;
    void                (*AnjutaLauncherOutputCallback)     (AnjutaLauncher *launcher,
                                                             AnjutaLauncherOutputType output_type,
                                                             const gchar *chars,
                                                             gpointer user_data);
    enum                AnjutaLauncherOutputType;
                        AnjutaLauncherPriv;
    gboolean            anjuta_launcher_execute             (AnjutaLauncher *launcher,
                                                             const gchar *command_str,
                                                             AnjutaLauncherOutputCallback callback,
                                                             gpointer callback_data);
    gboolean            anjuta_launcher_execute_v           (AnjutaLauncher *launcher,
                                                             gchar *const dir,
                                                             gchar *const argv[],
                                                             gchar *const envp[],
                                                             AnjutaLauncherOutputCallback callback,
                                                             gpointer callback_data);
    pid_t               anjuta_launcher_get_child_pid       (AnjutaLauncher *launcher);
    gboolean            anjuta_launcher_is_busy             (AnjutaLauncher *launcher);
    AnjutaLauncher *    anjuta_launcher_new                 (void);
    void                anjuta_launcher_reset               (AnjutaLauncher *launcher);
    void                anjuta_launcher_send_ptyin          (AnjutaLauncher *launcher,
                                                             const gchar *input_str);
    void                anjuta_launcher_send_stdin          (AnjutaLauncher *launcher,
                                                             const gchar *input_str);
    void                anjuta_launcher_send_stdin_eof      (AnjutaLauncher *launcher);
    gboolean            anjuta_launcher_set_buffered_output (AnjutaLauncher *launcher,
                                                             gboolean buffered);
    gboolean            anjuta_launcher_set_check_passwd_prompt
                                                            (AnjutaLauncher *launcher,
                                                             gboolean check_passwd);
    void                anjuta_launcher_set_encoding        (AnjutaLauncher *launcher,
                                                             const gchar *charset);
    gboolean            anjuta_launcher_set_terminal_echo   (AnjutaLauncher *launcher,
                                                             gboolean echo_on);
    gboolean            anjuta_launcher_set_terminate_on_exit
                                                            (AnjutaLauncher *launcher,
                                                             gboolean terminate_on_exit);
    void                anjuta_launcher_signal              (AnjutaLauncher *launcher,
                                                             int sig);

## Object Hierarchy

      GObject
       +----AnjutaLauncher

## Signals

      "busy"                                           : Run First
      "child-exited"                                   : Run First

## Description

## Details

### struct AnjutaLauncher

    struct AnjutaLauncher;

### struct AnjutaLauncherClass

    struct AnjutaLauncherClass {
        GObjectClass parent_class;

    	/* Signals */
    	void (*child_exited) (AnjutaLauncher *launcher,
    						  int child_pid, int exit_status,
    						  gulong time_taken_in_seconds);
    	void (*busy) (AnjutaLauncher *launcher, gboolean busy_flag);
    };

### AnjutaLauncherOutputCallback ()

    void                (*AnjutaLauncherOutputCallback)     (AnjutaLauncher *launcher,
                                                             AnjutaLauncherOutputType output_type,
                                                             const gchar *chars,
                                                             gpointer user_data);

This callback is called when new characters arrive from the launcher execution.

`launcher` : | a AnjutaLauncher object
`output_type` : | Type of the output
`chars` : | Characters being outputed
`user_data` : | User data passed back to the user

### enum AnjutaLauncherOutputType

    typedef enum {
    	ANJUTA_LAUNCHER_OUTPUT_STDOUT,
    	ANJUTA_LAUNCHER_OUTPUT_STDERR,
    	ANJUTA_LAUNCHER_OUTPUT_PTY
    } AnjutaLauncherOutputType;

### AnjutaLauncherPriv

    typedef struct _AnjutaLauncherPriv AnjutaLauncherPriv;

### anjuta_launcher_execute ()

    gboolean            anjuta_launcher_execute             (AnjutaLauncher *launcher,
                                                             const gchar *command_str,
                                                             AnjutaLauncherOutputCallback callback,
                                                             gpointer callback_data);

Executes a command in the launcher. Both outputs (STDOUT and STDERR) are delivered to the above callback. The data are delivered as they arrive from the process and could be of any lenght. If the process asks for passwords, the user will be automatically prompted with a dialog to enter it. Please note that not all formats of the password are recognized. Those with the standard 'assword:' substring in the prompt should work well.

`launcher` : | a AnjutaLancher object.
`command_str` : | The command to execute.
`callback` : | The callback for delivering output from the process.
`callback_data` : | Callback data for the above callback.
Returns : | TRUE if successfully launched, otherwise FALSE.

### anjuta_launcher_execute_v ()

    gboolean            anjuta_launcher_execute_v           (AnjutaLauncher *launcher,
                                                             gchar *const dir,
                                                             gchar *const argv[],
                                                             gchar *const envp[],
                                                             AnjutaLauncherOutputCallback callback,
                                                             gpointer callback_data);

The first of the `args` is the command itself. The rest are sent to the as it's arguments. This function works similar to `anjuta_launcher_execute()`.

`launcher` : | a AnjutaLancher object.
`dir` : | Working directory or NULL.
`argv` : | Command args.
`envp` : | Additional environment variable.
`callback` : | The callback for delivering output from the process.
`callback_data` : | Callback data for the above callback.
Returns : | TRUE if successfully launched, otherwise FALSE.

### anjuta_launcher_get_child_pid ()

    pid_t               anjuta_launcher_get_child_pid       (AnjutaLauncher *launcher);

Gets the Process ID of the child being executed.

`launcher` : | a AnjutaLancher object.
Returns : | Process ID of the child.

### anjuta_launcher_is_busy ()

    gboolean            anjuta_launcher_is_busy             (AnjutaLauncher *launcher);

Tells if the laucher is currently executing any command.

`launcher` : | a AnjutaLancher object.
Returns : | TRUE if launcher is busy, otherwisee FALSE.

### anjuta_launcher_new ()

    AnjutaLauncher *    anjuta_launcher_new                 (void);

Sets if input (those given in STDIN) should enabled or disabled. By default, it is disabled.

Returns : | a new instance of AnjutaLancher class.

### anjuta_launcher_reset ()

    void                anjuta_launcher_reset               (AnjutaLauncher *launcher);

Resets the launcher and kills (SIGTERM) current process, if it is still executing.

`launcher` : | a AnjutaLancher object.

### anjuta_launcher_send_ptyin ()

    void                anjuta_launcher_send_ptyin          (AnjutaLauncher *launcher,
                                                             const gchar *input_str);

Sends a string to TTY input of the process currently being executed. Mostly useful for entering passwords and other inputs which are directly read from TTY input of the process.

`launcher` : | a AnjutaLancher object.
`input_str` : | The string to send to PTY of the process.

### anjuta_launcher_send_stdin ()

    void                anjuta_launcher_send_stdin          (AnjutaLauncher *launcher,
                                                             const gchar *input_str);

Sends a EOF to Standard input of the process currently being executed.

`launcher` : | a AnjutaLancher object.

### anjuta_launcher_send_stdin_eof ()

    void                anjuta_launcher_send_stdin_eof      (AnjutaLauncher *launcher);

### anjuta_launcher_set_buffered_output ()

    gboolean            anjuta_launcher_set_buffered_output (AnjutaLauncher *launcher,
                                                             gboolean buffered);

Sets if output should buffered or not. By default, it is buffered.

`launcher` : | a AnjutaLancher object.
`buffered` : | buffer output.
Returns : | Previous flag value

### anjuta_launcher_set_check_passwd_prompt ()

    gboolean            anjuta_launcher_set_check_passwd_prompt
                                                            (AnjutaLauncher *launcher,
                                                             gboolean check_passwd);

Set if output is checked for a password prompti. A special dialog box is use to enter it in this case. By default, this behavior is enabled.

`launcher` : | a AnjutaLancher object.
`check_passwd` : | check for password.
Returns : | Previous flag value

### anjuta_launcher_set_encoding ()

    void                anjuta_launcher_set_encoding        (AnjutaLauncher *launcher,
                                                             const gchar *charset);

Sets the character set to use for Input/Output with the process.

`launcher` : | a AnjutaLancher object.
`charset` : | Character set to use for Input/Output with the process.

### anjuta_launcher_set_terminal_echo ()

    gboolean            anjuta_launcher_set_terminal_echo   (AnjutaLauncher *launcher,
                                                             gboolean echo_on);

Sets if input (those given in STDIN) should enabled or disabled. By default, it is disabled.

`launcher` : | a AnjutaLancher object.
`echo_on` : | Echo ON flag.
Returns : | Previous flag value

### anjuta_launcher_set_terminate_on_exit ()

    gboolean            anjuta_launcher_set_terminate_on_exit
                                                            (AnjutaLauncher *launcher,
                                                             gboolean terminate_on_exit);

When this flag is set, al i/o channels are closed and the child-exit signal is emitted as soon as the child exit. By default, or when this flag is clear, the launcher object wait until the i/o channels are closed.

`launcher` : | a AnjutaLancher object.
`terminate_on_exit` : | terminate on exit flag
Returns : | Previous flag value

### anjuta_launcher_signal ()

    void                anjuta_launcher_signal              (AnjutaLauncher *launcher,
                                                             int sig);

Sends a kernel signal to the process that is being executed.

`launcher` : | a AnjutaLancher object.
`sig` : | kernel signal ID (e.g. SIGTERM).

## Signal Details

### The `"busy"` signal

    void                user_function                      (AnjutaLauncher *launcher,
                                                            gboolean        busy,
                                                            gpointer        user_data)      : Run First

Emitted when a child starts after a call to one execute function (busy is TRUE) or when a child exits and all i/o channels are closed (busy is FALSE).

`launcher` : | a AnjutaLancher object.
`busy` : | TRUE is a child is currently running
`user_data` : | user data set when the signal handler was connected.

### The `"child-exited"` signal

    void                user_function                      (AnjutaLauncher *launcher,
                                                            gint            child_pid,
                                                            gint            status,
                                                            gulong          time,
                                                            gpointer        user_data)      : Run First

Emitted when the child has exited and all i/o channels have been closed. If the terminate on exit flag is set, the i/o channels are automatically closed when the child exit. You need to use WEXITSTATUS and friend to get the child exit code from the status returned.

`launcher` : | a AnjutaLancher object.
`child_pid` : | process ID of the child
`status` : | status as returned by waitpid function
`time` : | time in seconds taken by the child
`user_data` : | user data set when the signal handler was connected.