# 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:

- read the command or status line
- read the header (if any)
- if GWEN_NETCONN_MODE_WAITBEFOREBODYREAD is set: Stop reading, thus giving the program an opportunity to interfere Otherwise it goes on with the next step.
- call the callback function GWEN_NETCONNHTTP_WRITEBODY_FN with mode=GWEN_NetConnHttp_WriteBodyModeStart
- read the body, store it using the callback function GWEN_NETCONNHTTP_WRITEBODY_FN. If this callback is not set then the message body will be stored within the GWEN_BUFFER associated with the currently received message.
- call the callback function GWEN_NETCONNHTTP_WRITEBODY_FN with mode=GWEN_NetConnHttp_WriteBodyModeStop
- enqueue the received message when completed

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_NETMSG * | GWEN_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_NETCONNECTION * | GWEN_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
| ) |