Plugin SDK Changes Read Me by Aaron Ballman ([EMAIL PROTECTED])
7/31/07 The Plugin SDK is a venerable part of the REALbasic product which is showing definite signs of age. We are beginning the process of modernizing the SDK; this document describes the refactoring we have done so far and gives a road map for future changes. The SDK has now been split into a deprecated part and a non-deprecated part. We've deprecated a number of older APIs which duplicate functionality available through the dynamic access system. The future is to work within the dynamic access API whenever possible, since it provides plugin authors access to the full power of the REALbasic framework without requiring us to maintain a complex set of plugin-specific APIs. For example, instead of using REALSetControlVisible to toggle the visibility of a control on a window, you would instead use REALSetPropValue: // Old way REALSetControlVisible( mControl, 1 ); // New way REALSetPropValue( (REALobject)mControl, "Visible", true ); // Old way someString = REALSocketReadAll( mSocket ); // New way REALstring (*fpReadAll)( REALobject, long ) = (REALstring (*)( REALobject, long ))REALLoadObjectMethod( (REALobject)mSocket, "ReadAll( encoding as TextEncoding = nil ) as String" ); if (fpReadAll) someString = fpReadAll( (REALobject)mSocket, 0 ); The non-deprecated set is the minimum API needed to maintain feature parity with previous versions of the SDK. However, some superfluous functionality has been deprecated, such as features specific to 68k and Classic Mac targets, and other functions have been replaced with more appropriate ones. Here's a list of some commonly-used APIs that have been deprecated, and their replacement functionality: Old Function New Function ------------ ------------ REALCString REALGetStringContents REALPString REALGetStringContents (convert to PSring manually) REALGetStringCFString REALGetStringContents (convert to CFStringRef manually) REALRegisterMethod REALRegisterModule (set the method's scope to global) REALRegisterClassExtension REALRegisterModule (set the method's declaration to use extends) REALGetArrayInt REALGetArrayValue REALGetArrayString REALGetArrayValue REALGetArrayObject REALGetArrayValue (Note that REALGetArrayStructure is not deprecated) REALMemoryBlockGetPtr REALLoadObjectMethod (using Operator_Convert() as Ptr) REALPtrToMemoryBlock REALLoadObjectMethod( using Operator_Convert( p as Ptr )) REALRegisterStructure REALRegisterModule (set the structure field to global) REALRegisterEnum REALRegisterModule (set the enum field to global) REALnewInstance( const char *) REALnewInstance( REALClassRef ) The rest of the deprecated functions should be straight-forward to replace with the dynamic access APIs. The deprecated string functions (REALCString, et al) may raise some concerns, so I'd like to discuss that now. The functionality that those APIs exposed was nothing more than a way for you to get at the contents of a string's internal buffer of data in a constant fashion. With the advent of more string types, it becomes a problem that the SDK is constantly playing catch-up, and the old APIs expose some incorrect assumptions. However, now you are given an API which always gets you the internal backing buffer of the string by using REALGetStringContents without any assumptions. It is up to the programmer to interpret that data as appropriate (as it has always been), and convert it to another format as needed. So if you require that string's buffer to be in a particular format, you can use REALGetStringContents in conjunction with calls to REALGetStringEncoding or a dynamically-loaded call ConvertEncoding to manipulate the string as needed. However, it should also be noted that there is an easier way. If your function always requires the REALbasic string to be in UTF-16 format, then simply declare your API as requiring a WString. In that case, your plugin code can expect a const wchar_t * for that parameter. This negates the need to use REALGetStringContents entirely, and you don't have to worry about encoding manipulation functions at all. If you are using the string version REALnewInstance to create REALbasic objects, you should modify your code to instead create one from a REALClassRef. The best practice is to pre-load the class reference in the PluginEntry (which tells the REALbasic compiler about plugin class dependencies), and then refer to this cached REALClassRef when you wish to create the REALbasic object. Looking Back at the Past: Many plugin authors want their plugins to be supported on as many versions of REALbasic as possible, so you may wonder how these changes will affect new plugins used by older versions of the IDE. Unless you are using new functionality (such as access to arrays, etc), then your plugins should work with versions of the IDE as far back as 2005r1. The dynamic access APIs have been around since at least that version of REALbasic. However, many releases of REALbasic have improved the functionality provided by dynamic access, so it is possible that dynamic access functionality is not a constant behavior across all older versions of REALbasic. That's the reason for having a transitionary period for the deprecated functionality though. Roadmap for the Future: The current release of the SDK is an effort to clean-up the SDK while maintaining source code compatibility with previous versions. Existing plugins should continue to compile without modification. However, (assuming your compiler of choice supports it), you should be receiving warnings whenever you use a deprecated plugin SDK function. Future versions of the plugin SDK will break source code compatibility in two stages. First, existing plugins will have to include deprecated source code files manually in order to use the deprecated APIs. In the second stage, the deprecated APIs will be removed entirely from the SDK's header files, leaving only binary compatibility so that older plugins continue to work. _______________________________________________ Unsubscribe or switch delivery mode: <http://www.realsoftware.com/support/listmanager/> Search the archives: <http://support.realsoftware.com/listarchives/lists.html>
