1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
/*
* Created by yuuta on 7/13/22.
*/
#ifndef LIBAC_NET_H
#define LIBAC_NET_H
#include "incl.h"
#include "common.h"
#include "events.h"
#include "requests.h"
#include <stddef.h>
/* Connection */
typedef struct ac_connection_parameters {
char *host;
uint16_t port;
unsigned int version;
char *id;
char *token;
/**
* An established socket using the host and port parameters above.
* The type of the value is opaque to libac, and it will pass
* the value as-is to the on_send function pointer parameter.
*
* The user must keep the socket to disconnect manuall after
* calling ac_disconnect().
*/
void *sock;
/**
* Called when ac_request needs to write to the socket.
* This function is called on the same thread calling ac_*.
* Any functions related to the connection may call on_send.
* These functions do not have internal locking, and concurrent
* accesses to the same connection object is a racing condition.
* Applications are required to do their own locking to guard
* the connection.
* @param sock The same sock passed in.
* @param buffer The buffer of data.
* @param len The length to the buffer.
* @return 0 on success. Otherwise error.
*/
int (*on_send)(const void *sock, const void *buffer, const size_t len);
} ac_connection_parameters_t;
enum ac_connection_state {
AC_STATE_INIT,
AC_STATE_READY,
AC_STATE_CLOSED
};
/**
* Connect to the server.
* @param parameters Connection parameters. Untouched.
* @param out Output connection reference if succeeds. Not-NULL.
* @return AC_E_OK or an error code. When failed, *out will be untouched.
* MT-Safe
*/
LIBAC_EXPORT int ac_connect(ac_connection_parameters_t parameters, void **out);
/**
* Disconnect the connection.
* The user must manually disconnect the socket passed in during ac_connect.
* @param connection A non-NULL and connected connection passed as-is from ac_connect.
* @param force By default (false), libac will gracefully close the socket by writing something to it. If force is true,
* libac will directly free any internal structures without writing anything.
* @return AC_E_OK or an error code. When failed, connection is undefined. When succeeds, connection is freed and invalid.
* MT-Unsafe
*/
LIBAC_EXPORT int ac_disconnect(void *connection, bool force);
/**
* Blocks the current thread until a new response or event arrives.
* @param connection A non-NULL and connected connection passed as-is from ac_connect.
* @param buffer Buffer of data read from the socket.
* @param len Length to buffer.
* @param response Output response of either an event or a response. May be NULL even if it succeeds.
* @return AC_E_OK or an error code. When failed, *response is NULL.
* Notes: if the state is changed to CLOSED after receiving, this function will return AC_E_NET.
*/
LIBAC_EXPORT int ac_receive(void *connection,
const void *buffer,
size_t len,
ac_obj_t **response);
/**
* Get the current state of the connection.
* @param connection A non-NULL and connected connection passed as-is from ac_connect.
* @param out Output state.
* @return AC_E_OK or an error code. When failed, *out is untouched.
*/
LIBAC_EXPORT int ac_get_state(void *connection,
enum ac_connection_state *out);
#endif /* LIBAC_NET_H */
|