Function

Summary

For use as the main function for an automation server.

Package

com

Signature

automation-server-main &key exit-delay exit-function new-process force-server forced-exit-delay quit-on-registry-error handle-registry-error

Arguments

exit-delay

A non-negative real number.

exit-function

A function specifier.

new-process

A boolean.

force-server

A boolean.

forced-exit-delay

A non-negative real number.

quit-on-registry-error

A boolean.

handle-registry-error

A boolean.

Description

The function automation-server-main is for use as the main function for an automation server.

exit-delay, if supplied, sets the exit delay for automation-server-top-loop, by calling set-automation-server-exit-delay with it.

exit-function is an exit-function for automation-server-top-loop. The default value of exit-function is server-can-exit-p.

new-process controls whether to run automation-server-top-loop in its own process.

force-server controls whether to force running the automation server even if the application starts normally. The default value of force-server is t.

forced-exit-delay specifies the exit-delay in seconds when the server is forced.

automation-server-main checks the command line (using automation-server-command-line-action) for what action it should do, and then does it.

If the action is :register or :unregister, automation-server-main tries register or unregister the server (using register-server and unregister-server). If the operation succeeds, automation-server-main just returns :register or :unregister.

handle-registry-error controls what happens if there is an error while trying to register or unregister. If nil is supplied then error is called, and if a non-nil value is supplied, then the error is handled. If handle-registry-error is not supplied, by default the error is handled, but if the command line contains -debug or /debug, the error is not handled. The default value of handle-registry-error is nil.

quit-on-registry-error controls what happens if an error occurs during registration. If it is non-nil (the default), then automation-server-main calls quit with the appropriate status value (5). Otherwise it returns :register-failed or :unregister-failed. The default value of quit-on-registry-error is t.

If the command line action is :embedding or the action is nil and force-server is non-nil (the default) then automation-server-main runs the server by using automation-server-top-loop. If new-process is nil (the default), automation-server-top-loop is called on the current process. In this case automation-server-main returns only after automation-server-top-loop exits (and the server was closed). If new-process is true, automation-server-top-loop is called on its own process and automation-server-main returns immediately.

If the server is "forced", that is the action is nil but force-server is non-nil, and forced-exit-delay is non-nil, the exit-delay is set to forced-exit-delay (using set-automation-server-exit-delay). This overrides the value of the argument exit-delay.

automation-server-main returns the result of automation-server-command-line-action, except in the case of registry failure as described above.

Notes

1. automation-server-main is intended to be used as the main function in an automation server that is delivered as an executable (rather than as a DLL).
2. When the application acts only as automation server, automation-server-main can be the function argument to deliver, or the restart-function in save-image (multiprocessing t is needed too). It will deal correctly with registration when the command line argument is supplied, otherwise runs the server until it can exit and then returns (the application will exit because there will not be any other processes).
3. When the application also needs to do other things, automation-server-main can be used to run the server. Note that with the default values when automation-server-main runs the server it does not return until the server exits, so you need to either pass :new-process t, or run it on its own process. You will also need to consider whether to wait when failing to register, and hence may want to pass :quit-on-registry-failure nil.

See also

automation-server-top-loop
automation-server-command-line-action
set-automation-server-exit-delay