Sonork Instant Messaging
Visual Basic API Reference Manual



February 2003
Product Version: Sonork Server V 1.7




This manual describes the Sonork's Visual Basic API for Sonork IM to Version 1.7 .



Visual Basic API Reference Manual
Copyright Notice


© Copyright GTV Solutions, Inc. 1996, 2003. All rights reserved. May only be used pursuant to a Sonork Messaging Systems Software License Agreement. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without prior written permission of GTV Solutions, Inc. GTV Solutions, Inc. grants you limited permission to make hardcopy or other reproductions of any machine-readable documentation for your own use, provided that each such reproduction shall carry the GTV Solutions, Inc. notice. No other rights under copyright are granted without prior written permission of GTV Solutions, Inc. The document is not intended for production and is furnished “as is” without warranty of any kind. All warranties on this document are hereby disclaimed, including the warranties of merchantability and fitness for a particular purpose.
> U.S. Government Users Restricted Rights—Use, duplication or disclosure restricted, contact GTV Solutions. Inc.

Trademarks
Sonork Messaging System, and the Sonork logo are trademarks or registered trademarks of GTV Solutions, Inc. in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other company, product, or service names may be trademarks or service marks of others.

Notices
References in this publication to Sonork systems, products, programs, or services do not imply that they will be available in all countries in which GTV Solutions, Inc. operates. Any reference to these products, programs, or services is not intended to imply that only Sonork systems, products, programs, or services can be used.
> Subject to valid intellectual property or other legally protectable right of Sonork, any functionally equivalent product, program, or service can be used instead of the referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by GTV Solutions, Inc., are the responsibility of the user. GTV Solutions, Inc. may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the Sonork Director of Licensing, GTV Solutions, Inc., 49E. 21st. Street, 9th Floor, New York, NY 10010, United States of America.

© Copyright GTV Solutions, Inc. 2003. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted, contact GTV Solutions, Inc.

About This Manual
This Manual describes the different installation procedures that can be used to install or upgrade Sonork Instant Messaging System to Version 1.7

I. Audience
The target audience for this guide is programmers . Users of this guide should have knowledge of the following:

PC operating Systems
Database architecture and concepts
Networking
Graphical user interface

II. Organization
This manual is organized as follows:

Chapter 1: Overview
Chapter 2: Instance life-span
Chapter 3: Event-processing
Chapter 4: API Calls
Chapter 5: Special Values/Enums
Chapter 6: Data Types

III. Related Documents
Sonork provides the following related documentation:

Sonork Release Notes: may contain important undocumented information about anything related to Sonork Server that may affect your installation.

You can also view the Sonork Version 1.7 Technical Update for any additional information not included in this manual. You can access the Technical Update from the following URL: http://www.sonork.com/eng/support.html

IV. Reader’s Comments
Sonork welcomes any comments and suggestions you have on this and other Sonork manuals.
You can send your comments in the following ways:

Fax: 1-212-228-9600 Attn: SLD Publications
Internet electronic mail: readers_comment@sonork.com
Postal Address:

GTV Solutions
Attn: SLD Publications
49 East 21st Street
New York, NY 10010
USA

A Reader’s Comment form is located on your system in the following location:
$SONORK/doc/readers_comment.txt
Please include the following information along with your comments:

The section numbers and page numbers of the information on which you are commenting.
The version of Sonork that you are using.
If known, the type of processor that is running the Sonork Messaging System software.

The Sonork Library Department ( SLD) cannot respond to system problems or technical support inquiries. Please address technical questions to your local system vendor or to the appropriate Sonork technical support office. Information provided with the software media explains how to send problem reports to Sonork.

V. Conventions
This guide uses several typeface conventions for special terms and actions. These conventions have the following meaning:

BOLD Commands, keywords, file names, authorization roles URLs, names of windows and dialogs, other controls, or other information that you must use literally is in bold.
Italics Variables and values that you must provide, new terms, and words and phrases that are emphasized are in italics.

This Guide uses the UNIX convention for specifying environment variables and directory notation:

When using the windows command line, replace $variable with %variable% for environment variables and replace each forward slash (/) with a backslash (\) in directory paths.

VI. Publications On-line
When GTV published an update version of one or more online or hardcopy publications, they are posted to the Sonork Information Center. You can access updated publications in the Sonork Information Center from the following Sonork Customer Support Web Site: http://www.sonork.com/eng/suppport.html
The Sonork Information Center contains the most recent version of the books in the product library in PDF or HTML formats, or both. Translated documents are also available for some publications.

VII. Ordering Publications
You can order many Sonork publications online at the following Web site.
http://www.sonork.com/sonork.html
From this Web page, select Publications and follow the instructions.
In other countries, for a list of telephone numbers, see the following Web site: http://www.sonork.com/eng/contact.html

VIII. Customer support
If you have a problem with any Sonork product, you can contact Sonork Customer Support. See the Sonork Customer Support Handbook at the following Web Site: http://www.sonork.com/eng/support.html

Or visit
http://www.sonork.com

Server support
server-support@sonork.com

Client support
client-support@sonork.com

Developer support
developer@sonork.com








Overview

The Sonork VB API is a wrapper to use the Sonork engine from Microsoft's Visual BasicTM. It is composed of 2 items:

sonorkvblib.tlb: library type definition that must referenced from visual basic (from Project/References) so that all data types, enumerations and methods are available.
sonorkvblib.dll: DLL containing the API defined by sonorkvblib.tlb

The VB application (The HOST) creates one or more instances of the sonork engine (refer to Instance life-span) and obtains a handle for each. To keep the engine running, the host calls the TimeSlot (refer to SrkTimeSlot) method which will execute all pending tasks and invoke the application-defined callback (refer to The callback).

Instance life-span

Initializing

The host calls SrkCreateInstance to create an instance and register its callback (refer to The callback) along with an arbitrary tag. The handle returned is required for most API calls. The engine is kept running by invoking SrkTimeSlot at least twice per second for each instance. Every time the host's callback is invoked, both handle and tag are included along with the event's data so that the host may use the same procedure as callback for several instances.

Connecting and processing events

The host sets the target server with SrkSetSonorkServer and initiates the connection sequence with SrkConnect. Once connected, the application executes post-connection initialization tasks such as downloading user list with SrkRefreshUserList and/or obtain list of server-side services (e.g. file transfer services) with SrkRefreshConfig.
After post-connection initialization tasks are complete, the application set its online presence indicator with SrkSetSidMode.

Once presence indicator is set, engine will advise of events by invoking the callback (refer to The callback) with an event messages (refer to SONORK_EVENT_CLIENT_MSG) when an instant message arrives and with SONORK_EVENT_CLIENT_USER_SID when other users change their online status. The application sends messages by with SrkSendMsg.

