For library writers, the client requires a writable folder to store
For library writers, the client requires a writable folder to store data, functions for receiving and approving requests
data, functions for receiving and approving requests for creating
for creating secure end-to-end messaging channels, discovering users, and receiving different types of messages.
secure end-to-end messaging channels, for discovering users, and for
receiving different types of messages. Details for implementing these
features are in the [Library Overview section](#library-overview) below.
The client is open-source software released under the simplified BSD License.
The client is open-source software released under the simplified BSD License.
## Command Line Usage
## Command Line Usage
The command-line tool is intended for testing xx network functionality and not
The command-line tool is intended for testing xx network functionality and not for regular user use.
for regular user use.
These instructions assume that you have [Go 1.17.X installed](https://go.dev/doc/install), and GCC installed for Cgo (such as `build-essential` on Debian or Ubuntu).
These instructions assume that you have [Go 1.17.X](https://go.dev/doc/install) installed and GCC installed for
[cgo](https://pkg.go.dev/cmd/cgo)(such as `build-essential` on Debian or Ubuntu).
--send-auth-request Send an auth request to the specified destination and waitfor confirmation
--send-auth-request Send an auth request to the specified destination and waitfor confirmation
--sendCount uint The number of times to send the message (default 1)
--sendCount uint The number of times to send the message (default 1)
--sendDelay uint The delay between sending the messages in ms (default 500)
--sendDelay uint The delay between sending the messages in ms (default 500)
--sendid uint Use precanned user id (must be between 1 and 40, inclusive)
--sendid uint Use precanned user id (must be between 1 and 40, inclusive)
-s, --session string Sets the initial storage directory for client session data
-s, --session string Sets the initial storage directory for client session data
--slowPolling Enables polling for unfiltered network updates with RSA signatures
--slowPolling Enables polling for unfiltered network updates with RSA signatures
--splitSends Force sends to go over multiple rounds if possible
--unsafe Send raw, unsafe messages without e2e encryption.
--unsafe Send raw, unsafe messages without e2e encryption.
--unsafe-channel-creation Turns off the user identity authenticated channel check, automatically approving authenticated channels
--unsafe-channel-creation Turns off the user identity authenticated channel check, automatically approving authenticated channels
--verboseRoundTracking Verbose round tracking, keeps track and prints all rounds the client was aware of while running. Defaults to false if not set.
--verboseRoundTracking Verbose round tracking, keeps track and prints all rounds the client was aware of while running. Defaults to false if not set.
...
@@ -292,131 +296,111 @@ Flags:
...
@@ -292,131 +296,111 @@ Flags:
Use "client [command] --help" for more information about a command.
Use "client [command] --help" for more information about a command.
```
```
**Note:** The client cannot be used on the betanet with precanned user ids.
>💡 **Note:** The client cannot be used on the xx network with pre-canned user IDs.
## Library Overview
## Library Overview
The xx client is designed to be used as a go library (and by extension a
The xx client is designed to be a go library (and, by extension, a C library).
c library).
Support is also present for go mobile to build Android and iOS libraries. We
Support is also present for Go mobile to build Android and iOS libraries. In addition, we bind all exported symbols from
bind all exported symbols from the bindings package for use on mobile
the bindings package for use on mobile platforms.
platforms.
### Implementation Notes
### Implementation Notes
Clients need to perform the same actions *in the same order* as shown in
Clients must perform the same actions *in the same order* as shown in `cmd/root.go`. Specifically, certain handlers need
`cmd/root.go`. Specifically, certain handlers need to be registered and
to be registered and set up before starting network threads. Additionally, you cannot perform certain actions until the
set up before starting network threads. Additionally, you cannot perform certain actions until the network connection
network connection reaches a "healthy" state.
reaches a "healthy" state.
Refer to Setting Up a cMix Client in the API documentation for specific on how to do this.
See [main.go](https://git.xx.network/elixxir/xxdk-examples/-/blob/sample-messaging-app/sample-messaging-app/main.go) for relevant code listings on when and how to perform these actions.
The [Getting Started](https://xxdk-dev.xx.network/getting-started) guide provides further detail.
See the [xxdk Example repository](https://git.xx.network/elixxir/xxdk-examples/-/tree/master) for various example
implementations.
You can also visit the [API Quick Reference](https://xxdk-dev.xx.network/quick-reference)
In addition, the [Getting Started](https://xxdk-dev.xx.network/getting-started) guide provides further detail.
for information on the types and functions exposed by the Client API.
You can also visit the [API Quick Reference](https://xxdk-dev.xx.network/quick-reference) for information on the types
The main entry point for developing with the client is `api/client` (or
and functions exposed by the Client API.
`bindings/client`). We recommend using go doc to explore:
The main entry point for developing with the client is `xxdk/cmix` (or `bindings/cmix`). We recommend using the
```
[documentation in the Go package directory](https://pkg.go.dev/gitlab.com/elixxir/client/xxdk).
go doc -all ./api
go doc -all ./interfaces
Looking at the API will, for example, show you there is a `RoundEvents` callback registration function, which lets your
```
client see round events.
Looking at the API will, for example, show you there is a RoundEvents callback
> ```go
registration function, which lets your client see round events:
