ZINC™ v2.5 Extension SDK ©2006 Multidmedia Limited {mdm}
I
ZINC™ v2.5 Extension SDK
Table of Contents Foreword
0
Part I Introduction 1 Welcome
2
................................................................................................................................... 2
Part II Using DLL's
4
1 What are DLL's ................................................................................................................................... 4 2 Where to Find................................................................................................................................... DLL's 5
Part III Extension Architecture
7
1 Supported Features ................................................................................................................................... 7
Part IV The Extension Creator
10
1 Introduction ................................................................................................................................... 10 2 Making an Extension ................................................................................................................................... 10
Part V Step-by-Step Guide
13
1 Introduction ................................................................................................................................... 13 2 Creating an Extension ................................................................................................................................... 13 3 Installing an ................................................................................................................................... Extension 17 4 Using the Extension ................................................................................................................................... in a Project 17 5 Documenting................................................................................................................................... the Extension 18
Part VI Examples
22
1 C++ DLL Example ................................................................................................................................... 22 2 Delphi DLL Example ................................................................................................................................... 24 3 VB DLL Example ................................................................................................................................... 26
Part VII Appendix
28
1 Extension Architecture ................................................................................................................................... Features 28 2 Common Function ................................................................................................................................... Declaration Types 28 3 Advanced Uses ................................................................................................................................... 29 4 At-a-Glance Guide ................................................................................................................................... for Advanced Developers 30
Part VIII FAQs
33
Index
0
©2006 Multidmedia Limited {mdm}
Part
I
2
ZINC™ v2.5 Extension SDK
1
Introduction
1.1
Welcome Zinc™ has quickly become the standard in SWF2EXE applications and is now more frequently used to build and deploy Professional Desktop Applications. For this reason, and despite the fact that Zinc is already quite capable of accomplishing most tasks, we have added the Extensions Feature which makes the expandability of any Zinc™ Application virtually unlimited! The Extensions Feature works by extending the {mdm}Script 2.0 API with virtually unlimited new Commands/Methods and functionality! The functionality of these new commands is entirely up to the Extension Creator/Developer. A Zinc Extension is a single file which is composed internally of two main parts: 1) The DLL File (or reference to a standard DLL) 2) The DLL Interfacing Specification. By using this information, a Zinc Application knows how to access your DLL and generate the corresponding {mdm}Script 2.0 code interpreter. To make an extension you first need a standard Windows DLL. Next, using the Extension Creator, you compose the correct interface parameters and documentation. After exporting this extension, you can then install it to any Zinc™ 2.5 installation. When a Projector is compiled with the new Extension selected, the additional Extension Methods will then be available to that Projector. Zinc Extensions work this way: 1) Code in Actionscript calls an extension Method ( mdm.Extensions.ExtensionName.extensionMethod). 2) When the {mdm}script 2.0 method executes, the Zinc™ Application Wrapper detects this and relays the command to the Internal Extension Manager which is present in every Zinc™ Projector. 3) The Extension Manager in turn, relays the parameters and function to the actual DLL that does the work. 4) The DLL executes the Function. 5) Optionally, the DLL returns any resulting data back to the Projector via the Extension Manager.
©2006 Multidmedia Limited {mdm}
Part
II
4
ZINC™ v2.5 Extension SDK
2
Using DLL's
2.1
What are DLL's DLL (Dynamically Linked Libraries) are binary files which contain “chunks” of compiled executable code. Each of these chucks are just like the functions in Actionscript which can usually be called individually, or in conjunction with other functions. DLLs come in several different “flavors” depending on many aspects of their use. The main different categories are: Standard Window DLLs These are the original form of DLL files. They are the basic format of the Windows API and also most of the lower level applications that are used in Windows. These files are binary compiled code that have, among other things, a function table. This makes it possible for running code to connect and call any of the Functions that are in the Function table. They can have other things in there too, like resources which can store any additional data to be used. You can make these types of DLLs in nearly any language including: C, C++, VB, Delphi etc. ActiveX object DLLs These files are special DLLs that are to be used within the ActiveX/COM model. These DLLs need to first be registered on the system to be used. They are easier to use and overcome certain Development problems that arose from simply using Standard Windows DLLs. These files can have both the DLL, and the OCX extension when dealt with. An example of an ActiveX DLLs is the Macromedia Flash OCX File. .NET Assemblies DLLs With the advent of the .NET technology we now have a third major DLL type. These files, although they contain code with an even higher level code encapsulation method than the ActiveX method, can be cross platform or very expandable. However, it is very heavy and dependent on the .NET platform. Before we continue, we have to make clear that when we are talking about the ZINC extension SDK, the DLL files to be used at that first level of interfacing, will ALWAYS be the FIRST type, i.e.: Standard Windows DLLs. NOTE: ZINC extensions will NOT work with either ActiveX, COM nor .NET assembly DLL files. If however you still need to use these technologies in conjunction with the ZINC Extension Architecture, please see the: Appendix 4: Advanced Uses The creator of the DLL usually defines a “Map” of all the functions that reside in a DLL, in order for them to be used. Most DLLs that are intended for use by anybody other than the original Author, have some Documentation that provides, at the very least, a description of all the functions in the DLL, the return values to each function and also the arguments for each function. For an Example of this kind of documentation look at the Windows System API DLLs Documentation: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/winui/windowsuserinterface/windowing/windows/windowre ference/windowfunctions/setparent.asp This particular page contains the syntax for the setparent command which is a function located in the USER32.DLL. Clicking on the left you can see all the commands located in the windows API DLLs. Most public DLL makers have similar documentations to their DLLs. Important Note Some DLL developers, such as those that come with a proprietary application, might not have made these function definitions publicly available because their intention is to keep this information private for obvious copyright reasons. So before you decide to use/distribute any DLL files, it is important to make sure that it is legal for you to do so. “Dynamically Linked” means that the DLL is accessed and loaded AFTER the program has started running, so it makes very good sense to use these in ZINC projects because the user does not have to change the actual ZINC Projector code. Also Standard DLLs, unlike ActiveX Controls, do not need a system wide registration or Admin rights to be used so they are compatible with the standalone projector feature. So to summarize, DLLs can be thought of as a packaged collections of new functions and capabilities, available for anybody to use in their software, provided they have the specification of every function, and provided they are not violating the DLL creators Copyright and License.
©2006 Multidmedia Limited {mdm}
Using DLL's
2.2
5
Where to Find DLL's Apart from making your own DLLs (discussed later), you can also find a wide variety of readily available DLLs. Many of them are Commercial DLLs with professional support and documentation but there are also Freeware, Open Source and GPL project DLLs Available. On Windows Systems, DLLs are everywhere! DLLs are used by just about any Program written for Windows. Some DLLs that are very widely used are the DLLs that contain the Windows API. Among these are: USER32.DLL and KERNEL32.DLL. Many of the basic functions that Windows has, can be accomplished by just referencing and calling the functions included in these two DLLs. Events like moving, sizing, positioning, setting captions of windows, sending windows messages etc. are all part of the above DLLs. Windows DLLs, because they are included in the System, usually do not need to be redistributed. So when the time comes to select any of these system DLLs, remember that you do NOT need to pack them inside your Extension. Another source of DLLs is the Internet. There are numerous projects out there which provide solutions for various common tasks, such as media manipulations, audio, imaging, math functions, networking, hardware control, etc. there is truly a wealth of DLLs available waiting to be used with ZINC projects! Important Note Before using any of these projects, and especially before releasing any of your software that makes use of these DLLs, please make sure you are not breaching any Copyrights. Links to available DLLs online: Please note that you only use Standard DLLs, and not the ones called ActiveX controls or COM objects as these DLLs are used in a completely different manner, and are NOT usable with the ZINC extension feature. http://www.un4seen.com/bass.html BASS is an audio library for use in Windows software. Its purpose is to provide developers with the most powerful and efficient (yet easy to use), sample, stream (MP3, MP2, MP1, OGG, WAV, custom generated, WMA & CD via the add-ons), MOD music (XM, IT, S3M, MOD, MTM, UMX), MO3 music (MP3/OGG compressed MODs), and recording functions. All in a tiny DLL, under 100KB in size! http://www.imagemagick.org/ ImageMagickTM 6.0.0 is a robust collection of tools and libraries offered under a usage license to read, write, and manipulate an image in many image formats (over 89 major formats) including popular formats like TIFF, JPEG, PNG, PDF, PhotoCD, and GIF. With ImageMagick you can create images dynamically, making it suitable for Web applications. You can also resize, rotate, sharpen, color reduce, or add special effects to an image or image sequence and save your completed work in the same or differing image format. Image processing operations are available from the command line, or from the C, C++, Perl, Java, PHP, Python, or Ruby programming languages. A high-quality 2D renderer is included, which provides a subset of SVG capabilities. ImageMagick's focus is on performance, minimizing bugs, and providing stable APIs and ABIs. http://www.gzip.org/zlib/ The Zlib Compression Library http://www.dynamiclink.nl/frames/dllindex.htm Index of sites with thousands of DLL files for finding DLLs and DLL Creators. NOTE Not all DLLs are suitable for use in ZINC. This link if for research only. http://www.programmersheaven.com/ Type dll in the search box to find DLLs. Important Note With some DLLs (in particular those that need structured data as parameters, or use input parameters as return value holders, other wise known as “passing by reference”) in order to use their full potential of most DLLs you must call the functions with a helper DLL, however that said, we have successfully used many different ready dlls to accomplish a variety of tasks without ay changes.
©2006 Multidmedia Limited {mdm}
Part
III
Extension Architecture
3
Extension Architecture
3.1
Supported Features
7
ZINC Extension DLL Compatibility points: Ÿ The DLL interface in ZINC supports Standard Win32 DLLs Ÿ DLL Calling convention Method: Cdecl/stdcall/safecall Ÿ It does NOT support ActiveX, COM DLLs or .NET Framework DLLs. Ÿ Variable Arguments are NOT supported .This means that if you pass a pointer and expect to be able to read the updated value after the function has completed its task, this is NOT going to work. You have to either pass the data back to the Extension method via the result of the function, or save it to a file or other method of keeping the value. The reason for his is that flash variables are not stored in memory as standard windows data that can be accessed with a pointer but instead, they are part of the Flash Player Engine, and as such cannot be accessed by other programs directly. Ÿ Complex types such as object, structures etc. cannot be passed directly. You must use pointers. Ÿ Strings will be passed as pointers. Inside your DLL treat them as char* or wchar* and convert to the required type from those types inside your DLL code. Communication / Calling of functions: The Primary Communication method is the Call of the DLL function via a Custom method (as defined in the extension creator), when inside the projector, and by Calling the function when inside the Extension Creator. This means that if you need to set a value inside the DLL process, you must call a function of that DLL. It is Possible to set up custom (Secondary) ways of communication with the DLL, by using files or TCP/IP. These methods must be managed and created by the developer of the DLL. Argument/Parameter Passing: A function can have up to a maximum of 12 Parameters (arguments). A function can either have a result or not. Types supported for the passing arguments: Integer Form HWND Boolean String Unsigned char Unsigned char* Signed char Signed char* Unsigned short Unsigned short* Signed short Signed short* Unsigned long Unsigned long* Signed long Signed long* Float Float* Wchar*
an integer see note below a Boolean value a String value (technically the same as char*) a single byte value a pointer to a byte value (or first byte of a null terminated string) a signed single byte value pointer to the above type an unsigned two byte value pointer to the above type a signed two byte value pointer to the above type an unsigned Four byte value pointer to the above type a signed four byte value pointer to the above type a floating point number pointer to the above type a pointer to the first byte of data containing a wide string (used for passing values as
Unicode) Important Note The Form HWND is a Special Type: The given value in the Extension method will be ignored, and instead, the Handler Window of the Flash Movie will be passed to the function for further use by the author of the DLL. This feature is to be used for embedding your own controls and windows inside the flash movie. Values to be passed as Boolean should be passed as the value “1” for true and “0” for false when accessing them from ©2006 Multidmedia Limited {mdm}
8
ZINC™ v2.5 Extension SDK
ActionScript. Types supported for the result value (descriptions are the same as above): Integer Boolean String Unsigned char Unsigned char* Signed char Signed char* Unsigned short Unsigned short* Signed short Signed short* Unsigned long Unsigned long* Signed long Signed long* Float Float* Wchar*
©2006 Multidmedia Limited {mdm}
Part
IV
10
ZINC™ v2.5 Extension SDK
4
The Extension Creator
4.1
Introduction The Extension Creator is the tool included in Zinc 2.5 and is testing and debugging platform while you develop your extension. It allows you to define your DLL interface, number of methods, number of parameters and types for each methods (and also the return type if any). To launch the Extension Creator, inside Zinc v2 go to Tools > Extension Creator The extension creator comprises of four main parts (Separated by Tabs):
1) General Settings: This is the tab used in the first step of creating an extension. It is used to load the DLL to be used in the extension. When the DLL loads, you will be able to select the command prefix that you will be using. Also, here the user can select the general information that describes the extension. This information is also going to be used when installed in ZINC and also in the Help documentation created with Autodoc. 2) Extension Definition: Here you can define the parameters and return value used for each of the functions inside the DLL. It also provides information and description boxes which will be used to describe each Methods in the Autodoc feature. The sample values are the values that will be used when testing the extension. Make sure these values contain valid data. 3) Command Tester: This provides an environment for testing your extension. If it works here, it will work in an ZINC projector as well. There is also a Testing area here. This serves as a Testing window, and if you are using the HWND parameter anywhere in your commands, this parameter will contain the window Handle of that box. So if you are embedding anything this is where it will show. In the actual ZINC executable of course it will use the Flash Player Window Handle. 4) Autodoc: This tab provides a very efficient and quick way of producing documentation with your extensions. This feature relies on the user filling in ALL the information and description fields in the other tabs. The Autodoc feature will then be able to automatically provide full documentation in HTML form along with examples for each command. 5) Command List: There is also a separate tab in the left of the screen which is called Command List. This tab will contain all the functions that the DLL contains. You can edit, add and remove functions to this list.
4.2
Making an Extension 1) Selecting a DLL: Select your source DLL. After you browse for a DLL file, the extension creator will list all the functions that are contained in the DLL. Windows does not know what type of functions a DLL contains, so you will have to populate the parameters and result types for each command in the DLL you are planning to use. If you select a DLL that resided in the SYSTEM32 folder ©2006 Multidmedia Limited {mdm}
The Extension Creator
11
(or SYSTEM for windows 98), then the Extension creator will ask you if you actually want to pack the DLL in the extension or use the existing DLL that resides in each windows System. This can save you time, but also, makes sure that you don’t use the wrong version DLL on the wrong system (e.g. a Windows 98 user32.dll on a Windows XP System). You can use this feature also for any other third party DLL that you might plan to use, and resides in the System32 Folder. 2) Defining the functions Parameters: Populate at least 1 Function’s parameters and result type. 3) Loading the DLLs for testing: Once you have populated it, you can test that particular command, so to do this, you first load the DLL by clicking on the load button. 4) Test the function: Execute the populated Method by selecting it first, and then pressing the Execute Button. 5) Verify the result: If everything went correctly, you will see the result of the function that you just described. 6) Export the Extension: The final step is to Export the DLL to export an actual extension. To do this, go to the relevant menu item in the File menu. Close the extension Creator Window. You can now distribute this extension file to anybody, for them to use inside their projectors, as long as they have a properly installed version of ZINC v2. 7) Install the Extension: To install the extension you just made is your ZINC setup, Go to Tools > Install Extension. This will guide you through to the end of the installation of the extension in to your ZINC Application. 8) Include the Extension before building: To make the new Methods available inside your projectors just make sure that you have checked the relevant extension box in the extensions tab before compiling your application. You need to do this every time you build the application.
©2006 Multidmedia Limited {mdm}
Part
V
Step-by-Step Guide
5
Step-by-Step Guide
5.1
Introduction
13
This simple example shows how to use the extension creator shows how to create and use an extension. This designed for people who want to get used to the interface before they implement their personal projects. This guide will take you through a step by step demonstration and it is advised that you follow through each step on your own computer in order to get the full benefit. We are going to be making an extension that interfaces with a Microsoft Windows function that is called “beep”. This function is located inside a DLL file called KERNEL32.DLL. This DLL file is located in the System folder of all Windows Systems. On Windows NT, 2000 and XP it is located at: “C:\WINDOWS\SYSTEM32” On Windows 95 and 98 it is located at: “C:\WINDOWS\SYSTEM” This function is documented by Microsoft. We can find a version of this documentation here: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/debug/base/beep.asp Here we see the basic definition of this function (as copied and pasted from the MS site):
BOOL Beep( DWORD dwFreq, DWORD dwDuration ); So this function returns a variable of type BOOL and also takes two arguments of type DWORD and we can also see the description of these parameters. They are frequency and duration.
5.2
Creating an Extension 1) Open Zinc v2 and Open the Extension Creator. 2) Click on the DLL selection button and browse to the DLL file and select it. On Windows XP, 200 and NT browse to “C:\Windows\System32”, on older systems to “C:\Windows\System”. Find the file called “Kernel32.dll” and open it. 3)
4) When you select the DLL file, Extension Creator will show a dialog asking what the prefix of the Extension Object will be. The default name is the name of the DLL file so if you are happy with this leave it as it is, and click OK. In this case, if you select the default name which is kernel32.dll the command beep will be used as: kernel32.beep.
©2006 Multidmedia Limited {mdm}
14
ZINC™ v2.5 Extension SDK
5) When you select the file, because you opened it from the System Folder, Extension Creator will ask you if this DLL is present on all systems. If it is, then the extension will not include the DLL, but will only keep a reference to thee location of the DLL. Since this is a standard DLL, click Yes on the dialog.
6) After you click Yes on this dialog, Extension Creator will list all the functions that are in this DLL. In this case as this is a System DLL and contains a very large Chunk of the Actual Windows System it might take a few seconds. Please give it a few moments. 7) After it has stopped listing, we are ready to start Defining the new extension. First let’s fill in all the fields of the General Settings Tab. This information will be used later.
©2006 Multidmedia Limited {mdm}
Step-by-Step Guide
15
8) Now, let’s find the beep command. It should be listed on the left hand side tab. The functions are listed alphabetically so if you go to top of the list, you should fine the Beep command there. Click on it. 9) Click on the second tab, called: Extension Definition. This is the screen that edits the individual function parameters. When you click on an item on the command list on the left, this tab window on the right will show the settings (if any have been defined earlier) of that particulate command. At the moment since you have clicked already clicked on the Beep item it is showing the Page for that Command. If you have not already selected the beep item in the list on the left, please do this now. 10) Let’s start putting the parameters in now. We have two parameters and both are of type WORD. This type is really an integer value of between 0 and 65535 (a WORD is a two byte long number,). So we can safely select Integer for both of them as the integer is exactly that. So for the first two items in the list in the Extension definition tab select the type as integer.
11) Fill in the rest of the fields for these two values: The two sample values should be something meaningful so lets put in 100 for the frequency (Hz) and also 1000 for the time (milliseconds). Also fill in the description fields. Your Two rows should now look like this:
©2006 Multidmedia Limited {mdm}
16
ZINC™ v2.5 Extension SDK
12) Let’s define the return Value now. From Microsoft’s definition we know that it is of type BOOL which of course is a Boolean type. Also we know that the meaning of the return value is true for success and false for failing to make the sound. So let’s define this too. Also put something meaning full in the command description. If you have followed the instructions correctly the Extension definition tab contents should now look like this:
13) Lets save this project file somewhere on disk. To do this, go to the file menu and select “Save As…”. The extension project file is NOT the extension which we will be producing in a moment, but it is a project file that contains every setting we have set up to now, so you can add more definitions later if you wish, or change the descriptions or produce more help documentation. After you have saved it to a filename of your choice, we can continue with testing the extension. 14) Ok, now, let’s test and see if the extension will work. Let's go to the Command tester tab. Make sure that the Beep command is selected in the Command List. 15) Click on the Load Library button. This internally executes a standard Win32 API Loadlibrary command. This action loads the Library in memory ready for use. When you run this extension in a ZINC executable this happens automatically.
©2006 Multidmedia Limited {mdm}
Step-by-Step Guide
17
16) After you click on the Load Library button, you are ready to test your new method. You can verify that you are about to test the correct command by looking as the bottom of this screen. This window should contain the actionscript code that would be used if you were in flash to execute the command If everything has been done correctly it should show:
myresult=mdm.Extensions.kernel32.Beep("1000","1000"); As you can see, your custom Method is already taking shape. 17) Click the Execute Button. You should hear a beep of 1000Hz and it should last exactly for 1 second. Congratulations! You have tested and verified your first custom Method. You should also see the result value in the results box in this case “true”. If however it has failed and have not heard the sound and the return value is not “true” than please go back to the start of this guide and check to see if there is anything you have missed. 18) Now we have a verifiably working command. Let’s make that extension! Click on the File menu and select “Create Extension…” Save the extension somewhere on your disk. 19) Since you have saved this extension and also have saved the extension project file, we can close this window. You should find yourself back in the main ZINC window.
5.3
Installing an Extension 1) In the main ZINC screen go to the Extensions tab. 2) Click on “Install Extensions…” and browse to where you saved the extension from the Extension Creator. 3) You will presented with the Zinc Extension Manager Screen. As you can see the descriptive information that you have filled in the Extension Creator is used here. This is especially useful if you are making a commercial extension. 4) Click on Install. If you are dong this a second time replace the existing one, or go back and remove the existing one first.
5) Now the extension is installed. It can be included to any projects you compile from that setup. You only need to check the box.
5.4
Using the Extension in a Project 1) Open Macromedia® Flash. Make a new project and drop a button on you movie. 2) On the button put the following code:
©2006 Multidmedia Limited {mdm}
18
ZINC™ v2.5 Extension SDK
3) Export the movie. 4) In Zinc v2.5, make a new blank project and open this SWF file for the mainform. 5) Go to the extensions Tab and make sure the Extension SDK Demo Extension Item (that’s going to be the listed name if you Put the same descriptions as we have) and make sure it is checked. 6) Click on the build button and when the executable loads, press the button. If you hear the sound, Congratulations! You have successfully made an Zinc extension. Now you can go on to more advanced extensions. If however it failed, please check every single step in this guide to see if something has gone wrong.
5.5
Documenting the Extension 1) In Zinc 2.5, Go to the Extension Creator, and load your extension project file. To do this go to the File menu then “Open”. 2) When the extension project loads, go to the Autodoc tab. 3) Click on the “Preview” button. The help documentation is ready. You can see there is a General Extension Description here as well a list of Methods. 4) You can also export this documentation to any folder by clicking on the Export Button.
©2006 Multidmedia Limited {mdm}
Step-by-Step Guide
19
5) Find the Beep command and Click on it. In there you will see a page similar to the default ZINC help pages, describing this command with full example code. 6) You can export these html files to any location of the disk and include them with your extension release. Also you can edit them as they are basic html files.
©2006 Multidmedia Limited {mdm}
20
ZINC™ v2.5 Extension SDK
This brings us to the end of this step-by-step guide.
©2006 Multidmedia Limited {mdm}
Part
VI
22
ZINC™ v2.5 Extension SDK
6
Examples
6.1
C++ DLL Example The C++ template file is included with this SDK: c++_example.zip. To use this, unzip and compile. The C++ example exports one function called demo function. This function takes its single parameters which is a null terminated string pointer, and shows it using a standard dialog. It then returns a string value as the result of the function. Source code follows: Filename
stdafx.h
// stdafx.h : include file for standard system include files, // or project specific include files that are used frequently, but // are changed infrequently // #pragma once #define WIN32_LEAN_AND_MEAN headers // Windows Header Files: #include
// Exclude rarely-used stuff from Windows
// TODO: reference additional headers your program requires here extern "C" __declspec(dllexport) const char* demofunction(const char * inStr);
Filename
extensiontmp.cpp
©2006 Multidmedia Limited {mdm}
Examples
// // // // // //
23
This Source Code is part of the Extension SDK for Multidmedia Zinc version 2.0 29 October 2004 This is a basic template of a DLL that can communicate with flash via the Extension Archtechture of Zinc.
#include "stdafx.h" BOOL APIENTRY DllMain( HANDLE hModule, DWORD ul_reason_for_call, LPVOID lpReserved ) { switch (ul_reason_for_call) { case DLL_PROCESS_ATTACH: // uncomment this to see a messagebox when you load the library. // MessageBox(0,"Loading...","",0); case DLL_THREAD_ATTACH: case DLL_THREAD_DETACH: case DLL_PROCESS_DETACH: break; } return TRUE; } // implementing our function extern "C" __declspec(dllexport) const char* demofunction(const char * inStr){ MessageBox(0,(LPCTSTR)inStr,"",0);//show a box with the subitted string from flash return "You clicked OK!";//return some text. }
Notes on this example: 1) This is a basic example, you can add many enhancements to this but this is a good start and a working template 2) The function is define like this:
extern "C" __declspec(dllexport) const char*
demofunction(const char * inStr);
3) The function is implemented like this:
extern "C" __declspec(dllexport) const char*
demofunction(const char * inStr){
MessageBox(0,(LPCTSTR)inStr,"",0);//show a box with the subitted string from flash return "You clicked OK!";//return some text.} 4) To make an extension of this DLL, define one string parameter as input and one string return value.
©2006 Multidmedia Limited {mdm}
24
6.2
ZINC™ v2.5 Extension SDK
Delphi DLL Example The Delphi template file is included with this SDK: delphi_example.zip. To use this, unzip and compile. It should compile in most recent Win32 Delphi versions. The Delphi example exports one function called demofunction. This function takes its single parameters which is a null terminated string pointer, and shows it using a standard dialog. It then returns a string value as the result of the function. Source code follows:
©2006 Multidmedia Limited {mdm}
Examples
library extensiontmp; { Important note about DLL memory management: ShareMem must be the first unit in your library's USES clause AND your project's (select Project-View Source) USES clause if your DLL exports any procedures or functions that pass strings as parameters or function results. This applies to all strings passed to and from your DLL--even those that are nested in records and classes. ShareMem is the interface unit to the BORLNDMM.DLL shared memory manager, which must be deployed along with your DLL. To avoid using BORLNDMM.DLL, pass string information using PChar or ShortString parameters. } // // // // // //
This Source Code is part of the Extension SDK for Multidmedia Zinc version 2.0 29 October 2004 This is a basic template of a DLL that can communicate with flash via the Extension Archtechture of Zinc.
uses SysUtils,windows, Classes, dialogs; //include dialogs because we are using showmessage() {$R *.res} function demofunction(inStr:pchar):pchar; stdcall; begin showmessage(StrPas(inStr)); Result:='You clicked on OK!'; end; procedure DLLHandler(Reason: integer); begin case Reason of DLL_PROCESS_ATTACH: begin // uncomment this to see a messagebox when you load the library. // showmessage('Loading...'); end; DLL_PROCESS_DETACH: begin end; DLL_THREAD_ATTACH: begin end; DLL_THREAD_DETACH: begin end; end; end; exports demofunction; begin DLLProc := @DLLHandler; DLLHandler(DLL_PROCESS_ATTACH); end. Notes on this example: 1) Although a basic example, you can add many enhancements to this example making it a good start.
©2006 Multidmedia Limited {mdm}
25
26
ZINC™ v2.5 Extension SDK
2) To make an extension of this DLL, define one string parameter as input and one string return value.
6.3
VB DLL Example In Visual Basic .NET you can no longer create Binary DLL files.
©2006 Multidmedia Limited {mdm}
Part
VII
28
ZINC™ v2.5 Extension SDK
7
Appendix
7.1
Extension Architecture Features
7.2
DLL type
Supports Standard Win32 DLLs
Calling conventions
Cdecl , stdcall or safecall
Compiler compatibility
Any Compiler that can create standard Win32 DLLs
Number of Methods per extension
Unlimited
Number of parameters per extension
Up to 12
Accepted parameter types:
Integer,Boolean, unsigned char, unsigned char*,signed char,signed char*,unsigned short, unsigned short*,signed short,signed short*, unsigned long,unsigned long*, signed long, signed long*, float, float*,wchar*
Interface with Com,ActiveX
Yes, However not directly, you need to make interfacing Standard dll.
Return value
Yes any of the above types
Window Embedding
Yes you can embed any window ,control,graphics inside the Flash instance as the window handle of the flahs player can be provided.
Automatic Documentation
Yes
Safe testing
Yes
Distributable Extension File
Yes
Project Based Extension definition
Yes
Common Function Declaration Types Type as shown in Extension Creator
Types as must be declared in Programming Languages C++ (parameters could be casted in a different way)
Delphi
Integer
Int,HWND
Int,longint,WORD,Handle an integer
Boolean
Bool
String
Char*, LPSTR,LPCSTR
pchar
a String value (technically the same as char*)
unsigned char
unsigned char
One character:char,byte
a single byte value
unsigned char*
unsigned char*, LPSTR,LPCSTR
PChar
a pointer to a byte value (or first byte of a null terminated string)
signed char
signed char
ShortInt
a signed single byte value
signed char*
signed char*
^ShortInt
pointer to the above type
unsigned short
unsigned short
Word
an unsigned two byte value
unsigned short*
unsigned short*
^Word
pointer to the above type
signed short
signed short
SmallInt
a signed two byte value
a Boolean value
©2006 Multidmedia Limited {mdm}
Appendix
29
signed short*
signed short*
^SmallInt
pointer to the above type
unsigned long
unsigned long
Longword,int64
an unsigned Four byte value
unsigned long*
unsigned long*
^Longword,^int64
pointer to the above type
signed long
signed long
Integer
a signed four byte value
signed long*
signed long*
^Integer
pointer to the above type
float
float
Single
a floating point number
float*
float*
^Single
pointer to the above type
wchar*
wchar*
PWideChar
a pointer to the first byte of data containing a widestring (Used for passing values as Unicode)
NOTE: This table is only a guide and not complete.
7.3
Advanced Uses There are a few things that we have not mentioned yet but are possible with the ZINC Extension Feature. Here we list them and give a brief Description of how they work. 1) Embedding your own content inside a flash window You need to use the HWND value submitted from the Zinc wrapper to embed your own content in the Flash Player window. Make a function in whichever language you are writing in, and define one of the submitted parameters from the Extension Creator to Form HWND. This is a special Type Value that does not allow the user to submit any custom data (if you populate that data field it will be ignored) but instead it submits the current Window HANDLE to the receiving end function. As an example, follow the Simple example guide as mentioned in Chapter 3, but instead of loading kernel32.dll you loaded user32.dll. Then instead of looking for the Beep function look and find the functions called: SetWindowPos. With this function I can demonstrate how you have complete control of the Flash Window (remember however that as long you are in the Extension Creator the window to function as the container is the one designated as: “ Embedding Preview window”) The specification of the function is:
BOOL SetWindowPos( HWND hWnd, // handle of window HWND hWndInsertAfter, // placement-order handle int X, // horizontal position int Y, // vertical position int cx, // width int cy, // height UINT uFlags // window-positioning flags ); And as you can imagine all it does it move the window position and size according to the specified parameters. We are going to change the window size and position to 0, 0 and the size to 100x100 pixels. Set the Command parameters as follows:
©2006 Multidmedia Limited {mdm}
30
ZINC™ v2.5 Extension SDK
When you go to the Testing tab and execute this function you will see the Testing panel move and resize. So when you want to use the HWND feature with your projects, basically, just submit it together with any other function parameters and use the HWND value to manipulate the Flash player window. 2) ActiveX control loading If you want to load an ActiveX control and make an extension that provides functions to use the control follow these guidelines: Write a DLL that either: a) Mirrors all the functions of the ActiveX control and makes the parameters compatible with the Extension Requirements., and also provides instantiation commands. b) Simplifies the tasks that the extension is to be used for and provide the Flash Actionscripter with unified Methods that in the background execute a number of commands that, for example, instantiate, place, use and destroy the object to be used. This way you will make much more valuable controls because you will be offering simplicity of use to the extension user. If you are instantiating controls, make sure that the types and any objects that are to be accessed are available through your Extension Methods.
7.4
At-a-Glance Guide for Advanced Developers If you are an advanced developer who has built DLLs before and just want to know how to make a Zinc extension, this is the chapter for you: Information points about the ZINC Extension Feature: 1) Programming Languages: ©2006 Multidmedia Limited {mdm}
Appendix
31
You can use ANY language or compiler as long as it can compile Standard Win3 DLLs. Compilers include VC,VC++,VB, Delphi, GCC(not tested but possible),LCC-win32, freepascal, Codewarrior, Various Assemblers(!) etc. 2) What DLLs: You can ONLY use Standard Win32 DLLs. No ActiveX or .NET. 3) Calling Conventions: The calling convention should be one of: Cdecl , stdcall or safecall. Other calling conventions register values, reversed parameters or any other calling conventions not supported. 4) Strings: Strings cannot be passed directly. ALWAYS pass a pointer to null terminated strings: a) If you are using general strings (including binary data) use char*. b) If you want to pass wide strings or Unicode text use wchar*. 5) Structures, Types etc: Structures, Types, complex types/date are NOT supported directly. Devise your own methods of submitting them such as text files registry values, sockets, windows messages etc. Or simply take your Structure item apart and submit every single value as its own parameter and reconstruct the Structure or Type inside your DLL code. 6) ActiveX, COM, .NET and Non standard DLLs: If you HAVE to use or interface to an ActiveX control or .NET assembly, we advice that you use a little “glue” DLL which will to the relaying of commands to and from the COM control or Assembly. Make an Extension Quickstart: 1) Compile your DLL with your desired compiler. 2) Load it inside the Extension Creator. It will list all your functions. 3) For each function in the dll that you are planning to use, fill in the appropriate types and result type (if any), and sample values. 4) Go to the Command Tester tab, load the dll, and test the command. If everything works, the types are correct so you can go ahead and compile the extension. 5) Create the extension. 6) Now you can load it in any ZINC application and use the new commands that you have created.
©2006 Multidmedia Limited {mdm}
Part
VIII
FAQs
8
33
FAQs Q: I have loaded a DLL I know has many Functions but I only get 4 Functions listed. Their names are:
DllCanUnloadNow DllGetClassObject DllRegisterServer DllUnregisterServer Why can’t I use it with the Extension Creator? A: This DLL is not a Standard Win32 DLL. It is in fact an ActiveX/COM DLL. This DLL cannot be used directly. However you can still use it by either of the two following ways: a) Write a small interfacing standard win32 DLL that calls this object you want to use. b) Use the ActiveX command set that are built in each ZINC Projector. For more help Check the ZINC Help Documentation.
Q: I want to use ***put your dll name here*** and I cannot use it because the functions are very complicated and use Structures and types I cannot use as parameters in ZINC. What can I do? A: Write a small interfacing standard win32 DLL that makes all the calls you want to use and relays simpler functions back to Flash.
Q: I’m trying to communicate back to Flash when an event happens in my DLL. Simple results from the functions are no good for that. What can I do? A: You have a few options. Two of these are: a) Write a small text file to a specific location on the disk and in Flash check for any changes in this file. When a change happens you can assume that the event has triggered and make flash respond to this. b) Send a Socket Message To the flash instance you are trying to communicate with. If you are using the built in flash sockets, make sure you append a NULL char after your data in order to tell flash that your data sending has finished.
Q: I want to embed my own Windows inside the Projector just like you do with the browser and video methods. How can I do this with my extension? A: Check the Appendix: Advanced Uses.
©2006 Multidmedia Limited {mdm}
