Aw string

From ActiveWiki
Jump to: navigation, search


Minimum requirements
Added in version 2.1
SDKbuild 13


char* aw_string (AW_ATTRIBUTE a)

Description

Returns the value of a string attribute.

Callback

None (returns immediately)

Notes

Important: The returned pointer is only valid immediately after the call to this method and may be invalidated by subsequent calls into the SDK. Therefore an application must copy a string attribute to its own local buffer if it wishes to keep the string for an extended period of time.

Most of the string attributes have a maximum length defined by AW_MAX_ATTRIBUTE_LENGTH in Aw.h. This limit is currently 255 characters, or 256 bytes including the null character. There are a few attributes that can be longer than this (e.g. AW_BOTGRAM_TEXT). Their maximum lengths can vary up to 4095 characters (4096 bytes) depending on the attribute (e.g. AW_BOTGRAM_TEXT has a maximum length of 1000 characters).

See SDK Attributes for more information.

Arguments

a
Attribute (defined in Aw.h).

Argument attributes

None

Return values

NULL
The attribute is not a string, is outside the range of defined attributes (i.e. 0 to AW_MAX_ATTRIBUTE - 1), or there is no current instance (i.e. aw_instance () returns NULL).
Pointer to an empty string
Attribute has not been set.
Pointer to a string
Attribute has been set.

Usage

Keep track of the name of the most recent avatar to enter the scene.

char last_avatar_name[AW_MAX_ATTRIBUTE_LENGTH + 1];

void avatar_add (void)
{
  strcpy (last_avatar_name, aw_string (AW_AVATAR_NAME));
}

aw_event_set (AW_EVENT_AVATAR_ADD, avatar_add);

See also