Newer
Older
#ifndef __VEREIGN_VEREIGN_H
#define __VEREIGN_VEREIGN_H
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
#ifdef _WIN32
#ifdef WIN_EXPORT
#define PUBLIC_API __declspec(dllexport)
#else
#define PUBLIC_API __declspec(dllimport)
#endif
#else
#define PUBLIC_API
#endif
#ifdef __cplusplus
extern "C" {
#endif
/**
* Error codes.
*/
enum vereign_error_code {
VEREIGN_ERR_INTERNAL = 1,
VEREIGN_ERR_GRPC_BIND_FAILED = 2
};
/**
* Error object used for the error handling of the APIs.
*
* The error has a code and error message, which can be obtained by using the corresponding
* methods ...
*/
typedef struct vereign_error vereign_error;
/**
* Destroys ::vereign_error object.
*
* Error objects are created by the API calls as result of failures.
*
* It is safe to call it with null err.
*
* @param err The error to destroy.
*/
PUBLIC_API void vereign_error_free(vereign_error* err);
/**
* Returns error object's code.
*
* @param err The error object.
* @returns the error code.
*/
PUBLIC_API int vereign_error_code(vereign_error* err);
/**
* Returns error object's message.
*
* @param err The error object.
* @returns the error message.
*/
PUBLIC_API const char* vereign_error_message(vereign_error* err);
/**
* Provides the gRPC API services.
*
* The object is created with ::vereign_service_start method, and shutdown with
* ::vereign_service_shutdown.
*
* All object's methods are named with prefix `vereign_service_`.
*/
typedef struct vereign_service vereign_service;
// FIXME: generate SSL keys for gRPC communication.
/**
* Creates ::vereign_service object and starts the gRPC API.
*
* The returned ::vereign_service object must be destroyed with ::vereign_service_shutdown method.
* After successful start, the gRPC bind port can be retrieved with the
* ::vereign_service_selected_port method. This is useful if the `listen_address` is in the form
* "<host>:" (for example "localhost:"), in which case the port is not provided by the user but
* from the OS.
*
* When the gRPC server cannot bind, `err` will have code VEREIGN_ERR_GRPC_BIND_FAILED.
* Any other failures will set `err` with code VEREIGN_ERR_INTERNAL.
*
* **NOTE: On failure the `err` object must be freed with vereign_error_free method.**
*
* @param listen_address gRPC listen address, for example "localhost:".
* @param vereign_host Vereign restapi host.
* @param vereign_port Vereign restapi port - https, 443...
* @param storage_path Full path to directory where the storage files will stay.
* If the `storage_path` is `nullptr`, a default will be used. Under linux this default is
* `$HOME/vereign`, and under windows it is `C:\Users\<user>\AppData\Local\vereign`.
*
* @param err On failure err is initialized with the reason of the failure,
* otherwise err is set to nullptr.
* @returns vereign_service object if the gRPC is up and running, otherwise returns nullptr.
*/
PUBLIC_API vereign_service* vereign_service_start(
const char* listen_address,
const char* vereign_host,
const char* vereign_port,
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
vereign_error** err
);
/**
* Retruns the port number selected by the gRPC server of the service.
*
* Must be called after the service is created with ::vereign_service_start, and before
* it is destroyed with ::vereign_service_shutdown.
*
* @returns the port number selected by the gRPC server of the service.
*/
PUBLIC_API int vereign_service_selected_port(vereign_service* service);
/**
* Stops and destroys the vereign service.
*
* It is safe to call with null `service`.
*
* @param service The object returned by the ::vereign_service_start function.
*/
PUBLIC_API void vereign_service_shutdown(vereign_service* service);
#ifdef __cplusplus
};
#endif
#endif // __VEREIGN_VEREIGN_H