Plugin SDK Misc Reference
From Real Software Documentation
Contents |
REALRaiseException
Raises an exception from the plugin. Note that plugins cannot catch REALbasic exceptions (even though they can create and raise them). This function call does not assume ownership of the exception (contrary to what previous documentation claimed), so you should release the reference to the exception once the call has been made. Immediately after you release the reference, you should return control back to REALbasic.
void REALRaiseException(REALobject exception);
- exception: the exception to raise. While this parameter specifies a generic REALobject, the object must always be a RuntimeException or one of its subclasses. Passing in an object which is not a RuntimeException will cause the application to crash. If this parameter is NULL, no exception will be raised.
Return Value none
if (someFailureCase) {
REALobject exp = REALnewInstance( "OutOfBoundsException" );
REALRaiseException( exp );
RuntimeUnlockObject( exp );
return;
}
REALYieldToRB
This function yields time back to the REALbasic runtime so that it can do periodic processing, such as cooperative thread context switching. You should call this function any time you do a long task in a plugin. However, it is not advisable to call this function too frequently in a loop as it can degrade the performance of your plugin.
void REALYieldToRB(void);
- parameters: none
Return Value none
for (int i = 0; i < 5000; i++) {
// Random processing
// Yield some time back
if (i % 100 == 0) REALYieldToRB();
}
REALstringToOSType
Converts the given string to an OSType integer value as appropriate for the target platform. Note that OSType values are always big endian, regardless of the platform's native architecture endianness. The string passed into this function should be four characters long with all of the data being in the system encoding.
unsigned long REALstringToOSType(REALstring id);
- id: the four char code to convert
Return Value the OSType from the original string
REALLockObject
This method retains a reference to a REALbasic object so that it will not be released by the framework's memory manager. You should lock an object any time your plugin holds a permanent reference to it. For instance, if you have a property setter which holds onto the object reference, then you should lock the object before exiting the method.
void REALLockObject(REALobject obj);
- obj: the object to lock
Return Value none
Beware of inadvertant memory leaks when "exchanging" locks on objects, like the following:
REALLockObject( obj );
mStoredObjRef = obj;
// Wrong (improper lock exchange order)
REALUnlockObject( mStoredObjRef );
REALLockObject( obj );
mStoredObjtRef = obj;
// Correct
REALLockObject( obj );
REALUnlockObject( mStoredObjtRef );
mStoredObjRef = obj;
REALUnlockObject
This method releases a reference to a REALbasic object so that it can be released by the framework's memory manager if it's appropriate. You should unlock an object any time your plugin no longer needs to hold a reference to it. For instance, if you have a property setter while holds onto the object reference, then you should unlock the old stored reference since you no longer require it.
void REALUnlockObject(REALobject obj);
- obj: the object to unlock
Return Value none
Beware of inadvertant memory leaks when "exchanging" locks on objects, like the following:
REALLockObject( obj );
mStoredObjRef = obj;
// Wrong (improper lock exchange order)
REALUnlockObject( mStoredObjRef );
REALLockObject( obj );
mStoredObjtRef = obj;
// Correct
REALLockObject( obj );
REALUnlockObject( mStoredObjtRef );
mStoredObjRef = obj;
REALGetClassData
This method returns the instance-specific information about a plugin class. When a class is registered with the Plugin SDK, you reserve extra space for it with the REALclassDefinition.dataSize field. This function retrieves a pointer to that extra space. You are allowed to modify the data in this space, but you should never release this pointer (the framework will release it for you manually). Note that you should not use this
void *REALGetClassData(REALobject instance, REALclassDefinition *defn);
- instance: the REALobject instance from which to retrieve the data. This parameter cannot be NULL.
- efn: the class definition which describes the object. This parameter cannot be NULL.
Return Value a pointer to the instance-specific data section
It is recommended that you use the ClassData macro instead of calling this function directly as a way to access individual elements of your reserved space. For instance, if your class definition reserves space for a MySpiffyClassData structure:
struct MySpiffyClassData {
long mValue;
REALstring mText;
};
// Properly retrieve the class data
ClassData( &MyClassDefinition, realObjInstance, MySpiffyClassData, me );
me->mValue = 100;
me->mText = REALBuildString( "Wahoo", 5 );
REALGetControlData
This method returns the instance-specific information about a plugin control. When a control is registered with the Plugin SDK, you reserve extra space for it with the REALcontrol.dataSize field. This function retrieves a pointer to that extra space. You are allowed to modify the data in this space, but you should never release this pointer (the framework will release it for you manually).
void *REALGetControlData(REALcontrolInstance instance, REALcontrol *defn);
- instance: the REALobject instance from which to retrieve the data. This parameter cannot be NULL.
- efn: the class definition which describes the object. This parameter cannot be NULL.
Return Value A pointer to the instance-specific data section
It is recommended that you use the ControlData macro instead of calling this function directly as a way to access individual elements of your reserved space. For instance, if your control definition reserves space for a MySpiffyClassData structure:
