STMClientRest.h

00001 
00002 #ifndef _STM_CLIENT_REST_H_
00003 #define _STM_CLIENT_REST_H_
00004 
00005 #include "FP.h"
00006 #include "STMClient.h"
00007 
00008 // Default timeout for REST requests when waiting for a response
00009 #define DEFAULT_REST_TIMEOUT  5000
00010 
00011 typedef enum {
00012   HTTP_STATUS_OK = 200
00013 } HTTP_STATUS;
00014 
00015 // The STMClientRest class makes simple REST requests to a remote server. Each instance
00016 // is used to communicate with one server and multiple instances can be created to make
00017 // requests to multiple servers.
00018 // The STMClientRest class does not support concurrent requests to the same server because
00019 // only a single response can be recevied at a time and the responses of the two requests
00020 // may arrive out of order.
00021 // A major limitation of the REST class is that it does not store the response body. The
00022 // response status is saved in the class instance, so after a request completes and before
00023 // the next request is made a call to getResponse will return the status. However, only a pointer
00024 // to the response body is saved, which means that if any other message arrives and is
00025 // processed then the response body is overwritten by it. What this means is that if you
00026 // need the response body you best use waitResponse or ensure that any call to STMClient::process
00027 // is followed by a call to getResponse. Ideally someone improves this class to take a callback
00028 // into the user's sketch?
00029 // Another limitation is that the response body is 100 chars long at most, this is due to the
00030 // limitation of the SLIP protocol buffer available.
00031 class STMClientRest {
00032   public:
00033     STMClientRest(STMClient *e);
00034 
00035     // Initialize communication to a remote server, this communicates with esp-link but does not
00036     // open a connection to the remote server. Host may be a hostname or an IP address,
00037     // security causes HTTPS to be used (not yet supported). Returns 0 if the set-up is
00038     // successful, returns a negative error code if it failed.
00039     int begin(const char* host, uint16_t port=80, bool security=false);
00040 
00041     // Make a request to the remote server. The data must be null-terminated
00042     void request(const char* path, const char* method, const char* data=NULL);
00043 
00044     // Make a request to the remote server.
00045     void request(const char* path, const char* method, const char* data, int len);
00046 
00047     // Make a GET request to the remote server with NULL-terminated data
00048     void get(const char* path, const char* data=NULL);
00049 
00050     // Make a POST request to the remote server with NULL-terminated data
00051     void post(const char* path, const char* data);
00052 
00053     // Make a PUT request to the remote server with NULL-terminated data
00054     void put(const char* path, const char* data);
00055 
00056     // Make a DELETE request to the remote server
00057     void del(const char* path);
00058 
00059     // Retrieve the response from the remote server, returns the HTTP status code, 0 if no
00060     // response (may need to wait longer)
00061     uint16_t getResponse(char* data, uint16_t maxLen);
00062 
00063     // Wait for the response from the remote server, returns the HTTP status code, 0 if no
00064     // response (timeout occurred)
00065     uint16_t waitResponse(char* data, uint16_t maxLen, uint32_t timeout=DEFAULT_REST_TIMEOUT);
00066 
00067     // Set the user-agent for all subsequent requests
00068     void setUserAgent(const char* value);
00069 
00070     // Set the Content-Type Header for all subsequent requests
00071     void setContentType(const char* value);
00072 
00073     // Set a custom header for all subsequent requests
00074     void setHeader(const char* value);
00075 
00076   private:
00077     int32_t remote_instance;
00078     STMClient *_elc;
00079     void restCallback(void* resp);
00080     FP<void, void*>  restCb;
00081 
00082     int16_t _status;
00083     uint16_t _len;
00084     void *_data;
00085 
00086 
00087 };
00088 #endif // _STM_CLIENT_REST_H_