The client component provides means to retrieve data over a network using several protocols. The protocols currently supported are HTTP and FILE. The client can be used to retrieve ASCII or binary based documents. It has both a Tcl and a C++ interface, enabling its use in both script and C++ programs. The FILE protocol maps a file suffix to a MIME type using the definitions in your $HOME/.mime.types$

The interface of the client component is given below. The methods are grouped on the task they accomplish: sending requests, getting replies (two variants) and information about the reply.

    interface client {
          client();       
          ~client();
          
          // build request
          void get(const char* url);
          bool send_request();
  
          // get reply
          bool get_reply(char* &buffer, int &length);
          bool get_reply_header(char* &buffer, int &length);
          bool get_reply_body(char* &buffer, int &length);
          bool get_reply_trailer(char* &buffer, int &length);
          
          // alternative reply , use get_reply() first
          bool get_reply();               // use this first
          bool get_reply_body(int &fd);   // body can be read using fd
          
          // info about reply
          MIME* media();
          int length(void);
          int errorcode(void); 
    }; 
  

To retrieve data, a request has to be build first using get(url). The request can be send using send_request().

Two possibilities of getting a reply exist. It is possible to get the reply in a buffer that is created by the client component get_reply(buffer, length). This buffer will be available until the client is used to retrieve another document. It possible to get a pointer to the total reply (get_reply) but also to only parts of the reply, e.g. the header (get_reply_header), the body (get_reply_body) or the trailer (get_reply_trailer). An alternative reply is achieved by reading the file (socket) descriptor immediately. Although it should be faster (no buffering occurs), once the data is read it cannot be reread again.

Information about the data (transfer) can be obtained using the last group of methods. media returns the MIME type of the data, length the length of the body of the reply and errorcode returns the errorcode of the last transfer.

The following C++ example program shows how to employ the client component. The main function of the application creates a client object called net. This object is used to retrieve the hush-homepage into Buffer. After the page has been displayed some information about the length and MIME type of the hush homepage is shown.

    #include <hush/session.h>
    #include <hush/kit.h>
    #include <hush/client/client.h>
    #include <hush/client/MIME.h>
    #include <iostream.h>
  
    class application: public session {
        public:
          application(int argc, char* argv[], char* name):
                  session(argc, argv, name) {};
  
          int main() {
                  char* Buffer;
                  int Length;
                  client net;
  
                  net.get("http://www.cs.vu.nl/~hush/");
                  net.send_request();
                  net.get_reply_body(Buffer, Length);
                  
                  cout << "The hush homepage is:" << endl;
                  cout << Buffer;
                  cout << "The length is: " << Length << endl;
                  MIME* m = net.media();
                  cout << "The MIME type is: ";
                  cout << m->type() << "/" << m->subtype() << endl;
                  tk->quit();
                  return OK;
          }
    };
  
    int main(int argc, char* argv[])
    {
          application* App = new application(argc, argv, 0);
          return App.run();
    }
  

Not all MIME types are correctly recognized by the FILE protocol.