Exiting

Before exiting, the hosts disconnects with SrkDisconnect and destroys each instance with SrkDestroyHandle.

Event-processing

The callback
Events are received by the host through a callback that must have the following prototype:

Sub MyCallback(
ByVal handle As Long_
, ByRef SonorkEvent As vbSonorkApiEvent)

IMPORTANT: The host must never display modal dialogs nor take "long" (>0.5 seconds) when processing events because it will halt the engine and possibly the application. If the application needs more time, it should store the event's data and display the dialog outside the callback procedure.

Events and parameters

This section describes the meaning of SONORK_EVENT values and interpretation of the vbSonorkApiEvent structure passed as parameter to the callback.
The event member of the vbSonorkApiEvent structure is the event id that defines what the instance is reporting. Events are divided in 3 types: Client, Task and File. To differentiate each, the host application can compare the event's id against the xxx_FIRST and xxx_LAST values of the SONORK_EVENT enum:

CLIENT EVENTS

Notify about changes in the network status, online presence of other users, instant messages, etc. In general, these events are related to the Client-Server link or to internal tasks and may occur at any time during the life of the API instance.
Range: SONORK_EVENT_CLIENT_FIRST~SONORK_EVENT_CLIENT_LAST

TASK EVENTS

These events are in response to tasks initiated by the host, they report status and availability of data. Each task has 2 attributes: 1) A instance-wide unique task id assigned by the API and 2) A task tag which is an arbitrary value defined by the Host when creating the task.
> Whenever the API reports a task-related events, it will include these 2 attributes.
> Range: SONORK_EVENT_TASK_FIRST~SONORK_EVENT_TASK_LAST

FILE EVENTS

Notify about progress and status of file transfer sessions. As with tasks, file sessions have an instance-wide unique id assigned by the API and an arbitrary host-defined tag. These 2 attributes are included whenever the API reports a file-related event.
Range: SONORK_EVENT_TASK_FIRST~SONORK_EVENT_TASK_LAST

The appTag is the tag provided by the host when creating the instance. If the event is a task or file event, the taskId and taskTag members will be loaded with the task's/file session's id and tag provided by the host when creating the task/file session.
> The meaning of the other members of the structure depend on the event's id.

API calls

SrkCreateInstance

Description

Creates an instance of the engine. (Replaces SrkInit)

Prototype

Function SrkCreateInstance( _
callbackProc As Long _
, callbackTag As Long _
, useUnicode As Long) As Long

Parameters

callbackProc: The address of the host's callback (refer to The callback). Use the VB keyword "AddressOf" to obtain the address of a procedure.
callbackTag: An arbitrary value defined by the application. This tag is included when reporting events for the instance.
useUnicode: The API will perform unicode translations. Normally, this should be true.

Return values
The instance handle. Zero on failure

Example

Const
MyTag = 1000
Dim Instance As Long
Instance = SrkCreateInstance(AddressOf MyCallback, MyTag, True)
If Instance = 0 Then
' If zero, something is very wrong (the address is invalid)
' normally this will never happen: No other action than exiting is possible
MsgBox "Sonork DLL initialization failed!!"
Exit Sub
End If

SrkDestroyHandle

Description

Destroys an instance, file session or server session.

Prototype

Sub SrkDestroyHandle(objectHandle As Long)

Parameters

objectHandle: And instance handle, a file session or a server session

Remarks

The callback may be invoked before this call returns.
Replaces SrkExit and SrkDestroyFileSession

SrkTimeSlot

Description

Runs a time slot for the object and invokes the callback if there are events pending. The function returns immediately because all long-running tasks are fragmented.

Prototype

Function SrkTimeSlot( objectHandle As Long ) As Long

Parameters

objectHandle: An instance, file session or server session handle.
Return values
If the object is idle, return value is zero. If there are fragmented tasks still running, it returns non-zero. Host may use the return value to increase the frequency of calls to the method while it returns non-zero.

SrkSetSonorkServer

Description

Specifies the Sonork server to which SrkConnect will link. This address is also used by any server sessions.

Prototype

Function SrkSetSonorkServer( _
instance As Long _
, addressType As SONORK_PHYS_ADDR_TYPE _
, host As String _
, port As Long _
, loginMode As SONORK_LOGIN_MODE) As SONORK_RESULT

Parameters

instance: The instance handle.
addressType: The protocol the engine must use. Must be either TCP_1 or UDP_1.
host: The host of the Sonork server. (See remarks section)
port: The port used by the Sonork server for the specified addressType (default: 1503 for UDP, 1504 for TCP)
loginMode: Should be SONORK_LOGIN_MODE_INTERNET to connect to the public Internet server (host: server.sonork.com) or when connecting to a private server (Regardless of whether the connection is done over the Internet or not). Trying to connect to the public server with SONORK_LOGIN_MODE_INTRANET mode or vice-versa will always fail.

Return value

On success, the return value is SONORK_RESULT_OK.
On failure the result will be non-zero. Use SrkGetLastError to obtain the error information.

Remarks

The host may specify a dotted IP address or a DNS name. However, if a DNS name is supplied the engine will resolve the address synchronously and the application will be blocked while resolution takes place. Solid applications should use asynchronous name resolutions and pass the resolved IP address to the engine to avoid "freezing" until resolution is complete.

SrkConnect

Description

Initiates connection sequence. SrkSetSonorkServer must be invoked at least once before calling this function.

Prototype

Function SrkConnect( _
instance As Long
, userId As vbSonorkDw2
, password As String) As SONORK_RESULT

Parameters

instance: The instance handle.
userId: User account id.
password: User account password.

Return value

On success, the return value is SONORK_RESULT_OK. The callback will be invoked with event SONORK_EVENT_CLIENT_STATUS_CHANGE and status SONORK_NETIO_STATUS_CONNECTING before the function returns. The engine will report progress from within SrkTimeSlot with more SONORK_EVENT_CLIENT_STATUS_CHANGE events until SONORK_NETIO_STATUS_CONNECTED is reached. Once that status is reached, connection phase has ended and online functions are enabled. The host should then invoke SrkSetSidMode so that server notifies other online users about the connection.

On Failure the callback will not be invoked and the result will be non-zero. Use SrkGetLastError to obtain the error information.

SrkDisconnect

Description

Disconnects or aborts a connection sequence.

Prototype

Sub SrkDisconnect( objectHandle As Long _
, invokeHandlers as boolean)

Parameters

objectHandle: And instance handle, a file session or a server session
invokeHandlers: Allows invocation of handlers while disconnecting

Remarks

