The main account class. More...

#import <ZDKAccount.h>

Inheritance diagram for <ZDKAccount>:

Instance Methods
(id< ZDKResult >)	- registerAccount
	Registers the user to the configured service. More...

(id< ZDKResult >)	- unRegister
	Cancels registration and/or unregisters the user. More...

(id< ZDKResult >)	- createUser
	Creates a new user account. More...

(id< ZDKResult >)	- removeUser
	Destroys an user account object. More...

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

(void)	- setStatusEventListener:
	Adds a new account event listener. More...

(void)	- dropStatusEventListener:
	Removes a specific already added account event listener. More...

(id< ZDKCall > _Nullable)	- createCall:handlingVoipPhoneCallEvents:video:
	Creates and starts an outgoing call. More...

(NSArray *)	- getActiveCalls
	Gets a list with all account's active/ongoing calls. More...

(id< ZDKMessage >)	- createMessage:
	Creates a new EMPTY chat message with the given type. More...

(id< ZDKResult >)	- chatSessionEnd:
	End a chat session. More...

(id< ZDKResult >)	- setPresenceStatus:message:
	Start a presence publication for the user. More...

(id< ZDKResult >)	- stopPushAndUnregister:

(id< ZDKResult >)	- relinquishCallownership:

(NSString *)	- generateUUID:bufLen:
	Generate a random UUID. More...

(id< ZDKResult >)	- replaceUserRegistration
	Replace user registration. More...

(void)	- setProbeEventListener:
	Adds a new SIP probe event listener. More...

(void)	- dropProbeEventListener:
	Removes a specific already added SIP probe event listener. More...

(id< ZDKResult >)	- probeSipTransport:outboundProxy:username:authUsername:password:
	Probes for available transports for the given SIP settings. More...

(id< ZDKResult >)	- terminateConnection
	Terminates user's TCP-based connection. More...

(id< ZDKResult >)	- setTlsConfig:fileName:passPhrase:
	Configure TLS for a user. More...

(NSString *)	- handlesDescription

Instance Methods inherited from <ZDKZHandle>
(long int)	- handle

(void)	- initialize

(void)	- releaseReference

(NSString *)	- handlesDescription

Properties
long int	userHandle
	Gets the underlying user handler ID. More...

id< ZDKAccountConfig >	configuration
	Sets the account configuration. More...

long int	accountID
	Gets the ID of the account. More...

NSString *_Nullable	accountName
	Configures the account name. More...

ZDKAccountStatus	registrationStatus
	Gets the current account registration status. More...

NSArray< NSNumber * > *	mediaCodecs
	Configures the account's codecs allowed to be used. More...

int	actualRegistrationExpiry

Detailed Description

The main account class.

Method Documentation

◆ chatSessionEnd:

- (id< ZDKResult >) chatSessionEnd: (NSString *) pPeer

End a chat session.

NOT ZDKMPLEMENTED!

Parameters

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

Returns: Result of the ending

See also: ZDKResult

◆ clearMediaCodecs

- (void) clearMediaCodecs

Clears the account's codec list.

Equivalent to providing an empty list to mediaCodecs().

See also: AudioVideoCodecs, mediaCodecs()

◆ createCall:handlingVoipPhoneCallEvents:video:

