The main account class. More...

#include <Account.h>

Inheritance diagram for ZDK_NET::Account:

Public Member Functions
	Account (ZDK::Shared::Account src)

ZDK_NET::Result ^	RegisterAccount ()
	Registers the user to the configured service. More...

ZDK_NET::Result ^	UnRegister ()
	Cancels registration and/or unregisters the user. More...

ZDK_NET::Result ^	CreateUser ()
	Creates a new user account. More...

ZDK_NET::Result ^	RemoveUser ()
	Destroys an user account object. More...

void	ClearMediaCodecs ()
	Clears the account's codec list. More...

void	SetStatusEventListener (ZDK_NET::AccountEventsHandler^ value)
	Adds a new account event listener. More...

void	DropStatusEventListener (ZDK_NET::AccountEventsHandler^ value)
	Removes a specific already added account event listener. More...

ZDK_NET::Call ^	CreateCall (System::String^ calleeNumber, bool handlingVoipPhoneCallEvents, bool video)
	Creates and starts an outgoing call. More...

List< Call^> ^	GetActiveCalls ()
	Gets a list with all account's active/ongoing calls. More...

ZDK_NET::Message ^	CreateMessage (ZDK_NET::MessageType type)
	Creates a new EMPTY chat message with the given type. More...

ZDK_NET::Result ^	ChatSessionEnd (System::String^ pPeer)
	End a chat session. More...

ZDK_NET::Result ^	SetPresenceStatus (ZDK_NET::ContactStateType status, System::String^ message)
	Start a presence publication for the user. More...

ZDK_NET::Result ^	StopPushAndUnregister (bool shouldRegister)

ZDK_NET::Result ^	RelinquishCallOwnership (ZDK_NET::Call^ call)

System::String ^	GenerateUUID (bool noPrefix, int bufLen)
	Generate a random UUID. More...

ZDK_NET::Result ^	ReplaceUserRegistration ()
	Replace user registration. More...

void	SetProbeEventListener (ZDK_NET::SIPProbeEventsHandler^ value)
	Adds a new SIP probe event listener. More...

void	DropProbeEventListener (ZDK_NET::SIPProbeEventsHandler^ value)
	Removes a specific already added SIP probe event listener. More...

ZDK_NET::Result ^	ProbeSipTransport (System::String^ domain, System::String^ outboundProxy, System::String^ username, System::String^ authUsername, System::String^ password)
	Probes for available transports for the given SIP settings. More...

ZDK_NET::Result ^	TerminateConnection ()
	Terminates user's TCP-based connection. More...

ZDK_NET::Result ^	SetTlsConfig (ZDK_NET::SecureUserConfigType userConf, System::String^ fileName, System::String^ passPhrase)
	Configure TLS for a user. More...

virtual long long	Handle () override

virtual void	Initialize () override

virtual void	ReleaseReference () override

Public Attributes
ZDK::IAccount *	cppRef = nullptr

Properties
long long	UserHandle `[get]`
	Gets the underlying user handler ID. More...

ZDK_NET::AccountConfig^	Configuration `[get, set]`
	Sets the account configuration. More...

long long	AccountID `[get]`
	Gets the ID of the account. More...

System::String^	AccountName `[get, set]`
	Configures the account name. More...

ZDK_NET::AccountStatus	RegistrationStatus `[get]`
	Gets the current account registration status. More...

List< ZDK_NET::AudioVideoCodecs >^	MediaCodecs `[get, set]`
	Configures the account's codecs allowed to be used. More...

int	ActualRegistrationExpiry `[get]`

Detailed Description

The main account class.

Member Function Documentation

◆ ChatSessionEnd()

ZDK_NET::Result ^ ZDK_NET::Account::ChatSessionEnd ( System::String^ pPeer )

End a chat session.

NOT MPLEMENTED!

Parameters

[in] pPeer The Peer with whom to terminate the chat session

Returns: Result of the ending

See also: Result

◆ ClearMediaCodecs()

void ZDK_NET::Account::ClearMediaCodecs ( )

Clears the account's codec list.

Equivalent to providing an empty list to MediaCodecs().

See also: AudioVideoCodecs, MediaCodecs()

◆ CreateCall()

