| << Prev | appCORE Programming Guide | Next >> |
NAME
coreMain() -- main() function for a standard appCORE application.
SYNOPSIS
include "appcore.h" int coreMain( coreSPEC_t s1, coreAppSPEC_t* s2 )
DESCRIPTION
The coreMain() function implements the standard appCORE application structure.
The coreSPEC_t data type is used to configure appCORE, and the coreAppSPEC_t data type is used to configure the application. Always zero both elements before setting the desired parameters to insure reliable operation, default behavior, and compatibility with future releases.
The coreMain() function first initializes appCORE, then starts the main application thread. This function waits for the main application thread to exit. Before returning, appCORE is de-initialized and the status is returned.
PARAMETERS
s1
typedef struct _core_spec_
{
char ConfigFileName[ MAX_PATH + 1 ];
Specifies the full path name to the appCORE configuration file as a null
terminated string. This element is optional. Parameters defined in this
configuration file take precedence over parameters specified in this
specification record. This allows for control of the application without
recompiling.
char AppName[ CORE_APP_NAME_LEN + 1 ];
The name of the application as a null terminated string. This name
appears in the startup banner, can be accessed via a command session,
and appears in logging output. This element is optional. The configuration
file entry is "app.name".
char AppVersion[ CORE_APP_VERSION_LEN + 1 ];
The version of the application as a null terminated string. This version
appears in the startup banner and can be accessed via a command session.
This element is optional. The configuration file entry is "app.version".
char AppLockFileName[ MAX_PATH + 1 ];
Specifies the full path name to the application's lock file as a null
terminated string. If specified, the application will check for the existence
of this file. If found, the function will fail with a return code of -1 and
set errno to EEXIST. If not found, the application will create a file of this
name that contains the process identifier (PID). On application exit, the file
is deleted. This element is optional. The configuration file entry is
"app.lockfile.name". On some platforms, if the file contains a stale PID, it
is automatically deleted.
int coreSyslogOn;
If non-zero, appCORE starts the Syslog component and the Syslog parameters
below must be set for correct operation. The configuration file entry is
"core.syslog.on".
int AppCmdSesLocalOn;
If non-zero, the application will present a command session using stdin and
stdout. Also, logging output will be displayed on stdout. The configuration
file entry is "app.console.on"
int AppCmdSesPort;
If non-zero, the application will listen on this port for incoming
TCP connections. The application will create a command session for each
connection. Multiple command session connections are supported. The config-
uration file entry is "app.cmd.port".
coreSAI AppCmdSesBindAddr;
If non-zero, specifies the binding address for the network command session.
If not specified, the port will be bound to INADDR_ANY. The configuration file
entry is "app.cmd.bindaddr".
int coreTimerOff;
The timer facility is a standard appCORE feature and is enabled by default.
To disable the timer component, this value must be non-zero. The configuration
file entry is "core.timer.off".
int coreNetworkOff;
The network facility is a standard appCORE feature and is enabled by default.
To disable the network component, this value must be non-zero. The configuration
file entry is "core.network.off".
int coreSignalOff;
The signal handler facility is a standard appCORE feature and is enabled by
default. To disable the signal handler component, this value must be non-zero.
The configuration file entry is "core.signal.off". All platforms support some
level of signal handling.
int coreMsgPoolOff;
The message pool facility is a standard appCORE feature and is enabled by
default. To disable the message pool and use the heap directly for each
message allocation and free operation, this value must be non-zero. The
configuration file entry is "core.msgpool.off".
int coreStatsMemOn;
If non-zero, enables the collection of memory statistics. Default behavior
is off.
int coreStatsMsgOn;
If non-zero, enables the collection of message statistics. Default behavior
is off.
int coreStatsThrOn;
If non-zero, enables the collection of thread statistics. Default behavior
is off.
coreSAI coreSysLogAddr;
If non-zero, defines the send address of a syslog connection.
unsigned short coreSysLogPort;
If non-zero, defines the port address of the Syslog connection.
unsigned int coreSysLogOptions;
Defines Syslog options
unsigned char LogLevel[ LZ_MAX - LZ_START ];
The LogLevel array provides a way to specify any appCORE trace zones before
appCORE is started. The specified trace zone levels are copied into the main
control block. Trace zones can be initialized via the coreLogZoneInit()
function.
}
coreSPEC_t;
s2
typedef struct _core_app_spec_
{
void* ParamBlock;
The parameter block is passed to the StartUp function as the first argument.
This is how an arbitrary number of parameters can be passed to the thread's
startup function. This parameter is optional. It's use is up to the user.
int (*StartUp)( void* ParamBlock, void** ppCntxt );
The startup function. This function is called by the dispatch thread. This
function should not block. This function should perform whatever startup
processing is required. The first argument is the ParamBlock discussed above.
This is used to pass any parameters to the thread's startup function. The
second argument is a pointer to the thread's context pointer. The startup
function can create a context and return it to appCORE via this element.
This context is then passed to functions below. This parameter is optional.
int (*MsgHandler)( void* pCntxt, coreMsg_t* );
The main message processing, or dispatching, function. This function is called
with the thread context and a message. Normally this function is a simple switch
statement based on message type. This function should not block. This function
does not free the message pointer. appCORE manages message resources. This
parameter is required.
int (*ShutDown)( void* pCntxt );
The shutdown function. This function is called by the dispatch thread before the
dispatch thread exits. This function should perform whatever shutdown processing
is required. This parameter is optional.
int (*SignalHandler)( void* pCntxt, int Signal );
The signal handler function. This function is called in response to a signal.
This parameter is optional. If this function returns a non-zero value, the
appCORE shut down process is initiated. If the handler is NULL, normal appCORE
signal handling occurs.
void (*LogHandler)( const char* );
The custom log handler. If defined, this function is called with a null
terminated string containing the final output of appCORE log output. This
parameter can be NULL, in which case appCORE will display output to a console,
if requested, or to a syslog interface.
void (*ThreadBegin)( void* pCntxt );
If defined, this function is called by each thread when starting.
void (*ThreadEnd)( void* pCntxt );
If defined, this function is called before each thread exits.
unsigned char LogLevel[ LZ_START ];
The LogLevel array provides a way to specify any application defined log zone
setting before the main dispatcher is started. The specified trace zone levels
are copied into the main control block. The default range is 0 to
CORE_LOG_ZONE_START. The default value of CORE_LOG_ZONE_START is 100, allowing
100 user defined log zones. The function coreAppLogZoneInit() should be used to
initialize this array.
}
coreAppSPEC_t;
RETURN VALUE
coreInit() and coreAppStart() are called by coreMain().
| errno Value | Condition |
| EINVAL | Argument NULL or message handler function not defined. |
| ECANCELED | appCORE not in the initialized (INIT) state, or startup function failed. |
MULTI-THREAD SAFETY LEVEL
MT-safe.
SEE ALSO
| << Prev | appCORE Programming Guide | Next >> |