Visual Basic API Reference Manual
| Sonork Instant Messaging Visual Basic API Reference Manual | |
PC operating SystemsDatabase architecture and conceptsNetworkingGraphical user interfaceChapter 1: OverviewChapter 2: Instance life-spanChapter 3: Event-processingChapter 4: API CallsChapter 5: Special Values/EnumsChapter 6: Data TypesSonork Release Notes: may contain important undocumented information about anything related to Sonork Server that may affect your installation.Fax: 1-212-228-9600 Attn: SLD PublicationsInternet electronic mail: readers_comment@sonork.comPostal Address: 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.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.When using the windows command line, replace $variable with
%variable% for environment variables and replace each forward slash (/) with a
backslash (\) in directory paths.
|
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
|
|
| Sub
MyCallback( ByVal handle As Long_ , ByRef SonorkEvent As vbSonorkApiEvent) |
|
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.objectHandle: And
instance handle, a file session or a server sessioninstance: 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.instance: The
instance handle.userId: User
account id.password: User
account password.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.objectHandle: And
instance handle, a file session or a server sessioninvokeHandlers:
Allows invocation of handlers while disconnectinginstance: The
instance handle.sidMode: New sid
mode.sidText: Session
notes (Explain status. e.g. "I'm in a meeting" or "Out for lunch")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.sidMode: Sid mode
to translate. The equivalent primary sid mode. If the parameter is
already a primary type, the function returns that same value.instance: The
instance handle.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.instance: The
instance handle.flags: A
combination of SONORK_REFRESH_CONFIG_FLAGS 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.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_FLAGSauthPin:
Authorization pin other user has granted (normally zero)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.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.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.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_FLAGSauthPin:
Authorization pin other user has granted (not supported by API, set to zero)taskTag: An
arbitrary value associated to the task. 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.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_FLAGSsex: 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.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.instance: The
instance handle.callSign: Exact
name of call sign. Cannot be zero-length. Case insensitive.searchFlags:
Combination of SONORK_SEARCH_USER_FLAGSmaxResults:
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.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.instance: The
instance handle.userId: The
remote user's id.userAuth: The
authorization recordauthNotes:
Arbitrary text attached to the request.taskTag: An
arbitrary value associated to the task.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.instance: The
instance handle.userId: The
remote user's id.userAuth: The
authorization recordtaskTag: An
arbitrary value associated to the task.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.instance: The
instance handle.userId: The
remote user's id.taskTag: An
arbitrary value associated to the task.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.objectHandle: And
instance handle, a file session or a server sessionerror: Buffer to
load with error information.objectHandle: And
instance handle, a file session or a server sessionerror: Buffer to
load with error information. 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.objectHandle: And
instance handle or a server sessionuserData: Buffer
to load with user's informationSONORK_RESULT_OK on success. SONORK_RESULT_INVALID_OPERATION indicates that the event
being processed is invalid. Other non-zero results.objectHandle: And
instance handle or a server sessiontext: Returned
string/notes.SONORK_RESULT_OK on success. SONORK_RESULT_INVALID_OPERATION indicates that the event
being processed is invalid. Other non-zero results.instance: The
instance handle.userSid: Buffer
to load with sid information.SONORK_RESULT_OK on success. SONORK_RESULT_INVALID_OPERATION indicates that the event
being processed is invalid. Other non-zero results.instance: The
instance handle.msg: Buffer to
load with instant message.SONORK_RESULT_OK on success. SONORK_RESULT_INVALID_OPERATION indicates that the event
being processed is invalid. Other non-zero results.instance: The instance handle.authReq: Buffer
to load with authorization request. SONORK_RESULT_OK on success. SONORK_RESULT_INVALID_OPERATION indicates that the event
being processed is invalid. Other non-zero results.
|
data(0): Current
network statusdata(1): Previous
network statusresult: Reason
(SONORK_RESULT) for change.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.objId: The user
id of the sender.objId: The remote
user's id.objId: The user's
id.objId: The user's
id.objId: The user's
id.objId: The user's
id.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_1objId: The user's
id.result: SONORK_RESULT for the task. Extended information may be
obtained with SrkGetEventError while still processing
the event.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.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_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_INTERNET |
0 |
| SONORK_LOGIN_MODE_INTRANET |
1 |
| 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_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 |
| 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_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_NA |
0 |
| SONORK_SEX_M |
1 |
| ONORK_SEX_F |
2 |
| 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_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_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_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 |
|
v1: Server Id v2: User Id v1: v2:event: The id for
the event being reported. See SONORK_EVENT.appTag: The tag
supplied to SrkCreateInstanceresult: 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 eventsobjId,data: The
meaning depends on the event being reported. See Events
and parameters.result: SONORK_RESULT of the event, if applicable. ExtCode: IsLocal: Str: userId: sid: sid: sidFlags: sidVersion: reserved1: utsAddr: hostAddr: userId: alias: name: email: bornTime: pubAuthPin: region: infoFlags: region: userAddr:tag:flags: pin: requestingUserId: userAuth: userData: notes: issuedTime: userAddr: serial: reserved: sidText: Flags: Region: str serviceId: serviceInstance: serviceId: serviceType: serviceFlags:
