pbpal.h

00001 /* -*- c-file-style:"stroustrup"; indent-tabs-mode: nil -*- */
00002 #if !defined INC_PBPAL
00003 #define      INC_PBPAL
00004 
00005 #include <stdbool.h>
00006 #include <stdint.h>
00007 #include <stdlib.h>
00008 
00009 
00010 #include "pubnub_api_types.h"
00011 
00012 
00013 /** Initializes the Pubnub PAL for the given Pubnub context.
00014  */
00015 void pbpal_init(pubnub_t *pb);
00016 
00017 /** Results that functions for (DNS) resolving and
00018     connecting can return.
00019 */
00020 enum pbpal_resolv_n_connect_result {
00021     pbpal_resolv_resource_failure,
00022     pbpal_resolv_failed_send,
00023     pbpal_resolv_send_wouldblock,
00024     pbpal_resolv_sent,
00025     pbpal_resolv_failed_rcv,
00026     pbpal_resolv_rcv_wouldblock,
00027     pbpal_resolv_failed_processing,
00028     pbpal_connect_resource_failure,
00029     pbpal_connect_failed,
00030     pbpal_connect_wouldblock,
00031     pbpal_connect_success
00032 };
00033 
00034 /** Handles start of a TCP (HTTP) connection. It first handles DNS
00035     resolving for the context @p pb.  If DNS is already resolved, it
00036     proceeds to establishing TCP connection. Otherwise, will issue a
00037     DNS request.
00038     
00039     Call this function on start of a transaction or on receiving
00040     response from DNS server.
00041     
00042     It also establishes "a link" between the TCP connection (socket,
00043     or whatever in a given platform) and the Pubnub context.
00044     
00045     @note This uses a "non-conventional" interpretation of #PNR_IN_PROGRESS.
00046     Here it is not an error, but an indication that "DNS resolution is
00047     in progress", while #PNR_STARTED means "DNS resolved, TCP connect in
00048     progress". We could have provided another enum for results specific to
00049     this function, but then would have to map its errors to the generic
00050     Pubnub errors, which would take time and code.
00051     
00052     @param pb The context for which to handle starting of connection
00053     @return PNR_IN_PROGRESS: DNS not yet resolved, PNR_STARTED: await
00054     TCP connection, PNR_OK: TCP connected, other: the actual error
00055 */
00056 enum pbpal_resolv_n_connect_result pbpal_resolv_and_connect(pubnub_t *pb);
00057 
00058 
00059 enum pbpal_resolv_n_connect_result pbpal_check_resolv_and_connect(pubnub_t *pb);
00060 
00061 /** Sends data over an established connection (with the Pubnub server).
00062     At one time, only one sending of data can take place.
00063 
00064     If it cannot send all the data, it will send as much as it can.
00065     You should check if sending was completed by calling pbpal_sent().
00066 
00067     @param pb The context of an established TCP connection
00068     @param data Pointer to the first octet(byte) of the data to send
00069     @param n Number of octets (bytes) to send
00070     @return 0: sent, -1: error: sending already in progress, 
00071     +1: sending started, not finished
00072 */
00073 int pbpal_send(pubnub_t *pb, void const *data, size_t n);
00074 
00075 /** Helper macro for optimisation of sending of literal strings.
00076     We know their length, we don't have to call strlen().
00077  */
00078 #define pbpal_send_literal_str(pb, litstr) {          \
00079         uint8_t s_[] = litstr;                        \
00080         pbpal_send((pb), s_, sizeof s_ - 1); }
00081 
00082 /** The effect of this is the same as:
00083 
00084     return pbpal_send(pb, s, strlen(s));
00085 
00086     But, it doesn't have to be implemented that way.
00087 */
00088 int pbpal_send_str(pubnub_t *pb, char const *s);
00089 
00090 /** Returns the status of sending. Don't try another
00091     sending until previous is complete.
00092 
00093     @return 0: sending finished, +1: sending still in progress
00094     -1: sending failed
00095 */
00096 int pbpal_send_status(pubnub_t *pb);
00097 
00098 /** Starts reading a line from the TCP connection. In other words,
00099     reading until it finds a newline character.
00100 
00101     @param pb The Pubnub context of the connection 
00102     @return 0: newline read, else: not yet, try again later
00103 */
00104 int pbpal_start_read_line(pubnub_t *pb);
00105 
00106 /** Returns the status of reading a line. Line reading was
00107     started with pbpal_start_read_line().
00108     @return 0: line was read, +1: line reading still in progress
00109     -1: line reading failed
00110 */
00111 enum pubnub_res pbpal_line_read_status(pubnub_t *pb);
00112 
00113 /** Returns the length of the data in the receive buffer
00114     at this time.
00115 */
00116 int pbpal_read_len(pubnub_t *pb);
00117 
00118 /** Starts reading a given number of octets (bytes) from an
00119     established TCP connection. Only one reading can take place at any
00120     given time.
00121 
00122     To check if reading is complete, call pbpal_read_over().
00123 
00124     @param pb The Pubnub context of an established TCP connection
00125     @param n Number of octets (bytes) to read
00126     @return 0: OK (started), -1: error (reading already started)
00127 */
00128 int pbpal_start_read(pubnub_t *pb, size_t n);
00129 
00130 /** Returns if reading is done (has the requested number of octets
00131     (bytes) been read).
00132 */
00133 bool pbpal_read_over(pubnub_t *pb);
00134 
00135 /** Returns whether for the given Pubnub context the TCP
00136     connection has closed.
00137 */
00138 bool pbpal_closed(pubnub_t *pb);
00139 
00140 /** Breaks the link between a Pubnub context and the TCP connection.
00141 */
00142 void pbpal_forget(pubnub_t *pb);
00143 
00144 /** Closes (or starts the closing of) the TCP connection of the given
00145     Pubnub context 
00146 
00147     @return 0: OK, closed; +1: close initiated, call pbpal_closed()
00148     later to check; -1: error, can't close socket
00149 */
00150 int pbpal_close(pubnub_t *pb);
00151 
00152 /** Checks whether a TCP connection is established. Call after
00153     starting a TCP connection (thus, after DNS resolution is over).
00154 */
00155 enum pbpal_resolv_n_connect_result pbpal_check_connect(pubnub_t *pb);
00156 
00157 /** Sets blocking I/O option on the context for the communication */
00158 int pbpal_set_blocking_io(pubnub_t *pb);
00159 
00160 /** Frees-up any resources allocated by the PAL for the given
00161     context. After this call, context is not safe for use by PAL any
00162     more (it is assumed it will be freed-up by the caller).
00163 */
00164 void pbpal_free(pubnub_t *pb);
00165 
00166 
00167 #endif /* !defined INC_PBPAL */