le_appProc_interface.h File Reference

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

Go to the source code of this file.

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.

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

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]appProcRefApplication process to start.
[in]argArgument 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]appProcRefApplication process to start.
[in]handlerPtrHandler 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]appProcRefApplication 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]appProcRefApplication 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]appProcRefApplication 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]appNameName of the app.
[in]procNameName of the process.
[in]execPathPath 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]appProcRefApplication 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]appProcRefApplication process to start.
[in]actionFault 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]appProcRefApplication process to start.
[in]priorityPriority 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]appProcRefApplication process to start.
[in]stdErrFdFile 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]appProcRefApplication process to start.
[in]stdInFdFile 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]appProcRefApplication process to start.
[in]stdOutFdFile 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]appProcRefApplication 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.