diff options
Diffstat (limited to 'exports')
| -rw-r--r-- | exports/exports.go | 300 |
1 files changed, 282 insertions, 18 deletions
diff --git a/exports/exports.go b/exports/exports.go index a68dea9..65f1fdd 100644 --- a/exports/exports.go +++ b/exports/exports.go @@ -2,7 +2,7 @@ // // Some notes: // -// - Errors are returned as JSON c strings. The JSON type is defined in types/error/error.go Error. Free them using FreeString. Same is the case for other string types, you should also free them +// - Errors are returned as JSON c strings. The JSON type is defined in types/error/error.go Error. Free them using FreeString. Same is the case for other string types, you should also free them. The errors are always localized // // - Types are converted from the Go representation to C using JSON strings // @@ -144,6 +144,18 @@ func getVPNState() (*client.Client, error) { // After registering, the FSM is initialized and the state transition NO_SERVER should have been completed // If some error occurs during registering, it is returned as a types/error/error.go Error // +// Example Input: +// ```Register("org.eduvpn.app.linux", "0.0.1", "/tmp/eduvpn-common", myCallbackFunc, 1)``` +// +// Example Output: +// +// { +// "message": { +// "en": "failed to register, a VPN state is already present" +// }, +// "misc": false +// } +// //export Register func Register( name *C.char, @@ -191,6 +203,21 @@ func Register( // The expiry times structure is defined in types/server/server.go `Expiry` // If some error occurs, it is returned as types/error/error.go Error // +// Example Input: +// ```ExpiryTimes()``` +// +// Example Output (1...4 are unix timestamps): +// { +// "start_time": 1, +// "end_time": 2, +// "button_time": 3, +// "countdown_time": 4, +// "notification_times": [ +// 1, +// 2, +// ], +// }, null +// //export ExpiryTimes func ExpiryTimes() (*C.char, *C.char) { state, stateErr := getVPNState() @@ -210,12 +237,25 @@ func ExpiryTimes() (*C.char, *C.char) { // Deregister cleans up the state for the client. // -// If no client is available or deregistering fails, it returns an error -// // This function SHOULD be called when the application exits such that the configuration file is saved correctly. // Note that saving of the configuration file also happens in other cases, such as after getting a VPN configuration. // Thus it is often not problematic if this function cannot be called due to a client crash // +// If no client is available or deregistering fails, it returns an error. +// +// Example Input: +// ```Deregister()``` +// +// Example Output: +// +// { +// "message": { +// "en": "failed to deregister" +// }, +// "misc": false +// } +// +// //export Deregister func Deregister() *C.char { state, stateErr := getVPNState() @@ -244,8 +284,7 @@ func Deregister() *C.char { // // This `ni` flag is useful for preprovisioned servers. For normal usage, you want to set this to zero (meaning: False) // -// If the server cannot be added it returns the error as types/error/error.go Error -// +// If the server cannot be added it returns the error as types/error/error.go Error. // Note that the server is removed when an error has occured // // The following state callbacks are mandatory to handle: @@ -253,6 +292,19 @@ func Deregister() *C.char { // - OAUTH_STARTED: This indicates that the OAuth procedure has been started, it returns the URL as the data. // The client should open the webbrowser with this URL and continue the authorization process. // +// Example Input (3=custom server): +// ```AddServer(mycookie, 3, "https://demo.eduvpn.nl", 0)``` +// +// Example Output: +// +// { +// "message": { +// "en": "failed to add server" +// }, +// "misc": false +// } +// +// //export AddServer func AddServer(c C.uintptr_t, _type C.int, id *C.char, ni C.int) *C.char { // TODO: type @@ -280,9 +332,19 @@ func AddServer(c C.uintptr_t, _type C.int, id *C.char, ni C.int) *C.char { // // - In case of institute access: The base URL // -// If the server cannot be removed it returns the error types/error/error.go Error +// If the server cannot be removed it returns the error types/error/error.go Error. +// +// Example Input (3=custom server): +// ```RemoveServer(3, "bogus")``` // -// Note that the server is not removed when an error has occured +// Example Output: +// +// { +// "message": { +// "en": "failed to remove server" +// }, +// "misc": false +// } // //export RemoveServer func RemoveServer(_type C.int, id *C.char) *C.char { @@ -302,6 +364,47 @@ func RemoveServer(_type C.int, id *C.char) *C.char { // // If there is no current server or some other, e.g. there is no current state, an error is returned with a nil string // +// Example Input: +// ```CurrentServer()``` +// +// Example Output: +// { +// "institute_access_server": { +// "display_name": { +// "en": "Demo" +// }, +// "identifier": "https://demo.eduvpn.nl/", +// "profiles": { +// "map": { +// "internet": { +// "display_name": { +// "en": "Internet" +// }, +// "supported_protocols": [ +// 1, +// 2 +// ] +// }, +// "internet-split": { +// "display_name": { +// "en": "No rfc1918 routes" +// }, +// "supported_protocols": [ +// 1, +// 2 +// ] +// } +// }, +// "current": "internet" +// }, +// "support_contacts": [ +// "mailto:eduvpn@surf.nl" +// ], +// "delisted": false +// }, +// "server_type": 1 +// }, null +// //export CurrentServer func CurrentServer() (*C.char, *C.char) { state, stateErr := getVPNState() @@ -323,10 +426,33 @@ func CurrentServer() (*C.char, *C.char) { // // This is NOT the discovery list, but the servers that have previously been added with `AddServer` // -// It returns the server list as a JSON string defined in types/server/server.go List -// +// It returns the server list as a JSON string defined in types/server/server.go List. // If the server list cannot be retrieved it returns a nil string and an error // +// Example Input: +// ```ServerList()``` +// +// Example Output (current profile here is empty as none has been chosen yet): +// +// { +// "institute_access_servers": [ +// { +// "display_name": { +// "en": "Demo" +// }, +// "identifier": "https://demo.eduvpn.nl/", +// "profiles": { +// "current": "" +// }, +// "support_contacts": [ +// "mailto:eduvpn@surf.nl" +// ], +// "delisted": false +// } +// ] +// }, null +// +// //export ServerList func ServerList() (*C.char, *C.char) { state, stateErr := getVPNState() @@ -421,6 +547,17 @@ func ServerList() (*C.char, *C.char) { // The client should open the webbrowser with this URL and continue the authorization process. // This is only called if authorization needs to be retriggered // +// Example Input (3=custom server): +// ```GetConfig(myCookie, 3, "https://demo.eduvpn.nl/", 0, 0)``` +// +// Example Output (2=WireGuard): +// +// { +// "config": "https://demo.eduvpn.nl/\n# Profile: ...\n# Expires: ...\n\n[Interface]\nPrivateKey = ...\nAddress = ...\nDNS = ...\n\n[Peer]\nPublicKey = ...=\nAllowedIPs = 0.0.0.0/0,::/0\nEndpoint = ...", +// "protocol": 2, +// "default_gateway": true +// } +// //export GetConfig func GetConfig(c C.uintptr_t, _type C.int, id *C.char, pTCP C.int, startup C.int) (*C.char, *C.char) { state, stateErr := getVPNState() @@ -449,7 +586,17 @@ func GetConfig(c C.uintptr_t, _type C.int, id *C.char, pTCP C.int, startup C.int // // `Data` is the profile ID // -// It returns an error if unsuccessful +// It returns an error if unsuccessful. +// Example Input: ```SetProfileID("splittunnel")``` +// +// Example Output: +// +// { +// "message": { +// "en": "profile does not exist" +// }, +// "misc": false +// } // //export SetProfileID func SetProfileID(data *C.char) *C.char { @@ -470,7 +617,17 @@ func SetProfileID(data *C.char) *C.char { // `c` is the Cookie that needs to be passed. To create a cookie, first call `CookieNew` // `Data` is the location ID // -// It returns an error if unsuccessful +// It returns an error if unsuccessful. +// Example Input: ```SetSecureLocation("nl")``` +// +// Example Output: +// +// { +// "message": { +// "en": "location does not exist" +// }, +// "misc": false +// } // //export SetSecureLocation func SetSecureLocation(c C.uintptr_t, data *C.char) *C.char { @@ -493,6 +650,32 @@ func SetSecureLocation(c C.uintptr_t, data *C.char) *C.char { // If it was unsuccessful, it returns an error. Note that when the lib was built in release mode the data is almost always non-nil, even when an error has occurred // This means it has just returned the cached list // +// Example Input: ```DiscoServers(myCookie)``` +// +// Example Output: +// +// { +// "v": 1695291170, +// "server_list": [ +// { +// "base_url": "https://eduvpn.rash.al/", +// "country_code": "AL", +// "public_key_list": [ +// "k7.pub.S4j5JJiTEz1fWMkI.hzU_xJasWzD6Da2WR7hgbobx9n3o4XSDeqFh03tgM-0" +// ], +// "server_type": "secure_internet", +// "support_contact": [ +// "mailto:helpdesk@rash.al" +// ] +// }, +// { +// "base_url": "https://eduvpn.deic.dk/", +// "country_code": "DK", +// "public_key_list": [ +// "k7.pub.RNOJIYbemlfsE7EL.BxmV2l2UV7pCqz135ofBgyG9-xLg0R9rILQedZrfLtE" +// ], .................. +// } , null +// //export DiscoServers func DiscoServers(c C.uintptr_t) (*C.char, *C.char) { state, stateErr := getVPNState() @@ -521,6 +704,36 @@ func DiscoServers(c C.uintptr_t) (*C.char, *C.char) { // If it was unsuccessful, it returns an error. Note that when the lib was built in release mode the data is almost always non-nil, even when an error has occurred // This means it has just returned the cached list // +// Example Input: ```DiscoOrganizations(myCookie)``` +// +// Example Output: +// { +// "v": 1695291170, +// "organization_list": [ +// { +// "display_name": { +// "en": "Academic Network of Albania - RASH" +// }, +// "org_id": "https://idp.rash.al/simplesaml/saml2/idp/metadata.php", +// "secure_internet_home": "https://eduvpn.rash.al/" +// }, +// { +// "display_name": { +// "da": "Dansk Sprognævn", +// "en": "Danish Language Council" +// }, +// "org_id": "http://idp.dsn.dk/adfs/services/trust", +// "secure_internet_home": "https://eduvpn.deic.dk/" +// }, +// { +// "display_name": { +// "da": "Erhvervsakademi Aarhus", +// "en": "Business Academy Aarhus" +// }, +// "org_id": "http://adfs.eaaa.dk/adfs/services/trust", +// "secure_inte ..................... +// }, null +// //export DiscoOrganizations func DiscoOrganizations(c C.uintptr_t) (*C.char, *C.char) { state, stateErr := getVPNState() @@ -547,8 +760,18 @@ func DiscoOrganizations(c C.uintptr_t) (*C.char, *C.char) { // This MUST be called when disconnecting, see https://docs.eduvpn.org/server/v3/api.html#application-flow // `c` is the Cookie that needs to be passed. Create a new Cookie using `CookieNew` // -// If it was unsuccessful, it returns an error +// If it was unsuccessful, it returns an error. +// +// Example Input: ```Cleanup(myCookie)``` // +// Example Output: +// +// { +// "message": { +// "en": "cleanup was not successful" +// }, +// "misc": false +// } //export Cleanup func Cleanup(c C.uintptr_t) *C.char { state, stateErr := getVPNState() @@ -569,7 +792,17 @@ func Cleanup(c C.uintptr_t) *C.char { // And it also possibly re-runs every state callback you need when getting a config. // So least you MUST handle the OAuth started transition // -// It returns an error if unsuccessful +// It returns an error if unsuccessful. +// Example Input: ```RenewSession(myCookie)``` +// +// Example Output: +// +// { +// "message": { +// "en": "could not renew session" +// }, +// "misc": false +// } // //export RenewSession func RenewSession(c C.uintptr_t) *C.char { @@ -585,7 +818,8 @@ func RenewSession(c C.uintptr_t) *C.char { return getCError(renewSessionErr) } -// SetSupportWireguard enables or disables WireGuard for the client +// SetSupportWireguard enables or disables WireGuard for the client. +// *WARNING: This function will be removed* // // By default WireGuard support is enabled // To disable it you can pass a 0 int to this @@ -593,6 +827,7 @@ func RenewSession(c C.uintptr_t) *C.char { // `support` thus indicates whether or not to enable WireGuard // An error is returned if this is not possible // +// //export SetSupportWireguard func SetSupportWireguard(support C.int) *C.char { state, stateErr := getVPNState() @@ -614,9 +849,12 @@ func SetSupportWireguard(support C.int) *C.char { // - `readRxBytes` is a function that returns the current rx bytes of the VPN interface, this should return a `long long int` in c // // It returns a boolean whether or not the common lib has determined that it cannot reach the gateway. Non-zero=dropped, zero=not dropped. -// // It also returns an error, if it fails to indicate if it has dropped or not. In this case, dropped is also set to zero // +// Example Input: ```StartFailover(myCookie, "10.10.10.1", 1400, myRxBytesReader)``` +// +// Example Output: ```1, null``` +// //export StartFailover func StartFailover(c C.uintptr_t, gateway *C.char, mtu C.int, readRxBytes C.ReadRxBytes) (C.int, *C.char) { state, stateErr := getVPNState() @@ -646,7 +884,10 @@ func StartFailover(c C.uintptr_t, gateway *C.char, mtu C.int, readRxBytes C.Read // SetState sets the state of the statemachine // -// Note: this transitions the FSM into the new state without passing any data to it +// Note: this transitions the FSM into the new state without passing any data to it. +// Example Input: ```SetState(5)``` +// +// Example Output: ```null``` // //export SetState func SetState(fsmState C.int) *C.char { @@ -659,6 +900,10 @@ func SetState(fsmState C.int) *C.char { // InState checks if the FSM is in `fsmState` // +// Example Input: ```InState(5)``` +// +// Example Output: ```1, null``` +// //export InState func InState(fsmState C.int) (C.int, *C.char) { state, stateErr := getVPNState() @@ -678,6 +923,8 @@ func InState(fsmState C.int) (C.int, *C.char) { // The client MUST thus ensure that this memory is freed using this function. // Simply pass the pointer to the string in here // +// Example Input: ```FreeString(strPtr)``` +// //export FreeString func FreeString(addr *C.char) { C.free(unsafe.Pointer(addr)) @@ -720,7 +967,10 @@ func getCookie(c C.uintptr_t) (*cookie.Cookie, error) { // // - The `tokens`, defined in types/server/server.go `Tokens` marshalled as JSON // -// It returns an error when the tokens cannot be set +// It returns an error when the tokens cannot be set. +// Example Input: ```SetTokenHandler(getterFunc, setterFunc)``` +// +// Example Output: ```null``` // //export SetTokenHandler func SetTokenHandler(getter C.TokenGetter, setter C.TokenSetter) *C.char { @@ -790,6 +1040,10 @@ func SetTokenHandler(getter C.TokenGetter, setter C.TokenSetter) *C.char { // - Send a reply to a state transition (ASK_PROFILE and ASK_LOCATION) // // Functions that take a cookie have it as the first argument + +// Example Input: ```CookieNew()``` +// +// Example Output: ```5``` // //export CookieNew func CookieNew() C.uintptr_t { @@ -805,6 +1059,10 @@ func CookieNew() C.uintptr_t { // // - `data` is the data to send, e.g. a profile ID // +// Example Input: ```CookieReply(myCookie, "split-tunnel-profile")``` +// +// Example Output: ```null``` +// //export CookieReply func CookieReply(c C.uintptr_t, data *C.char) *C.char { v, err := getCookie(c) @@ -817,7 +1075,10 @@ func CookieReply(c C.uintptr_t, data *C.char) *C.char { // CookieDelete deletes the cookie by cancelling it and deleting the underlying cgo handle // -// This function MUST be called when the cookie that is created using `CookieNew` is no longer needed +// This function MUST be called when the cookie that is created using `CookieNew` is no longer needed. +// Example Input: ```CookieDelete(myCookie)``` +// +// Example Output: null // //export CookieDelete func CookieDelete(c C.uintptr_t) *C.char { @@ -837,6 +1098,9 @@ func CookieDelete(c C.uintptr_t) *C.char { // The error cause is always context.Canceled for that cancelled function: https://pkg.go.dev/context#pkg-variables // // This CookieCancel function can also return an error if cancelling was unsuccessful +// Example Input: ```CookieCancel(myCookie)``` +// +// Example Output: null // //export CookieCancel func CookieCancel(c C.uintptr_t) *C.char { |