Chuck Swiger / Pubnub_c_core2

publish final code

Fork of Pubnub_c_core by Srdjan Veljkovic

pbpal.h@3:9cb790d5df10, 2017-02-21 (annotated)

Committer:
cswiger
Date:
Tue Feb 21 22:23:28 2017 +0000
Revision:
3:9cb790d5df10
Parent:
0:d13755cfb705 
Publish final project code

Who changed what in which revision?

UserRevisionLine numberNew contents of line
sveljko 0:d13755cfb705 1 /* -*- c-file-style:"stroustrup"; indent-tabs-mode: nil -*- */
sveljko 0:d13755cfb705 2 #if !defined INC_PBPAL
sveljko 0:d13755cfb705 3 #define INC_PBPAL
sveljko 0:d13755cfb705 4
sveljko 0:d13755cfb705 5 #include <stdbool.h>
sveljko 0:d13755cfb705 6 #include <stdint.h>
sveljko 0:d13755cfb705 7 #include <stdlib.h>
sveljko 0:d13755cfb705 8
sveljko 0:d13755cfb705 9
sveljko 0:d13755cfb705 10 #include "pubnub_api_types.h"
sveljko 0:d13755cfb705 11
sveljko 0:d13755cfb705 12
sveljko 0:d13755cfb705 13 /** Initializes the Pubnub PAL for the given Pubnub context.
sveljko 0:d13755cfb705 14 */
sveljko 0:d13755cfb705 15 void pbpal_init(pubnub_t *pb);
sveljko 0:d13755cfb705 16
sveljko 0:d13755cfb705 17 /** Results that functions for (DNS) resolving and
sveljko 0:d13755cfb705 18 connecting can return.
sveljko 0:d13755cfb705 19 */
sveljko 0:d13755cfb705 20 enum pbpal_resolv_n_connect_result {
sveljko 0:d13755cfb705 21 pbpal_resolv_resource_failure,
sveljko 0:d13755cfb705 22 pbpal_resolv_failed_send,
sveljko 0:d13755cfb705 23 pbpal_resolv_send_wouldblock,
sveljko 0:d13755cfb705 24 pbpal_resolv_sent,
sveljko 0:d13755cfb705 25 pbpal_resolv_failed_rcv,
sveljko 0:d13755cfb705 26 pbpal_resolv_rcv_wouldblock,
sveljko 0:d13755cfb705 27 pbpal_resolv_failed_processing,
sveljko 0:d13755cfb705 28 pbpal_connect_resource_failure,
sveljko 0:d13755cfb705 29 pbpal_connect_failed,
sveljko 0:d13755cfb705 30 pbpal_connect_wouldblock,
sveljko 0:d13755cfb705 31 pbpal_connect_success
sveljko 0:d13755cfb705 32 };
sveljko 0:d13755cfb705 33
sveljko 0:d13755cfb705 34 /** Handles start of a TCP (HTTP) connection. It first handles DNS
sveljko 0:d13755cfb705 35 resolving for the context @p pb. If DNS is already resolved, it
sveljko 0:d13755cfb705 36 proceeds to establishing TCP connection. Otherwise, will issue a
sveljko 0:d13755cfb705 37 DNS request.
sveljko 0:d13755cfb705 38
sveljko 0:d13755cfb705 39 Call this function on start of a transaction or on receiving
sveljko 0:d13755cfb705 40 response from DNS server.
sveljko 0:d13755cfb705 41
sveljko 0:d13755cfb705 42 It also establishes "a link" between the TCP connection (socket,
sveljko 0:d13755cfb705 43 or whatever in a given platform) and the Pubnub context.
sveljko 0:d13755cfb705 44
sveljko 0:d13755cfb705 45 @note This uses a "non-conventional" interpretation of #PNR_IN_PROGRESS.
sveljko 0:d13755cfb705 46 Here it is not an error, but an indication that "DNS resolution is
sveljko 0:d13755cfb705 47 in progress", while #PNR_STARTED means "DNS resolved, TCP connect in
sveljko 0:d13755cfb705 48 progress". We could have provided another enum for results specific to
sveljko 0:d13755cfb705 49 this function, but then would have to map its errors to the generic
sveljko 0:d13755cfb705 50 Pubnub errors, which would take time and code.
sveljko 0:d13755cfb705 51
sveljko 0:d13755cfb705 52 @param pb The context for which to handle starting of connection
sveljko 0:d13755cfb705 53 @return PNR_IN_PROGRESS: DNS not yet resolved, PNR_STARTED: await
sveljko 0:d13755cfb705 54 TCP connection, PNR_OK: TCP connected, other: the actual error
sveljko 0:d13755cfb705 55 */
sveljko 0:d13755cfb705 56 enum pbpal_resolv_n_connect_result pbpal_resolv_and_connect(pubnub_t *pb);
sveljko 0:d13755cfb705 57
sveljko 0:d13755cfb705 58
sveljko 0:d13755cfb705 59 enum pbpal_resolv_n_connect_result pbpal_check_resolv_and_connect(pubnub_t *pb);
sveljko 0:d13755cfb705 60
sveljko 0:d13755cfb705 61 /** Sends data over an established connection (with the Pubnub server).
sveljko 0:d13755cfb705 62 At one time, only one sending of data can take place.
sveljko 0:d13755cfb705 63
sveljko 0:d13755cfb705 64 If it cannot send all the data, it will send as much as it can.
sveljko 0:d13755cfb705 65 You should check if sending was completed by calling pbpal_sent().
sveljko 0:d13755cfb705 66
sveljko 0:d13755cfb705 67 @param pb The context of an established TCP connection
sveljko 0:d13755cfb705 68 @param data Pointer to the first octet(byte) of the data to send
sveljko 0:d13755cfb705 69 @param n Number of octets (bytes) to send
sveljko 0:d13755cfb705 70 @return 0: sent, -1: error: sending already in progress,
sveljko 0:d13755cfb705 71 +1: sending started, not finished
sveljko 0:d13755cfb705 72 */
sveljko 0:d13755cfb705 73 int pbpal_send(pubnub_t *pb, void const *data, size_t n);
sveljko 0:d13755cfb705 74
sveljko 0:d13755cfb705 75 /** Helper macro for optimisation of sending of literal strings.
sveljko 0:d13755cfb705 76 We know their length, we don't have to call strlen().
sveljko 0:d13755cfb705 77 */
sveljko 0:d13755cfb705 78 #define pbpal_send_literal_str(pb, litstr) { \
sveljko 0:d13755cfb705 79 uint8_t s_[] = litstr; \
sveljko 0:d13755cfb705 80 pbpal_send((pb), s_, sizeof s_ - 1); }
sveljko 0:d13755cfb705 81
sveljko 0:d13755cfb705 82 /** The effect of this is the same as:
sveljko 0:d13755cfb705 83
sveljko 0:d13755cfb705 84 return pbpal_send(pb, s, strlen(s));
sveljko 0:d13755cfb705 85
sveljko 0:d13755cfb705 86 But, it doesn't have to be implemented that way.
sveljko 0:d13755cfb705 87 */
sveljko 0:d13755cfb705 88 int pbpal_send_str(pubnub_t *pb, char const *s);
sveljko 0:d13755cfb705 89
sveljko 0:d13755cfb705 90 /** Returns the status of sending. Don't try another
sveljko 0:d13755cfb705 91 sending until previous is complete.
sveljko 0:d13755cfb705 92
sveljko 0:d13755cfb705 93 @return 0: sending finished, +1: sending still in progress
sveljko 0:d13755cfb705 94 -1: sending failed
sveljko 0:d13755cfb705 95 */
sveljko 0:d13755cfb705 96 int pbpal_send_status(pubnub_t *pb);
sveljko 0:d13755cfb705 97
sveljko 0:d13755cfb705 98 /** Starts reading a line from the TCP connection. In other words,
sveljko 0:d13755cfb705 99 reading until it finds a newline character.
sveljko 0:d13755cfb705 100
sveljko 0:d13755cfb705 101 @param pb The Pubnub context of the connection
sveljko 0:d13755cfb705 102 @return 0: newline read, else: not yet, try again later
sveljko 0:d13755cfb705 103 */
sveljko 0:d13755cfb705 104 int pbpal_start_read_line(pubnub_t *pb);
sveljko 0:d13755cfb705 105
sveljko 0:d13755cfb705 106 /** Returns the status of reading a line. Line reading was
sveljko 0:d13755cfb705 107 started with pbpal_start_read_line().
sveljko 0:d13755cfb705 108 @return 0: line was read, +1: line reading still in progress
sveljko 0:d13755cfb705 109 -1: line reading failed
sveljko 0:d13755cfb705 110 */
sveljko 0:d13755cfb705 111 enum pubnub_res pbpal_line_read_status(pubnub_t *pb);
sveljko 0:d13755cfb705 112
sveljko 0:d13755cfb705 113 /** Returns the length of the data in the receive buffer
sveljko 0:d13755cfb705 114 at this time.
sveljko 0:d13755cfb705 115 */
sveljko 0:d13755cfb705 116 int pbpal_read_len(pubnub_t *pb);
sveljko 0:d13755cfb705 117
sveljko 0:d13755cfb705 118 /** Starts reading a given number of octets (bytes) from an
sveljko 0:d13755cfb705 119 established TCP connection. Only one reading can take place at any
sveljko 0:d13755cfb705 120 given time.
sveljko 0:d13755cfb705 121
sveljko 0:d13755cfb705 122 To check if reading is complete, call pbpal_read_over().
sveljko 0:d13755cfb705 123
sveljko 0:d13755cfb705 124 @param pb The Pubnub context of an established TCP connection
sveljko 0:d13755cfb705 125 @param n Number of octets (bytes) to read
sveljko 0:d13755cfb705 126 @return 0: OK (started), -1: error (reading already started)
sveljko 0:d13755cfb705 127 */
sveljko 0:d13755cfb705 128 int pbpal_start_read(pubnub_t *pb, size_t n);
sveljko 0:d13755cfb705 129
sveljko 0:d13755cfb705 130 /** Returns if reading is done (has the requested number of octets
sveljko 0:d13755cfb705 131 (bytes) been read).
sveljko 0:d13755cfb705 132 */
sveljko 0:d13755cfb705 133 bool pbpal_read_over(pubnub_t *pb);
sveljko 0:d13755cfb705 134
sveljko 0:d13755cfb705 135 /** Returns whether for the given Pubnub context the TCP
sveljko 0:d13755cfb705 136 connection has closed.
sveljko 0:d13755cfb705 137 */
sveljko 0:d13755cfb705 138 bool pbpal_closed(pubnub_t *pb);
sveljko 0:d13755cfb705 139
sveljko 0:d13755cfb705 140 /** Breaks the link between a Pubnub context and the TCP connection.
sveljko 0:d13755cfb705 141 */
sveljko 0:d13755cfb705 142 void pbpal_forget(pubnub_t *pb);
sveljko 0:d13755cfb705 143
sveljko 0:d13755cfb705 144 /** Closes (or starts the closing of) the TCP connection of the given
sveljko 0:d13755cfb705 145 Pubnub context
sveljko 0:d13755cfb705 146
sveljko 0:d13755cfb705 147 @return 0: OK, closed; +1: close initiated, call pbpal_closed()
sveljko 0:d13755cfb705 148 later to check; -1: error, can't close socket
sveljko 0:d13755cfb705 149 */
sveljko 0:d13755cfb705 150 int pbpal_close(pubnub_t *pb);
sveljko 0:d13755cfb705 151
sveljko 0:d13755cfb705 152 /** Checks whether a TCP connection is established. Call after
sveljko 0:d13755cfb705 153 starting a TCP connection (thus, after DNS resolution is over).
sveljko 0:d13755cfb705 154 */
sveljko 0:d13755cfb705 155 enum pbpal_resolv_n_connect_result pbpal_check_connect(pubnub_t *pb);
sveljko 0:d13755cfb705 156
sveljko 0:d13755cfb705 157 /** Sets blocking I/O option on the context for the communication */
sveljko 0:d13755cfb705 158 int pbpal_set_blocking_io(pubnub_t *pb);
sveljko 0:d13755cfb705 159
sveljko 0:d13755cfb705 160 /** Frees-up any resources allocated by the PAL for the given
sveljko 0:d13755cfb705 161 context. After this call, context is not safe for use by PAL any
sveljko 0:d13755cfb705 162 more (it is assumed it will be freed-up by the caller).
sveljko 0:d13755cfb705 163 */
sveljko 0:d13755cfb705 164 void pbpal_free(pubnub_t *pb);
sveljko 0:d13755cfb705 165
sveljko 0:d13755cfb705 166
sveljko 0:d13755cfb705 167 #endif /* !defined INC_PBPAL */