cc3100_netapp.h

00001 /*
00002  * netapp.h - CC31xx/CC32xx Host Driver Implementation
00003  *
00004  * Copyright (C) 2014 Texas Instruments Incorporated - http://www.ti.com/ 
00005  * 
00006  * 
00007  *  Redistribution and use in source and binary forms, with or without 
00008  *  modification, are permitted provided that the following conditions 
00009  *  are met:
00010  *
00011  *    Redistributions of source code must retain the above copyright 
00012  *    notice, this list of conditions and the following disclaimer.
00013  *
00014  *    Redistributions in binary form must reproduce the above copyright
00015  *    notice, this list of conditions and the following disclaimer in the 
00016  *    documentation and/or other materials provided with the   
00017  *    distribution.
00018  *
00019  *    Neither the name of Texas Instruments Incorporated nor the names of
00020  *    its contributors may be used to endorse or promote products derived
00021  *    from this software without specific prior written permission.
00022  *
00023  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
00024  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
00025  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00026  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
00027  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
00028  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
00029  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
00030  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
00031  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
00032  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
00033  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034  *
00035 */
00036 
00037 #ifndef __NETAPP_H__
00038 #define    __NETAPP_H__
00039 
00040 /*****************************************************************************/
00041 /* Include files                                                             */
00042 /*****************************************************************************/
00043 
00044 #include "cc3100_simplelink.h"
00045 
00046 
00047 #ifdef    __cplusplus
00048 extern "C" {
00049 #endif
00050 
00051 /*!
00052 
00053     \addtogroup netapp
00054     @{
00055 
00056 */
00057 
00058 /*****************************************************************************/
00059 /* Macro declarations                                                        */
00060 /*****************************************************************************/
00061 
00062 /*ERROR code*/
00063 #define SL_ERROR_NETAPP_RX_BUFFER_LENGTH_ERROR (-230)
00064 
00065 /*  Http Server interface */
00066 #define MAX_INPUT_STRING                              (64) /*  because of WPA */
00067 
00068 #define MAX_AUTH_NAME_LEN                             (20)
00069 #define MAX_AUTH_PASSWORD_LEN                         (20)
00070 #define MAX_AUTH_REALM_LEN                            (20)
00071 
00072 #define MAX_DEVICE_URN_LEN (15+1)
00073 #define MAX_DOMAIN_NAME_LEN    (24+1)
00074 
00075 #define MAX_ACTION_LEN                                (30)
00076 /* Important: in case the max len is changed, make sure the struct sl_NetAppHttpServerSendToken_t in protocol.h is padded correctly! */
00077 #define MAX_TOKEN_NAME_LEN                            (20)  
00078 #define MAX_TOKEN_VALUE_LEN        MAX_INPUT_STRING
00079 
00080 #define NETAPP_MAX_SERVICE_TEXT_SIZE                  (256)
00081 #define NETAPP_MAX_SERVICE_NAME_SIZE                  (60)
00082 #define NETAPP_MAX_SERVICE_HOST_NAME_SIZE             (64)
00083 
00084 
00085 /* Server Responses */
00086 #define SL_NETAPP_RESPONSE_NONE                       (0)
00087 #define SL_NETAPP_HTTPSETTOKENVALUE                   (1)
00088 
00089 #define SL_NETAPP_FAMILY_MASK                         (0x80)
00090 
00091 /* mDNS types */
00092 #define SL_NET_APP_MASK_IPP_TYPE_OF_SERVICE           (0x00000001)
00093 #define SL_NET_APP_MASK_DEVICE_INFO_TYPE_OF_SERVICE   (0x00000002)
00094 #define SL_NET_APP_MASK_HTTP_TYPE_OF_SERVICE          (0x00000004)
00095 #define SL_NET_APP_MASK_HTTPS_TYPE_OF_SERVICE         (0x00000008)
00096 #define SL_NET_APP_MASK_WORKSATION_TYPE_OF_SERVICE    (0x00000010)
00097 #define SL_NET_APP_MASK_GUID_TYPE_OF_SERVICE          (0x00000020)
00098 #define SL_NET_APP_MASK_H323_TYPE_OF_SERVICE          (0x00000040)
00099 #define SL_NET_APP_MASK_NTP_TYPE_OF_SERVICE           (0x00000080)
00100 #define SL_NET_APP_MASK_OBJECITVE_TYPE_OF_SERVICE     (0x00000100)
00101 #define SL_NET_APP_MASK_RDP_TYPE_OF_SERVICE           (0x00000200)
00102 #define SL_NET_APP_MASK_REMOTE_TYPE_OF_SERVICE        (0x00000400)
00103 #define SL_NET_APP_MASK_RTSP_TYPE_OF_SERVICE          (0x00000800)
00104 #define SL_NET_APP_MASK_SIP_TYPE_OF_SERVICE           (0x00001000)
00105 #define SL_NET_APP_MASK_SMB_TYPE_OF_SERVICE           (0x00002000)
00106 #define SL_NET_APP_MASK_SOAP_TYPE_OF_SERVICE          (0x00004000)
00107 #define SL_NET_APP_MASK_SSH_TYPE_OF_SERVICE           (0x00008000)
00108 #define SL_NET_APP_MASK_TELNET_TYPE_OF_SERVICE        (0x00010000)
00109 #define SL_NET_APP_MASK_TFTP_TYPE_OF_SERVICE          (0x00020000)
00110 #define SL_NET_APP_MASK_XMPP_CLIENT_TYPE_OF_SERVICE   (0x00040000)
00111 #define SL_NET_APP_MASK_RAOP_TYPE_OF_SERVICE          (0x00080000)
00112 #define SL_NET_APP_MASK_ALL_TYPE_OF_SERVICE           (0xFFFFFFFF)
00113 
00114 /********************************************************************************************************/
00115 /* sl_NetAppDnsGetHostByName error codes     */
00116 
00117 #define SL_NET_APP_DNS_QUERY_NO_RESPONSE              (-159)  /* DNS query failed, no response                        */ 
00118 #define SL_NET_APP_DNS_NO_SERVER                      (-161)  /* No DNS server was specified                          */ 
00119 #define SL_NET_APP_DNS_PARAM_ERROR                    (-162)  /* mDNS parameters error                                */
00120 #define SL_NET_APP_DNS_QUERY_FAILED                   (-163)  /* DNS query failed; no DNS server sent an 'answer'     */ 
00121 #define SL_NET_APP_DNS_INTERNAL_1                     (-164)
00122 #define SL_NET_APP_DNS_INTERNAL_2                     (-165)
00123 #define SL_NET_APP_DNS_MALFORMED_PACKET               (-166)  /* Improperly formed or corrupted DNS packet received   */ 
00124 #define SL_NET_APP_DNS_INTERNAL_3                     (-167)
00125 #define SL_NET_APP_DNS_INTERNAL_4                     (-168)
00126 #define SL_NET_APP_DNS_INTERNAL_5                     (-169)
00127 #define SL_NET_APP_DNS_INTERNAL_6                     (-170)
00128 #define SL_NET_APP_DNS_INTERNAL_7                     (-171)
00129 #define SL_NET_APP_DNS_INTERNAL_8                     (-172)
00130 #define SL_NET_APP_DNS_INTERNAL_9                     (-173)
00131 #define SL_NET_APP_DNS_MISMATCHED_RESPONSE            (-174)  /* Server response type does not match the query request*/
00132 #define SL_NET_APP_DNS_INTERNAL_10                    (-175)
00133 #define SL_NET_APP_DNS_INTERNAL_11                    (-176)
00134 #define SL_NET_APP_DNS_NO_ANSWER                      (-177)  /* No response for one-shot query */
00135 #define SL_NET_APP_DNS_NO_KNOWN_ANSWER                (-178)  /* No known answer for query */
00136 #define SL_NET_APP_DNS_NAME_MISMATCH                  (-179)  /* Illegal service name according to the RFC            */
00137 #define SL_NET_APP_DNS_NOT_STARTED                    (-180)  /* mDNS is not running                                  */
00138 #define SL_NET_APP_DNS_HOST_NAME_ERROR                (-181)  /* Host name error. Host name format is not allowed according to RFC 1033,1034,1035, 6763 */
00139 #define SL_NET_APP_DNS_NO_MORE_ENTRIES                (-182)  /* No more entries be found.                            */
00140                                                       
00141 #define SL_NET_APP_DNS_MAX_SERVICES_ERROR             (-200)  /* Maximum advertise services are already configured    */
00142 #define SL_NET_APP_DNS_IDENTICAL_SERVICES_ERROR       (-201)  /* Trying to register a service that is already exists  */
00143 #define SL_NET_APP_DNS_NOT_EXISTED_SERVICE_ERROR      (-203)  /* Trying to delete service that does not existed       */
00144 #define SL_NET_APP_DNS_ERROR_SERVICE_NAME_ERROR       (-204)  /* Illegal service name according to the RFC            */
00145 #define SL_NET_APP_DNS_RX_PACKET_ALLOCATION_ERROR     (-205)  /* Retry request                                        */
00146 #define SL_NET_APP_DNS_BUFFER_SIZE_ERROR              (-206)  /* List size buffer is bigger than internally allowed in the NWP */
00147 #define SL_NET_APP_DNS_NET_APP_SET_ERROR              (-207)  /* Illegal length of one of the mDNS Set functions      */
00148 #define SL_NET_APP_DNS_GET_SERVICE_LIST_FLAG_ERROR    (-208)
00149 #define SL_NET_APP_DNS_NO_CONFIGURATION_ERROR         (-209)
00150 
00151 /* Set Dev name error codes  (NETAPP_SET_GET_DEV_CONF_OPT_DEVICE_URN) */
00152 #define SL_ERROR_DEVICE_NAME_LEN_ERR                   (-117) 
00153 #define SL_ERROR_DEVICE_NAME_INVALID                   (-118)
00154 /* Set domain name error codes (NETAPP_SET_GET_DEV_CONF_OPT_DOMAIN_NAME) */
00155 #define SL_ERROR_DOMAIN_NAME_LEN_ERR                   (-119)
00156 #define SL_ERROR_DOMAIN_NAME_INVALID                   (-120)
00157 
00158 /********************************************************************************************************/
00159 
00160 /* NetApp application IDs */
00161 #define SL_NET_APP_HTTP_SERVER_ID                     (1)
00162 #define SL_NET_APP_DHCP_SERVER_ID                     (2)
00163 #define SL_NET_APP_MDNS_ID                            (4)
00164 #define SL_NET_APP_DNS_SERVER_ID                      (8)
00165 #define SL_NET_APP_DEVICE_CONFIG_ID                   (16)
00166 /* NetApp application set/get options */             
00167 #define NETAPP_SET_DHCP_SRV_BASIC_OPT                 (0)             
00168 /* HTTP server set/get options */                    
00169 #define NETAPP_SET_GET_HTTP_OPT_PORT_NUMBER           (0)
00170 #define NETAPP_SET_GET_HTTP_OPT_AUTH_CHECK            (1)
00171 #define NETAPP_SET_GET_HTTP_OPT_AUTH_NAME             (2)
00172 #define NETAPP_SET_GET_HTTP_OPT_AUTH_PASSWORD         (3)
00173 #define NETAPP_SET_GET_HTTP_OPT_AUTH_REALM            (4)
00174 #define NETAPP_SET_GET_HTTP_OPT_ROM_PAGES_ACCESS      (5)
00175                                                      
00176 #define NETAPP_SET_GET_MDNS_CONT_QUERY_OPT            (1)
00177 #define NETAPP_SET_GET_MDNS_QEVETN_MASK_OPT           (2)
00178 #define NETAPP_SET_GET_MDNS_TIMING_PARAMS_OPT         (3)
00179 
00180 /* DNS server set/get options */
00181 #define NETAPP_SET_GET_DNS_OPT_DOMAIN_NAME            (0)
00182 
00183 /* Device Config set/get options */
00184 #define NETAPP_SET_GET_DEV_CONF_OPT_DEVICE_URN        (0)
00185 #define NETAPP_SET_GET_DEV_CONF_OPT_DOMAIN_NAME       (1)
00186 
00187 
00188 /*****************************************************************************/
00189 /* Structure/Enum declarations                                               */
00190 /*****************************************************************************/
00191 
00192 typedef struct
00193 {
00194     _u32    PacketsSent;
00195     _u32    PacketsReceived;
00196     _u16    MinRoundTime;
00197     _u16    MaxRoundTime;
00198     _u16    AvgRoundTime;
00199     _u32    TestTime;
00200 }SlPingReport_t;
00201 
00202 typedef struct
00203 {
00204     _u32    PingIntervalTime;       /* delay between pings, in milliseconds */
00205     _u16    PingSize;               /* ping packet size in bytes           */
00206     _u16    PingRequestTimeout;     /* timeout time for every ping in milliseconds  */
00207     _u32    TotalNumberOfAttempts;  /* max number of ping requests. 0 - forever    */
00208     _u32    Flags;                  /* flag - 0 report only when finished, 1 - return response for every ping, 2 - stop after 1 successful ping.  */
00209     _u32    Ip;                     /* IPv4 address or IPv6 first 4 bytes  */
00210     _u32    Ip1OrPaadding;
00211     _u32    Ip2OrPaadding;
00212     _u32    Ip3OrPaadding;
00213 }SlPingStartCommand_t;
00214 
00215 typedef struct _slHttpServerString_t
00216 {
00217     _u8     len;
00218     _u8     *data;
00219 } slHttpServerString_t;
00220 
00221 typedef struct _slHttpServerData_t
00222 {
00223     _u8     value_len;
00224     _u8     name_len;
00225     _u8     *token_value;
00226     _u8     *token_name;
00227 } slHttpServerData_t;
00228 
00229 typedef struct _slHttpServerPostData_t
00230 {
00231     slHttpServerString_t action;
00232     slHttpServerString_t  token_name;
00233     slHttpServerString_t token_value;
00234 }slHttpServerPostData_t;
00235 
00236 typedef union
00237 {
00238   slHttpServerString_t  httpTokenName; /* SL_NETAPP_HTTPGETTOKENVALUE */
00239   slHttpServerPostData_t   httpPostData;  /* SL_NETAPP_HTTPPOSTTOKENVALUE */
00240 } SlHttpServerEventData_u;
00241 
00242 typedef union
00243 {
00244   slHttpServerString_t token_value;
00245 } SlHttpServerResponsedata_u;
00246 
00247 typedef struct
00248 {
00249    _u32                    Event;
00250    SlHttpServerEventData_u EventData;
00251 }SlHttpServerEvent_t;
00252 
00253 typedef struct
00254 {
00255    _u32                       Response;
00256    SlHttpServerResponsedata_u ResponseData;
00257 }SlHttpServerResponse_t;
00258 
00259 
00260 typedef struct
00261 {
00262     _u32   lease_time;
00263     _u32   ipv4_addr_start;
00264     _u32   ipv4_addr_last;
00265 }SlNetAppDhcpServerBasicOpt_t; 
00266 
00267 /*mDNS parameters*/
00268 typedef enum
00269 {
00270     SL_NET_APP_FULL_SERVICE_WITH_TEXT_IPV4_TYPE = 1,
00271     SL_NET_APP_FULL_SERVICE_IPV4_TYPE,
00272     SL_NET_APP_SHORT_SERVICE_IPV4_TYPE
00273  
00274 } SlNetAppGetServiceListType_e;
00275 
00276 typedef struct
00277 {
00278     _u32   service_ipv4;
00279     _u16   service_port;
00280     _u16   Reserved;
00281 }SlNetAppGetShortServiceIpv4List_t;
00282 
00283 typedef struct
00284 {
00285     _u32   service_ipv4;
00286     _u16   service_port;
00287     _u16   Reserved;
00288     _u8    service_name[NETAPP_MAX_SERVICE_NAME_SIZE];
00289     _u8    service_host[NETAPP_MAX_SERVICE_HOST_NAME_SIZE];
00290 }SlNetAppGetFullServiceIpv4List_t;
00291 
00292 typedef struct
00293 {
00294     _u32    service_ipv4;
00295     _u16    service_port;
00296     _u16    Reserved;
00297     _u8     service_name[NETAPP_MAX_SERVICE_NAME_SIZE];
00298     _u8     service_host[NETAPP_MAX_SERVICE_HOST_NAME_SIZE];
00299     _u8     service_text[NETAPP_MAX_SERVICE_TEXT_SIZE];
00300 }SlNetAppGetFullServiceWithTextIpv4List_t;
00301 
00302 typedef struct
00303 {
00304     /*The below parameters are used to configure the advertise times and interval
00305     For example:
00306         If:
00307         Period is set to T
00308         Repetitions are set to P
00309         Telescopic factor is K=2
00310         The transmission shall be:
00311         advertise P times
00312         wait T
00313         advertise P times
00314         wait 4 * T
00315         advertise P time
00316         wait 16 * T  ... (till max time reached / configuration changed / query issued)
00317     */
00318     _u32    t;              /* Number of ticks for the initial period. Default is 100 ticks for 1 second. */
00319     _u32    p;              /* Number of repetitions. Default value is 1                                  */
00320     _u32    k;              /* Telescopic factor. Default value is 2.                                     */
00321     _u32    RetransInterval;/* Announcing retransmission interval                                         */
00322     _u32    Maxinterval;     /* Announcing max period interval                                            */
00323     _u32    max_time;       /* Announcing max time                                                        */
00324 }SlNetAppServiceAdvertiseTimingParameters_t;
00325 
00326 /*****************************************************************************/
00327 /* Types declarations                                               */
00328 /*****************************************************************************/
00329 typedef void (*P_SL_DEV_PING_CALLBACK)(SlPingReport_t*);
00330 
00331 /*****************************************************************************/
00332 /* Function prototypes                                                       */
00333 /*****************************************************************************/
00334 
00335 
00336 /*!
00337     \brief Starts a network application
00338 
00339     Gets and starts network application for the current WLAN mode
00340 
00341     \param[in] AppBitMap      application bitmap, could be one or combination of the following: \n
00342                               - SL_NET_APP_HTTP_SERVER_ID   
00343                               - SL_NET_APP_DHCP_SERVER_ID   
00344                               - SL_NET_APP_MDNS_ID          
00345 
00346     \return                   On error, negative number is returned
00347 
00348     \sa                       Stop one or more the above started applications using sl_NetAppStop
00349     \note                     This command activates the application for the current WLAN mode (AP or STA)
00350     \warning
00351     \par                 Example:  
00352     \code                
00353     For example: Starting internal HTTP server + DHCP server: 
00354     sl_NetAppStart(SL_NET_APP_HTTP_SERVER_ID | SL_NET_APP_DHCP_SERVER_ID)
00355     
00356     \endcode
00357 */
00358 #if _SL_INCLUDE_FUNC(sl_NetAppStart)
00359 _i16 sl_NetAppStart(_u32 AppBitMap);
00360 #endif
00361 /*!
00362     \brief Stops a network application
00363 
00364     Gets and stops network application for the current WLAN mode
00365 
00366     \param[in] AppBitMap    application id, could be one of the following: \n
00367                             - SL_NET_APP_HTTP_SERVER_ID 
00368                             - SL_NET_APP_DHCP_SERVER_ID 
00369                             - SL_NET_APP_MDNS_ID 
00370 
00371     \return                 On error, negative number is returned
00372 
00373     \sa
00374     \note                This command disables the application for the current active WLAN mode (AP or STA)
00375     \warning
00376     \par                 Example:
00377     \code                
00378     
00379     For example: Stopping internal HTTP server: 
00380                          sl_NetAppStop(SL_NET_APP_HTTP_SERVER_ID); 
00381     
00382     \endcode
00383 */
00384 #if _SL_INCLUDE_FUNC(sl_NetAppStop)
00385 _i16 sl_NetAppStop(_u32 AppBitMap);
00386 #endif
00387 
00388 /*!
00389     \brief Get host IP by name
00390 
00391     Obtain the IP Address of machine on network, by machine name.
00392 
00393     \param[in]  hostname        host name
00394     \param[in]  usNameLen       name length
00395     \param[out] out_ip_addr     This parameter is filled in with
00396                                 host IP address. In case that host name is not
00397                                 resolved, out_ip_addr is zero.
00398     \param[in]  family          protocol family
00399 
00400     \return                     On success, 0 is returned.
00401                                 On error, negative is returned
00402                                 SL_POOL_IS_EMPTY may be return in case there are no resources in the system
00403                                 In this case try again later or increase MAX_CONCURRENT_ACTIONS
00404                                 Possible DNS error codes:
00405                                 - SL_NET_APP_DNS_QUERY_NO_RESPONSE       
00406                                 - SL_NET_APP_DNS_NO_SERVER               
00407                                 - SL_NET_APP_DNS_QUERY_FAILED            
00408                                 - SL_NET_APP_DNS_MALFORMED_PACKET        
00409                                 - SL_NET_APP_DNS_MISMATCHED_RESPONSE     
00410 
00411     \sa
00412     \note   Only one sl_NetAppDnsGetHostByName can be handled at a time.
00413             Calling this API while the same command is called from another thread, may result
00414             in one of the two scenarios:
00415             1. The command will wait (internal) until the previous command finish, and then be executed.
00416             2. There are not enough resources and POOL_IS_EMPTY error will return. 
00417             In this case, MAX_CONCURRENT_ACTIONS can be increased (result in memory increase) or try
00418             again later to issue the command.
00419     \warning
00420     \par  Example:
00421     \code
00422     _u32 DestinationIP;
00423     sl_NetAppDnsGetHostByName("www.google.com", strlen("www.google.com"), &DestinationIP,SL_AF_INET);
00424 
00425     Addr.sin_family = SL_AF_INET;
00426     Addr.sin_port = sl_Htons(80);
00427     Addr.sin_addr.s_addr = sl_Htonl(DestinationIP);
00428     AddrSize = sizeof(SlSockAddrIn_t);
00429     SockID = sl_Socket(SL_AF_INET,SL_SOCK_STREAM, 0);
00430     \endcode
00431 */
00432 #if _SL_INCLUDE_FUNC(sl_NetAppDnsGetHostByName)
00433 _i16 sl_NetAppDnsGetHostByName(_i8 * hostname, _u16 usNameLen, _u32*  out_ip_addr,_u8 family );
00434 #endif
00435 
00436 /*!
00437         \brief Return service attributes like IP address, port and text according to service name
00438         \par
00439         The user sets a service name Full/Part (see example below), and should get:
00440         - IP of service
00441         - The port of service
00442         - The text of service
00443 
00444         Hence it can make a connection to the specific service and use it.
00445         It is similar to get host by name method.
00446         It is done by a single shot query with PTR type on the service name.
00447                   The command that is sent is from constant parameters and variables parameters.
00448 
00449         \param[in]     pService                   Service name can be full or partial. \n
00450                                                   Example for full service name:
00451                                                   1. PC1._ipp._tcp.local
00452                                                   2. PC2_server._ftp._tcp.local \n
00453                                                   .
00454                                                   Example for partial service name:
00455                                                   1. _ipp._tcp.local
00456                                                   2. _ftp._tcp.local
00457 
00458         \param[in]    ServiceLen                  The length of the service name (in_pService).
00459         \param[in]    Family                      IPv4 or IPv6 (SL_AF_INET , SL_AF_INET6).
00460         \param[out]    pAddr                      Contains the IP address of the service.
00461         \param[out]    pPort                      Contains the port of the service.
00462         \param[out]    pTextLen                   Has 2 options. One as Input field and the other one as output:
00463                                                   - Input: \n
00464                                                   Contains the max length of the text that the user wants to get.\n
00465                                                   It means that if the text len of service is bigger that its value than
00466                                                   the text is cut to inout_TextLen value.
00467                                                   - Output: \n
00468                                                    Contain the length of the text that is returned. Can be full text or part of the text (see above).
00469 
00470         \param[out]   pOut_pText     Contains the text of the service full or partial
00471 
00472         \return       On success, zero is returned
00473                       SL_POOL_IS_EMPTY may be return in case there are no resources in the system
00474                       In this case try again later or increase MAX_CONCURRENT_ACTIONS
00475                       In case No service is found error SL_NET_APP_DNS_NO_ANSWER will be returned
00476 
00477         \note         The returns attributes belongs to the first service found.
00478                       There may be other services with the same service name that will response to the query.
00479                       The results of these responses are saved in the peer cache of the Device and should be read by another API.
00480                           
00481                       Only one sl_NetAppDnsGetHostByService can be handled at a time.
00482                       Calling this API while the same command is called from another thread, may result
00483                       in one of the two scenarios:
00484                       1. The command will wait (internal) until the previous command finish, and then be executed.
00485                       2. There are not enough resources and SL_POOL_IS_EMPTY error will return. 
00486                       In this case, MAX_CONCURRENT_ACTIONS can be increased (result in memory increase) or try
00487                       again later to issue the command.
00488 
00489         \warning      Text length can be 120 bytes only
00490 */
00491 #if _SL_INCLUDE_FUNC(sl_NetAppDnsGetHostByService)
00492 _i32 sl_NetAppDnsGetHostByService(_i8  *pServiceName, /*  string containing all (or only part): name + subtype + service */
00493                                   _u8  ServiceLen,
00494                                   _u8  Family,        /*  4-IPv4 , 16-IPv6  */
00495                                   _u32 pAddr[], 
00496                                   _u32 *pPort,
00497                                   _u16 *pTextLen,     /*  in: max len , out: actual len */
00498                                   _i8  *pText
00499                                  );
00500 
00501 #endif
00502 
00503 /*!
00504         \brief Get service List
00505         Insert into out pBuffer a list of peer's services that are the NWP.
00506         The list is in a form of service struct. The user should chose the type
00507         of the service struct like:
00508             - Full service parameters with text.
00509             - Full service parameters.
00510             - Short service parameters (port and IP only) especially for tiny hosts.
00511 
00512         The different types of struct are made to give the 
00513         Possibility to save memory in the host 
00514 
00515         
00516         The user also chose how many max services to get and start point index
00517         NWP peer cache.
00518         For example:
00519             1.    Get max of 3 full services from index 0.Up to 3 full services
00520             from index 0 are inserted into pBuffer (services that are in indexes 0,1,2).
00521             2.    Get max of 4 full services from index 3.Up to 4 full services
00522             from index 3 are inserted into pBuffer (services that are in indexes 3,4,5,6).
00523             3.    Get max of 2 int services from index 6.Up to 2 int services
00524             from index 6 are inserted into pBuffer (services that are in indexes 6,7).
00525 
00526         See below - command parameters.
00527                     
00528         \param[in] indexOffset - The start index in the peer cache that from it the first service is returned.
00529         \param[in] MaxServiceCount - The Max services that can be returned if existed or if not exceed the max index 
00530                       in the peer cache
00531         \param[in] Flags - an ENUM number that means which service struct to use (means which types of service to fill)                                            
00532                         - use SlNetAppGetFullServiceWithTextIpv4List_t
00533                         - use SlNetAppGetFullServiceIpv4List_t
00534                         - use SlNetAppGetShortServiceIpv4List_t
00535 
00536        \param[out]  Buffer - The Services are inserted into this buffer. In the struct form according to the bit that is set in the Flags 
00537                       input parameter.
00538  
00539         \return    ServiceFoundCount - The number of the services that were inserted into the buffer. zero means no service is found 
00540                     negative number means an error
00541         \sa           sl_NetAppMDNSRegisterService
00542         \note        
00543         \warning 
00544                     if the out pBuffer size is bigger than an RX packet(1480), than
00545                     an error is returned because there
00546                     is no place in the RX packet.
00547                     The size is a multiply of MaxServiceCount and size of service struct(that is set 
00548                     according to flag value).
00549 */
00550 
00551 #if _SL_INCLUDE_FUNC(sl_NetAppGetServiceList)
00552 _i16 sl_NetAppGetServiceList(_u8   IndexOffest,
00553                              _u8   MaxServiceCount,
00554                              _u8   Flags,
00555                              _i8   *pBuffer,
00556                              _u32  RxBufferLength
00557                             );
00558 
00559 #endif
00560 
00561 /*!
00562         \brief Unregister mDNS service
00563         This function deletes the mDNS service from the mDNS package and the database.
00564 
00565         The mDNS service that is to be unregistered is a service that the application no longer wishes to provide. \n
00566         The service name should be the full service name according to RFC
00567         of the DNS-SD - meaning the value in name field in the SRV answer.
00568                     
00569         Examples for service names:
00570         1. PC1._ipp._tcp.local
00571         2. PC2_server._ftp._tcp.local
00572 
00573         \param[in]    pServiceName            Full service name. \n
00574                                                 Example for service name:
00575                                                 1. PC1._ipp._tcp.local
00576                                                 2. PC2_server._ftp._tcp.local
00577         \param[in]    ServiceLen              The length of the service. 
00578         \return    On success, zero is returned 
00579         \sa          sl_NetAppMDNSRegisterService
00580         \note        
00581         \warning 
00582         The size of the service length should be smaller than 255.
00583 */
00584 #if _SL_INCLUDE_FUNC(sl_NetAppMDNSUnRegisterService)
00585 _i16 sl_NetAppMDNSUnRegisterService(const _i8 *pServiceName,_u8 ServiceNameLen);
00586 #endif
00587 
00588 /*!
00589         \brief Register a new mDNS service
00590         \par
00591         This function registers a new mDNS service to the mDNS package and the DB.
00592                     
00593         This registered service is a service offered by the application.
00594         The service name should be full service name according to RFC
00595         of the DNS-SD - meaning the value in name field in the SRV answer.
00596         Example for service name:
00597         1. PC1._ipp._tcp.local
00598         2. PC2_server._ftp._tcp.local
00599 
00600         If the option is_unique is set, mDNS probes the service name to make sure
00601         it is unique before starting to announce the service on the network.
00602         Instance is the instance portion of the service name.
00603 
00604         \param[in]  ServiceLen         The length of the service.
00605         \param[in]  TextLen            The length of the service should be smaller than 64.
00606         \param[in]  port               The port on this target host port.
00607         \param[in]  TTL                The TTL of the service
00608         \param[in]  Options            bitwise parameters: \n
00609                                        - bit 0  - service is unique (means that the service needs to be unique)
00610                                        - bit 31  - for internal use if the service should be added or deleted (set means ADD).
00611                                        - bit 1-30 for future.
00612 
00613         \param[in]    pServiceName              The service name.
00614                                        Example for service name: \n
00615                                                 1. PC1._ipp._tcp.local
00616                                                 2. PC2_server._ftp._tcp.local
00617 
00618         \param[in] pText                     The description of the service.
00619                                                 should be as mentioned in the RFC
00620                                                 (according to type of the service IPP,FTP...)
00621 
00622         \return     On success, zero is returned
00623                     Possible error codes:
00624                     - Maximum advertise services are already configured. 
00625                                 Delete another existed service that is registered and then register again the new service
00626                     - Trying to register a service that is already exists
00627                     - Trying to delete service that does not existed
00628                     - Illegal service name according to the RFC
00629                     - Retry request
00630                     - Illegal length of one of the mDNS Set functions
00631                     - mDNS is not operational as the device has no IP.Connect the device to an AP to get an IP address.
00632                     - mDNS parameters error
00633                     - mDNS internal cache error
00634                     - mDNS internal error
00635                     - Adding a service is not allowed as it is already exist (duplicate service)
00636                     - mDNS is not running                    
00637                     - Host name error. Host name format is not allowed according to RFC 1033,1034,1035, 6763
00638                     - List size buffer is bigger than internally allowed in the NWP (API get service list),
00639                      change the APIs� parameters to decrease the size of the list
00640                                         
00641 
00642         \sa              sl_NetAppMDNSUnRegisterService
00643 
00644         \warning      1) Temporary -  there is an allocation on stack of internal buffer.
00645                     Its size is NETAPP_MDNS_MAX_SERVICE_NAME_AND_TEXT_LENGTH. \n
00646                     It means that the sum of the text length and service name length cannot be bigger than
00647                     NETAPP_MDNS_MAX_SERVICE_NAME_AND_TEXT_LENGTH.\n
00648                     If it is - An error is returned. \n
00649                     2) According to now from certain constraints the variables parameters are set in the
00650                     attribute part (contain constant parameters)
00651 */
00652 #if _SL_INCLUDE_FUNC(sl_NetAppMDNSRegisterService)
00653 _i16 sl_NetAppMDNSRegisterService( const _i8*  pServiceName, 
00654                                    _u8         ServiceNameLen,
00655                                    const _i8*  pText,
00656                                    _u8         TextLen,
00657                                    _u16        Port,
00658                                    _u32        TTL,
00659                                    _u32        Options);
00660 #endif
00661 
00662 /*!
00663     \brief send ICMP ECHO_REQUEST to network hosts
00664 
00665     Ping uses the ICMP protocol's mandatory ECHO_REQUEST
00666 
00667     \param[in]   pPingParams     Pointer to the ping request structure: \n
00668                                  - if flags parameter is set to 0, ping will report back once all requested pings are done (as defined by TotalNumberOfAttempts). \n
00669                                  - if flags parameter is set to 1, ping will report back after every ping, for TotalNumberOfAttempts.
00670                                  - if flags parameter is set to 2, ping will stop after the first successful ping, and report back for the successful ping, as well as any preceding failed ones. 
00671                                  For stopping an ongoing ping activity, set parameters IP address to 0
00672                                  
00673     \param[in]   family          SL_AF_INET or  SL_AF_INET6
00674     \param[out]  pReport         Ping pReport
00675     \param[out]  pCallback       Callback function upon completion.
00676                                  If callback is NULL, the API is blocked until data arrives
00677 
00678 
00679     \return    On success, zero is returned. On error, -1 is returned
00680                SL_POOL_IS_EMPTY may be return in case there are no resources in the system
00681                In this case try again later or increase MAX_CONCURRENT_ACTIONS
00682 
00683     \sa       sl_NetAppPingReport
00684     \note      Only one sl_NetAppPingStart can be handled at a time.
00685               Calling this API while the same command is called from another thread, may result
00686                   in one of the two scenarios:
00687               1. The command will wait (internal) until the previous command finish, and then be executed.
00688               2. There are not enough resources and SL_POOL_IS_EMPTY error will return. 
00689               In this case, MAX_CONCURRENT_ACTIONS can be increased (result in memory increase) or try
00690               again later to issue the command.
00691     \warning  
00692     \par      Example:
00693     \code     
00694     
00695     An example of sending 20 ping requests and reporting results to a callback routine when 
00696               all requests are sent:
00697 
00698               // callback routine
00699               void pingRes(SlPingReport_t* pReport)
00700               {
00701                // handle ping results 
00702               }
00703               
00704               // ping activation
00705               void PingTest()
00706               {
00707                  SlPingReport_t report;
00708                  SlPingStartCommand_t pingCommand;
00709                  
00710                  pingCommand.Ip = SL_IPV4_VAL(10,1,1,200);     // destination IP address is 10.1.1.200
00711                  pingCommand.PingSize = 150;                   // size of ping, in bytes 
00712                  pingCommand.PingIntervalTime = 100;           // delay between pings, in milliseconds
00713                  pingCommand.PingRequestTimeout = 1000;        // timeout for every ping in milliseconds
00714                  pingCommand.TotalNumberOfAttempts = 20;       // max number of ping requests. 0 - forever 
00715                  pingCommand.Flags = 0;                        // report only when finished
00716   
00717                  sl_NetAppPingStart( &pingCommand, SL_AF_INET, &report, pingRes ) ;
00718              }
00719 
00720     \endcode
00721 */
00722 #if _SL_INCLUDE_FUNC(sl_NetAppPingStart)
00723 _i16 sl_NetAppPingStart(SlPingStartCommand_t* pPingParams,_u8 family,SlPingReport_t *pReport,const P_SL_DEV_PING_CALLBACK pPingCallback);
00724 #endif
00725 
00726 /*!
00727     \brief     Internal function for setting network application configurations
00728 
00729     \return    On success, zero is returned. On error, -1 is
00730                returned
00731 
00732     \param[in] AppId          Application id, could be one of the following: \n
00733                               - SL_NET_APP_HTTP_SERVER_ID
00734                               - SL_NET_APP_DHCP_SERVER_ID
00735                               - SL_NET_APP_DHCP_SERVER_ID
00736 
00737     \param[in] SetOptions     set option, could be one of the following: \n
00738                               NETAPP_SET_BASIC_OPT
00739 
00740     \param[in] OptionLen       option structure length
00741 
00742     \param[in] pOptionValues   pointer to the option structure
00743     \sa
00744     \note
00745     \warning
00746     \par
00747     \code
00748         Set DHCP Server (AP mode) parameters example:
00749                           
00750         SlNetAppDhcpServerBasicOpt_t dhcpParams; 
00751         _u8 outLen = sizeof(SlNetAppDhcpServerBasicOpt_t); 
00752         dhcpParams.lease_time      = 4096;                         // lease time (in seconds) of the IP Address
00753         dhcpParams.ipv4_addr_start =  SL_IPV4_VAL(192,168,1,10);   // first IP Address for allocation. IP Address should be set as Hex number - i.e. 0A0B0C01 for (10.11.12.1)
00754         dhcpParams.ipv4_addr_last  =  SL_IPV4_VAL(192,168,1,16);   // last IP Address for allocation. IP Address should be set as Hex number - i.e. 0A0B0C01 for (10.11.12.1)
00755         sl_NetAppStop(SL_NET_APP_DHCP_SERVER_ID);                  // Stop DHCP server before settings
00756         sl_NetAppSet(SL_NET_APP_DHCP_SERVER_ID, NETAPP_SET_DHCP_SRV_BASIC_OPT, outLen, (_u8* )&dhcpParams);  // set parameters
00757         sl_NetAppStart(SL_NET_APP_DHCP_SERVER_ID);                 // Start DHCP server with new settings
00758     \endcode
00759     \code
00760         Set Device URN name example:
00761  
00762         Device name, maximum length of 33 characters 
00763         Device name affects URN name, own SSID name in AP mode, and WPS file "device name" in WPS I.E (STA-WPS / P2P)
00764         In case no device URN name set, the default name is "mysimplelink" 
00765         Allowed characters in device name are: 'a - z' , 'A - Z' , '0-9' and '-'
00766 
00767         _u8 *my_device = "MY-SIMPLELINK-DEV";
00768         sl_NetAppSet (SL_NET_APP_DEVICE_CONFIG_ID, NETAPP_SET_GET_DEV_CONF_OPT_DEVICE_URN, strlen(my_device), (_u8 *) my_device);
00769     \endcode
00770 
00771 */
00772 #if _SL_INCLUDE_FUNC(sl_NetAppSet)
00773 _i32 sl_NetAppSet(_u8 AppId ,_u8 Option,_u8 OptionLen, _u8 *pOptionValue);
00774 #endif
00775 
00776 /*!
00777     \brief     Internal function for getting network applications configurations
00778 
00779     \return    On success, zero is returned. On error, -1 is
00780                returned
00781 
00782     \param[in] AppId          Application id, could be one of the following: \n
00783                               - SL_NET_APP_HTTP_SERVER_ID
00784                               - SL_NET_APP_DHCP_SERVER_ID
00785 
00786     \param[in] Options        Get option, could be one of the following: \n
00787                               NETAPP_SET_BASIC_OPT
00788 
00789     \param[in] OptionLen     The length of the allocated memory as input, when the
00790                                         function complete, the value of this parameter would be
00791                                         the len that actually read from the device.
00792                                         If the device return length that is longer from the input
00793                                         value, the function will cut the end of the returned structure
00794                                         and will return ESMALLBUF
00795 
00796     \param[out] pValues      pointer to the option structure which will be filled with the response from the device
00797 
00798     \sa
00799     \note
00800     \warning
00801     \par
00802     \code
00803          Get DHCP Server parameters example:
00804 
00805          SlNetAppDhcpServerBasicOpt_t dhcpParams;
00806          _u8 outLen = sizeof(SlNetAppDhcpServerBasicOpt_t);
00807          sl_NetAppGet(SL_NET_APP_DHCP_SERVER_ID, NETAPP_SET_DHCP_SRV_BASIC_OPT, &outLen, (_u8* )&dhcpParams);
00808  
00809          printf("DHCP Start IP %d.%d.%d.%d End IP %d.%d.%d.%d Lease time seconds %d\n",                                                           
00810             SL_IPV4_BYTE(dhcpParams.ipv4_addr_start,3),SL_IPV4_BYTE(dhcpParams.ipv4_addr_start,2),
00811             SL_IPV4_BYTE(dhcpParams.ipv4_addr_start,1),SL_IPV4_BYTE(dhcpParams.ipv4_addr_start,0), 
00812             SL_IPV4_BYTE(dhcpParams.ipv4_addr_last,3),SL_IPV4_BYTE(dhcpParams.ipv4_addr_last,2),
00813             SL_IPV4_BYTE(dhcpParams.ipv4_addr_last,1),SL_IPV4_BYTE(dhcpParams.ipv4_addr_last,0),         
00814             dhcpParams.lease_time);    
00815     \endcode
00816     \code
00817          Get Device URN name example:
00818          Maximum length of 33 characters of device name. 
00819          Device name affects URN name, own SSID name in AP mode, and WPS file "device name" in WPS I.E (STA-WPS / P2P)
00820          in case no device URN name set, the default name is "mysimplelink" 
00821 
00822          _u8 my_device_name[35];
00823          sl_NetAppGet (SL_NET_APP_DEVICE_CONFIG_ID, NETAPP_SET_GET_DEV_CONF_OPT_DEVICE_URN, strlen(my_device_name), (_u8 *)my_device_name); 
00824     \endcode
00825 */
00826 #if _SL_INCLUDE_FUNC(sl_NetAppGet)
00827 _i32 sl_NetAppGet(_u8 AppId, _u8 Option,_u8 *pOptionLen, _u8 *pOptionValue);
00828 #endif
00829 
00830 
00831 
00832 /*!
00833 
00834  Close the Doxygen group.
00835  @}
00836 
00837  */
00838 
00839 
00840 #ifdef  __cplusplus
00841 }
00842 #endif /*  __cplusplus */
00843 
00844 #endif    /*  __NETAPP_H__ */
00845 
00846