#include "legato.h"
#include "le_limit_interface.h"

Typedefs
typedef void(*	le_appProc_DisconnectHandler_t) (void *)

typedef struct le_appProc_Ref *	le_appProc_RefRef_t

typedef struct le_appProc_StopHandler *	le_appProc_StopHandlerRef_t

typedef void(*	le_appProc_StopHandlerFunc_t) (int32_t exitCode, void *contextPtr)

Enumerations
enum	le_appProc_FaultAction_t { LE_APPPROC_FAULT_ACTION_IGNORE = 0, LE_APPPROC_FAULT_ACTION_RESTART_PROC = 1, LE_APPPROC_FAULT_ACTION_RESTART_APP = 2, LE_APPPROC_FAULT_ACTION_STOP_APP = 3, LE_APPPROC_FAULT_ACTION_REBOOT = 4 }

Functions
void	le_appProc_ConnectService (void)

le_result_t	le_appProc_TryConnectService (void)

void	le_appProc_SetServerDisconnectHandler (le_appProc_DisconnectHandler_t disconnectHandler, void *contextPtr)

void	le_appProc_DisconnectService (void)

le_appProc_RefRef_t	le_appProc_Create (const char LE_NONNULL appName, const char LE_NONNULL procName, const char *LE_NONNULL execPath)

void	le_appProc_SetStdIn (le_appProc_RefRef_t appProcRef, int stdInFd)

void	le_appProc_SetStdOut (le_appProc_RefRef_t appProcRef, int stdOutFd)

void	le_appProc_SetStdErr (le_appProc_RefRef_t appProcRef, int stdErrFd)

le_appProc_StopHandlerRef_t	le_appProc_AddStopHandler (le_appProc_RefRef_t appProcRef, le_appProc_StopHandlerFunc_t handlerPtr, void *contextPtr)

void	le_appProc_RemoveStopHandler (le_appProc_StopHandlerRef_t handlerRef)

void	le_appProc_AddArg (le_appProc_RefRef_t appProcRef, const char *LE_NONNULL arg)

void	le_appProc_ClearArgs (le_appProc_RefRef_t appProcRef)

void	le_appProc_SetPriority (le_appProc_RefRef_t appProcRef, const char *LE_NONNULL priority)

void	le_appProc_ClearPriority (le_appProc_RefRef_t appProcRef)

void	le_appProc_SetFaultAction (le_appProc_RefRef_t appProcRef, le_appProc_FaultAction_t action)

void	le_appProc_ClearFaultAction (le_appProc_RefRef_t appProcRef)

le_result_t	le_appProc_Start (le_appProc_RefRef_t appProcRef)

void	le_appProc_Delete (le_appProc_RefRef_t appProcRef)

Detailed Description

Legato Application Process Execution API include file.

Copyright (C) Sierra Wireless Inc.

Typedef Documentation

