Classes
struct	asdk::certificate_t
	A server certificate, as filled in by sdk_t::RequestCertificate. More...

Typedefs
typedef uint8_t	asdk::UserCapabilityValue
typedef int	asdk::DeviceCapabilityValue
typedef void(*)	asdk::ServerStateFunc(const ServerState serverState, void *opaque)
	The connection to the server changed state.
typedef void(*)	asdk::AuthenticateResponseFunc(const AuthenticationResponse authenticateResponse, void *opaque)
	The server answered the login, see AuthenticationResponse for the bits.

Enumerations
enum	asdk::ServerState { asdk::ServerStateUndef , asdk::ServerStateDisconnected , asdk::ServerStateConnected , asdk::ServerStateConnectedAndAuthenticated , asdk::ServerStateAuthenticateError }
	State of the connection to the server, reported by ServerStateFunc. More...
enum	asdk::AuthenticationResponse { asdk::AuthenticationResponseUndef = 0 , asdk::AuthenticationResponseSuccess = 1 << 0 , asdk::AuthenticationResponseError = 1 << 1 , asdk::AuthenticationResponseVersionError = 1 << 2 , asdk::AuthenticationResponseVersionRecUpgrade = 1 << 3 , asdk::AuthenticationResponseVersionMayUpgrade = 1 << 4 , asdk::AuthenticationResponseLoggedInOther = 1 << 5 , asdk::AuthenticationResponseKickedOther = 1 << 6 , asdk::AuthenticationResponseWrongLoginType = 1 << 7 , asdk::AuthenticationResponseTryAgainLater = 1 << 8 , asdk::AuthenticationResponseFormatError = 1 << 9 , asdk::AuthenticationResponseRequestedCapError = 1 << 10 }
	Outcome of a login attempt, reported by AuthenticateResponseFunc. More...
enum	asdk::UserCapability : uint8_t { asdk::UserCapabilityUndef = 0 , asdk::UserCapabilitySender = 1 << 0 , asdk::UserCapabilityController = 1 << 1 , asdk::UserCapabilityViewer = 1 << 2 , asdk::UserCapabilityGuest = 1 << 3 , asdk::UserCapabilitySuper = 1 << 6 , asdk::UserCapabilityUnsure = 1 << 7 }
	The role a client asks the server for on connect. More...
enum	asdk::DeviceCapability : int { asdk::DeviceCapabilityUndef = 0 , asdk::DeviceCapabilityVideoAV1 = 1 << 1 , asdk::DeviceCapabilityVideoH264 = 1 << 2 , asdk::DeviceCapabilityVideoH265 = 1 << 3 , asdk::DeviceCapabilityAudioOpus = 1 << 4 , asdk::DeviceCapabilityAudioSpeex = 1 << 5 , asdk::DeviceCapabilityAudioMIC = 1 << 6 , asdk::DeviceCapabilityPhotoModeWEBP = 1 << 7 , asdk::DeviceCapabilityPhotoModeHEIF = 1 << 8 , asdk::DeviceCapabilityPhotoModeAVIF = 1 << 9 , asdk::DeviceCapabilityPhotoROI = 1 << 10 , asdk::DeviceCapabilityVideoROI = 1 << 11 , asdk::DeviceCapabilityChat = 1 << 12 , asdk::DeviceCapabilityDisplay = 1 << 13 , asdk::DeviceCapabilityFileTransfer = 1 << 16 , asdk::DeviceCapabilityASIGN = 1 << 31 , asdk::DeviceCapabilityBasic , asdk::DeviceCapabilityCore , asdk::DeviceCapabilityFull , asdk::DeviceCapabilityHeadless }
	What a client announces it can do, as a DeviceCapabilityValue. More...
enum	asdk::CertificateState { asdk::CertificateStateUndef , asdk::CertificateStateConnected , asdk::CertificateStateReceived , asdk::CertificateStateConnectError }
	Outcome of sdk_t::RequestCertificate. More...

Functions
Status	asdk::sdk_t::Connect (const char ip, const uint16_t port, const uint32_t timeout, const bool highLatency, const char username, const char password, const UserCapabilityValue userCapability, const DeviceCapabilityValue deviceCapability, const char displayName=nullptr)
	Connect to ASMIRA server.
