1    /*
     2     * Copyright (c) 2012, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    
    33    /*!
    34     *  ======== IServiceMgrSupport ========
    35     *  Interface defining the ServiceMgr's proxy
    36     *
    37     *  This module defines the interface that the ServiceMgr
    38     *  support proxy must adhere to.
    39     */
    40    interface IServiceMgrSupport  {
    41    
    42        /*!
    43         *  ======== newService ========
    44         *  Function called within ServiceMgr_register
    45         *
    46         *  All services must call ServiceMgr.register. The ServiceMgr
    47         *  manages the processFxn callback. It then calls the proxy's
    48         *  newService function.
    49         *
    50         *  @param(id)         Id of the new service
    51         *  @param(periodInMs) Period requested by the service (in millisecond)
    52         */
    53        metaonly Void newService(Int id, UInt32 periodInMs);
    54    
    55        /*!
    56         *  ======== freePacket ========
    57         *  Function called within ServiceMgr_freePacket
    58         *
    59         *  This function can be used to return an unused packet back to the
    60         *  module. It must only return packets that were obtained via
    61         *  the {@link #getFreePacket} function.
    62         *
    63         *  @param(packet)  Pointer to a UIAPacket
    64         */
    65        @DirectCall
    66        Void freePacket(UIAPacket.Hdr *packet);
    67    
    68        /*!
    69         *  ======== getFreePacket ========
    70         *  Function called within ServiceMgr_getFreePacket
    71         *
    72         *  The service can specify what type of packet it wants with the
    73         *  first parameter.
    74         *
    75         *  The function fills in the HdrType field of the packet automatically
    76         *  for the service. All other fields are un-initialized.
    77         *
    78         *  @param(type)    Requested type of packet
    79         *  @param(timeout) return after this many system time units
    80         *
    81         *  @b(returns)     Point to the free UIA packet. NULL if not successful.
    82         */
    83        @DirectCall
    84        UIAPacket.Hdr *getFreePacket(UIAPacket.HdrType type, UInt timeout);
    85    
    86        /*!
    87         *  ======== requestEnergy ========
    88         *  Function called within ServiceMgr_requestEnergy
    89         *
    90         *  Generally services do not maintain an active thread. Services may
    91         *  request the ServiceMgr module to call the {@link #ProcessCallback}
    92         *  in the context of the transfer agent. This can be accomplished via
    93         *  this function.
    94         *
    95         *  @param(id)     Id of the service
    96         */
    97         @DirectCall
    98         Void requestEnergy(Int id);
    99    
   100        /*!
   101         *  ======== sendPacket ========
   102         *  Function called within ServiceMgr_sendPacket
   103         *
   104         *  All UIAPacket fields except for SenderAdrs must be filled in.
   105         *
   106         *  The caller loses ownership of the packet once it is successfully sent.
   107         *  If this function fails, the caller still owns the packet.
   108         *
   109         *  @param(packet)  UIAPacket to be sent
   110         *
   111         *  @b(returns)     TRUE denotes success and the packet is
   112         *                  no longer owned by the caller. FALSE denotes
   113         *                  failure and the packet is still owned by the caller.
   114         */
   115        @DirectCall
   116        Bool sendPacket(UIAPacket.Hdr *packet);
   117    
   118        /*!
   119         *  ======== setPeriod ========
   120         *  Function called within ServiceMgr_setPeriod
   121         *
   122         *  Services period should be a multiple of the ServiceMgr's period
   123         *  ({@link #periodInMs}). If it is not, they will called at the rounded
   124         *  up period. For example, if ServiceMgr.periodInMs = 100 and a service sets
   125         *  its period to 250. That service will be called every 300 milliseconds.
   126         *
   127         *  @param(id)         Service id of the service
   128         *
   129         *  @param(periodInMs) Requested period in milliseconds
   130         */
   131         @DirectCall
   132         Void setPeriod(Int id, UInt32 periodInMs);
   133    }