The callback may be invoked before this call returns.
Information set by SrkSetSonorkServer is preserved.

SrkSetSidMode

Description
Sets online status (refer to SONORK_SID_MODE) (BUSY, AVAILABLE, AWAY, etc.) and message. If the engine is currently connected a global task is initiated to synchronize the mode with server and notify other users about the change. If engine is not connected, the function has no effect.

Prototype

Function SrkSetSidMode( _
instance As Long _
, sidMode As SONORK_SID_MODE
, sidText As String) As SONORK_RESULT

Parameters

instance: The instance handle.
sidMode: New sid mode.
sidText: Session notes (Explain status. e.g. "I'm in a meeting" or "Out for lunch")

Return value

On success, the return value is SONORK_RESULT_OK. If engine is currently connected a global task will also be started and the callback will be invoked with event SONORK_EVENT_CLIENT_GLOBAL_TASK_START and task type SONORK_GLOBAL_TASK_SET_SID before the function returns. The engine will report task completion (and result) by sending a SONORK_EVENT_CLIENT_GLOBAL_TASK_END event with the same task type.

On failure, the callback will not be invoked and the result will be different from SONORK_RESULT_OK. Use SrkGetLastError to obtain the error information.

Remarks

When connected, a SONORK_RESULT_OK return value does not guarantee that the sid mode has changed: It only indicates that the global task was successfully started. The host application must process the SONORK_EVENT_CLIENT_GLOBAL_TASK_END result's to check if the engine was able to synchronize the sid mode with the server.

SrkNormalizeSidMode

Description

Translates a SONORK_SID_MODE to one of the primary types. To ensure compatibility with future client/server versions, the host application should always translate sid modes before testing them against one of the primary types.

Prototype

Function SrkNormalizeSidMode( _
sidMode As SONORK_SID_MODE) As SONORK_SID_MODE

Parameters

sidMode: Sid mode to translate.

Return value

The equivalent primary sid mode. If the parameter is already a primary type, the function returns that same value.

SrkRefreshUserList

Description

Downloads the user list from the server. This is a global task.

Prototype

Function SrkRefreshUserList(
instance as Long) As SONORK_RESULT

Parameters

instance: The instance handle.

Return value

On success, the return value is SONORK_RESULT_OK. A global task will also be started and the callback will be invoked with event SONORK_EVENT_CLIENT_GLOBAL_TASK_START and task type SONORK_GLOBAL_TASK_REFRESH_USER_LIST before the function returns. The engine will send one SONORK_EVENT_CLIENT_USER_ADD event for each user retrieved and completion (with result) will be indicated with a SONORK_EVENT_CLIENT_GLOBAL_TASK_END event.

On failure to initiate the task, the callback will not be invoked and the result will be different from SONORK_RESULT_OK. Use SrkGetLastError to obtain the error information.

Remarks

When connected, a SONORK_RESULT_OK return value does not guarantee that the user list was refreshed: It only indicates that the global task was successfully started. The host application must process the SONORK_EVENT_CLIENT_GLOBAL_TASK_END result's to check if the engine was able to complete the operation.

SrkRefreshConfig

Description

Downloads configuration items from server. This is a global task.

Prototype

Function SrkRefreshConfig(
instance As Long
, flags As long) As SONORK_RESULT

Parameters

instance: The instance handle.
flags: A combination of SONORK_REFRESH_CONFIG_FLAGS

Return value

On success, the return value is SONORK_RESULT_OK. A global task will also be started and the callback will be invoked with event SONORK_EVENT_CLIENT_GLOBAL_TASK_START and task type SONORK_GLOBAL_TASK_REFRESH_CONFIG before the function returns. Depending on the task type, the engine might send other events before the completion (with result) is indicated with a SONORK_EVENT_CLIENT_GLOBAL_TASK_END event.

On failure to initiate the task, the callback will not be invoked and the result will be different from SONORK_RESULT_OK. Use SrkGetLastError to obtain the error information.

Remarks

When reporting SONORK_EVENT_CLIENT_GLOBAL_TASK_START, SONORK_EVENT_CLIENT_GLOBAL_TASK_END events, data(1) of vbSonorkApiEvent (vbSonorkApiEvent.data(1)) contains the flags specified when creating the task.
Most configuration items are valid only while connected and discarded after the engine disconnects (refer to SONORK_EVENT_CLIENT_STATUS_CHANGE). Applications that support file transfer should refresh the configuration immediately after connecting with flags SONORK_REFRESH_CONFIG_MAPPINGS and SONORK_REFRESH_CONFIG_SERVICES.

SrkRefreshUser

Description

Refreshes a remote user's data in background. Similar to SrkGetUserById.

Prototype

Function SrkRefreshUser( _
instance As Long _
, userId As vbSonorkDw2 _
, userInfoLevel As SONORK_USER_INFO_LEVEL
, getUserFlags As Long
, authPin As Long) As SONORK_RESULT

Parameters

instance: The instance handle.
userId: The user's id.
userInfoLevel: The requested information level (should normally be SONORK_USER_INFO_LEVEL_1)
getUserFlags: Data requested and method (normally zero), a combination of SONORK_GET_USER_DATA_FLAGS
authPin: Authorization pin other user has granted (normally zero)

Return value

On success, the return value is SONORK_RESULT_OK. If the engine is able to retrieve the user's data, a SONORK_EVENT_CLIENT_USER_REFRESH_DATA event will be sent before the task end is reported with a SONORK_EVENT_CLIENT_USER_REFRESH_END event.

On failure to initiate the task, the callback will not be invoked and the result will be different from SONORK_RESULT_OK. Use SrkGetLastError to obtain the error information.

SrkSendMsg

Description

Sends an instant message.

Prototype

Function SrkSendMsg( _
instance As Long _
, vbLocus As vbSonorkLocus1 _
, msg As VbSonorkMsg _
, taskTag As Long) As Long

Parameters

instance: The instance handle.
vbLocus: The user location (user id and sid), see remarks section.
msg: The instant message.
taskTag: An arbitrary value associated to the task.

Return value

On success, the return value is a non-zero task id. The completion (and result) of the task will be reported to the callback by sending a SONORK_EVENT_TASK_END event with the proper values loaded in the taskId and taskTag members of the vbSonorkApiEvent.

On failure to initiate the task, the callback will not be invoked and the function returns zero (0). Use SrkGetLastError to obtain the error information.

Remarks

The host application must process the SONORK_EVENT_TASK_END result's to check if the engine was able to complete the operation.

Depending on the configuration, the server may allow all zeros in the sid member of vbLocus. Setting sid to zero forces the server to resolve it and/or store the message if user is offline, however this method is not recommended because it is much slower and might not work if the server's administrator has disabled delayed resolution or offline messaging. The recommended way is to store the user's sid value when a SONORK_EVENT_CLIENT_USER_SID event is received by the callback (Sid information is included in the event) and then use that value when invoking this function.

SrkGetUserById

Description

Retrieve an user or list of users. SrkGetUserById is similar to SrkRefreshUser: Both return always 0 or 1 records, but the later is done in background. SrkGetUserByInfo and SrkGetUserByCallSign are used to search the accounts database.

Prototypes

Function SrkGetUserById( _
instance As long _
, userId As vbSonorkDw2 _
, userInfoLevel As SONORK_USER_INFO_LEVEL _
, getUserFlags As long _
, authPin as long _
, taskTag as long) As long

Parameters

instance: The instance handle.
userId: The user's id.
userInfoLevel: The requested information level (should normally be SONORK_USER_INFO_LEVEL_1)
getUserFlags: Data requested and method (normally zero), a combination of SONORK_GET_USER_DATA_FLAGS
authPin: Authorization pin other user has granted (not supported by API, set to zero)
taskTag: An arbitrary value associated to the task.

Return value

On success, the return value is a non-zero task id. A SONORK_EVENT_TASK_USER_DATA event will be sent for each user retrieved, the completion (and result) of the task will be reported to the callback by sending a SONORK_EVENT_TASK_END event. For both events, proper values will be loaded in the taskId and taskTag members of the vbSonorkApiEvent.

On failure to initiate the task, the callback will not be invoked and the function returns zero (0). Use SrkGetLastError to obtain the error information.

Remarks

The authorized list members are notified by the server when the list's owner changes attributes such as online mode (SONORK_EVENT_CLIENT_USER_SID) and user data (SONORK_EVENT_CLIENT_USER_SET). A private authorization record is also created; this record allows the host to modify permissions such as status, e-mail and network address visibility on a per-user basis. See SrkGetUserById and SrkRefreshUser.
After the server accepts and processes the request, it'll notify both source and target entities with a SONORK_EVENT_CLIENT_USER_AUTH_REQ event. The request will remain in "pending" state until it is cancelled (by either side) with SrkDelAuth or accepted by the target with SrkAcceptAuth. If the user was already in the authorized list, the server silently removes it before sending the notifications (iow: Receiving a SONORK_EVENT_CLIENT_USER_AUTH_REQ event implies the user is no longer in the authorized list).

Sonork user lists are symmetric: If user A is in B's authorized list, then B is also in A's authorized list

SrkGetUserByInfo

Description
Retrieve an user or list of users. SrkGetUserById is similar to SrkRefreshUser: Both return always 0 or 1 records, but the later is done in background. SrkGetUserByInfo and SrkGetUserByCallSign are used to search the accounts database.

Prototypes

Function SrkGetUserByInfo( _
instance As long _
, alias As string _
, name As string _
, email As String _
, notes As String _
, searchFlags As Long _
, sex As SONORK_SEX _
, region As vbSonorkDw2 _
, maxResults As Long _
, taskTag As Long) As long

Parameters
instance: The instance handle.
alias, name, email, notes: Information that the returned list of users must match. Case insensitive. Zero length strings match all records; at least one must be non-empty.
searchFlags: Combination of SONORK_SEARCH_USER_FLAGS
sex: Use SEX_NA to include all.
maxResults: Maximum records the server will return. Depending on the server's configuration, this parameter may be adjusted to the maximum allowed for the user requesting the list.
taskTag: An arbitrary value associated to the task.

Return value

On success, the return value is a non-zero task id. A SONORK_EVENT_TASK_USER_DATA event will be sent for each user retrieved, the completion (and result) of the task will be reported to the callback by sending a SONORK_EVENT_TASK_END event. For both events, proper values will be loaded in the taskId and taskTag members of the vbSonorkApiEvent.

On failure to initiate the task, the callback will not be invoked and the function returns zero (0). Use SrkGetLastError to obtain the error information.

Remarks

The authorized list members are notified by the server when the list's owner changes attributes such as online mode (SONORK_EVENT_CLIENT_USER_SID) and user data (SONORK_EVENT_CLIENT_USER_SET). A private authorization record is also created; this record allows the host to modify permissions such as status, e-mail and network address visibility on a per-user basis. See SrkGetUserById and SrkRefreshUser.
After the server accepts and processes the request, it'll notify both source and target entities with a SONORK_EVENT_CLIENT_USER_AUTH_REQ event. The request will remain in "pending" state until it is cancelled (by either side) with SrkDelAuth or accepted by the target with SrkAcceptAuth. If the user was already in the authorized list, the server silently removes it before sending the notifications (iow: Receiving a SONORK_EVENT_CLIENT_USER_AUTH_REQ event implies the user is no longer in the authorized list).

Sonork user lists are symmetric: If user A is in B's authorized list, then B is also in A's authorized list.

SrkGetUserByCallSign

Description

Retrieve an user or list of users. SrkGetUserById is similar to SrkRefreshUser: Both return always 0 or 1 records, but the later is done in background. SrkGetUserByInfo and SrkGetUserByCallSign are used to search the accounts database.

Prototypes

Function SrkGetUserByCallSign( _
instance As long _
, callSign As string _
, searchFlags As Long _
, maxResults As Long _
, taskTag As Long) As long

Parameters

instance: The instance handle.
callSign: Exact name of call sign. Cannot be zero-length. Case insensitive.
searchFlags: Combination of SONORK_SEARCH_USER_FLAGS
maxResults: Maximum records the server will return. Depending on the server's configuration, this parameter may be adjusted to the maximum allowed for the user requesting the list.
taskTag: An arbitrary value associated to the task.

Return value

On success, the return value is a non-zero task id. A SONORK_EVENT_TASK_USER_DATA event will be sent for each user retrieved, the completion (and result) of the task will be reported to the callback by sending a SONORK_EVENT_TASK_END event. For both events, proper values will be loaded in the taskId and taskTag members of the vbSonorkApiEvent.

On failure to initiate the task, the callback will not be invoked and the function returns zero (0). Use SrkGetLastError to obtain the error information.

Remarks

The authorized list members are notified by the server when the list's owner changes attributes such as online mode (SONORK_EVENT_CLIENT_USER_SID) and user data (SONORK_EVENT_CLIENT_USER_SET). A private authorization record is also created; this record allows the host to modify permissions such as status, e-mail and network address visibility on a per-user basis. See SrkGetUserById and SrkRefreshUser.
After the server accepts and processes the request, it'll notify both source and target entities with a SONORK_EVENT_CLIENT_USER_AUTH_REQ event. The request will remain in "pending" state until it is cancelled (by either side) with SrkDelAuth or accepted by the target with SrkAcceptAuth. If the user was already in the authorized list, the server silently removes it before sending the notifications (iow: Receiving a SONORK_EVENT_CLIENT_USER_AUTH_REQ event implies the user is no longer in the authorized list).
Sonork user lists are symmetric: If user A is in B's authorized list, then B is also in A's authorized list.

