aboutsummaryrefslogtreecommitdiff
path: root/client/libacron/include/net.h
blob: 7b28df2bdad7d3fb5130b226a50956e662e17adc (plain)
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
99
100
101
102
103
104
105
/*
 * 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 pos Read the buffer starting at pos.
 * @param len Length to buffer.
 * @param response Output response of either an event or a response. May be NULL even if it succeeds.
 * @param len_read Output the bytes read. Must be <= len. The caller must call it again with pos = *len_read until
 * the sum of *len_read == len or when return value == AC_E_AGAIN, except when return value != AC_E_OK.
 * Note: if return value == AC_E_AGAIN, call ac_receive with buffer = pos = len = 0 once, regardless of *len_read.
 * In this case, len_read is ignored.
 * @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 pos,
                            size_t len,
                            ac_obj_t **response,
                            size_t *len_read);

/**
 * 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 */