|
Communication with the Mac client will be provided using Apple events. Potential developers are then free to use scripting languages, such as Frontier or AppleScript, or traditional programming languages to develop their programs. For consistency, the Mac client is intended to support a set of events parallel to those defined in the Windows client section above.
- None of the following WorldsAway events will be recordable for version 2.1.
- All of the events will be documented in the WorldsAway Apple event dictionary.
- The message display area needs to be implemented in the Object model to allow developers to "get text of message display area".
- A header file will be provided in C defining the appropriate constants for developers using C or C++.
DeveloperAPI suite
Events in this suite are sent from an external application to the WorldsAway client.
Register
Event ID: 'Regi'
Arguments:
application signature
[direct parameter, '----', typeApplSignature]
Specifies application to be registered. If absent, sender application will be used. -
application name
[as, 'Name', typeChar]
Identifying name to use for communication. Case is not sensitive. Maximum length is 50 characters. If longer than 50 characters, a truncated version will be registered instead. If absent, the name of the registering application will be used.
Returns:
0 - registration was successful
DAPI-specific error conditions:
- 1 - "Unable to locate the specified application" (failed to locate an application with the specified application signature)
- 2 - "Unable to register an application without a name" (no name specified, empty name specified, or application has no name)
- 3 - "No more applications can be registered" (maximum of 25 external applications can be registered at once)
- 4 - "Application with this name is already registered." (cannot register the same name twice)
Description:
Registers the external application with the WorldsAway client. All API messages directed to the specified application name will now be forwarded to the application specified by the application signature. Forwarding will continue until the WorldsAway client quits or receives the Unregister event.
Examples:
register
register as "my cool game"
Unregister
Event ID: 'Unre'
Arguments:
-
application signature
[direct parameter, '----', typeApplSignature]
Specifies application to be unregistered. If absent, sender application will be used.
-
application name
[as, 'Name', typeChar]
Identifying name being used for communication. Case is not sensitive. Maximum length is 50 characters.
Returns:
0 - unregistration was successful.
10 - application was not registered
DAPI-specific error conditions:
"Unable to locate the specified application" (failed to locate an application with the specified application signature)
Description:
Unregisters the external application. See Register event for more information.
Example:
unregister
Send
Event ID: 'Send'
Arguments:
-
data
direct parameter, '----', typeWildCard
A stream of data to be sent to another avatar. Only the first 4000 bytes of data will be sent.
recipient
[to, 'Avat', typeAEList | typeChar]
Recipient avatar(s). If not specified, the data will be sent to all avatars in the current region. application name
[in, 'Name', typeChar]
Identifying name being used for communication. Case is not sensitive. Maximum length is 50 characters. If not specified, the name of the sending application will be used.
Returns:
result code
- 0 - command sent successfully
- 1 - target avatar not logged on*
- 2 - your avatar not allowed to send/receive API messages
- 3 - target avatar not allowed to send/receive API messages*
- 4 - you are in a region that does not allow API messages
- 5 - target avatar in a region that does not allow API messages*
- 6 - your avatar is currently busy
- 7 - target avatar is currently busy*
Note: Result codes marked by asterisk (*) are only returned if a single target avatar was specified in the Send request. If multiple avatars or the entire region are specified, result 0 will be returned, even if results codes 1, 3, 5 or 7 apply to any or all of the target avatars individually.
DAPI-specific error conditions:
"Must be connected to a world"
"Unable to send without an application name" (no name specified, empty name specified, or application has no name)
Description:
Send the specified data stream to the specified avatar. If the avatar has the application name registered, a Receive event will direct the data to the application on that avatar's system. The WorldsAway client then sends an Acknowledge event back to the originating application.
Example:
send "move 3g to 3h" to "Danijela" in "my cool game"
Communicate
Event ID:
'Comm'
Arguments:
-
data
direct parameter, '----', typeChar
Text to be communicated.
-
mode
[as, 'Ctyp', typeEnumerated]
- speech (default for avatars)
- thought
- ESP (default for ghosts)
avatar name
[to, 'Avat', typeChar]
Name of target avatar (required for ESP communications)
Returns:
none
DAPI-specific error conditions:
"Must be connected to a world"
"No target avatar specified for ESP"
Description:
Send the text to the WorldsAway server as a communication.
Examples:
communicate "Somebody join my cool game, please!" as speech
communicate "Hi, are you having a good day?" as ESP to "Danijela"
DeveloperAPI Receive Suite
Events in this suite are sent from the WorldsAway client to the external application. These events are not understood or handled by the WorldsAway client.
Receive
Event ID: 'SndR'
Arguments:
data
direct parameter, '----', typeWildCard
A stream of data sent from another avatar. Will not exceed 4000 bytes. recipient
from, 'Avat', typeChar
Name of sending avatar. Will not exceed 31 characters. application name
in, 'Name', typeChar
Name being used for communication. Will not exceed 50 characters.
Returns:
none
Description:
Registered applications will receive data from other avatars via this event.
|
