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 /** @} */

Generated on Mon Jun 12 10:23:01 2006 for uIP 1.0 by  doxygen 1.4.6