typedef void(* le_appProc_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

typedef struct le_appProc_Ref* le_appProc_RefRef_t

Reference to application process objects.

typedef void(* le_appProc_StopHandlerFunc_t) (int32_t exitCode,void *contextPtr)

A handler that is called when the application process exits.

typedef struct le_appProc_StopHandler* le_appProc_StopHandlerRef_t

Reference type used by Add/Remove functions for EVENT 'le_appProc_Stop'

Enumeration Type Documentation

enum le_appProc_FaultAction_t

Fault action for a process.

Enumerator
LE_APPPROC_FAULT_ACTION_IGNORE	A fault occured but no further action is required.
LE_APPPROC_FAULT_ACTION_RESTART_PROC	The process should be restarted.
LE_APPPROC_FAULT_ACTION_RESTART_APP	The application should be restarted.
LE_APPPROC_FAULT_ACTION_STOP_APP	The application should be terminated.
LE_APPPROC_FAULT_ACTION_REBOOT	The system should be rebooted.

Function Documentation

void le_appProc_AddArg	(	le_appProc_RefRef_t	appProcRef,
		const char *LE_NONNULL	arg
	)

Adds a command line argument to the application process.

If the application process is a configured process adding any argument means no arguments from the configuration database will be used.

Adding an empty argument validates the argument list but does not acutally add an argument. This is useful for overriding the configured arguments list with an empty argument list.

If there is an error this function will kill the calling client.

Parameters

[in]	appProcRef	Application process to start.
[in]	arg	Argument to add.

le_appProc_StopHandlerRef_t le_appProc_AddStopHandler	(	le_appProc_RefRef_t	appProcRef,
		le_appProc_StopHandlerFunc_t	handlerPtr,
		void *	contextPtr
	)

Add handler function for EVENT 'le_appProc_Stop'

Process stopped event.

Parameters

[in]	appProcRef	Application process to start.
[in]	handlerPtr	Handler for the event.
[in]	contextPtr

void le_appProc_ClearArgs ( le_appProc_RefRef_t appProcRef )

Deletes and invalidates the cmd-line arguments to a process and use the configured arguments if available.

Note: If the caller is passing an invalid reference to the application process, it is a fatal error, the function will not return.

Parameters

[in] appProcRef Application process to start.

void le_appProc_ClearFaultAction ( le_appProc_RefRef_t appProcRef )

Clears the application process's fault action and use either the configured fault action or the default.

Note: If the caller is passing an invalid reference to the application process, it is a fatal error, the function will not return.

Parameters

[in] appProcRef Application process to start.

void le_appProc_ClearPriority ( le_appProc_RefRef_t appProcRef )

Clears the application process's priority and use either the configured priority or the default.

Note: If the caller is passing an invalid reference to the application process, it is a fatal error, the function will not return.

Parameters

[in] appProcRef Application process to start.

void le_appProc_ConnectService ( void )

Connect the current client thread to the service providing this API. Block until the service is available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

le_appProc_RefRef_t le_appProc_Create	(	const char *LE_NONNULL	appName,
		const char *LE_NONNULL	procName,
		const char *LE_NONNULL	execPath
	)

Creates a process in an app. This function can be used to create and subsequently start a process in an application that the application normally would not start on its own. This function does not actually start the process, use Start() to start the process.

If the specified process name matches a name in the app's list of configured processes then runtime parameters such as environment variables, priority, etc. will be taken from the configuration database. Otherwise default parameters will be used.

Parameters can be overridden by the other functions in this API such as AddArg(), SetPriority(), etc.

If the executable path is empty and the process name matches a configured process then the configured executable is used. Otherwise the specified executable path is used.

Either the process name or the executable path may be empty but not both.

It is an error to call this function on a configured process that is already running.

Returns: Reference to the application process object if successful. NULL if there was an error.

Note: If the application or process names pointers are null or if their strings are empty or of bad format it is a fatal error, the function will not return.

Parameters

[in]	appName	Name of the app.
[in]	procName	Name of the process.
[in]	execPath	Path to the executable file.

void le_appProc_Delete ( le_appProc_RefRef_t appProcRef )

Deletes the application process object.

Note: If the caller is passing an invalid reference to the application process, it is a fatal error, the function will not return.

Parameters

[in] appProcRef Application process to start.

void le_appProc_DisconnectService ( void )

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client-specific Functions.

This function is created automatically.

void le_appProc_RemoveStopHandler ( le_appProc_StopHandlerRef_t handlerRef )

Remove handler function for EVENT 'le_appProc_Stop'

Parameters

[in] handlerRef

void le_appProc_SetFaultAction	(	le_appProc_RefRef_t	appProcRef,
		le_appProc_FaultAction_t	action
	)

Sets the application process's fault action.

Note: If the caller is passing an invalid reference to the application process, it is a fatal error, the function will not return.

Parameters

[in]	appProcRef	Application process to start.
[in]	action	Fault action for the application process.

void le_appProc_SetPriority	(	le_appProc_RefRef_t	appProcRef,
		const char *LE_NONNULL	priority
	)

Sets the application process's priority.

The priority string must be either 'idle','low', 'medium', 'high', 'rt1', 'rt2'...'rt32'.

If there is an error this function will kill the client.

Parameters

[in]	appProcRef	Application process to start.
[in]	priority	Priority for the application process.

void le_appProc_SetServerDisconnectHandler	(	le_appProc_DisconnectHandler_t	disconnectHandler,
		void *	contextPtr
	)

Set handler called when server disconnection is detected.

When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants to continue without exiting, it should call longjmp() from inside the handler.

void le_appProc_SetStdErr	(	le_appProc_RefRef_t	appProcRef,
		int	stdErrFd
	)

Sets the file descriptor that the application process's standard err should be attached to.

By default the standard err is directed to the logs.

If there is an error this function will kill the calling process

Parameters

[in]	appProcRef	Application process to start.
[in]	stdErrFd	File descriptor to use as the app proc's standard error. -1 means direct to logs.

void le_appProc_SetStdIn	(	le_appProc_RefRef_t	appProcRef,
		int	stdInFd
	)

Sets the file descriptor that the application process's standard in should be attached to.

By default the standard in is directed to /dev/null.

If there is an error this function will kill the calling process

Parameters

[in]	appProcRef	Application process to start.
[in]	stdInFd	File descriptor to use as the app proc's standard in. -1 means direct to /dev/null.

void le_appProc_SetStdOut	(	le_appProc_RefRef_t	appProcRef,
		int	stdOutFd
	)

Sets the file descriptor that the application process's standard out should be attached to.

By default the standard out is directed to the logs.

If there is an error this function will kill the calling process

Parameters

[in]	appProcRef	Application process to start.
[in]	stdOutFd	File descriptor to use as the app proc's standard out. -1 means direct to logs.

le_result_t le_appProc_Start ( le_appProc_RefRef_t appProcRef )

Starts the application process. If the application was not running this function will start it first.

Returns: LE_OK if successful. LE_FAULT if there was some other error.

Note: If the caller is passing an invalid reference to the application process, it is a fatal error, the function will not return.

Parameters

[in] appProcRef Application process to start.

le_result_t le_appProc_TryConnectService ( void )

Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

Returns

LE_OK if the client connected successfully to the service.
LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
LE_COMM_ERROR if the Service Directory cannot be reached.

/ Build Apps

le_appProc_interface.h File Reference

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation