netconnectionhttp.h File Reference

#include <gwenhywfar/gwenhywfarapi.h>
#include <gwenhywfar/netconnection.h>
#include <gwenhywfar/bufferedio.h>

Go to the source code of this file.

Mode Settings

#define GWEN_NETCONN_MODE_DEFAULT
#define GWEN_NETCONN_MODE_IPC   0x00000004
#define GWEN_NETCONN_MODE_RAW   0x00000004
#define GWEN_NETCONN_MODE_WAITBEFOREBODYREAD   0x00000002
#define GWEN_NETCONN_MODE_WAITBEFOREREAD   0x00000001

Status Settings

#define GWEN_NETCONNHTTP_STATE_STARTEDBODYREAD   0x0002
#define GWEN_NETCONNHTTP_STATE_STARTEDREAD   0x0001
#define GWEN_NETCONNHTTP_STATE_WAITINGFORBODYREAD   0x0008
#define GWEN_NETCONNHTTP_STATE_WAITINGFORREAD   0x0004

Reading the Message Body

When receiving a message this class does this:
Whenever there is an error while reading the message body the callback function GWEN_NETCONNHTTP_WRITEBODY_FN will be called with mode=GWEN_NetConnHttp_WriteBodyModeAbort

typedef int(* GWEN_NETCONNHTTP_WRITEBODY_FN )(GWEN_NETCONNECTION *conn, const char *buffer, GWEN_TYPE_UINT32 *bsize, GWEN_NETCONNHTTP_WRITEBODY_MODE m)
GWENHYWFAR_API GWEN_NETMSGGWEN_NetConnectionHTTP_GetCurrentInMsg (GWEN_NETCONNECTION *conn)
GWENHYWFAR_API void GWEN_NetConnectionHTTP_StartBodyRead (GWEN_NETCONNECTION *conn)
GWENHYWFAR_API void GWEN_NetConnectionHTTP_StartRead (GWEN_NETCONNECTION *conn)

Informational Functions

GWENHYWFAR_API void GWEN_NetConnectionHTTP_AddMode (GWEN_NETCONNECTION *conn, GWEN_TYPE_UINT32 m)
const char * GWEN_NetConnectionHTTP_GetDefaultURL (const GWEN_NETCONNECTION *conn)
GWENHYWFAR_API GWEN_TYPE_UINT32 GWEN_NetConnectionHTTP_GetMode (GWEN_NETCONNECTION *conn)
GWENHYWFAR_API GWEN_TYPE_UINT32 GWEN_NetConnectionHTTP_GetState (GWEN_NETCONNECTION *conn)
void GWEN_NetConnectionHTTP_SetDefaultURL (GWEN_NETCONNECTION *conn, const char *s)
GWENHYWFAR_API void GWEN_NetConnectionHTTP_SetMode (GWEN_NETCONNECTION *conn, GWEN_TYPE_UINT32 m)
GWENHYWFAR_API void GWEN_NetConnectionHTTP_SubMode (GWEN_NETCONNECTION *conn, GWEN_TYPE_UINT32 m)
GWENHYWFAR_API int GWEN_NetConnectionHTTP_AddRequest (GWEN_NETCONNECTION *conn, GWEN_DB_NODE *dbRequest, GWEN_BUFFER *body, GWEN_BUFFEREDIO *bio)
GWENHYWFAR_API int GWEN_NetConnectionHTTP_AddResponse (GWEN_NETCONNECTION *conn, GWEN_DB_NODE *dbResponse, GWEN_BUFFER *body, GWEN_BUFFEREDIO *bio)

Tool Functions

GWENHYWFAR_API void GWEN_NetConnectionHTTP_Escape (const char *src, GWEN_BUFFER *buf)
GWENHYWFAR_API int GWEN_NetConnectionHTTP_Unescape (const char *src, GWEN_BUFFER *buf)

Enumerations

enum  GWEN_NETCONNHTTP_WRITEBODY_MODE { GWEN_NetConnHttp_WriteBodyModeStart = 0, GWEN_NetConnHttp_WriteBodyModeWrite, GWEN_NetConnHttp_WriteBodyModeStop, GWEN_NetConnHttp_WriteBodyModeAbort }

Functions

GWENHYWFAR_API GWEN_NETCONNECTIONGWEN_NetConnectionHTTP_new (GWEN_NETTRANSPORT *tr, int take, GWEN_TYPE_UINT32 libId, int pmajor, int pminor)


Define Documentation

#define GWEN_NETCONN_MODE_DEFAULT
 

Value:

(\
  0 \
  )

#define GWEN_NETCONN_MODE_IPC   0x00000004
 

Always act as if this were a passive connection as opposed to an active one. This is only usefull for passive connections (as used by HTTP servers) if you want to use the protocol for IPC purposes.

Without this flag the connection could only work in a one-way request-response mode. With this flag set there are only requests (so the server must return another request in order to tell the requestor about the result).

If this sounds complicated to you then you most probably do not need this mode ;-) However, it MUST NOT be activated for normal HTTP io.

#define GWEN_NETCONN_MODE_RAW   0x00000004
 

#define GWEN_NETCONN_MODE_WAITBEFOREBODYREAD   0x00000002
 

#define GWEN_NETCONN_MODE_WAITBEFOREREAD   0x00000001
 

#define GWEN_NETCONNHTTP_STATE_STARTEDBODYREAD   0x0002
 

Started to read the body of the next message

#define GWEN_NETCONNHTTP_STATE_STARTEDREAD   0x0001
 

Started to read the next message

#define GWEN_NETCONNHTTP_STATE_WAITINGFORBODYREAD   0x0008
 

Waiting for the program's ok to start reading the body of the next message. The program must call GWEN_NetConnectionHTTP_StartBodyRead to actually start reading the body.

#define GWEN_NETCONNHTTP_STATE_WAITINGFORREAD   0x0004
 

Waiting for the program's ok to start reading the next message. The program must call GWEN_NetConnectionHTTP_StartRead to actually start reading


Typedef Documentation

typedef int(* GWEN_NETCONNHTTP_WRITEBODY_FN)(GWEN_NETCONNECTION *conn, const char *buffer, GWEN_TYPE_UINT32 *bsize, GWEN_NETCONNHTTP_WRITEBODY_MODE m)
 


Enumeration Type Documentation

enum GWEN_NETCONNHTTP_WRITEBODY_MODE
 

This type is used when calling the callback function which writes the body received.

Enumerator:
GWEN_NetConnHttp_WriteBodyModeStart  starting to receive the message body
GWEN_NetConnHttp_WriteBodyModeWrite  have something to write (part of the message body)
GWEN_NetConnHttp_WriteBodyModeStop  finished receiving the body of the message
GWEN_NetConnHttp_WriteBodyModeAbort  aborting reception of the message body (due to an error)


Function Documentation

GWENHYWFAR_API void GWEN_NetConnectionHTTP_AddMode GWEN_NETCONNECTION conn,
GWEN_TYPE_UINT32  m
 

GWENHYWFAR_API int GWEN_NetConnectionHTTP_AddRequest GWEN_NETCONNECTION conn,
GWEN_DB_NODE dbRequest,
GWEN_BUFFER body,
GWEN_BUFFEREDIO bio
 

Functions in this group add a request or response which is sent as soon as possible. The request itself consists of three parts:

  • a command (or a status in case of a response)
  • an optional header
  • a message body

The first two items are stored inside a GWEN_DB. This GWEN_DB has the following structure (example):

   request {
     command {                 # this group only exists in requests
       cmd="get"               # or "put" or "head" or any other valid HTTP
       url="/"                 # command uniform ressource locator on the
                               # server

       vars {                  # this group is optional and may contain
         user="me"             # whatever variable you like. All these
         pass="xy"             # variables are URL-encoded and appended to
       }                       # the URL before sending
     }                         # HTTP-escaping is done transparently

     status {                  # this group only exists in responses
       int code="200"          # status code
       text="Ok"               # status message (human readable)
     }

     header {                  # this group is optional and may contain
       connection="keep-alive" # any valid HTTP header.
       accept="image/gif"      # any data MUST be completely surrounded
     }                         # quotation marks (no kommas outside!)
   }
The body (if any) can be given by either of two ways:
  • by a GWEN_BUFFER (use argument body)
  • by a GWEN_BUFFEREDIO (use argument bio)

You can not use both.
If neither way is selected no body is sent.

Note:This function takes over the ownership of the GWEN_BUFFER (if any) and the GWEN_BUFFEREDIO (if given) regardless of the result.

Parameters:
conn HTTP connection to use
dbRequest command and optional header as described above
body message body given by a GWEN_BUFFER (0 if not)
bio message body given by a GWEN_BUFFEREDIO (0 if not)

GWENHYWFAR_API int GWEN_NetConnectionHTTP_AddResponse GWEN_NETCONNECTION conn,
GWEN_DB_NODE dbResponse,
GWEN_BUFFER body,
GWEN_BUFFEREDIO bio
 

GWENHYWFAR_API void GWEN_NetConnectionHTTP_Escape const char *  src,
GWEN_BUFFER buf
 

GWENHYWFAR_API GWEN_NETMSG* GWEN_NetConnectionHTTP_GetCurrentInMsg GWEN_NETCONNECTION conn  ) 
 

This returns a pointer to the message currently under receiption. You can inspect the GWEN_DB_NODE inside that message object which contains the command line and message header (if any). This can be used to determine how or where to store the message body and e.g. to setup the bufferedIO for storing the message body. This functions does not relinquish ownership of the message ! So you MUST NOT free it (and you should not manipulate data inside this object besides the GWEN_DB_NODE and the GWEN_BUFFEREDIO settings).

const char* GWEN_NetConnectionHTTP_GetDefaultURL const GWEN_NETCONNECTION conn  ) 
 

GWENHYWFAR_API GWEN_TYPE_UINT32 GWEN_NetConnectionHTTP_GetMode GWEN_NETCONNECTION conn  ) 
 

GWENHYWFAR_API GWEN_TYPE_UINT32 GWEN_NetConnectionHTTP_GetState GWEN_NETCONNECTION conn  ) 
 

You can use this function to check whether the connection needs the program's attention.

GWENHYWFAR_API GWEN_NETCONNECTION* GWEN_NetConnectionHTTP_new GWEN_NETTRANSPORT tr,
int  take,
GWEN_TYPE_UINT32  libId,
int  pmajor,
int  pminor
 

void GWEN_NetConnectionHTTP_SetDefaultURL GWEN_NETCONNECTION conn,
const char *  s
 

GWENHYWFAR_API void GWEN_NetConnectionHTTP_SetMode GWEN_NETCONNECTION conn,
GWEN_TYPE_UINT32  m
 

GWENHYWFAR_API void GWEN_NetConnectionHTTP_StartBodyRead GWEN_NETCONNECTION conn  ) 
 

This function is only needed if the connection mode GWEN_NETCONN_MODE_WAITBEFOREBODYREAD is in effect. In this case you need to call this function to actually start reading the message body.

GWENHYWFAR_API void GWEN_NetConnectionHTTP_StartRead GWEN_NETCONNECTION conn  ) 
 

This function is only needed if the connection mode GWEN_NETCONN_MODE_WAITBEFOREREAD is in effect. In this case you need to call this function to actually start reading the next message.

GWENHYWFAR_API void GWEN_NetConnectionHTTP_SubMode GWEN_NETCONNECTION conn,
GWEN_TYPE_UINT32  m
 

GWENHYWFAR_API int GWEN_NetConnectionHTTP_Unescape const char *  src,
GWEN_BUFFER buf
 


Generated on Fri Mar 10 08:15:17 2006 for gwenhywfar by  doxygen 1.4.6