Status	asdk::sdk_t::ConnectSecured (const char ip, const uint16_t port, const uint32_t timeout, const bool highLatency, const char username, const char password, const UserCapabilityValue userCapability, const DeviceCapabilityValue deviceCapability, const char certificate, const char *displayName=nullptr)
	Connect to ASMIRA server.
Status	asdk::sdk_t::RequestCertificate (const char address, const uint16_t port, const char userName, const char password, CertificateState certificateStateOut, certificate_t *certificateOut, const int timeout=3000)
	Request certificate from ASMIRA server.
Status	asdk::sdk_t::CachedCertificate (certificate_t *certificateOut)
	Get cached certificate from ASMIRA server.
Status	asdk::sdk_t::Disconnect ()
	Disconnects from ASMIRA server.
void	asdk::sdk_t::SetServerStateCallback (ServerStateFunc func, void *opaque=nullptr)
	Server state callback.
void	asdk::sdk_t::SetAuthenticateResponseCallback (AuthenticateResponseFunc func, void *opaque=nullptr)
	Login result callback.

Detailed Description

Opening a session against an ASMIRA server: certificates, login, the user and device capabilities announced on connect, and the resulting connection state.

Typedef Documentation

◆ UserCapabilityValue

typedef uint8_t asdk::UserCapabilityValue

A single UserCapability value

Examples: example_complete.cpp.

Definition at line 351 of file asmirasdk.h.

◆ DeviceCapabilityValue

typedef int asdk::DeviceCapabilityValue

Bit set of DeviceCapability values

Examples: example_complete.cpp.

Definition at line 404 of file asmirasdk.h.

◆ ServerStateFunc

typedef void(*) asdk::ServerStateFunc(const ServerState serverState, void *opaque)

The connection to the server changed state.

Definition at line 816 of file asmirasdk.h.

◆ AuthenticateResponseFunc

typedef void(*) asdk::AuthenticateResponseFunc(const AuthenticationResponse authenticateResponse, void *opaque)

The server answered the login, see AuthenticationResponse for the bits.

Definition at line 839 of file asmirasdk.h.

Enumeration Type Documentation

◆ ServerState

enum asdk::ServerState

State of the connection to the server, reported by ServerStateFunc.

Enumerator
ServerStateUndef	Undefined
ServerStateDisconnected	Disconnected
ServerStateConnected	Connected
ServerStateConnectedAndAuthenticated	Connected and authenticated
ServerStateAuthenticateError	Authentication error

Examples: example_basic.cpp, and example_complete.cpp.

Definition at line 179 of file asmirasdk.h.

◆ AuthenticationResponse

enum asdk::AuthenticationResponse

Outcome of a login attempt, reported by AuthenticateResponseFunc.

A bit set rather than a single value: a successful login can also carry a version bit or a kicked-out-another-client bit. Test with a bitwise and.

Enumerator
AuthenticationResponseUndef	0	Undefined
AuthenticationResponseSuccess	1 << 0	Logged in
AuthenticationResponseError	1 << 1	Login refused
AuthenticationResponseVersionError	1 << 2	Major version differs, the connection is not usable
AuthenticationResponseVersionRecUpgrade	1 << 3	Minor version differs, operations may be affected
AuthenticationResponseVersionMayUpgrade	1 << 4	Patch version differs, operations not affected
AuthenticationResponseLoggedInOther	1 << 5	Someone logged into the server with these credentials
AuthenticationResponseKickedOther	1 << 6	Logged in, but caused the server to kick out another client
AuthenticationResponseWrongLoginType	1 << 7	Logged in with the wrong user capability for the account
AuthenticationResponseTryAgainLater	1 << 8	Too many or too frequent login attempts
AuthenticationResponseFormatError	1 << 9	The server was unable to read the login data
AuthenticationResponseRequestedCapError	1 << 10	The requested capability is not available for this user

Examples: example_basic.cpp, and example_complete.cpp.

Definition at line 194 of file asmirasdk.h.

◆ UserCapability

enum asdk::UserCapability : uint8_t

The role a client asks the server for on connect.

Pass one of these as the userCapability argument of sdk_t::Connect or sdk_t::ConnectSecured. Use a single role bit; the server checks it against the account and answers with AuthenticationResponseWrongLoginType when it does not match. Sender, Controller and Super are the privileged roles, for example for sdk_t::RoomFileDelete.

