Newer
Older
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
#ifndef VEREIGN_VEREIGN_H_
#define VEREIGN_VEREIGN_H_
#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);
/**
* 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;
/**
* 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.
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
106
107
*
* 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 vereignHost Vereign restapi host.
* @param vereignPort Vereign restapi port - https, 443...
* @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,
const char* public_key,
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_