SrkRequestAuth

Description

Issues a request to add a member to the local "authorized" user list.

Prototype

Function SrkRequestAuth( _
instance As long _
, userId As vbSonorkDw2 _
, userAuth As vbSonorkUserAuth _
, authNotes As string _
, taskTag As Long) As long

Parameters

instance: The instance handle.
userId: The remote user's id.
userAuth: The authorization record
authNotes: Arbitrary text attached to the request.
taskTag: An arbitrary value associated to the task.

Return value

On success, the return value is a non-zero task id. The completion (and result) of the task will be reported to the callback by sending a SONORK_EVENT_TASK_END event with the proper values loaded in the taskId and taskTag members of the vbSonorkApiEvent.

On failure to initiate the task, the callback will not be invoked and the function returns zero (0). Use SrkGetLastError to obtain the error information.

Remarks

The authorized list members are notified by the server when the list's owner changes attributes such as online mode (SONORK_EVENT_CLIENT_USER_SID) and user data (SONORK_EVENT_CLIENT_USER_SET). A private authorization record is also created; this record allows the host to modify permissions such as status, e-mail and network address visibility on a per-user basis. See SrkGetUserById and SrkRefreshUser.
After the server accepts and processes the request, it'll notify both source and target entities with a SONORK_EVENT_CLIENT_USER_AUTH_REQ event. The request will remain in "pending" state until it is cancelled (by either side) with SrkDelAuth or accepted by the target with SrkAcceptAuth. If the user was already in the authorized list, the server silently removes it before sending the notifications (iow: Receiving a SONORK_EVENT_CLIENT_USER_AUTH_REQ event implies the user is no longer in the authorized list).
Sonork user lists are simmetric: If user A is in B's authorized list, then B is also in A's authorized list.

SrkAcceptAuth

Description

Accepts an incoming authorization request. Accepting a request will add the remote user to the local's "authorized" user list.

Prototype

Function SrkAcceptAuth( _
instance As Long _
, userId As vbSonorkDw2_
, userAuth As vbSonorkUserAuth _
, taskTag As Long) As Long

Parameters

instance: The instance handle.
userId: The remote user's id.
userAuth: The authorization record
taskTag: An arbitrary value associated to the task.

Return value

On success, the return value is a non-zero task id. The completion (and result) of the task will be reported to the callback by sending a SONORK_EVENT_TASK_END event with the proper values loaded in the taskId and taskTag members of the vbSonorkApiEvent.

On failure to initiate the task, the callback will not be invoked and the function returns zero (0). Use SrkGetLastError to obtain the error information.

Remarks

The function will fail if the authorization request was issued locally with SrkRequestAuth: Only incoming requests may be accepted; incoming authorization requests are received via the SONORK_EVENT_CLIENT_USER_AUTH_REQ event.
If the request is successful, the server will send a SONORK_EVENT_CLIENT_USER_ADD event to both ends.
See remarks under SrkRequestAuth for information about the authorized list.

SrkDelAuth

Description

Denies/Cancels an authorization request. Removes a member from the local's "authorized" list.

Prototype

Function SrkDelAuth( _
instance As Long _
, userId As vbSonorkDw2 _
, taskTag As Long) As Long

Parameters

instance: The instance handle.
userId: The remote user's id.
taskTag: An arbitrary value associated to the task.

Return value

On success, the return value is a non-zero task id. The completion (and result) of the task will be reported to the callback by sending a SONORK_EVENT_TASK_END event with the proper values loaded in the taskId and taskTag members of the vbSonorkApiEvent.

On failure to initiate the task, the callback will not be invoked and the function returns zero (0). Use SrkGetLastError to obtain the error information.

Remarks

This function also cancels any request issued with SrkRequestAuth and if userId specifies a member of the "authorized list", the member is removed and the private authorization record deleted.
If the request is successful, the server will send a SONORK_EVENT_CLIENT_USER_DEL event to both ends.
See remarks under SrkRequestAuth for information about the authorized list.

SrkGetLastError

Description

Gets extended error information for the last operation.

Prototype

Function SrkGetLastError( _
objectHandle As Long _
, error as VbSonorkError) As SONORK_RESULT

Parameters

objectHandle: And instance handle, a file session or a server session
error: Buffer to load with error information.

Return value

The last error code (Also returned in result member of error parameter)
If instance parameter is invalid, it will return SONORK_RESULT_INVALID_HANDLE and error will not be loaded.

SrkGetEventError

Description

Gets extended error information for the current event. May only be invoked while processing an event (In the callback).

Prototype

Function SrkGetEventError( _
objectHandle As Long _
, error as VbSonorkError) As SONORK_RESULT


Parameters

objectHandle: And instance handle, a file session or a server session
error: Buffer to load with error information.

Return value

Current event's error code (Also returned in result member of error parameter)
If instance parameter is invalid, it will return SONORK_RESULT_INVALID_HANDLE and error will not be loaded.

SrkGetEventUser

Description

Gets the user information for the current event. May only be invoked while processing an event which specifically returns user data. (i.e. SONORK_EVENT_TASK_USER_DATA)

Prototype

Function SrkGetEventUser( _
objectHandle As Long _
, userData As VbSonorkUserData) As SONORK_RESULT


Parameters

objectHandle: And instance handle or a server session
userData: Buffer to load with user's information

Return value

SONORK_RESULT_OK on success.
SONORK_RESULT_INVALID_OPERATION indicates that the event being processed is invalid.
Other non-zero results.

SrkGetEventNotes

Description

Gets the text/notes associated to the current event. May only be invoked while processing an event which contains user data or text. (i.e. SONORK_EVENT_TASK_USER_DATA)

Prototype

Function SrkGetEventNotes(
objectHandle As Long
, text As string) As SONORK_RESULT

Parameters

objectHandle: And instance handle or a server session
text: Returned string/notes.

Return value

SONORK_RESULT_OK on success.
SONORK_RESULT_INVALID_OPERATION indicates that the event being processed is invalid.
Other non-zero results.

SrkGetEventSid

Description

Gets the sid information for the current event. May only be invoked while processing an event which specifically contains sid information. (i.e. SONORK_EVENT_CLIENT_USER_SID)
Sid information is used to send messages (refer to SrkSendMsg) and update the user's online mode.

Prototype

