AXUserBegin

Syntax

#include <cafe.h>
#include <cafe/ax.h>

s32 AXUserBegin(void);

Parameters

None.

Return Values

AXSYNC_ERROR_TOO_MANY_PROTECTS No more resources - try again later.
AXSYNC_ERROR_IN_CALLBACK Attempted to call AXUserBegin from within a callback.
>= 0 User-level protection state has been asserted.

Description

Assert a user-level protection state. This state can be detected by calling AXUserIsProtected. This state is useful for protecting global data that is accessed by application threads and the AX user callback.

For convenience, voice parameters that are modified using the AXSetVoice... from within a user-level protection clause will automatically be protected. Using the AXVoiceBegin and AXVoiceEnd delimiters are not necessary.

The protection state will apply until the corresponding call to AXUserEnd.

The "begin" and "end" clauses can be nested. The nesting limit is equal to AX_MAX_VOICES.

AXSYNC_ERROR_IN_CALLBACK

Making this call from a callback handler will return AXSYNC_ERROR_IN_CALLBACK but have no other effect. Nor will its matching AXUserEnd call have any effect.

It is possible to get a return value of AXSYNC_ERROR_IN_CALLBACK from calls not made during the callback handler. This is an indication of a programming error elsewhere in the application, such as:

Availability

Library Version Availability
Sound 2.0 Yes
Sound 1.0 Yes

Do Not Call From

None.

See Also

AX Programming Model Overview
AXUserEnd
AXUserIsProtected
AXVoiceIsProtected

Revision History

2013/05/08 Automated cleanup pass.
2011/03/02 Initial version.


CONFIDENTIAL