Authors
- Richard Frith-Macdonald (
rfm@gnu.org
)
-
Copyright: (C) 2012 Free Software Foundation, Inc.
- Declared in:
- EcProcess.h
- Conforms to:
- CmdClient
- EcAlarmDestination
Command line arguments -
On startup, these are taken from the command line, or
from the local user defaults database of the person
running the program.
If the EcEffectiveUser
specifies an alternative user, or the program is
able to read the database for the 'ecuser' user, then
the other values are read from the defaults database of
that user.
After startup, the command line arguments still take
precedence, but values retrieved from the
network configuration system will then override any
read from the local user defaults database.
Settings in the network configuration system will
have no effect on the following defaults which are
used BEFORE the network configuration can be read.
- EcDaemon
-
To specify whether the program should run in the
background (boolean,
YES
if the
program is to run as a daemon, NO
otherwise).
The value in the network
configuration has no effect.
- EcEffectiveUser
-
To tell the server to change to being this user on
startup. defaults to 'ecuser', but the default
can be overridden by specifying
'-DEC_EFFECTIVE_USER+@"username"'
in the local.make make file.
Set a value of '*'
to remain whoever runs the program rather than
changing.
- EcInstance
-
To set the program instance ID (an arbitrary string).
If this is specified, the program name has
a hyphen and the id appended to it by
the '-initWithDefaults:' method.
The following settings will be revised after startup to
include the values from the network configuration
system.
- EcAuditLocal
-
A boolean used to specify that audit information should
be logged locally rather than sending it to be logged
centrally.
Default value is
NO
.
- EcAuditFlush
-
A flush interval in seconds (optionally followed by a
colon and a buffer size in KiloBytes) to control
flushing of audit logs.
Setting an
interval of zero or less disables flushing by
timer.
Setting a size of zero or less,
disables buffering (so logs are flushed
immediately).
- EcDebug-XXX
-
A boolean used to ensure that the debug mode named
'XXX' is either turned on or turned off. The value
of 'XXX' must match the name of a debug mode used by
the program!
- EcDebugLocal
-
A boolean used to specify that debug information should
be logged locally rather than sending it to be logged
centrally.
Default value is
YES
.
- EcDebugFlush
-
A flush interval in seconds (optionally followed by a
colon and a buffer size in KiloBytes) to control
flushing of debug logs.
Setting an
interval of zero or less disables flushing by
timer.
Setting a size of zero or less,
disables buffering (so logs are flushed
immediately).
- EcMemory
-
A boolean used to ensure that monitoring of memory
allocation is turned on or turned off.
- EcRelease
-
A boolean used to specify whether the program should
perform sanity checks for retain/release
combinations. Slows things down a lot!
- EcTesting
-
A boolean used to specify whether the program is
running in test mode or not.
- EcWellKnownHostNames
-
A dictionary mapping host names/address values to well
known names (the canonical values used by Command
and Control).
Method summary
- (void)
addServerToList: (NSString*)serverName;
This is a convenience method equivalent to calling
-addServerToList:for:
passing
nil
as the second argument.
- (void)
addServerToList: (NSString*)serverName
for: (id)anObject;
Adds the specified
serverName to the list
of named servers to which we make automatic distributed
object connections.
By default the supplied
serverName is taken as the name of the
server to which the distributed objects connection
is made, and the connection is to any host on the local
network. However configuration in the user
defaults system (using keys derived from the
serverName) may be used to modify this
behavior:
- serverNameName
-
Specifies the actual distributed objects port
name to which the connection is made, instead of
using serverName.
- serverNameHost
-
Specifies the actual distributed objects host
name to which the connection is made, instead of
using an asterisk (any host).
- serverNameBroadcast
-
Specifies that the server should actually be
configured to be a broadcast proxy (see
EcBroadcastProxy
).
The value of this field must be an array containing the configuration information for the EcBroadcastProxy
instance.
If this is defined then the serverNameName and serverNameHost values (if present) are ignored, and the connections are made to the individual servers listed in the elements of this array.
The argument
anObject is an object which will be messaged when the connection to the server is established (or lost). The messages sent are those in the
RemoteServerDelegate informal protocol.
If no object is specified, the receiver is used.
Once a server has been added to the list, it can be accessed using the
-server:
or
-server:forNumber:
method.
- (
EcAlarm*)
alarmConfigurationFor: (NSString*)managedObject
specificProblem: (NSString*)specificProblem
additionalText: (NSString*)additionalText
critical: (BOOL)isCritical;
Convenience method to produce a generic
configuration alarm and send it via the
-alarm:
method.
The managed object may be
nil
(in which case it's the default
managed object for the current process).
The
implied event type is
EcAlarmEventTypeProcessingError.
The implied probable cause is
EcAlarmConfigurationOrCustomizationError.
The implied severity is EcAlarmSeverityMajor
unless
isCritical is
YES
.
The implied trend is EcAlarmTrendNone.
The implied proposed repair action is to check/correct
the config.
The specific problem and additional
text should be used to suggest what is wrong with the
config and where the config error should be
found/corrected.
- (NSArray*)
alarms;
Returns the array of current alarms.
- (void)
clearConfigurationFor: (NSString*)managedObject
specificProblem: (NSString*)specificProblem
additionalText: (NSString*)additionalText;
- (void)
cmdAlert: (NSString*)fmt
,...;
- (void)
cmdAlert: (NSString*)fmt
arguments: (va_list)args;
Send a SEVERE error message to the server.
- (NSString*)
cmdArchive: (NSString*)subdir;
Archives debug log files into the specified
subdirectory of the debug logging directory.
If subdir is nil
then a
subdirectory name corresponding to the current
date is generated and that subdirectory is created if
necessary.
- (void)
cmdAudit: (NSString*)fmt
,...;
- (void)
cmdAudit: (NSString*)fmt
arguments: (va_list)args;
Send a log message to the server.
- (id)
cmdConfig: (NSString*)key;
- (id)
cmdConnectionBecameInvalid: (NSNotification*)notification;
Handles loss of connection to the server.
- (NSString*)
cmdDataDirectory;
Returns the path to the data storage directory used
by this process to store files containing persistent
information.
- (void)
cmdDbg: (NSString*)type
msg: (NSString*)fmt
,...;
Send a debug message - as
long as the
debug mode specified as 'type' is currently set.
Operates by calling the
-cmdDbg:msg:arguments:
method.
- (void)
cmdDbg: (NSString*)type
msg: (NSString*)fmt
arguments: (va_list)args;
Send a debug message - as long as the
debug mode specified as 'type' is currently set.
- (void)
cmdDebug: (NSString*)fmt
,...;
Send a debug message with debug mode 'defaultMode'.
Operates by calling the
-cmdDebug:arguments:
method.
- (void)
cmdDebug: (NSString*)fmt
arguments: (va_list)args;
- (BOOL)
cmdDebugMode: (NSString*)mode;
Check to see if a debug mode is active.
- (void)
cmdDebugMode: (NSString*)mode
active: (BOOL)flag;
Set a particular (named) debug mode to be
active or inactive.
- (NSUserDefaults*)
cmdDefaults;
Returns the NSUserDefaults instance containing the
configuration information for this process.
- (void)
cmdDefaultsChanged: (NSNotification*)n;
Called whenever the user defaults are updated (which
may be due to a central configuration in additions to
other defaults system changes).
This is
automatically called by
-cmdUpdate:
(even if the user defaults database has not actually
changed), in this case the notification argument
is
nil
.
If you override this to
handle configuration changes, don't forget to call
the superclass implementation.
This method is
provided to allow subclasses to control the order
in which defaults changes are handled by them and their
superclasses.
Generally, this method
is for use handling changes in the local NSUserDefaults
database; to handle explict configuration changes
from the central configuration in the Control server,
you should usually override the
-cmdUpdated
method instead.
- (void)
cmdError: (NSString*)fmt
,...;
- (void)
cmdError: (NSString*)fmt
arguments: (va_list)args;
Send an error message to the server.
- (void)
cmdFlushLogs;
Flush logging information.
- (NSTimeInterval)
cmdInterval;
Description forthcoming.
- (BOOL)
cmdIsClient;
This message returns YES
if the receiver
is intended to be a client of a Command server, and
NO
if it is a standalone process which
does not need to contact the Command server.
The default implementation returns YES
,
but subclasses may override this method to return
NO
if they do not wish to contact the
Command server.
- (BOOL)
cmdIsConnected;
Returns a flag indicating whether this process is
currently connected it its Command server.
- (BOOL)
cmdIsTesting;
Returns YES
is the process is running
in test mode, NO
otherwise.
Test
mode is defined by the EcTesting user default.
- (void)
cmdLogEnd: (NSString*)name;
Closes a file handle previously obtained using the
-cmdLogFile:
method. You should not close a logging handle
directly, use this method.
- (NSFileHandle*)
cmdLogFile: (NSString*)name;
Obtain a file handle for logging purposes. The file
will have the specified
name and will be
created (if necessary) in the processes logging
directory.
If there is already a handle
for the specified file, this method returns the
existing handle rather than creating a new one.
Do not close this file handle other than by
calling the
-cmdLogEnd:
method.
- (BOOL)
cmdMatch: (NSString*)val
toKey: (NSString*)key;
Utility method to perform partial (case
insensitive) matching of an abbreviated
command word (val) to a keyword (
key)
- (NSString*)
cmdMesg: (NSArray*)msg;
Handle with care - this method invokes the
cmdMesg... methods.
- (void)
cmdMesgCache;
Description forthcoming.
- (void)
cmdMesgData: (NSData*)dat
from: (NSString*)name;
Used by the Command server to send messages to your
application.
- (void)
cmdMesgarchive: (NSArray*)msg;
Description forthcoming.
- (void)
cmdMesgdebug: (NSArray*)msg;
Description forthcoming.
- (void)
cmdMesghelp: (NSArray*)msg;
Description forthcoming.
- (void)
cmdMesgmemory: (NSArray*)msg;
Description forthcoming.
- (void)
cmdMesgnodebug: (NSArray*)msg;
Description forthcoming.
- (void)
cmdMesgstatus: (NSArray*)msg;
Description forthcoming.
- (NSString*)
cmdName;
Retrurns the name by which this process is known
to the Command server.
- (id)
cmdNewServer;
Attempt to establish connection to Command server
etc. Return a proxy to that server if it is available.
- (NSMutableDictionary*)
cmdOperator: (NSString*)name
password: (NSString*)pass;
Return dictionary giving info about specified
operator. If the password string matches the
password of the operator (or the operator has no
password) then the dictionary field @"Password"
will be set to @"yes", otherwise it will be @"no". If
the named operator does not exist, the method will
return nil
.
- (void)
cmdPrintf: (NSString*)fmt
,...;
May be used withing cmdMesg... methods to return
formatted text to the Console.
- (void)
cmdPrintf: (NSString*)fmt
arguments: (va_list)args;
May be used withing cmdMesg... methods to return
formatted text to the Console.
- (void)
cmdQuit: (NSInteger)status;
Should be over-ridden to perform extra tidy up on
shutdown of the process - should call [super
cmdQuit:...] at the end of the method.
- (int)
cmdSignalled;
Returns non-zero (a signal) if the process has
received a unix signal.
- (void)
cmdUnregister;
Description forthcoming.
- (void)
cmdUpdate: (NSMutableDictionary*)info;
Used to tell your application about configuration
changes (the default implementation merges the
configuration change into the NSUserDefaults
system and sends the defaults change notification).
If you want to deal with configuration
changes actively - override this and call [super
cmdUpdate:...] to install the changed
configuration before anything else. NB. This
method WILL be called before your application is
initialised. Make sure it is safe.
- (NSString*)
cmdUpdated;
Used to tell your application about configuration
changes.
This is called after the
NSUserDefaults system is updated with the
changes, so you may use it to update internal
state in the knowledge that code watching for user
defaults change notifications will have updated
already.
NB. This method will be called
even if your implementation of
-cmdUpdate:
suppresses the actual update. In this situation
this method will find the configuration unchanged
since the previous time that it was called.
The return value of this method is used to control
automatic generation of alarms for fatal
configuration errors. If the return value is
nil
(the default), then any
configuration error alarm is cleared.
Otherwise, a configuration error alarm will be
raised (using the returned string as the 'additional
text' of the alarm), and the process will be
terminated by a call to
-cmdQuit:
with an argument of 1.
When you implement this
method, you must ensure that your implementation
calls the superclass implementation, and if that
returns a non-nil result, you should pass that on
as the return value from your own implementation.
- (void)
cmdWarn: (NSString*)fmt
,...;
Send a warning message to the server.
- (void)
cmdWarn: (NSString*)fmt
arguments: (va_list)args;
Send a warning message to the server.
- (NSString*)
ecCopyright;
Return a short copyright notice...
subclasses should override.
- (void)
ecDoLock;
Obtain a lock on the shared EcProcess for
thread-safe updates to process-wide variables.
- (void)
ecHadIP: (NSDate*)when;
Records the timestamp of the latest significant
input for this process. If when is
nil
the current timestmp is used.
- (void)
ecHadOP: (NSDate*)when;
Records the timestamp of the latest significant
output for this process. If when is
nil
the current timestmp is used.
- (void)
ecNewDay: (NSCalendarDate*)when;
Called on the first timeout of a new day.
The
argument 'when' is the timestamp of the timeout.
- (void)
ecNewHour: (NSCalendarDate*)when;
Called on the first timeout of a new hour.
The argument 'when' is the timestamp of the timeout.
- (void)
ecNewMinute: (NSCalendarDate*)when;
Called on the first timeout of a new minute.
The argument 'when' is the timestamp of the timeout.
- (NSUInteger)
ecNotLeaked;
Return heap memory known not to be leaked... for use
in internal monitoring of memory usage. You should
override this ti add in any heap store you have
used and know is not leaked.
- (int)
ecRun;
Establishes the receiver as a DO server and
runs the runloop.
Returns zero when the run
loop completes.
Returns one (immediately) if
the receiver is transent.
Returns two if unable
to register as a DO server.
- (NSDate*)
ecStarted;
Return the timestamp at which this process started
up (when the receiver was initialised).
- (void)
ecTestLog: (NSString*)fmt
,...;
Logs a message iff the process is running in test
mode.
Operates by calling the
-ecTestLog:arguments:
method.
- (void)
ecTestLog: (NSString*)fmt
arguments: (va_list)args;
Logs a message iff the process is running in test mode
(that is, when EcTesting is set).
- (void)
ecUnLock;
Release a lock on the shared EcProcess after
thread-safe updates to process-wide variables.
- (NSString*)
ecUserDirectory;
Returns the directory set as the root for files
owned by the ECCL user
- (id)
initWithDefaults: (NSDictionary*)defs;
[-initWithDefaults:]
is the Designated initialiser
It adds the
defaults specified to the defaults system.
It sets the process name to be that specified in the
'EcProgramName' default with an '-id' affix
if EcInstance is used to provide an instance
id.
Moves to the directory
(relative to the current user's home directory)
given in 'EcHomeDirectory'.
If
'EcHomeDirectory' is not present in the
defaults system (or is an empty string) then no
directory change is done.
Please note,
that the base implementation of this method may cause
other methods (eg
-cmdUpdated
and -cmdDefaultsChaned) to be called, so you must take
care that when you override those methods, your own
implementations do not depend on
initialisation having completed. It's
therefore recommended that you use 'lazy'
initialisation of subclass instance
variables as/when they are needed, rather than
initialising them in the
-initWithDefaults:
method.
An alternative strategy is to
perform subclass initialisaton before calling the
superclass implementation.
- (BOOL)
isServerMultiple: (NSString*)serverName;
Standard servers return NO
to the
following. But if we are using a
multiple/broadcast server, this returns
YES
.
- (void)
log: (NSString*)message
type: (
EcLogType)t;
Description forthcoming.
- (void)
removeServerFromList: (NSString*)serverName;
Removes the serverName from the list of
server processes for which we automatically maintain
distributed object connections.
See the
addServerToList:for: metho for more
details.
- (id)
server: (NSString*)serverName;
- (id)
server: (NSString*)serverName
forNumber: (NSString*)num;
Like
-server:
,
but if the configuration contains a multiple servers,
this tries to locate the specific server that is set
up to deal with cases where the last two digits of an
identifer as as specified.
This mechanism
permits work to be balanced/shared over up to 100
separate server processes.
- (void)
setCmdDebug: (NSString*)mode
withDescription: (NSString*)desc;
Register a debug mode 'mode'
- (void)
setCmdInterval: (NSTimeInterval)interval;
Description forthcoming.
- (void)
setCmdTimeout: (SEL)sel;
Specify a handler method to be invoked after each
timeout to let you perform additional tasks.
- (void)
triggerCmdTimeout;
Description forthcoming.
- Declared in:
- EcProcess.h
Description forthcoming.
Method summary
- (void)
cmdLostConnectionToServer: (NSString*)serverName;
Description forthcoming.
- (void)
cmdMadeConnectionToServer: (NSString*)serverName;
Description forthcoming.
- Declared in:
- EcProcess.h
- Conforms to:
- CmdPing
- CmdConfig
Messages that the Command server may send to
clients.
Method summary
- (oneway void)
cmdMesgData: (in bycopy NSData*)dat
from: (NSString*)name;
Description forthcoming.
- (oneway void)
cmdQuit: (NSInteger)status;
Description forthcoming.
- Declared in:
- EcProcess.h
The CmdConfig protocol is needed by objects that send and
receive configuarion information.
Method summary
- (oneway void)
requestConfigFor: (id<
CmdConfig>)c;
Description forthcoming.
- (oneway void)
updateConfig: (in bycopy NSData*)info;
Description forthcoming.
- Declared in:
- EcProcess.h
- Conforms to:
- CmdClient
Messages a Command logging process can be expected
to handle.
Method summary
- (void)
flush;
Description forthcoming.
- (oneway void)
logMessage: (NSString*)msg
type: (
EcLogType)t
for: (id)o;
Description forthcoming.
- (oneway void)
logMessage: (NSString*)msg
type: (
EcLogType)t
name: (NSString*)c;
Description forthcoming.
- (bycopy NSData*)
registerClient: (id)c
name: (NSString*)n;
Description forthcoming.
- (void)
unregisterByName: (NSString*)n;
Description forthcoming.
- (void)
unregisterByObject: (id)obj;
Description forthcoming.
- Declared in:
- EcProcess.h
A 'ping' can be sent from or to any process to check that
it is alive. A 'gnip' should be sent in response to each
'ping' Each 'ping' carries a sequence number which
should be echoed in its 'gnip'. Optionally, the 'ping'
can also transport a serialized property-list to provide
additional data or instructions - the value of
which is dependent on the program being pinged -
normally this value is nil
.
Method summary
- (oneway void)
cmdGnip: (id<
CmdPing>)from
sequence: (unsigned)num
extra: (in bycopy NSData*)data;
Description forthcoming.
- (oneway void)
cmdPing: (id<
CmdPing>)from
sequence: (unsigned)num
extra: (in bycopy NSData*)data;
Description forthcoming.
- Declared in:
- EcProcess.h
- Conforms to:
- CmdLogger
- CmdConfig
- EcAlarmDestination
Messages that clients may send to the server. NB.
The 'registerClient...' message must be sent first.
Method summary
- (oneway void)
alarm: (in bycopy
EcAlarm*)alarm;
Description forthcoming.
- (oneway void)
command: (in bycopy NSData*)dat
to: (NSString*)t
from: (NSString*)f;
Description forthcoming.
- (bycopy NSData*)
configurationFor: (NSString*)name;
This is an exceptional method which may be used
without registering your process with a Command
server first (ie, it can be used by anyone, not only
clients of the Command server).
It's meant
to be used remotely by Java servlets, and all sort of
software running on the machine and which is *not*
a full Command client (ie, a subclass of EcProcess) but
which still wants to retrieve configuration from a
central location (the Control/Command servers).
The returned value is a a serialized property
list... you need to deserialize using the standard
GNUstep property list APIs.
NB: The
configuration might change later on, so you
must not cache the configuration after asking for it,
but rather ask for it each time your software needs it.
- (bycopy NSData*)
registerClient: (id<
CmdClient>)c
name: (NSString*)n
transient: (BOOL)t;
Description forthcoming.
- (oneway void)
reply: (NSString*)msg
to: (NSString*)n
from: (NSString*)c;
Description forthcoming.
- (oneway void)
terminate;
Shut down the Command server and all its clients
- Declared in:
- EcProcess.h
- Conforms to:
- NSObject
Description forthcoming.
Method summary
- (oneway void)
information: (NSString*)txt;
Description forthcoming.
- Declared in:
- EcProcess.h
- Conforms to:
- CmdPing
- CmdConfig
- EcAlarmDestination
Description forthcoming.
Method summary
- (oneway void)
alarm: (in bycopy
EcAlarm*)alarm;
Description forthcoming.
- (oneway void)
command: (in bycopy NSData*)cmd
from: (NSString*)f;
Description forthcoming.
- (oneway void)
domanage: (NSString*)name;
Description forthcoming.
- (oneway void)
information: (NSString*)msg
type: (
EcLogType)t
to: (NSString*)to
from: (NSString*)from;
Description forthcoming.
- (bycopy NSData*)
registerCommand: (id<
Command>)c
name: (NSString*)n;
Description forthcoming.
- (bycopy NSString*)
registerConsole: (id<
Console>)c
name: (NSString*)n
pass: (NSString*)p;
Description forthcoming.
- (oneway void)
reply: (NSString*)msg
to: (NSString*)n
from: (NSString*)c;
Description forthcoming.
- (oneway void)
servers: (in bycopy NSData*)a
on: (id<
Command>)s;
Description forthcoming.
- (oneway void)
unmanage: (NSString*)name;
Description forthcoming.
- (void)
unregister: (id)o;
Description forthcoming.
typedef enum ... EcLogType;
Description forthcoming.
EcProcess* EcProc;
Description forthcoming.
NSString* cmdConnectDbg;
Description forthcoming.
NSString* cmdDefaultDbg;
Description forthcoming.
NSString* cmdDetailDbg;
Description forthcoming.
NSString* cmdLogFormat(EcLogType t, NSString* fmt);
Description forthcoming.
NSString* cmdLogKey(EcLogType t);
Description forthcoming.
NSString* cmdLogName();
Description forthcoming.
NSString* cmdLogsDir(NSString* date);
Description forthcoming.
void cmdSetHome(NSString* home);
Description forthcoming.
NSString* cmdVersion(NSString* ver);
Description forthcoming.