@@ -26,6 +26,29 @@ typedef struct ExchangeCancelToken ExchangeCancelToken;
2626
2727typedef struct RequestCancelHandle RequestCancelHandle ;
2828
29+ typedef struct SwiftApiContext {
30+ const struct ApiContext * _0 ;
31+ } SwiftApiContext ;
32+
33+ typedef struct SwiftCancelHandle {
34+ struct RequestCancelHandle * ptr ;
35+ } SwiftCancelHandle ;
36+
37+ typedef struct SwiftMullvadApiResponse {
38+ uint8_t * body ;
39+ uintptr_t body_size ;
40+ uint16_t status_code ;
41+ uint8_t * error_description ;
42+ uint8_t * server_response_code ;
43+ bool success ;
44+ bool should_retry ;
45+ uint64_t retry_after ;
46+ } SwiftMullvadApiResponse ;
47+
48+ typedef struct CompletionCookie {
49+ void * _0 ;
50+ } CompletionCookie ;
51+
2952typedef struct ProxyHandle {
3053 void * context ;
3154 uint16_t port ;
@@ -51,30 +74,87 @@ typedef struct EphemeralPeerParameters {
5174 struct WgTcpConnectionFunctions funcs ;
5275} EphemeralPeerParameters ;
5376
54- typedef struct SwiftApiContext {
55- const struct ApiContext * _0 ;
56- } SwiftApiContext ;
77+ extern const uint16_t CONFIG_SERVICE_PORT ;
5778
58- typedef struct SwiftCancelHandle {
59- struct RequestCancelHandle * ptr ;
60- } SwiftCancelHandle ;
79+ /**
80+ * # Safety
81+ *
82+ * `host` must be a pointer to a null terminated string representing a hostname for Mullvad API host.
83+ * This hostname will be used for TLS validation but not used for domain name resolution.
84+ *
85+ * `address` must be a pointer to a null terminated string representing a socket address through which
86+ * the Mullvad API can be reached directly.
87+ *
88+ * If a context cannot be constructed this function will panic since the call site would not be able
89+ * to proceed in a meaningful way anyway.
90+ *
91+ * This function is safe.
92+ */
93+ struct SwiftApiContext mullvad_api_init_new (const uint8_t * host ,
94+ const uint8_t * address );
6195
62- typedef struct SwiftMullvadApiResponse {
63- uint8_t * body ;
64- uintptr_t body_size ;
65- uint16_t status_code ;
66- uint8_t * error_description ;
67- uint8_t * server_response_code ;
68- bool success ;
69- bool should_retry ;
70- uint64_t retry_after ;
71- } SwiftMullvadApiResponse ;
96+ /**
97+ * # Safety
98+ *
99+ * `api_context` must be pointing to a valid instance of `SwiftApiContext`. A `SwiftApiContext` is created
100+ * by calling `mullvad_api_init_new`.
101+ *
102+ * `completion_cookie` must be pointing to a valid instance of `CompletionCookie`. `CompletionCookie` is
103+ * safe because the pointer in `MullvadApiCompletion` is valid for the lifetime of the process where this
104+ * type is intended to be used.
105+ *
106+ * This function is not safe to call multiple times with the same `CompletionCookie`.
107+ */
108+ struct SwiftCancelHandle mullvad_api_get_addresses (struct SwiftApiContext api_context ,
109+ void * completion_cookie );
72110
73- typedef struct CompletionCookie {
74- void * _0 ;
75- } CompletionCookie ;
111+ /**
112+ * Called by the Swift side to signal that a Mullvad API call should be cancelled.
113+ * After this call, the cancel token is no longer valid.
114+ *
115+ * # Safety
116+ *
117+ * `handle_ptr` must be pointing to a valid instance of `SwiftCancelHandle`. This function
118+ * is not safe to call multiple times with the same `SwiftCancelHandle`.
119+ */
120+ void mullvad_api_cancel_task (struct SwiftCancelHandle handle_ptr );
76121
77- extern const uint16_t CONFIG_SERVICE_PORT ;
122+ /**
123+ * Called by the Swift side to signal that the Rust `SwiftCancelHandle` can be safely
124+ * dropped from memory.
125+ *
126+ * # Safety
127+ *
128+ * `handle_ptr` must be pointing to a valid instance of `SwiftCancelHandle`. This function
129+ * is not safe to call multiple times with the same `SwiftCancelHandle`.
130+ */
131+ void mullvad_api_cancel_task_drop (struct SwiftCancelHandle handle_ptr );
132+
133+ /**
134+ * Maps to `mullvadApiCompletionFinish` on Swift side to facilitate callback based completion flow when doing
135+ * network calls through Mullvad API on Rust side.
136+ *
137+ * # Safety
138+ *
139+ * `response` must be pointing to a valid instance of `SwiftMullvadApiResponse`.
140+ *
141+ * `completion_cookie` must be pointing to a valid instance of `CompletionCookie`. `CompletionCookie` is safe
142+ * because the pointer in `MullvadApiCompletion` is valid for the lifetime of the process where this type is
143+ * intended to be used.
144+ */
145+ extern void mullvad_api_completion_finish (struct SwiftMullvadApiResponse response ,
146+ struct CompletionCookie completion_cookie );
147+
148+ /**
149+ * Called by the Swift side to signal that the Rust `SwiftMullvadApiResponse` can be safely
150+ * dropped from memory.
151+ *
152+ * # Safety
153+ *
154+ * `response` must be pointing to a valid instance of `SwiftMullvadApiResponse`. This function
155+ * is not safe to call multiple times with the same `SwiftMullvadApiResponse`.
156+ */
157+ void mullvad_response_drop (struct SwiftMullvadApiResponse response );
78158
79159/**
80160 * Initializes a valid pointer to an instance of `EncryptedDnsProxyState`.
@@ -200,20 +280,6 @@ int32_t start_shadowsocks_proxy(const uint8_t *forward_address,
200280 */
201281int32_t stop_shadowsocks_proxy (struct ProxyHandle * proxy_config );
202282
203- struct SwiftApiContext mullvad_api_init_new (const uint8_t * host , const uint8_t * address );
204-
205- struct SwiftCancelHandle mullvad_api_get_addresses (struct SwiftApiContext api_context ,
206- void * completion_cookie );
207-
208- void mullvad_api_cancel_task (struct SwiftCancelHandle handle_ptr );
209-
210- void mullvad_api_cancel_task_drop (struct SwiftCancelHandle handle_ptr );
211-
212- extern void mullvad_api_completion_finish (struct SwiftMullvadApiResponse response ,
213- struct CompletionCookie completion_cookie );
214-
215- void mullvad_response_drop (struct SwiftMullvadApiResponse response );
216-
217283int32_t start_tunnel_obfuscator_proxy (const uint8_t * peer_address ,
218284 uintptr_t peer_address_len ,
219285 uint16_t peer_port ,
0 commit comments