# apps/webclient/webclient.h

Go to the documentation of this file.

    00001 /**
    00002  * \addtogroup webclient
    00003  * @{
    00004  */
    00005
    00006 /**
    00007  * \file
    00008  * Header file for the HTTP client.
    00009  * \author Adam Dunkels <adam@dunkels.com>
    00010  */
    00011
    00012 /*
    00013  * Copyright (c) 2002, Adam Dunkels.
    00014  * All rights reserved.
    00015  *
    00016  * Redistribution and use in source and binary forms, with or without
    00017  * modification, are permitted provided that the following conditions
    00018  * are met:
    00019  * 1. Redistributions of source code must retain the above copyright
    00020  *    notice, this list of conditions and the following disclaimer.
    00021  * 2. Redistributions in binary form must reproduce the above
    00022  *    copyright notice, this list of conditions and the following
    00023  *    disclaimer in the documentation and/or other materials provided
    00024  *    with the distribution.
    00025  * 3. The name of the author may not be used to endorse or promote
    00026  *    products derived from this software without specific prior
    00027  *    written permission.
    00028  *
    00029  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
    00030  * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    00031  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    00032  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
    00033  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    00034  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
    00035  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    00036  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    00037  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    00038  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    00039  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    00040  *
    00041  * This file is part of the uIP TCP/IP stack.
    00042  *
    00043  * $Id: webclient.h,v 1.2 2006/06/11 21:46:37 adam Exp $
    00044  *
    00045  */
    00046 #ifndef __WEBCLIENT_H__
    00047 #define __WEBCLIENT_H__
    00048
    00049
    00050 #include "webclient-strings.h"
    00051 #include "uipopt.h"
    00052
    00053 #define WEBCLIENT_CONF_MAX_URLLEN 100
    00054
    00055 struct webclient_state {
    00056   u8_t timer;
    00057   u8_t state;
    00058   u8_t httpflag;
    00059
    00060   u16_t port;
    00061   char host[40];
    00062   char file[WEBCLIENT_CONF_MAX_URLLEN];
    00063   u16_t getrequestptr;
    00064   u16_t getrequestleft;
    00065
    00066   char httpheaderline[200];
    00067   u16_t httpheaderlineptr;
    00068
    00069   char mimetype[32];
    00070 };
    00071
    00072 typedef struct webclient_state uip_tcp_appstate_t;
    00073 #define UIP_APPCALL webclient_appcall
    00074
    00075 /**
    00076  * Callback function that is called from the webclient code when HTTP
    00077  * data has been received.
    00078  *
    00079  * This function must be implemented by the module that uses the
    00080  * webclient code. The function is called from the webclient module
    00081  * when HTTP data has been received. The function is not called when
    00082  * HTTP headers are received, only for the actual data.
    00083  *
    00084  * \note This function is called many times, repetedly, when data is
    00085  * being received, and not once when all data has been received.
    00086  *
    00087  * \param data A pointer to the data that has been received.
    00088  * \param len The length of the data that has been received.
    00089  */
    00090 void webclient_datahandler(char *data, u16_t len);
    00091
    00092 /**
    00093  * Callback function that is called from the webclient code when the
    00094  * HTTP connection has been connected to the web server.
    00095  *
    00096  * This function must be implemented by the module that uses the
    00097  * webclient code.
    00098  */
    00099 void webclient_connected(void);
    00100
    00101 /**
    00102  * Callback function that is called from the webclient code if the
    00103  * HTTP connection to the web server has timed out.
    00104  *
    00105  * This function must be implemented by the module that uses the
    00106  * webclient code.
    00107  */
    00108 void webclient_timedout(void);
    00109
    00110 /**
    00111  * Callback function that is called from the webclient code if the
    00112  * HTTP connection to the web server has been aborted by the web
    00113  * server.
    00114  *
    00115  * This function must be implemented by the module that uses the
    00116  * webclient code.
    00117  */
    00118 void webclient_aborted(void);
    00119
    00120 /**
    00121  * Callback function that is called from the webclient code when the
    00122  * HTTP connection to the web server has been closed.
    00123  *
    00124  * This function must be implemented by the module that uses the
    00125  * webclient code.
    00126  */
    00127 void webclient_closed(void);
    00128
    00129
    00130
    00131 /**
    00132  * Initialize the webclient module.
    00133  */
    00134 void webclient_init(void);
    00135
    00136 /**
    00137  * Open an HTTP connection to a web server and ask for a file using
    00138  * the GET method.
    00139  *
    00140  * This function opens an HTTP connection to the specified web server
    00141  * and requests the specified file using the GET method. When the HTTP
    00142  * connection has been connected, the webclient_connected() callback
    00143  * function is called and when the HTTP data arrives the
    00144  * webclient_datahandler() callback function is called.
    00145  *
    00146  * The callback function webclient_timedout() is called if the web
    00147  * server could not be contacted, and the webclient_aborted() callback
    00148  * function is called if the HTTP connection is aborted by the web
    00149  * server.
    00150  *
    00151  * When the HTTP request has been completed and the HTTP connection is
    00152  * closed, the webclient_closed() callback function will be called.
    00153  *
    00154  * \note If the function is passed a host name, it must already be in
    00155  * the resolver cache in order for the function to connect to the web
    00156  * server. It is therefore up to the calling module to implement the
    00157  * resolver calls and the signal handler used for reporting a resolv
    00158  * query answer.
    00159  *
    00160  * \param host A pointer to a string containing either a host name or
    00161  * a numerical IP address in dotted decimal notation (e.g., 192.168.23.1).
    00162  *
    00163  * \param port The port number to which to connect, in host byte order.
    00164  *
    00165  * \param file A pointer to the name of the file to get.
    00166  *
    00167  * \retval 0 if the host name could not be found in the cache, or
    00168  * if a TCP connection could not be created.
    00169  *
    00170  * \retval 1 if the connection was initiated.
    00171  */
    00172 unsigned char webclient_get(char *host, u16_t port, char *file);
    00173
    00174 /**
    00175  * Close the currently open HTTP connection.
    00176  */
    00177 void webclient_close(void);
    00178 void webclient_appcall(void);
    00179
    00180 /**
    00181  * Obtain the MIME type of the current HTTP data stream.
    00182  *
    00183  * \return A pointer to a string contaning the MIME type. The string
    00184  * may be empty if no MIME type was reported by the web server.
    00185  */
    00186 char *webclient_mimetype(void);
    00187
    00188 /**
    00189  * Obtain the filename of the current HTTP data stream.
    00190  *
    00191  * The filename of an HTTP request may be changed by the web server,
    00192  * and may therefore not be the same as when the original GET request
    00193  * was made with webclient_get(). This function is used for obtaining
    00194  * the current filename.
    00195  *
    00196  * \return A pointer to the current filename.
    00197  */
    00198 char *webclient_filename(void);
    00199
    00200 /**
    00201  * Obtain the hostname of the current HTTP data stream.
    00202  *
    00203  * The hostname of the web server of an HTTP request may be changed
    00204  * by the web server, and may therefore not be the same as when the
    00205  * original GET request was made with webclient_get(). This function
    00206  * is used for obtaining the current hostname.
    00207  *
    00208  * \return A pointer to the current hostname.
    00209  */
    00210 char *webclient_hostname(void);
    00211
    00212 /**
    00213  * Obtain the port number of the current HTTP data stream.
    00214  *
    00215  * The port number of an HTTP request may be changed by the web
    00216  * server, and may therefore not be the same as when the original GET
    00217  * request was made with webclient_get(). This function is used for
    00218  * obtaining the current port number.
    00219  *
    00220  * \return The port number of the current HTTP data stream, in host byte order.
    00221  */
    00222 unsigned short webclient_port(void);
    00223
    00224
    00225
    00226 #endif /* __WEBCLIENT_H__ */
    00227
    00228 /** @} */