What's New in Director 8.5 > Using the Shockwave Multiuser Server and Xtra > Using groups > Working with group attributes |
![]() ![]() ![]() |
Working with group attributes
You may wish to keep track of the traits of a group or set of groups. For example, for groups of people working for two different companies that are collaborating, you might want to store the name of the leader of each group. If the groups are negotiating the price of a contract, you might store the current amount of each group's bid. In a gaming scenario, each team might choose a mascot, a theme song, or a starting location in a virtual world. Each of these can be stored as an attribute of a group as long as the group exists. Attributes can be set to any of the Lingo values that can be sent using sendNetMessage
. Group attributes persist as long as the group exists on the server. To store information that must persist indefinitely on the server, use databases instead; see Using databases for more information.
You use setAttribute
to add an attribute or update its value and getAttribute
to determine the current value of the attribute. These commands are specified in the #recipient
parameter of a sendNetMessage()
, and the attributes you wish to access are specified in the #content
parameter of the message.
The Lingo to define the current location and mascot of the group @RedTeam looks like this:
errCode = gMultiuserInstance.sendNetMessage("system.group.setAttribute", "anySubject", [#group: "@RedTeam", #attribute: [#currentLocation: "New York City", #mascot: "dalmatian", #lastUpdateTime: "1999/07/27 15:52:11.123456"]])
When you use setAttribute
the #content
parameter of your message contains a #group
property and an #attribute
property. The #group
property indicates which group you are setting attributes for. The #attribute
property indicates which attributes you are setting. The names of the attributes you set should always be symbols beginning with the #
character. In the example above, the #group
is @RedTeam and the #attribute
is a list of two attributes, #currentLocation
and #mascot
.
The #lastUpdateTime
property is optional and lets you determine whether some other user has updated the attributes of the group since you last checked them with getAttribute
. When you use getAttribute
the server responds with the values of the attributes you requested plus a #lastUpdateTime
property, which indicates the moment in time when the server read the values of those attributes for the group you requested. The #lastUpdateTime
property is a string containing the year, month, day, hour, minutes, seconds, and microseconds on the server. By sending this same string with your setAttribute
command, you allow the server to check whether the attributes for the group have been updated since you last checked them.
If the server determines that any attributes for the group have been updated by someone else since you checked them, it responds with an #errorCode
, indicating a concurrency error. If no one else has updated the attributes since you checked them, the server responds with a new #lastUpdateTime
for the group, indicating that you have just updated the attributes.
This statement gets the values of the attributes #currentLocation
and #mascot
for the group @RedTeam:
errCode = gMultiuserInstance.sendNetMessage("system.group.getAttribute", "anySubject", [#group: "@RedTeam", #attribute: [#currentLocation, #mascot]])
The server's response looks like this:
[#errorCode: 0, #recipients: ["Bob"], #senderID: "system.group.getAttribute", #subject: "anySubject", #content: ["@RedTeam": [#currentLocation: "New York City", #mascot: "dalmatian", #lastUpdateTime: "1999/07/27 15:53:32.123456"]]]
You can get attributes for more than one group at a time by including multiple group names in your request:
errCode = gMultiuserInstance.sendNetMessage("system.group.getAttribute", "anySubject", [#group: ["@RedTeam", "@BlueTeam"], #attribute: [#currentLocation, #mascot]])
When you make a request for multiple groups, it is possible that part of the request will succeed while part of it produces errors. In the example above, attributes are requested for the group @BlueTeam. If this group has not yet been created, the server response will include errors in both the #errorCode
property of the response and the attributes list for @BlueTeam. If a requested attribute has not been set, no error is generated and the attribute is simply omitted from the response.
The server's response looks something like this:
[#errorCode: -2147216173, #recipients: ["Bob"], #senderID: "system.group.getAttribute", #subject: "anySubject", #content: ["@RedTeam": [#currentLocation: "New York City", #mascot: "dalmatian", #lastUpdateTime: "1999/07/27 15:53:32.123456"], "@BlueTeam": [#errorCode: [-2147216194]]]]
The first of these error codes indicates that the #content
property of the message contains errors that you should check. The second error code indicates that the group @BlueTeam does not exist. (See getNetErrorString() for a list of error codes and their strings.)
If you want to determine exactly what attributes have been declared for a particular group, use getAttributeNames
. It returns a list of the attribute names for the group:
errCode = gMultiuserInstance.sendNetMessage ("system.group.getAttributeNames", "anySubject", [#group: "@RedTeam"])
To remove an attribute from the attribute list for a group, use deleteAttribute
. The following example deletes the #mascot
property from the group @RedTeam:
errCode = gMultiuserInstance.sendNetMessage("system.group.deleteAttribute", "anySubject", [#group: "@RedTeam", #attribute: #mascot])
Keep in mind that the attributes you define for groups will persist only while the group exists. If you want this kind of information to be stored indefinitely so that it can be recalled from one multiuser session to the next, use database commands.
![]() ![]() ![]() |