Sharvil Nanavati | c2031c4 | 2014-07-25 15:50:17 -0700 | [diff] [blame^] | 1 | /****************************************************************************** |
| 2 | * |
| 3 | * Copyright (C) 2014 Google, Inc. |
| 4 | * |
| 5 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 6 | * you may not use this file except in compliance with the License. |
| 7 | * You may obtain a copy of the License at: |
| 8 | * |
| 9 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 10 | * |
| 11 | * Unless required by applicable law or agreed to in writing, software |
| 12 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 14 | * See the License for the specific language governing permissions and |
| 15 | * limitations under the License. |
| 16 | * |
| 17 | ******************************************************************************/ |
| 18 | |
| 19 | #pragma once |
| 20 | |
| 21 | #include <stddef.h> |
| 22 | #include <stdint.h> |
| 23 | |
| 24 | typedef struct reactor_t reactor_t; |
| 25 | typedef struct socket_t socket_t; |
| 26 | typedef uint16_t port_t; |
| 27 | |
| 28 | typedef void (*socket_cb)(socket_t *socket, void *context); |
| 29 | |
| 30 | // Returns a new socket object. The socket is in an idle, disconnected state when |
| 31 | // it is returned by this function. The returned object must be freed by calling |
| 32 | // |socket_free|. Returns NULL on failure. |
| 33 | socket_t *socket_new(void); |
| 34 | |
| 35 | // Frees a socket object created by |socket_new| or |socket_accept|. |socket| may |
| 36 | // be NULL. If the socket was connected, it will be disconnected. |
| 37 | void socket_free(socket_t *socket); |
| 38 | |
| 39 | // Puts |socket| in listening mode for incoming TCP connections on the specified |
| 40 | // |port|. Returns true on success, false on failure (e.g. |port| is bound by |
| 41 | // another socket). |socket| may not be NULL. |
| 42 | bool socket_listen(const socket_t *socket, port_t port); |
| 43 | |
| 44 | // Blocks on a listening socket, |socket|, until a client connects to it. Returns |
| 45 | // a connected socket on success, NULL on failure. The returned object must be |
| 46 | // freed by calling |socket_free|. |socket| may not be NULL. |
| 47 | socket_t *socket_accept(const socket_t *socket); |
| 48 | |
| 49 | // Reads up to |count| bytes from |socket| into |buf|. This function will not |
| 50 | // block. This function returns a positive integer representing the number |
| 51 | // of bytes copied into |buf| on success, 0 if the socket has disconnected, |
| 52 | // and -1 on error. This function may return a value less than |count| if not |
| 53 | // enough data is currently available. If this function returns -1, errno will also |
| 54 | // be set (see recv(2) for possible errno values). If there were no bytes available |
| 55 | // to be read, this function returns -1 and sets errno to EWOULDBLOCK. Neither |
| 56 | // |socket| nor |buf| may be NULL. |
| 57 | ssize_t socket_read(const socket_t *socket, void *buf, size_t count); |
| 58 | |
| 59 | // Writes up to |count| bytes from |buf| into |socket|. This function will not |
| 60 | // block. Returns a positive integer representing the number of bytes written |
| 61 | // to |socket| on success, 0 if the socket has disconnected, and -1 on error. This |
| 62 | // function may return a value less than |count| if writing more bytes would result |
| 63 | // in blocking. If this function returns -1, errno will also be set (see send(2) for |
| 64 | // possible errno values). If no bytes could be written without blocking, this |
| 65 | // function will return -1 and set errno to EWOULDBLOCK. Neither |socket| nor |buf| |
| 66 | // may be NULL. |
| 67 | ssize_t socket_write(const socket_t *socket, const void *buf, size_t count); |
| 68 | |
| 69 | // Registers |socket| with the |reactor|. When the socket becomes readable, |read_cb| |
| 70 | // will be called. When the socket becomes writeable, |write_cb| will be called. The |
| 71 | // |context| parameter is passed, untouched, to each of the callback routines. Neither |
| 72 | // |socket| nor |reactor| may be NULL. |read_cb| or |write_cb|, but not both, may be NULL. |
| 73 | // |context| may be NULL. |
| 74 | void socket_register(socket_t *socket, reactor_t *reactor, socket_cb read_cb, socket_cb write_cb, void *context); |
| 75 | |
| 76 | // Unregisters |socket| from whichever reactor it is registered with, if any. This |
| 77 | // function is idempotent. |
| 78 | void socket_unregister(socket_t *socket); |