Enumerator
UserCapabilityUndef	0	Undefined
UserCapabilitySender	1 << 0	Streams video, audio and position to a room
UserCapabilityController	1 << 1	Watches a room and controls the senders in it
UserCapabilityViewer	1 << 2	Watches a room
UserCapabilityGuest	1 << 3	Watches a room with the fewest rights
UserCapabilitySuper	1 << 6	Reserved bit for super user
UserCapabilityUnsure	1 << 7	Connect without knowing the role, the server decides

Definition at line 340 of file asmirasdk.h.

◆ DeviceCapability

enum asdk::DeviceCapability : int

What a client announces it can do, as a DeviceCapabilityValue.

A bit set passed as the deviceCapability argument of sdk_t::Connect or sdk_t::ConnectSecured. It tells the server and the other room members which codecs and features this client handles, so declare only what is really supported. DeviceCapabilityBasic, DeviceCapabilityCore, DeviceCapabilityHeadless and DeviceCapabilityFull are ready made combinations.

Enumerator
DeviceCapabilityUndef	0	Undefined
DeviceCapabilityVideoAV1	1 << 1	Handles AV1 video
DeviceCapabilityVideoH264	1 << 2	Handles H.264 video
DeviceCapabilityVideoH265	1 << 3	Handles H.265 video
DeviceCapabilityAudioOpus	1 << 4	Handles Opus audio. Not yet implemented
DeviceCapabilityAudioSpeex	1 << 5	Handles Speex audio
DeviceCapabilityAudioMIC	1 << 6	Has a microphone, or is otherwise capable of audio input
DeviceCapabilityPhotoModeWEBP	1 << 7	Handles WebP photo mode stills
DeviceCapabilityPhotoModeHEIF	1 << 8	Handles HEIF photo mode stills. Not yet implemented
DeviceCapabilityPhotoModeAVIF	1 << 9	Handles AVIF photo mode stills. Not yet implemented
DeviceCapabilityPhotoROI	1 << 10	Handles a region of interest in photo mode
DeviceCapabilityVideoROI	1 << 11	Handles a region of interest in video
DeviceCapabilityChat	1 << 12	Handles room chat, see sdk_t::SendChatMessage
DeviceCapabilityDisplay	1 << 13	Has a display, is not headless or autonomous
DeviceCapabilityFileTransfer	1 << 16	Handles room files, see Room file transfer
DeviceCapabilityASIGN	1 << 31	Handles ASIGN
DeviceCapabilityBasic	DeviceCapabilityVideoH265 \| DeviceCapabilityAudioSpeex \| DeviceCapabilityAudioMIC \| DeviceCapabilityPhotoModeWEBP \| DeviceCapabilityPhotoROI \| DeviceCapabilityDisplay \| DeviceCapabilityVideoROI \| DeviceCapabilityChat	Common baseline: H.265 video, Speex audio, microphone, WebP photo mode, ROI, chat and a display.
DeviceCapabilityCore	DeviceCapabilityBasic \| DeviceCapabilityVideoAV1 \| DeviceCapabilityVideoH264 \| DeviceCapabilityDisplay	Desktop ASMIRA: DeviceCapabilityBasic plus AV1 and H.264.
DeviceCapabilityFull	DeviceCapabilityCore \| DeviceCapabilityAudioOpus \| DeviceCapabilityASIGN	Everything, including the parts not yet implemented.
DeviceCapabilityHeadless	DeviceCapabilityVideoH265 \| DeviceCapabilityVideoAV1 \| DeviceCapabilityVideoH264 \| DeviceCapabilityPhotoModeWEBP \| DeviceCapabilityPhotoROI \| DeviceCapabilityVideoROI	Headless ASMIRA: video and photo mode only, no audio, chat or display.

Definition at line 364 of file asmirasdk.h.

◆ CertificateState

enum asdk::CertificateState

Outcome of sdk_t::RequestCertificate.

Enumerator
CertificateStateUndef	Undefined, the request was not carried out
CertificateStateConnected	Reached the server
CertificateStateReceived	Certificate received, ready for sdk_t::ConnectSecured
CertificateStateConnectError	Could not reach the server

Examples: example_complete.cpp.

Definition at line 784 of file asmirasdk.h.

Function Documentation

◆ Connect()

