1    /* --COPYRIGHT--,ESD
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved. 
     3     *  This program and the accompanying materials are made available under the 
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at 
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * --/COPYRIGHT--*/
    13    /*!
    14     *  ======== ILogger ========
    15     *  Interface to service Log events
    16     *
    17     *  A logger is responsible for recording, transmitting, or otherwise
    18     *  handling `{@link Log#EventDesc Log Events}` generated by clients of the
    19     *  `{@link Log}` module. The `Log` module uses modules that implement the
    20     *  `ILogger` interface to record the log events. Most application code will
    21     *  use the `Log` module instead of directly calling the specific `ILogger`
    22     *  module implementation.
    23     *
    24     *  All logger implementations must inherit from this interface. The
    25     *  derived implementations must implement the functions defined in this
    26     *  interface but may also add additional configuration parameters and
    27     *  functions.
    28     */
    29    interface ILogger {
    30    
    31    instance:
    32    
    33        /*! 
    34         *  ======== write4 ========
    35         *  Process a log event with up to 4 arguments.
    36         *
    37         *      At the time this method is called, `evt` encodes two values: the
    38         *      module ID of the module that "triggered" a `{@link Log#Event}`
    39         *      and the `{@link Log#EventId}` of the event.  The module ID can
    40         *      be obtained via `{@link Types#getModuleId}(evt)`
    41         *      and the event ID can be obtained via
    42         *      `{@link Types#getEventId}(evt)`.
    43         *
    44         *      The event ID can be used to compare against other known
    45         *      `Log.Event`s.
    46         *      @p(code)
    47         *          if (Log_getEventId(MY_EVENT) == Types_getEventId(evt)) {
    48         *              :
    49         *          }
    50         *      @p
    51         *
    52         *      The event ID value of `0` is used to indicate an event triggered
    53         *      by a call to one of the `{@link Log#print0 Log_print[0-6]}`
    54         *      methods. These methods take a 
    55         *      format string rather than a `Log_Event` argument and, as a result,
    56         *      the event ID encoded in `evt` is `0` and the parameter `a1` is
    57         *      the format string.
    58         *
    59         *      Non-zero event IDs can also be used to access the `msg` string
    60         *      associated with the `{@link Log#EventDesc}` that originally
    61         *      defined the `Log` event.
    62         *      @p(code)
    63         *          Types_EventId id = Types_getEventId(evt));
    64         *          if (id != 0) {
    65         *              String msg = Text_ropeText(id);
    66         *              System_aprintf(msg, a1, a2, a3, a4);
    67         *          }
    68         *      @p
    69         *      This works because an event's ID is simply an offset into a table
    70         *      of characters (maintained by the `{@link Text}` module)
    71         *      containing the event's msg string.
    72         *
    73         *  @param(evt) event to be logged
    74         *
    75         *  @param(a1)  arbitrary argument passed by caller
    76         *
    77         *      This parameter, along with `a2`, `a3`, and `a4` are parameters
    78         *      that are to be interpreted according to the message format string
    79         *      associated with `evt`.
    80         *
    81         *  @see Log#Event
    82         *  @see Log#EventDesc
    83         *  @see Text#ropeText
    84         *  @see Types#getEventId
    85         */
    86        Void write4(Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4);
    87    
    88        /*! 
    89         *  ======== write8 ========
    90         *  Process a log event with up to 8 arguments.
    91         *
    92         *  Same as `write4` except with 8 arguments rather than 4.
    93         *
    94         *  @see ILogger#write4()
    95         */
    96        Void write8(Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
    97                    IArg a5, IArg a6, IArg a7, IArg a8);
    98    }
    99    /*
   100     *  @(#) xdc.runtime; 2, 0, 0, 0,214; 7-29-2009 14:53:43; /db/ztree/library/trees/xdc-t56x/src/packages/
   101     */
   102