-
Jakub Pelka authoredJakub Pelka authored
sidebar_position: 3API Quick Reference
This document provides brief descriptions of all public functions, types, and interfaces exposed by the Client API (xxDK).
:::note If you are new to the xxDK, you can start with the Overview and Getting Started docs. :::
Note that if you're running the client locally, you can use go doc to explore the list of functions and interfaces.
// cd into the `client` directory
go doc -all ./api
go doc -all ./interfacesHow to Use the API
The API exposes multiple functions, as well as types and their associated method sets. For example, browsing through the API will show you there is a GetRoundEvents() callback registration function that lets your client see round events:
func (c *Client) GetRoundEvents() interfaces.RoundEventsGetRoundEvents() returns a RoundEvents interface. Exploring the broader xxDK for this interface reveals a few functions, such as AddRoundEvent() that enable monitoring of a specified event:
type RoundEvents interface {
// designates a callback to call on the specified event
// rid is the id of the round the event occurs on
// callback is the callback the event is triggered on
// timeout is the amount of time before an error event is returned
// valid states are the states which the event should trigger on
AddRoundEvent(rid id.Round, callback ds.RoundEventCallback,
timeout time.Duration, validStates ...states.Round) *ds.EventCallback
// designates a go channel to signal the specified event
// rid is the id of the round the event occurs on
// eventChan is the channel the event is triggered on
// timeout is the amount of time before an error event is returned
// valid states are the states which the event should trigger on
AddRoundEventChan(rid id.Round, eventChan chan ds.EventReturn,
timeout time.Duration, validStates ...states.Round) *ds.EventCallback
//Allows the un-registration of a round event before it triggers
Remove(rid id.Round, e *ds.EventCallback)
}Investigating the callback parameter of AddRoundEvent() yields the following prototype showing that you can receive a full RoundInfo object for any round event received by the client on the network:
// Callbacks must use this function signature
type RoundEventCallback func(ri *pb.RoundInfo, timedOut bool)API Quick Reference
Constants
const (
// SaltSize size of user salts
SaltSize = 32
)Functions
func CompressJpeg
func CompressJpeg(imgBytes []byte) ([]byte, error)CompressJpeg takes a JPEG image in byte format and compresses it based on desired output size.
func CompressJpegForPreview
func CompressJpegForPreview(imgBytes []byte) ([]byte, error)CompressJpegForPreview takes a JPEG image in byte format and compresses it based on desired output size.
func DownloadAndVerifySignedNdfWithUrl
func DownloadAndVerifySignedNdfWithUrl(url, cert string) ([]byte, error)DownloadAndVerifySignedNdfWithUrl retrieves the NDF from a specified URL. The NDF is processed into a protobuf containing a signature which is verified using the cert string passed in. The NDF is returned as marshaled byte data which may be used to start a client.
func LoadSecretWithMnemonic
func LoadSecretWithMnemonic(mnemonic, path string) (secret []byte, err error)LoadSecretWithMnemonic loads the encrypted secret from storage and decrypts the secret using the given mnemonic.
func NewClient
func NewClient(ndfJSON, storageDir string, password []byte,
registrationCode string) error NewClient creates client storage, generates keys, connects, and registers with the network. Note that this does not register a username/identity, but merely creates a new cryptographic identity for adding such information at a later date.
func NewPrecannedClient
func NewPrecannedClient(precannedID uint, defJSON, storageDir string,
password []byte) errorNewPrecannedClient is used for integration testing and should not be used unless you are working on the cMix gateway and servers. You cannot connect to any public networks with a precanned client.
func NewProtoClient_Unsafe
func NewProtoClient_Unsafe(ndfJSON, storageDir string, password,
protoClientJSON []byte) errorNewProtoClient_Unsafe initializes a client object from a JSON containing predefined cryptographic which defines a user. This is designed for some specific deployment procedures and is generally unsafe.
:::note
NewProtoClient_Unsafe is planned to be deprecated in favor of a new account backup API.
:::
func NewVanityClient
func NewVanityClient(ndfJSON, storageDir string, password []byte,
registrationCode string, userIdPrefix string) errorNewVanityClient creates a user with a receptionID that starts with the supplied prefix It creates client storage, generates keys, connects, and registers with the network. Note that this does not register a username/identity, but merely creates a new cryptographic identity for adding such information at a later date.
func StoreSecretWithMnemonic
func StoreSecretWithMnemonic(secret []byte, path string) (string, error)StoreSecretWithMnemonic creates a mnemonic and uses it to encrypt the secret. This encrypted data saved in storage.
Types
type Client
type Client struct {
// Has unexported fields.
}func Login
func Login(storageDir string, password []byte, parameters params.Network) (*Client, error)Login initializes a client object from existing storage.
func LoginWithNewBaseNDF_UNSAFE
func LoginWithNewBaseNDF_UNSAFE(storageDir string, password []byte,
newBaseNdf string, parameters params.Network) (*Client, error)LoginWithNewBaseNDF_UNSAFE initializes a client object from existing storage while replacing the base NDF. This is designed for some specific deployment procedures and is generally unsafe.
func LoginWithProtoClient
func LoginWithProtoClient(storageDir string, password []byte, protoClientJSON []byte,
newBaseNdf string, parameters params.Network) (*Client, error)LoginWithProtoClient creates a client object with a protoclient JSON containing the cryptographic primitives. This is designed for some specific deployment procedures and is generally unsafe.
func OpenClient
func OpenClient(storageDir string, password []byte, parameters params.Network) (*Client, error)Open a client session, but do not connect to the network or log in.
func (*Client) AddService
func (c *Client) AddService(sp Service) errorAddService adds a service to be controlled by the client thread control; these will be started and stopped with the network follower.
func (*Client) ConfirmAuthenticatedChannel
func (c *Client) ConfirmAuthenticatedChannel(recipient contact.Contact) (id.Round, error)ConfirmAuthenticatedChannel creates an authenticated channel out of a valid received request and sends a message to the requestor that the request has been confirmed. It will not run if the network state is not healthy. An error will be returned if a channel already exists, if a request does not exist, or if the passed in contact does not exactly match the received request. Can be retried.
func (*Client) ConstructProtoUerFile
func (c *Client) ConstructProtoUerFile() ([]byte, error)ConstructProtoUerFile is a helper function which is used for proto client testing. This is used for development testing.
func (*Client) DeleteAllRequests
func (c *Client) DeleteAllRequests() errorDeleteAllRequests clears all requests from client's auth storage.
func (*Client) DeleteContact
func (c *Client) DeleteContact(partnerId *id.ID) errorDeleteContact removes a partner from the client's storage.
func (*Client) DeleteReceiveRequests
func (c *Client) DeleteReceiveRequests() errorDeleteReceiveRequests clears receive requests from client's auth storage.
func (*Client) DeleteSentRequests
func (c *Client) DeleteSentRequests() error