The main communication method to the client will be using Dynamic Data Exchange or DDE. This is the same method that we use to interface with Netscape and Internet Explorer so it has proven track record and is very powerful. Developers will not need a library or header files to use this method. We can add functionality without breaking previously developed applications. Also, DDE is supported by multiple programming languages.

Register

Each developer application will need a name to identify itself to DDE. For example, Netscape uses "netscape" and Internet Explorer uses "iexplore". WorldsAway will use "WorldsApi" for developers API DDE calls.

When a developer application runs, it must register itself to the client by sending it a WorldsApi_Register DDE message with its DDE identifier name. WorldsAway will maintain a list of applications that have registered with it. This list will have a maximum of 25 entries and will not store duplicate names. The list will be purged when WorldsAway exits. Case is also not sensitive, so "Netscape" and "netscape" will be the same application.

The syntax of the register command is as follows:

Service:

WorldsApi

Topic:

WorldsApi_Register

Item:

WorldsApi_Register

Data String:

AppName

Where AppName is the DDE name of developer application - must be null terminated

Transaction Type:

XTYP_POKE

Sends:

(one of the following codes via a WorldsApi_Ack message)

• 0 - command sent successfully
• 8 - too many names already registered
• 9 - application name already registered

Description:

This call tells WorldsAway to start sending the application AppName all API messages. The maximum length of AppName is 50 characters. If AppName is greater than 50 characters, it will truncate the name at 50 characters. The maximum number of applications that can be registered at one time is 25. All register requests after that will be denied. Case is not sensitive for AppName. Thus, "Bingo" and "bingo" will be the same application. It is not critical that applications have unique names but it would avoid problems with users running two different applications with the same name at the same time.

Unregister

When a developer application exits, it must unregister itself from WorldsAway by sending it a WorldsApi_Unregister DDE message with its DDE identifier name.

The syntax of the unregister command is as follows:

Service:

WorldsApi

Topic:

WorldsApi_Unregister

Item:

WorldsApi_Unregister

Data String:

AppName

AppName is the DDE name of developer application - must be null terminated

Transaction Type:

XTYP_POKE

Sends:

one of the following codes via a WorldsApi_Ack message:

• 0 - command sent successfully
• 10 - application name was not registered

Description:

This call tells WorldsAway to stop sending API messages.

The maximum length of AppName is 50 characters. If AppName is greater than 50 characters, it will truncate the name at 50 characters.

Send

Once an application has registered, it can start sending and receiving data.

To send a data stream, it must use the WorldsApi_Send DDE command. This command allows sending data to one avatars, multiple avatars or all the avatars in the current region. To send to multiple avatars, the AvatarName argument must be a long string of names separated by the formfeed character (0x0C). To send to all the avatars in a region, leave the AvatarName argument blank.

The syntax of the send command is as follows:

Service:

WorldsApi

Topic:

WorldsApi_Send

Item:

WorldsApi_Send

Data String:

AppName<FF> AvatarName [<LF>AvatarName [<LF>AvatarName]...]<FF> DataLength<FF> Data

Where:

• <FF> represents a formfeed character (0x0C). Arguments must be separated by <FF> characters
• <LF> represents a linefeed character (0x0A). Arguments that may be a list must separate list items by <FF> characters.
• AppName is the DDE name of developer application
• AvatarName is the name or names of avatars to send to. If AvatarName is blank, then send to all the avatars in the same region as the sender. If more than one name is specified, names must be separated by a linefeed character <LF> (0x0A).
• DataLength is the length of data stream
• Data is the data to send - may contain null's or any other special characters

Transaction Type:

XTYP_POKE

Sends:

one of the following codes via a WorldsApi_Ack message:

• 0 - command sent successfully
• 1 - target avatar is not logged on *
• 2 - your avatar not allowed to send/receive API messages
• 3 - target avatar is not allowed to send/receive API messages *
• 4 - you are in a region that does not allow API messages
• 5 - target avatar is in a region that doesn't allow API messages *
• 6 - your avatar is currently busy
• 7 - target avatar is currently busy *
• 10 - application name was not registered
• 14 - one or more arguments are missing
• 15 - data length <= 0
• 16 - no data was specified
• 17 - you have not logged in yet

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.

Secondary Actions:

Sends a WorldsApi_Receive DDE message to the target if successful.

Description:

This call sends a data stream to the specified avatar or avatars, or to everyone in the region is no avatar is specified.

The maximum length of AppName is 50 characters. If AppName is greater than 50 characters, it will truncate the name at 50 characters.

The maximum length of AvatarName is 255 characters. If AvatarName is greater than 255 characters, it will truncate the name(s) at 255 characters.

If more than one avatar name is specified in AvatarName, each name must be separated by the linefeed character which is 10 in decimal and 0x0A in hex. There must be no blanks before or after the linefeed characters unless they are part of the avatar name.

The maximum amount of data that can be sent is decimal 4000 bytes. If DataLength is greater than 4000, it will truncate the data at 4000 bytes.

The arguments in the argument string must be separated by formfeed characters which is 12 in decimal and 0x0c in hex. There must be no blanks before or after the formfeed characters unless they are part of the argument.