Function SrkGetEventSid( _
instance As Long _
, userSid As vbSonorkUserSid) As SONORK_RESULT

Parameters

instance: The instance handle.
userSid: Buffer to load with sid information.

Return value

SONORK_RESULT_OK on success.
SONORK_RESULT_INVALID_OPERATION indicates that the event being processed is invalid.
Other non-zero results.

SrkGetEventMsg

Description

Gets the instant message for the current event. May only be invoked while processing an event which specifically contains a related instant message. (i.e. SONORK_EVENT_CLIENT_MSG)

Prototype

Function SrkGetEventMsg( _
instance As Long _
, msg As VbSonorkMsg) As SONORK_RESULT

Parameters

instance: The instance handle.
msg: Buffer to load with instant message.

Return value

SONORK_RESULT_OK on success.
SONORK_RESULT_INVALID_OPERATION indicates that the event being processed is invalid.
Other non-zero results.

SrkGetEventAuthReq

Description

Gets the authorization (user list modification) request for the current event. May only be invoked while processing an event which specifically contains a related authorization request. (i.e. SONORK_EVENT_CLIENT_USER_AUTH_REQ)

Prototype

Function SrkGetEventAuthReq( _
instance As Long _
, authReq As vbSonorkUserAuthReq) As SONORK_RESULT

Parameters

instance: The instance handle.
authReq: Buffer to load with authorization request.

Return value

SONORK_RESULT_OK on success.
SONORK_RESULT_INVALID_OPERATION indicates that the event being processed is invalid.
Other non-zero results.

SrkInit

Obsolete, use SrkCreateInstance instead.

SrkExit

Obsolete, use SrkDestroyHandle instead.

Special values/Enums

SONORK_EVENT

SONORK_EVENT_CLIENT_STATUS_CHANGE


Description

The engine has changed its network status.

Parameters

data(0): Current network status
data(1): Previous network status
result: Reason (SONORK_RESULT) for change.

Remarks

Values for network status are listed under SONORK_NETIO_STATUS.
When the event indicates disconnection (data(0) is SONORK_NETIO_STATUS_DISCONNECTED), host must clear all session information obtained by processing the SONORK_EVENT_CLIENT_USER_SID event and check the result member which will hold the error code if disconnection was unexpected or SONORK_RESULT_OK if the change was requested by the host application.
result is always SONORK_RESULT_OK unless reporting a disconnection.

SONORK_EVENT_CLIENT_GLOBAL_TASK_START, SONORK_EVENT_CLIENT_GLOBAL_TASK_END

Description