- (id< ZDKCall > _Nullable) createCall:	(NSString *)	calleeNumber
handlingVoipPhoneCallEvents:	(BOOL)	handlingVoipPhoneCallEvents
video:	(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: ZDKCall, ZDKCallEventsHandler

◆ createMessage:

- (id< ZDKMessage >) createMessage: (ZDKMessageType) 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: ZDKMessage, MessageType

◆ createUser

- (id< ZDKResult >) 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: ZDKResult, configuration(), - removeUser

◆ dropProbeEventListener:

- (void) dropProbeEventListener: (id< ZDKSIPProbeEventsHandler >) 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: ZDKSIPProbeEventsHandler, setProbeEventListener()

◆ dropStatusEventListener:

- (void) dropStatusEventListener: (id< ZDKAccountEventsHandler >) 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: ZDKAccountEventsHandler, setStatusEventListener()

◆ generateUUID:bufLen:

- (NSString *) generateUUID:	(BOOL)	noPrefix
bufLen:	(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 ZDKSIPConfig'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 ZDKSIPConfig'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

- (NSArray *) getActiveCalls

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

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

See also: ZDKCall

◆ handlesDescription

- (NSString *) handlesDescription

Reimplemented from <ZDKZHandle>.

◆ probeSipTransport:outboundProxy:username:authUsername:password:

- (id< ZDKResult >) probeSipTransport:	(NSString *)	domain
outboundProxy:	(NSString *)	outboundProxy
username:	(NSString *)	username
authUsername:	(NSString *)	authUsername
password:	(NSString *)	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: ZDKSIPProbeEventsHandler, ZDKResult

◆ registerAccount

- (id< ZDKResult >) 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: zdkAccountEventsHandler(), ZDKResult

◆ removeUser

- (id< ZDKResult >) 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: ZDKResult, - createUser

◆ replaceUserRegistration

- (id< ZDKResult >) replaceUserRegistration

Replace user registration.

For protocols such as ZDKAX2 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 ZDKContext'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: ZDKResult, - registerAccount, - unRegister

◆ setPresenceStatus:message:

- (id< ZDKResult >) setPresenceStatus:	(ZDKContactStateType)	status
message:	(NSString *_Nullable)	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: ZDKResult

◆ setProbeEventListener:

- (void) setProbeEventListener: (id< ZDKSIPProbeEventsHandler >) 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: ZDKSIPProbeEventsHandler, dropProbeEventListener()

◆ setStatusEventListener:

- (void) setStatusEventListener: (id< ZDKAccountEventsHandler >) 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: ZDKAccountEventsHandler, dropStatusEventListener()

◆ setTlsConfig:fileName:passPhrase:

- (id< ZDKResult >) setTlsConfig:	(ZDKSecureUserConfigType)	userConf
fileName:	(NSString *)	fileName
passPhrase:	(NSString *_Nullable)	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

- (id< ZDKResult >) 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

- (id< ZDKResult >) 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: zdkAccountEventsHandler(), ZDKResult

Property Documentation

◆ accountID

- (long int) accountID

readnonatomicassign

Gets the ID of the account.

Returns: The account's ZDKD

◆ accountName

- (NSString* _Nullable) accountName

readwritenonatomicassign

Configures the account name.

Parameters

[in] value The account's name

◆ configuration

- (id<ZDKAccountConfig>) configuration

readwritenonatomicassign

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

- (NSArray<NSNumber*>*) mediaCodecs

readwritenonatomicassign

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

- (ZDKAccountStatus) registrationStatus

readnonatomicassign

Gets the current account registration status.

Returns: The account's registration status

See also: ZDKAccountStatus

◆ userHandle

- (long int) userHandle

readnonatomicassign

Gets the underlying user handler ID.

Internally assigned on successful createUser invocation and invalidated on removeUser.

Returns: The underlying user handler ZDKD

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

ZDKAccount.h

Instance Methods

Properties

Detailed Description

Method Documentation

◆ chatSessionEnd:

◆ clearMediaCodecs

◆ createCall:handlingVoipPhoneCallEvents:video:

◆ createMessage:

◆ createUser

◆ dropProbeEventListener:

◆ dropStatusEventListener:

◆ generateUUID:bufLen:

◆ getActiveCalls

◆ handlesDescription

◆ probeSipTransport:outboundProxy:username:authUsername:password:

◆ registerAccount

◆ removeUser

◆ replaceUserRegistration

◆ setPresenceStatus:message:

◆ setProbeEventListener:

◆ setStatusEventListener:

◆ setTlsConfig:fileName:passPhrase:

◆ terminateConnection

◆ unRegister

Property Documentation

◆ accountID

◆ accountName

◆ configuration

◆ mediaCodecs

◆ registrationStatus

◆ userHandle