Note that if AvatarName contains multiple avatars, result codes 1, 3, 5 and 7 will not be returned even if all the avatars meet the description of the error. Thus the command will always return 0 for multiple avatars unless errors 2, 4, 6, 10, 14, 15, 16 or 17 occur. To get codes 1, 3, 5 and 7, a developer application should send separate commands to each avatar.

ACK (acknowledge)

When an application makes any WorldsApi command except for the WorldsApi_GetAllText command, an acknowledge command is sent back to the application via a WorldsApi_Ack message. This message contains the status of the command.

The syntax of the acknowledge message is as follows:

Service:

WorldsApi

Topic:

WorldsApi_Ack

Item:

WorldsApi_Ack

Data String:

• Result

Where:

Result is one of the following result codes

• 0 - command sent successfully
• 1 - target avatar is not logged on
• 2 - your avatar not allowed to send/receive API messages
• 3 - target avatar is not allowed to send/receive API messages
• 4 - you are in a region that does not allow API messages
• 5 - target avatar is in a region that doesn't allow API messages
• 6 - your avatar is currently busy
• 7 - target avatar is currently busy
• 8 - too many names already registered
• 9 - application name already registered
• 10 - application name was not registered
• 11 - no text was specified
• 12 - mode was ESP but no avatar name was specified
• 13 - mode was speak or think but your avatar is a ghost
• 14 - one or more arguments are missing
• 15 - data length <= 0
• 16 - no data was specified
• 17 - you have not logged in yet

Transaction Type:

XTYP_POKE

Description:

This message is sent from WorldsAway to the developer application when it receives any WorldsApi command except for the WorldsApi_GetAllText command. A developer application should wait for this message after it sends a WorldsApi command to make sure it was sent successfully but it is not mandatory.

In order for an developer application to receive an ACK message, it must send the AppName parameter correctly for all commands. Otherwise, WorldsAway will not know which application to send the result codes to.

Receive

When a message is sent using the WorldsApi_Send command, the avatar that the message was directed to receives a WorldsApi_Receive. The message is sent to the developer application specified by the sender's AppName only if the developer application has registered with the receiving client.

The syntax of the receive message is as follows:

Service:

WorldsApi

Topic:

WorldsApi_Receive

Item:

WorldsApi_Receive

Data String:

AvatarName<FF> DataLength<FF> Data

Where:

• <FF> represents a formfeed character (0x0C). Arguments must be separated by <FF> characters
• AvatarName is the name of avatar that sent the data
• DataLength is the length of data stream
• Data is the data sent

Transaction Type:

XTYP_POKE

Description:

This is the message that WorldsAway sends when it receives a message from a WorldsApi_Send message.

Developer applications must be set up to listen for this message and process it when it arrives.

The maximum length of AvatarName is 31 characters.

The maximum length DataLength is 4000 bytes.

Communicate

The WorldsApi_Communicate command allows an application to send a speech, thought or ESP message. It has the exact same effect as an avatar in speech, thought or ESP mode typing in a string and pressing enter.

The syntax of the communicate command is as follows:

Service:

WorldsApi

Topic:

WorldsApi_Communicate

Item:

WorldsApi_Communicate

Data String:

AppName<FF> Mode<FF> AvatarName<FF> Text

Where:

• <FF> represents a formfeed character (0x0C). Arguments must be separated by <FF> characters AppName - DDE name of developer application Mode is the communication type for the message. Must be one of:
  • 0 - speak (default)
  • 1 - think
  • 2 - ESP
• AvatarName is the name of avatar to send data to if type is ESP; else it is ignored - only one name allowed
• Text is the text to send.

Transaction Type:

XTYP_POKE

Sends:

one of the following codes via a WorldsApi_Ack message:

• 0 - command sent successfully
• 6 - your avatar is currently busy
• 10 - application name was not registered
• 11 - no text was specified
• 12 - mode was ESP but no avatar name was specified
• 13 - mode was speak or think but your avatar is a ghost
• 14 - one or more arguments are missing
• 17 - you have not logged in yet

Description:

The arguments in the argument string must be separated by formfeed characters which is 12 in decimal and 0x0c in hex. There must be no blanks before or after the formfeed characters unless they are part of the argument.

GetAllText

The WorldsApi_GetAllText command allows an application to retrieve the entire contents of the speech window. Only the text that is currently visible in the window and text visible via the scrollbar will be retrievable.

Note that this is the only command that uses the XTYP_REQUEST transaction type which also means that the AppName must be sent as an item string. If the command fails, it will return an empty string.

The syntax of the get all text command is as follows:

Service:

WorldsApi

Topic:

WorldsApi_GetAllText

Item:

AppName

AppName is the DDE name of developer application - must be null terminated

Transaction Type:

Returns:

Text from speech window (via a HDDEDATA structure).

Sends:

one of the following codes via a WorldsApi_Ack message:

• 0 - command sent successfully
• 10 - application name was not registered.
• 17 - you have not logged in yet

Description:

This call retrieves the entire contents of the speech window. The return text will be null terminated so a string length function such as strlen can be used to retrieve the length.

© 1997 Fujitsu Systems Business of America,Inc.