fnet_poll.h

00001 /**************************************************************************
00002 *
00003 * Copyright 2011-2016 by Andrey Butok. FNET Community.
00004 * Copyright 2008-2010 by Andrey Butok. Freescale Semiconductor, Inc.
00005 *
00006 ***************************************************************************
00007 *
00008 *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00009 *  not use this file except in compliance with the License.
00010 *  You may obtain a copy of the License at
00011 *
00012 *  http://www.apache.org/licenses/LICENSE-2.0
00013 *
00014 *  Unless required by applicable law or agreed to in writing, software
00015 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00016 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00017 *  See the License for the specific language governing permissions and
00018 *  limitations under the License.
00019 *
00020 **********************************************************************/
00021 /*!
00022 * @brief FNET Services polling mechanism API.
00023 *
00024 ***************************************************************************/
00025 
00026 #ifndef _FNET_POLL_H_
00027 
00028 #define _FNET_POLL_H_
00029 
00030 /*! @addtogroup fnet_polling
00031 * The polling mechanism enables the execution of registered services
00032 * (DHCP client, TFTP client, Shell, Telnet server or HTTP server) in
00033 * "background" - during the application
00034 * idle time. Typically, the polling callback is registered during the service
00035 * initialization (for example the @ref fnet_http_init() or other service initialization
00036 * function).
00037 * In order to make the polling mechanism work, the user application should
00038 * call the @ref fnet_poll_service() API function periodically, during the idle time.@n
00039 * @n
00040 * Configuration parameters:
00041 * - @ref FNET_CFG_POLL_MAX
00042 */
00043 /*! @{ */
00044 
00045 /**************************************************************************/ /*!
00046  * @brief Descriptor of a registered service.
00047  ******************************************************************************/
00048 typedef fnet_uint32_t fnet_poll_desc_t;
00049 
00050 /**************************************************************************/ /*!
00051  * @brief Service callback function prototype.
00052  *
00053  * @param service_param   This parameter is assigned during
00054  *                        a service registration by the @ref
00055  *                        fnet_poll_service_register().
00056  *
00057  ******************************************************************************/
00058 typedef void (* fnet_poll_service_t)(void *service_param);
00059 
00060 #if defined(__cplusplus)
00061 extern "C" {
00062 #endif
00063 
00064 /***************************************************************************/ /*!
00065  *
00066  * @brief    Main polling function.
00067  *
00068  * @see fnet_poll_service_register()
00069  *
00070  ******************************************************************************
00071  *
00072  * This function calls all registered service routines.@n
00073  * The user application should call this function periodically, after any service
00074  * initialization.
00075  *
00076  ******************************************************************************/
00077 void fnet_poll_service(void);
00078 
00079 /***************************************************************************/ /*!
00080  *
00081  * @brief    Unregisters all registered service routines.
00082  *
00083  * @see fnet_poll_service_register(), fnet_poll_service_unregister()
00084  *
00085  ******************************************************************************
00086  *
00087  * This function unregisters all registered service routines from
00088  * the polling list.
00089  *
00090  ******************************************************************************/
00091 void fnet_poll_service_release(void);
00092 
00093 /***************************************************************************/ /*!
00094  *
00095  * @brief    Registers the service routine in the polling list.
00096  *
00097  * @param service        Pointer to the service-polling routine.
00098  *
00099  * @param service_param  Service-polling-routine-specific parameter.
00100  *
00101  * @return This function returns:
00102  *   - Service descriptor, if no error occurs.
00103  *   - @c 0 if an error occurs.
00104  *
00105  * @see fnet_poll_service_unregister()
00106  *
00107  ******************************************************************************
00108  *
00109  * This function adds the service routine into the polling list.@n
00110  * This function is usually called during a service initialization.
00111  * User application should not call this function directly.
00112  *
00113  ******************************************************************************/
00114 fnet_poll_desc_t fnet_poll_service_register( fnet_poll_service_t service, void *service_param );
00115 
00116 /***************************************************************************/ /*!
00117  *
00118  * @brief    Unregisters the service routine.
00119  *
00120  * @param desc       Service descriptor to be unregistered.
00121  *
00122  * @see fnet_poll_service_register()
00123  *
00124  ******************************************************************************
00125  *
00126  * This function unregisters the service routine assigned to the @c desc
00127  * descriptor.@n
00128  * This function is usually called during a service release.
00129  * User application should not call this function directly.
00130  *
00131  ******************************************************************************/
00132 void fnet_poll_service_unregister( fnet_poll_desc_t desc );
00133 
00134 #if defined(__cplusplus)
00135 }
00136 #endif
00137 
00138 /*! @} */
00139 
00140 #endif