ZDK_NET::Call ^ ZDK_NET::Account::CreateCall	(	System::String^	calleeNumber,
		bool	handlingVoipPhoneCallEvents,
		bool	video
	)

Creates and starts an outgoing call.

Creates a call originating from the specified user and starts it. If there is no error the function will return immediately. Updates on the call status will come via callbacks.

Parameters

[in]	calleeNumber	The number/user to call. The actual address is created from this ID and the account's configued domain.
[in]	handlingVoipPhoneCallEvents	Indicator whether to handle/receive call specific events
[in]	video	Indicator whether to initiate a video call, if supported

Returns: The newly created call

See also: Call, CallEventsHandler

◆ CreateMessage()

ZDK_NET::Message ^ ZDK_NET::Account::CreateMessage ( ZDK_NET::MessageType type )

Creates a new EMPTY chat message with the given type.

Creates and returns a new empty chat message from the given type that has to be filled in and then sent!

Parameters

[in] type The type of message to be created

Returns: The newly created empty message

See also: Message, MessageType

◆ CreateUser()

ZDK_NET::Result ^ ZDK_NET::Account::CreateUser ( )

Creates a new user account.

Creates a new protocol user, based on the assigned configuration, that can be used to register on a server for incoming calls, create outgoing calls, subscribe for presence, etc. This is a mandatory operation before using most of the ZDK's functions.

Returns: Result of the creation

See also: Result, Configuration(), RemoveUser()

◆ DropProbeEventListener()

void ZDK_NET::Account::DropProbeEventListener ( ZDK_NET::SIPProbeEventsHandler^ value )

Removes a specific already added SIP probe event listener.

All added/left listeners will be notified for each event.

Parameters

[in] value The SIP probe event listener to be removed

See also: SIPProbeEventsHandler, SetProbeEventListener()

◆ DropStatusEventListener()

void ZDK_NET::Account::DropStatusEventListener ( ZDK_NET::AccountEventsHandler^ value )

Removes a specific already added account event listener.

All added/left listeners will be notified for each event.

Parameters

[in] value The account event listener to be removed

See also: AccountEventsHandler, SetStatusEventListener()

◆ GenerateUUID()

System::String ^ ZDK_NET::Account::GenerateUUID	(	bool	noPrefix,
		int	bufLen
	)

Generate a random UUID.

Generates a valid RFC 4122 (RFC 2141) UUID URN that can be used for RFC 5626 (SIP Outbound).

The result is a string in the format

"urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

or the format

"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

depending on the "noPrefix" parameter. The prefix is there for easier use of SIPConfig's SipInstance().

In case the "urn:uuid:" prefix is not desired, put 1 to the "noPrefix" parameter. The resulting string will be shorter and will contain only the random part.

If "noPrefix" is set to 0, the resulting string can be given directly to SIPConfig's SipInstance().

Parameters

[in]	noPrefix	Set to 0 for full URN, 1 for a UUID without prefix
[in]	bufLen	Available bytes in the buffer (64 bytes or more are sufficient)

Returns: The generated UUID string

◆ GetActiveCalls()

List<Call^> ^ ZDK_NET::Account::GetActiveCalls ( )

Gets a list with all account's active/ongoing calls.

Returns: The list with all account's active/ongoing calls

See also: Call

◆ ProbeSipTransport()

ZDK_NET::Result ^ ZDK_NET::Account::ProbeSipTransport	(	System::String^	domain,
		System::String^	outboundProxy,
		System::String^	username,
		System::String^	authUsername,
		System::String^	password
	)

Probes for available transports for the given SIP settings.

Probes consecutively for transport availability over SIP with the given account settings.

The tests are done via SIP REGISTER requests with the given settings. The actual account's configuration will be used for this. No user-specific callbacks will be fired for this process.

This might be useful during the creation/configuration of the user account in order to notify the user for the supported transports and/or misconfiguration of either server or credentials.

During the TLS checks a Certificate-related callback can be fired which will usually result in TLS being rejected as a viable transport and the probing will continue with TCP.

If the TLS settings are changed the probing can be restarted.

The profile generated for the TLS test will benefit from any certificates that were added for a SIP user with the same configuration.

STUN and rport will not be used or tested. This may cause the probing to fail because of NAT issues.