The engine has started/ended a global task. Global tasks are a small set of functions that must be serialized because they would be meaningless if done concurrently (For example: Changing online mode (refer to SrkSetSidMode) or refreshing the user list (refer to SrkRefreshUserList). There can only be one (1) global task active at the same time in the same instance.
Global tasks may execute concurrently with normal tasks, but not with another global task, so host application must not call any functions that start global tasks while one is already running.

Parameters

data(0): The task type (A SONORK_GLOBAL_TASK value)
data(1): The task flags (depends on the task type)
result: Applies only to SONORK_EVENT_CLIENT_GLOBAL_TASK_END, holds the SONORK_RESULT of the task. Extended information may be obtained with SrkGetEventError.

Remarks

When the task type indicates SONORK_GLOBAL_TASK_REFRESH_CONFIG, data(1) contains the flags specified when invoking SrkRefreshConfig. data(1) is undefined for all other task types.

SONORK_EVENT_CLIENT_MONITOR

Description

The engine has executed the monitor. Normally once every 5 seconds the engine will monitor for network and task time-outs.

SONORK_EVENT_CLIENT_MSG

Description

An instant message has arrived. The message may be obtained with SrkGetEventMsg.

Parameters

objId: The user id of the sender.

SONORK_EVENT_CLIENT_USER_AUTH_REQ

Description

Server is notifying that a request to modify our user list has been issued.
The full request may be obtained by calling SrkGetEventAuthReq

Parameters

objId: The remote user's id.

Remarks

Notification is sent even if the request was issued by the host with SrkGetEventAuthReq.
The request may be accepted with SrkAcceptAuth or denied/canceled with SrkDelAuth.
Receiving this event implies the remote user is no longer in the authorized list.

SONORK_EVENT_CLIENT_USER_ADD

Description

Server is notifying that user has been added to our user list.
Notification is also sent when refreshing the user list in response to SrkRefreshUserList.
User's data may be obtained by calling SrkGetEventUser and SrkGetEventNotes.

Parameters

objId: The user's id.


SONORK_EVENT_CLIENT_USER_SET

Description

Server is notifying that a user in our list has modified its data.
The application may choose to ignore the notification or call SrkRefreshUser to obtain the new user's data. This notification is not sent when the remote user modifies its online state or if the server's administrator has disabled the "notify-on-change" functions.

Parameters

objId: The user's id.

SONORK_EVENT_CLIENT_USER_SID

Description

Server is notifying that a user in our list has modified its online status (refer to SONORK_SID_MODE) (Connected, Disconnected, Change mode, etc)
The host may call SrkGetEventSid to obtain the new user's address, sid and flags.

Parameters

objId: The user's id.

Remarks

The host should ideally store the session information in order to properly display the user's status and send messages (refer to SrkSendMsg). This information must be discarded when the engine disconnects (refer to SONORK_EVENT_CLIENT_STATUS_CHANGE).

SONORK_EVENT_CLIENT_USER_DEL

Description

Server is notifying that a user has been removed from our user list

Parameters

objId: The user's id.

SONORK_EVENT_CLIENT_USER_REFRESH_DATA

Description

API is notifying that a SrkRefreshUser background task has retrieved the user's data which may be obtained with SrkGetEventUser and SrkGetEventNotes.

Parameters

objId: The user's id.
data(0): User information level. The host must ignore the event if level is less than SONORK_USER_INFO_LEVEL_1

SONORK_EVENT_CLIENT_USER_REFRESH_END

Description

API is notifying that a SrkRefreshUser background task has ended. If the task was successful, the host received one or more SONORK_EVENT_CLIENT_USER_REFRESH_DATA events before this one.

Parameters

objId: The user's id.
result: SONORK_RESULT for the task. Extended information may be obtained with SrkGetEventError while still processing the event.

SONORK_EVENT_TASK_END

Description

API is notifying that a task has ended. (e.g. Send a message)

Parameters

taskId: The task's id (Returned by function that starts the task)
taskTag: The task's tag (provided by the host when starting the task)
result: SONORK_RESULT for the task. Extended information may be obtained with SrkGetEventError while still processing the event.

SONORK_EVENT_TASK_USER_DATA

Description

API is notifying that the task is returning user data. Applies only to tasks that request user information. (e.g. SrkGetUserById) To obtain the user's information, host may call SrkGetEventUser and SrkGetEventNotes while still processing the event.

Parameters

taskId: The task's id (Returned by function that starts the task)
taskTag: The task's tag (Provided by the host when starting the task)
objId: The user's id.
data(0): User information level. The host must ignore the event if level is less than SONORK_USER_INFO_LEVEL_1

SONORK_RESULT

Error codes returned by the library.

SONORK_RESULT_OK
0
SONORK_RESULT_NO_DATA
1
SONORK_RESULT_DUPLICATE_DATA
2
SONORK_RESULT_CODEC_ERROR
3
SONORK_RESULT_PROTOCOL_ERROR
4
SONORK_RESULT_INVALID_PARAMETER
5
SONORK_RESULT_INVALID_VERSION
6
SONORK_RESULT_INVALID_OPERATION
7
SONORK_RESULT_INVALID_ENCRYPTION
8
SONORK_RESULT_NOT_SUPPORTED
9
SONORK_RESULT_SERVICE_BUSY
10
SONORK_RESULT_QUOTA_EXCEEDED
11
SONORK_RESULT_TIMEOUT
12
SONORK_RESULT_OUT_OF_RESOURCES
13
SONORK_RESULT_NOT_ACCEPTED
14
SONORK_RESULT_NETWORK_ERROR
15
SONORK_RESULT_STORAGE_ERROR
16
SONORK_RESULT_INTERNAL_ERROR
17
SONORK_RESULT_ACCESS_DENIED
18
SONORK_RESULT_USER_TERMINATION
19
SONORK_RESULT_FORCED_TERMINATION
20
SONORK_RESULT_CONFIGURATION_ERROR
21
SONORK_RESULT_INVALID_HANDLE
22
SONORK_RESULT_NOT_AVAILABLE
23
SONORK_RESULT_OS_ERROR
24
SONORK_RESULT_INVALID_MODE
25
SONORK_RESULT_INVALID_SERVER
26
SONORK_RESULT_NOT_READY
27
SONORK_RESULT_FUNCTION_DISABLED
28
SONORK_RESULT_DATABASE_ERROR
100
SONORK_RESULT_OK_PENDING
200

SONORK_LOGIN_MODE

Login mode: Parameter for SrkSetSonorkServer. Use INTERNET when connecting to the one and only public Internet server farm hosted by Sonork.com (host: server.sonork.com) and INTRANET when connecting to a private server (Regardless of whether the connection to the private server is done over the Internet).

SONORK_LOGIN_MODE_INTERNET
0
SONORK_LOGIN_MODE_INTRANET
1

SONORK_PHYS_ADDR_TYPE

Network address type, used by SrkSetSonorkServer to select preferred transport. Against what is normally expected: Sonork is usually faster using TCP in LANs and more reliable using UDP on WANs.

SONORK_PHYS_ADDR_ANY
-1
SONORK_PHYS_ADDR_NONE
0
SONORK_PHYS_ADDR_TCP_1
1
SONORK_PHYS_ADDR_UDP_1
2

SONORK_NETIO_STATUS

Generic network status. Not all values apply to the Sonork engine which reports changes to the callback with a SONORK_EVENT_CLIENT_STATUS_CHANGE event.

SONORK_NETIO_STATUS_DISCONNECTED
0
SONORK_NETIO_STATUS_DISCONNECTING
1
SONORK_NETIO_STATUS_CONNECT_REQ
2
SONORK_NETIO_STATUS_CONNECTING
3
SONORK_NETIO_STATUS_AUTHORIZING
4
SONORK_NETIO_STATUS_CONNECTED
5
SONORK_NETIO_STATUS_LISTENING
6

SONORK_SID_MODE

Valid online modes for presence indicator. Some values are reserved for future versions and should not be used. To ensure compatibility with future client/server versions, the host application should always translate reserved sid modes using SrkNormalizeSidMode to one of the primary types.

Enum
Value
Type
SONORK_SID_MODE_DISCONNECTED
0
primary
SONORK_SID_MODE_ONLINE
1
primary
SONORK_SID_MODE_BUSY
2
primary
SONORK_SID_MODE_AT_WORK
3
primary
SONORK_SID_MODE_FRIENDLY
4
primary
SONORK_SID_MODE_AWAY
5
primary
SONORK_SID_MODE_AWAY_AUTO
6
extended
SONORK_SID_MODE_INVISIBLE
7
primary
SONORK_SID_MODE_ONLINE_02
8
reserved
SONORK_SID_MODE_ONLINE_03
9
reserved
SONORK_SID_MODE_BUSY_02
10
reserved
SONORK_SID_MODE_BUSY_03
11
reserved
SONORK_SID_MODE_AT_WORK_02
12
reserved
SONORK_SID_MODE_AT_WORK_03
13
reserved
SONORK_SID_MODE_FRIENDLY_02
14
reserved
SONORK_SID_MODE_FRIENDLY_03
15
reserved
SONORK_SID_MODE_AWAY_HOLD
16
reserved
SONORK_SID_MODE_AWAY_PHONE
17
reserved
SONORK_SID_MODE_AWAY_02
18
reserved
SONORK_SID_MODE_AWAY_03
19
reserved
SONORK_SID_MODE_INVISIBLE_02
20
reserved
SONORK_SID_MODE_INVISIBLE_03
21
reserved

SONORK_USER_INFO_LEVEL

User information level, an attribute of the user authorization flags that specifies what data a user or service can access from another. Used by API when reporting the level of information available to SrkGetEventUser and by the host when retrieving user information with SrkRefreshUser or SrkGetUserById.

SONORK_USER_INFO_LEVEL_0
(None)
0
SONORK_USER_INFO_LEVEL_1
Default/Shared
1
SONORK_USER_INFO_LEVEL_2
Private
2
SONORK_USER_INFO_LEVEL_3
Full
3

SONORK_SEX

User attribute. NA is used for services and robots.

SONORK_SEX_NA
0
SONORK_SEX_M
1
ONORK_SEX_F
2

SONORK_GET_USER_DATA_FLAGS

Flags that may be combined to modify behavior of SrkRefreshUser and SrkGetUserById.

SONORK_GET_USER_DATA_F_USE_PUBLIC
Translate data using user's public authorization flags.
1
SONORK_GET_USER_DATA_F_USE_PRIVATE
Translate data using authorization flags granted to requesting user. Will fail if not authorizations have been granted (i.e. Requesting entity is not in user list of requested user)
2
SONORK_GET_USER_DATA_F_FIELDS
Retreive user extended fields (Currently not supported by API)
16

SONORK_SEARCH_USER_FLAGS

Flags that may combined to modify behavior of SrkGetUserByCallSign and SrkGetUserByInfo.

SONORK_SEARCH_USER_EXCLUDE_BUSY
Will exclude users in busy mode.
1
SONORK_SEARCH_USER_FRIENDLY_ONLY
Will only return users in friendly mode.
2
SONORK_SEARCH_USER_OFFLINE
Will return users that are offline.
4
SONORK_SEARCH_USER_ONLINE
Will return users that are online.
8

SONORK_GLOBAL_TASK

Implemented global tasks. See SONORK_EVENT_CLIENT_GLOBAL_TASK_START, SONORK_EVENT_CLIENT_GLOBAL_TASK_END.

SONORK_GLOBAL_TASK_UNKNOWN
Engine is executing a global task unknown to current API implementation.
0
SONORK_GLOBAL_TASK_SET_SID
Engine is synchronizing its sid mode with the server.
See SrkSetSidMode .
1
SONORK_GLOBAL_TASK_REFRESH_USER_LIST
Engine is downloading user list. See SrkRefreshUserList .
2
SONORK_GLOBAL_TASK_REFRESH_CONFIG
Engine is downloading configuration. See SrkRefreshConfig.
3

SONORK_REFRESH_CONFIG_FLAGS

Refreshable configuration items. These flags are combined when starting a SrkRefreshConfig global task.

SONORK_REFRESH_CONFIG_MAPPINGS
Network mappings (required for P2P connections and file transfers)
1
SONORK_REFRESH_CONFIG_SERVICES
Obtain list of server services (required for file transfers)
2
SONORK_REFRESH_CONFIG_WAPPS
Retrieve web applications list.
4
SONORK_REFRESH_CONFIG_FIELDS
Retrieve server-side user field labels.
8
SONORK_REFRESH_SYS_MSGS
Retrieve system messages.
16

Data types

vbSonorkDw2

Generic 64-bit object id/flags. Sonork User Ids are of this type.

Type vbSonorkDw2
v1 as long
v2 as long
End Type

Values
v1: Server Id
v2: User Id

vbSonorkDw4

Generic 128-bit object id/flags.

Type vbSonorkDw4
v1 as vbSonorkDw2
v2 as vbSonorkDw2
End Type

Values
v1:
v2:

vbSonorkApiEvent

Common header for all events.

Type vbSonorkApiEvent
event as SONORK_EVENT
appTag as long
result as SONORK_RESULT
taskId as long
taskTag as long
objId as vbSonorkDw2
data(0 To 7) As long
End Type

Values

event: The id for the event being reported. See SONORK_EVENT.
appTag: The tag supplied to SrkCreateInstance
result: SONORK_RESULT of the event, if applicable.
taskId: Task or file session id. Not used for client events.
taskTag: Task or file session tag, provided by the host when creating the task or file session. Not used for client events
objId,data: The meaning depends on the event being reported. See Events and parameters.

VbSonorkError

Extended error information.

Type vbSonorkError
result as SONORK_RESULT
extCode as long
isLocal as long
str as string
End Type

Values

result: SONORK_RESULT of the event, if applicable.
ExtCode:
IsLocal:
Str:

vbSonorkLocus1

Object location/session (level 1). Used to locate an online user or service. The sid member for users is obtained when processing the SONORK_EVENT_CLIENT_USER_SID event.

Type vbSonorkLocus1
userId as vbSonorkDw2
sid as vbSonorkDw2
End Type

Values

userId:
sid:

vbSonorkUserAddr

User or service address.

Type vbSonorkUserAddr
sid as vbSonorkDw2
sidFlags as vbSonorkDw4
sidVersion as vbSonorkDw4
reserved1 as long
utsAddr as string
hostAddr as string
End Type

Value

sid:
sidFlags:
sidVersion:
reserved1:
utsAddr:
hostAddr:

VbSonorkUserData

Basic user information

Type vbSonorkUserAddr
userId as vbSonorkDw2
alias as string
name as string
email as string
bornTime as string
pubAuthPin as long
pubAuthFlags as vbSonorkDw2
region as vbSonorkDw2
infoFlags as vbSonorkDw2
region as vbSonorkDw2
userAddr as vbSonorkUserAddr
End Type

Value

userId:
alias:
name:
email:
bornTime:
pubAuthPin:
region:
infoFlags:
region:
userAddr:

vbSonorkUserAuth

User authorization

Type vbSonorkUserAuth
tag as long
flags as vbSonorkDw2
pin as long
End Type

Value
tag:
flags:
pin:

vbSonorkUserAuthReq

User authorization request

Type vbSonorkUserAuthReq
requestingUserId as vbSonorkDw2
userAuth as vbSonorkUserAuth
userData as VbSonorkUserData
notes as string
issuedTime as string
End Type

Value
requestingUserId:
userAuth:
userData:
notes:
issuedTime:

vbSonorkUserSid

User/Service session information

Type vbSonorkUserAuthReq
userAddr as vbSonorkUserAddr
serial as vbSonorkDw2
reserved as long
sidText as string
End Type

Value

userAddr:
serial:
reserved:
sidText:

vbSonorkText

Full text of an instant message or event.

Type vbSonorkText
flags as long
region as vbSonorkDw2
str as string
End Type

Value

Flags:
Region:
str

vbSonorkServiceId

Sub service of the messenger. Sub-services are external applications or modules that exchange message. If serviceId is zero, the service id is the host application. An application may use these values to specify to which window/application the message or event should be delivered.

Type vbSonorkServiceId
serviceId as long
serviceInstance as long
End Type

Value

serviceId:
serviceInstance:

vbSonorkServiceInfo

Info. about a service provided by host. See remarks under vbSonorkServiceId.

Type vbSonorkServiceInfo
serviceId as long
serviceType as long
serviceFlags as long
End Type

Value

serviceId:
serviceType:
serviceFlags:

vbSonorkMsgHeader

Header of an instant message.

Type vbSonorkMsgHeader
sourceUserId as vbSonorkDw2
sourceService as vbSonorkServiceId
targetUserId as vbSonorkDw2
targetService as vbSonorkServiceId
usrFlags as long
sysFlags as long
trackingNo as vbSonorkDw2
dataServiceInfo as vbSonorkServiceInfo
sentDate as string
End Type

Value

sourceUserId:
sourceService:
targetUserId:
targetService:
usrFlags:
sysFlags:
trackingNo:
dataServiceInfo:
sentDate:

vbSonorkMsg

An instant message (without extended/attached data)

Type vbSonorkMsg
header as VbSonorkMsgHeader
text as VbSonorkText
End Type

Value

Header:
Text: