trick/trick_source/sim_services/Message/main_page.dox_in
2015-02-26 09:02:31 -06:00

61 lines
3.5 KiB
Plaintext

/**
@anchor StatusMessageSystem
@page LEVEL2 Trick Message Publisher/Subscriber
The Message Publisher publishes executive and/or model messages. A Message Subscriber gets the messages published by the Publisher.
@section LEVEL3 Message Publisher
Trick creates one instance of the Message Publisher (in the S_define file). It is responsible for keeping track of all Message Subscribers,
and sending any message that is published to all of the Message Subscribers. A subscriber is made known to the Message Publisher by calling its
::message_subscribe routine (and conversely can be removed from the publisher by calling ::message_unsubscribe).
Publishing a message that you want to be output by all subscribers is done by calling ::message_publish.
If there are no subscribers, then publishing a message has no effect.
@section LEVEL3 Message Subscriber
There can be any number of Message Subscribers, whose job is to receive (and usually output) published messages. Trick automatically creates three Message Subscribers:
- Trick::MessageCout - outputs messages to the standard output stream
- Trick::MessageFile - outputs messages to a file named "send_hs" in the RUN directory
- Trick::MessageTCDevice - outputs messages to a socket at port 7200, used by the Simulation Control Panel for its Status Messages display
So by default, when you publish a message, it will be output by the three subscribers above.
A subscriber can be enabled / disabled at any time during simulation execution to output / ignore messages as desired.
The user may also add their own subscriber by creating a derived class from Trick::MessageSubscriber.
@section LEVEL3 User accessible routines
To publish a message:
@li int ::message_publish(int level, const char * format_msg, ...) ;
@li int ::send_hs(FILE * fp, const char * format_msg, ...) ;
The level number can be any integer from 0 to 99. Trick has a few predefined levels (Trick::MessagePublisher::MESSAGE_TYPE) that it uses for publishing messages.
If the message subscriber's color is enabled (see below), then a particular colored message will be displayed for each of these levels:
- @e 0 - normal message, default color
- @e 1 - informational message, green
- @e 2 - warning message, yellow
- @e 3 - error message, red
- @e 10 - debug message, cyan
To subscribe / unsubscribe Trick's default subscribers (these call ::message_subscribe / ::message_unsubscribe mentioned above):\n
By default these are all subscribed. You can use subscribe/unsubscribe throughout a simulation to turn on/off messages at will.
@li int message_cout_subscribe() ;
@li int message_cout_unsubscribe() ;
@li int message_file_subscribe() ;
@li int message_file_unsubscribe() ;
@li int message_device_subscribe() ;
@li int message_device_unsubscribe() ;
To enable / disable Trick's default subscribers:\n
By default these are all enabled. If you disable file at startup, the send_hs file will not be created/opened. If you disable device at startup, its connection will not be established.
That means you cannot then later try to enable and subscribe to file/device.
@li int message_cout_set_enabled(int yes_no) ;
@li int message_file_set_enabled(int yes_no) ;
@li int message_device_set_enabled(int yes_no) ;
To enable / disable showing colored messages in Trick's default subscribers:\n
By default color is enabled for cout and device. Color is achieved by adding ANSI escape codes around the message.
@li int message_cout_set_color(int yes_no) ;
@li int message_file_set_color(int yes_no) ;
@li int message_device_set_color(int yes_no) ;
*/