Status asdk::sdk_t::Connect	(	const char *	ip,
		const uint16_t	port,
		const uint32_t	timeout,
		const bool	highLatency,
		const char *	username,
		const char *	password,
		const UserCapabilityValue	userCapability,
		const DeviceCapabilityValue	deviceCapability,
		const char *	displayName = nullptr )

inline

Connect to ASMIRA server.

Parameters

ip	Server IP.
port	Server port.
timeout	Timeout in milliseconds.
highLatency	High latency client connection.
username	Server login user name.
password	Server login user password (as plaintext).
userCapability	User capability.
deviceCapability	Device capability.
displayName	Server login user display name.

Returns: Status

Definition at line 986 of file asmirasdk.h.

References asdk::StatusErrorHandle.

◆ ConnectSecured()

Status asdk::sdk_t::ConnectSecured	(	const char *	ip,
		const uint16_t	port,
		const uint32_t	timeout,
		const bool	highLatency,
		const char *	username,
		const char *	password,
		const UserCapabilityValue	userCapability,
		const DeviceCapabilityValue	deviceCapability,
		const char *	certificate,
		const char *	displayName = nullptr )

inline

Connect to ASMIRA server.

Parameters

ip	Server IP.
port	Server port.
timeout	Timeout in milliseconds. 9000 is recommended.
highLatency	High latency client connection.
username	Server login user name.
password	Server login user password (as plaintext).
userCapability	User capability.
deviceCapability	Device capability.
certificate	Certificate obtained from RequestCertificate or CachedCertificate.
displayName	Server login user display name.

Returns: Status

Definition at line 1015 of file asmirasdk.h.

References asdk::StatusErrorHandle.

◆ RequestCertificate()

Status asdk::sdk_t::RequestCertificate	(	const char *	address,
		const uint16_t	port,
		const char *	userName,
		const char *	password,
		CertificateState *	certificateStateOut,
		certificate_t *	certificateOut,
		const int	timeout = 3000 )

inline

Request certificate from ASMIRA server.

Fetches the certificate ConnectSecured needs. Both output arguments are filled in on success; the certificate data is owned by the SDK and stays valid only until the next call.

Parameters

address	Server IP.
port	Server port.
userName	Server login user name.
password	Server login user password (as plaintext).
certificateStateOut	Receives the outcome of the request, see CertificateState.
certificateOut	Receives the certificate, see certificate_t.
timeout	Timeout in milliseconds.

Returns: Status

Definition at line 1046 of file asmirasdk.h.

References asdk::StatusErrorHandle.

◆ CachedCertificate()

Status asdk::sdk_t::CachedCertificate ( certificate_t * certificateOut )

inline

Get cached certificate from ASMIRA server.

Parameters

certificateOut Certificate data.

Returns: Status

Definition at line 1065 of file asmirasdk.h.

References asdk::StatusErrorHandle.

◆ Disconnect()

Status asdk::sdk_t::Disconnect ( )

inline

Disconnects from ASMIRA server.

Returns: Status

Definition at line 1078 of file asmirasdk.h.

References asdk::StatusErrorHandle.

◆ SetServerStateCallback()

void asdk::sdk_t::SetServerStateCallback	(	ServerStateFunc	func,
		void *	opaque = nullptr )

inline

Server state callback.

Parameters

func	Callback to install.
opaque	Caller data passed back unchanged to every invocation.

Definition at line 1371 of file asmirasdk.h.

◆ SetAuthenticateResponseCallback()

void asdk::sdk_t::SetAuthenticateResponseCallback	(	AuthenticateResponseFunc	func,
		void *	opaque = nullptr )

inline

Login result callback.

Parameters

func	Callback to install.
opaque	Caller data passed back unchanged to every invocation.

Definition at line 1431 of file asmirasdk.h.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ UserCapabilityValue

◆ DeviceCapabilityValue

◆ ServerStateFunc

◆ AuthenticateResponseFunc

Enumeration Type Documentation

◆ ServerState

◆ AuthenticationResponse

◆ UserCapability

◆ DeviceCapability

◆ CertificateState

Function Documentation

◆ Connect()

◆ ConnectSecured()

◆ RequestCertificate()

◆ CachedCertificate()

◆ Disconnect()

◆ SetServerStateCallback()

◆ SetAuthenticateResponseCallback()