The transports are checked in this order:

TLS
TCP
UDP

Each test will generate an informative callback. The process will be considered successful after the first successful REGISTER. The newly created binding on the server will be removed (the temporary profile will be unregistered).

Parameters

[in]	domain	Domain (SIP user creation: realm entry)
[in]	outboundProxy	Outbound proxy (SIP user creation: server entry)
[in]	username	Username
[in]	authUsername	Authentication username
[in]	password	Authentication password

Returns: Result of the invocation

See also: SIPProbeEventsHandler, Result

◆ RegisterAccount()

ZDK_NET::Result ^ ZDK_NET::Account::RegisterAccount ( )

Registers the user to the configured service.

Starts the user's registration process. If the registration process was started the function returns Ok. The result of the process will be delivered by a callback.

Returns: Result of the invocation

See also: AccountEventsHandler(), Result

◆ RemoveUser()

ZDK_NET::Result ^ ZDK_NET::Account::RemoveUser ( )

Destroys an user account object.

Destroys an user account object and all related structures. Automatically unregisters the account from the server.

Fails if the user has active calls.

Returns: Result of the removal

See also: Result, CreateUser()

◆ ReplaceUserRegistration()

ZDK_NET::Result ^ ZDK_NET::Account::ReplaceUserRegistration ( )

Replace user registration.

For protocols such as AX2 there is no "binding" and this operation does not apply. For those types of protocols the function will internally call RegisterUser() and then return its status.

This function will first try to cleanly remove any active bindings on the registrar server that were put by this instance of the library.

Then it will try to create a new registration binding on the server.

This is mostly useful when switching network types and an IP address change has been detected. This function will try to remove the old (stale) binding that is currently active on the server and replace it with a "fresh" one done from the new IP address.

!NOTE! Network changed handling MUST be done with Context's NetworkChanged()!

A better approach might be to use SIP Outbound (RFC 5626) but that requires server support.

Returns: Result of the invocation

See also: Result, RegisterAccount(), UnRegister()

◆ SetPresenceStatus()

ZDK_NET::Result ^ ZDK_NET::Account::SetPresenceStatus	(	ZDK_NET::ContactStateType	status,
		System::String^	message
	)

Start a presence publication for the user.

Use this function to publish the user's status on the server (if the server supports it). Use this function again at any time to change the account's status.

Parameters

[in]	status	Status of the user
[in]	message	If not NULLor empty, this will be published in the PIDF

Returns: Result of the set

See also: Result

◆ SetProbeEventListener()

void ZDK_NET::Account::SetProbeEventListener ( ZDK_NET::SIPProbeEventsHandler^ value )

Adds a new SIP probe event listener.

All added listeners will be notified for each event.

Parameters

[in] value The SIP probe event listener to be added

See also: SIPProbeEventsHandler, DropProbeEventListener()

◆ SetStatusEventListener()

void ZDK_NET::Account::SetStatusEventListener ( ZDK_NET::AccountEventsHandler^ value )

Adds a new account event listener.

All added listeners will be notified for each event.

Parameters

[in] value The account event listener to be added

See also: AccountEventsHandler, DropStatusEventListener()

◆ SetTlsConfig()

ZDK_NET::Result ^ ZDK_NET::Account::SetTlsConfig	(	ZDK_NET::SecureUserConfigType	userConf,
		System::String^	fileName,
		System::String^	passPhrase
	)

Configure TLS for a user.

Not only configuring a certificates for TLS is needed but also to run without one or to assign the user to a global TLS transport.

Although this function is meant to be used for different protocols, currently it only supports SIP.

Parameters

