CF Types and AU
CF Types and AU
- Subject: CF Types and AU
- From: Bill Stewart <email@hidden>
- Date: Mon, 4 Aug 2003 19:02:02 -0700
Here's a list of the AU properties that interact with CF types... The
retain/release semantics are based around the usage/implementation
strategies in AUBase that have been shipping for some time now... It is
extremely difficult to change these semantics without causing possible
problems.
If there are other usage scenarios where the semantic implied in the
list below is untenable, then please let us know ASAP and we'll see if
we can alter this.
AU CFProperties based properties:
CFProperties:
kAudioUnitProperty_ClassInfo -> CFDictionary
Get
- Creates a new CFDictionary - should be released by client
Set
- after setting, should be released by client
kAudioUnitProperty_ParameterInfo -> CFString
Get
- should release the CFString that is created for the parameter name
-> depends on the release cfname flag
kAudioUnitProperty_ParameterValueStrings -> CFArray
Get
- New Array -> should release the returned array
kAudioUnitProperty_FactoryPresets -> CFArray
Get
- New Array -> should release the returned array
kAudioUnitProperty_CurrentPreset -> AUPreset
Contains a CFString
Get
- returns the AU's preset (doesn't retain string)
- should not release
- should retain/release if want to use preset name outside of AU
Set
- string is retained by AUBase
- client should release string after setting property
kAudioUnitProperty_ElementName -> CFString
Get
- returns AU's copy
- should not release
Set
- retained by AU
- client should release string after setting property
kAudioUnitProperty_CocoaUI -> AudioUnitCocoaViewInfo
typedef struct AudioUnitCocoaViewInfo {
CFURLRef mCocoaAUViewBundleLocation;
CFStringRef mCocoaAUViewClass[1];
} AudioUnitCocoaViewInfo;
Get
- don't release
kAudioUnitProperty_ParameterValueName -> AudioUnitParameterValueName
typedef struct AudioUnitParameterValueName {
AudioUnitParameterID inParamID;
Float32 *inValue;
CFStringRef *outName;
} AudioUnitParameterValueName;
Get
- should be released by caller
(So, if AU has static CFStrings for these, it should call CFRetain
on these names before returning them)
kMusicDeviceProperty_BankName -> CFString
Get
- should be released by caller
kAudioUnitOfflineProperty_PreflightName -> CFString
Get
- don't release
kAudioUnitProperty_ParameterIDName
kAudioUnitProperty_ParameterClumpName
These two properties use
typedef struct AudioUnitParameterNameInfo {
UInt32 inID;
SInt32 inDesiredLength;
CFStringRef *outName;
} AudioUnitParameterIDName;
Get
Client should release string after using it.
(So, if AU has static CFStrings for these, it should call CFRetain
on these names before returning them)
kMusicDeviceProperty_SoundBankData = 1008,
Set (not a CF Property)
- with a void* and size
- Caller maintains reference whilst data in use
Breaking these down into their respective Get/Set modes:
Set
Caller should CFRelease
kAudioUnitProperty_ClassInfo
kAudioUnitProperty_CurrentPreset
kAudioUnitProperty_ElementName
kMusicDeviceProperty_SoundBankData
This provides data for the music device (a sound bank loaded into
memory as a void*)
Caller responsible for maintaining data pointer whilst bank-data is
in use
Get
Caller should CFRelease
kAudioUnitProperty_ClassInfo
kAudioUnitProperty_ParameterValueStrings
kAudioUnitProperty_FactoryPresets
kAudioUnitProperty_ParameterValueName
kAudioUnitProperty_ParameterIDName
kAudioUnitProperty_ParameterClumpName
kMusicDeviceProperty_BankName
Caller *doesn't* CFRelease
kAudioUnitProperty_CurrentPreset
kAudioUnitProperty_ElementName
kAudioUnitProperty_CocoaUI
kAudioUnitOfflineProperty_PreflightName
Qualitified CFRelease
kAudioUnitProperty_ParameterInfo's CFName iff
kAudioUnitParameterFlag_CFNameRelease is set in ParameterInfo
In the cases where the caller does *NOT* release a CF object after
retrieving it, then the caller should retain/release the object if it
is using the object beyond the lifetime of the object in the AU.
For instance, the name of a current preset.
when this is set, the AU releases its existing name and retains the new
name that is set.
Thus, if a UI or other element were using this name, then that CFString
would become invalid when a new preset is set, so the caller should
have a retain count.
In these cases, the host is still in control of the CF semantics around
these objects (ie. the AU doesn't arbitrarily release a name of a
preset, but those names will be released whenever any action is done to
the AU)
A good semantic to apply is:
Get CF Property value
if (doesn't require releasing)
CFRetain (cfObject)
... when host is finished with CF object:
CFRelease (cfObject)
For instance, when retrieving the parameter information with the new
kAudioUnitParameterFlag_CFNameRelease, this flag can be used in the if
test above to determine if the host needs to retain the string for the
lifetime of its usage of it, so it's automatic release (when it is
finished with it) will be correct
Comments?
Bill
--
mailto:email@hidden
tel: +1 408 974 4056
________________________________________________________________________
__
"Much human ingenuity has gone into finding the ultimate Before.
The current state of knowledge can be summarized thus:
In the beginning, there was nothing, which exploded" - Terry Pratchett
________________________________________________________________________
__
_______________________________________________
coreaudio-api mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/coreaudio-api
Do not post admin requests to the list. They will be ignored.