[in]	userConf	The TLS server mode setting: ClientOnly - This setting switches the user to a certificate-less operation. This mode is used by the majority of TLS client applciations and should be the default setting. This mode ignores `fileName` and `passPhrase`. For SIP, rport is almost certainly required for this to work properly before we add support for RFC 5626 (SIP Outbound). This will try to force any requests over TLS to come back over our outbound TLS connection as we won't have a working TLS server for this user. Common - In case ZDK was configured to accept incoming TLS connections, there is a global TLS server object which can be shared between the users of the same protocol (SIP only for now). This mode ignores `fileName` and `passPhrase`. For SIP, rport is highly recommended but not required for this mode because we can receive incoming TLS connections unless a firewall interferes with our traffic. Dedicated - This mode is available in case the TLS server requires user certificates. The user certificate must be provided in `fileName` and if the key along with the certificate is encrypted, the encryption passphrase must be provided in `passPhrase`. The format for the key+cert combination is either PEM or PKCS#12. Additional certificates in case the format is PKCS#12 are added to the trusted root certificate authorities list. For SIP, rport is highly recommended. See Common's notes on rport above. Generated - This mode will generate a self-signed certificate with the protocol-level URI as certificate subject (this is the SIP URI for SIP users). It will then create a dedicated TLS server transport and bind it to the generated certificate. This mode ignores `fileName` and `passPhrase`. NOT RECOMMENDED.
[in]	fileName	Used to point to a PEM or PKCS#12 certificate to load for this user, depending on `userConf`.
[in]	passPhrase	Used to provide the encryption pass phrase in case a certificate is being loaded

Returns: Result of the set

See also: VerifyUserCertificate()

◆ TerminateConnection()

ZDK_NET::Result ^ ZDK_NET::Account::TerminateConnection ( )

Terminates user's TCP-based connection.

Destroys the currently used TCP-based connection. That triggers re-registration of EVERY already registered user using this socket/connection.

Very handy when PUSH is used for example, where it is nearly certain the connection is stale/half-opened.

Returns: Result of the invocation - ResultCode::InvalidArgument error in cases where the given connection is not TCP-based!

◆ UnRegister()

ZDK_NET::Result ^ ZDK_NET::Account::UnRegister ( )

Cancels registration and/or unregisters the user.

If the user account is in the process of registration this function will cancel it. If the user was already registered an unregistration process will start. If there is no error the function will return immediately and the final result will be delivered via a callback.

Returns: Result of the invocation

See also: AccountEventsHandler(), Result

Property Documentation

◆ AccountID

long long ZDK_NET::Account::AccountID

get

Gets the ID of the account.

Returns: The account's D

◆ AccountName

System:: String^ ZDK_NET::Account::AccountName

getset

Configures the account name.

Parameters

[in] value The account's name

◆ Configuration

ZDK_NET:: AccountConfig^ ZDK_NET::Account::Configuration

getset

Sets the account configuration.

All changes checks and actions are taken automatically - e.g. reregister the account

Parameters

[in] value The account configuration

See also: AccountConfig

◆ MediaCodecs

List< ZDK_NET:: AudioVideoCodecs>^ ZDK_NET::Account::MediaCodecs

getset

Configures the account's codecs allowed to be used.

The order in which codecs are added is important. The codecs that are first in the list have greater priority. To reorder the list re-add the codecs with the proper order.

Parameters

[in] value The full list with codecs to be used

See also: AudioVideoCodecs

◆ RegistrationStatus

ZDK_NET:: AccountStatus ZDK_NET::Account::RegistrationStatus

get

Gets the current account registration status.

Returns: The account's registration status

See also: AccountStatus

◆ UserHandle

long long ZDK_NET::Account::UserHandle

get

Gets the underlying user handler ID.

Internally assigned on successful CreateUser() invocation and invalidated on RemoveUser().

Returns: The underlying user handler D

The documentation for this class was generated from the following file:

Account.h

Public Member Functions

Public Attributes

Properties

Detailed Description

Member Function Documentation

◆ ChatSessionEnd()

◆ ClearMediaCodecs()

◆ CreateCall()

◆ CreateMessage()

◆ CreateUser()

◆ DropProbeEventListener()

◆ DropStatusEventListener()

◆ GenerateUUID()

◆ GetActiveCalls()

◆ ProbeSipTransport()

◆ RegisterAccount()

◆ RemoveUser()

◆ ReplaceUserRegistration()

◆ SetPresenceStatus()

◆ SetProbeEventListener()

◆ SetStatusEventListener()

◆ SetTlsConfig()

◆ TerminateConnection()

◆ UnRegister()

Property Documentation

◆ AccountID

◆ AccountName

◆ Configuration

◆ MediaCodecs

◆ RegistrationStatus

◆ UserHandle