In part one I showed you how to open a Library. But just the Library is not enough as we also need to open the Interface of the Library.
The statement “IIntuition = (struct IntuitionIFace *) IExec->GetInterface (IntuitionBase, “main”, 1, NULL);” will open the Interface of the Intuition Library. IExec->GetInterface will open the Interface of the Intuition Library. The (struct IntuitionIFace *) will make sure the value returned will be of the type struct IntuitionIFace. This is called a cast and if you have opened libraries on the classic Amiga you have encountered this before and are familiar with it. It might be somewhat technical to understand at first. With a cast we are forcing the system to make sure the returned value is of a value we need. See it as asking for Euros and to make sure you get Euros and not Dollars you clearly tell the person at the other end of the booth that you need it to be in Euros. That, telling the person, is what you can call the cast.
The part (IntuitionBase, “main”, 1, NULL); is trying to get the Interface of the (IntuitionBase) Intuition Library. Looking at ….“main”, 1, NULL); we can see that we are trying to get the main interface and the version number is 1. The last parameter (NULL) is a pointer to a tag list which we won’t discuss here. Just like with the Library we need to check if we managed to get the Interface. If we did IIntuition would not be zero (NULL) and we managed to get the Interface. If it is still zero (NULL) we failed to get the Interface. The “if (IIntuition != NULL)” statement will check this for us.
Of course we need to close everything we have opened.
The IExec->DropInterface will close the Interface if it is open. The “struct Interface *” part is indeed a cast telling that the value of IIntuition is of the type struct Interface. When we tried to get the Interface we checked if it succeeded or not. If it would have failed our code would drop to this part printing that we cannot get the Interface. The same goes for the Library part. If it is open close it and if our previous check to see if we managed to open the Library resulted in failure our code would drop to this part printing that we are unable to open the Library.
Getting to understand the opening and closing of Libraries and Interfaces can be a bit of a hurdle at first. Besides talking about it here I also have some other articles in The Bucket Programming Corner that discuss Libraries and Interfaces with an example as well. Don’t worry as sooner or later you will understand the concept of Libraries and Interfaces.
That leaves us with ReAction classes. It’s the same concept as with the Libraries. You open it, check if you managed or failed and when you are done close them
In this example we are trying to open the Window Class. When we open the Window Class we need to store the value somewhere. For this we have the statement “struct ClassLibrary *WindowBase = NULL;”. And yes we indeed set it to zero (NULL) like we did with the Library so we can check if we succeeded in opening the Window Class. Besides opening the Window Class we will also have to get it’s Class pointer. And this also need to be stored somewhere for which we have the statement “Class *WindowClass;”. We will discuss the concept class pointer at a later stage. For now all we need to know is that besides the Class we also need to get the Class pointer.
The above statement will open the Window Class Library and the Class pointer in one time. The part “52” is the minimum version we want. We check just like with the Libraries if we managed to open the Window Class. The “&WindowClass” part will get the Class pointer. I could not find any info on this but I assume that if we managed to open the Window Class we automatically will get the Class pointer and do not need to check this as well.
All that is left is to close the Window Class Library. With it we also take care of the Class pointer. Just like with the Library example our code with jump to here if we failed to open the Window Class Library and prints that we are unable to do this. That’s it for this short tutorial in Libraries and Interfaces and ReAction classes.
I was always a fan of opening and closing my libraries myself. You could have them automatically opened and closed and save you the time of writing the code for it. I did sometimes switch to use the auto open and close function so I could skip writing code for it. When you have to open and close a lot of libraries this certainly save you a lot of time. Not to mention the check part if you actually managed to open them. I was about to switch to this automatically opening if libraries when I came across some new info regarding ReAction. Since ReAction classes are implemented as system libraries we use the OpenLibrary function to open them. With the release of OS4.x a new Intuition function called OpenClass has been introduced which will open ReAction classes. If we make use of the auto open function we will also open ReAction classes. To avoid problems we better switch to opening and closing everything ourself. Besides following the proper way of opening our ReAction classes we also have full control on what is happening with our code.
Let’s talk a bit about opening Libraries and of course closing them. And not to forget opening and closing ReAction classes. In this example we are going to open the Intuition Library. If you programmed in C on the classic Amiga and also worked with libraries you will notice something new when it comes to OS4.x. Besides opening the Library we also need to open it’s Interface. The Interface can be seen as a front end for the Library. Let’s say we want to ask the Library to do a certain task. Instead of asking it directly we will ask it’s Interface to talk for us with the Library. The reason why this Interface was added would be to technical and complicated (at this moment) to discuss but one of the reason has to do with compatibility of classic software.
First up we need to declare two pointer structures for our Library and it’s Interface. When we open both of them we need to store the values we get back and for this we have the above two statements. It is very important we set the value to zero (NULL). If we don’t they might point to a random address in memory which might cause the whole system to crash.
Next up we need to open the Library and also the Interface. With the statement “IntuitionBase = IExec->OpenLibrary(“intuition.library”, 50L);” we are trying to open the Intuition Library. Important to know is that with the Amiga OS there is always one Library open from the moment the system is up and running and that is the Exec Library. You might have guessed it already that the “IExec->” function is part of the Interface of the Exec Library. As explained before the Interface of the Exec Library is talking to the Exec Library for us and in this case it is asking to open the Intuition Library for us. The “50L” part is the minimum version we want to open. The value that we get back when trying to open it will be stored in IntuitionBase. We will have to check if we managed to open it. For this we will check the value that is stored in IntuitionBase. Remember we set it to zero (NULL)? So if we check that the value is not zero (NULL) we managed to open it. If it still has the value zero (NULL) we failed to open it.
I will divide this article in two parts. In the next and last part I will discuss opening the Interface of a Library as well as closing it including the Library and also discuss ReAction classes.
The first thing that fascinated me when I tried programming for the Amiga were the libraries. The first language I used to open and close libraries and use it’s functions was Assembler. At that time it took me some time to understand how libraries worked. This was because of the available information I had. Even today when I look at some of that information I can see that the way it was explained was just too difficult. Would it have been done easier it would have been quicker for me to get to grips with it. The only source of information you had was the magazines and the odd programming book you might be able to purchase. Not like today when you have the internet which gives you access to unlimited resources.
But what are those libraries you keep talking about? The ROM Kernel Manual describes it as follow:
The Amiga has two kinds of libraries: run-time libraries and link libraries. Run-time libraries make up most of the Amiga’s operating system. There is another type of library known as a link library. Even though a link library is a collection of functions just like a run-time library, there are some major differences in the two types.
Run-time libraries
A run-time, or shared library is a group of functions managed by Exec that resides either in ROM or on disk (in the LIBS: directory). A run-time library must be opened before it can be used. The functions in a run-time library are accessed dynamically at run-time and can be used by many programs at once even though only one copy of the library is in memory. A disk based run-time library is loaded into memory only if requested by a program and can be automatically flushed from memory when no longer needed.
Link libraries
A link library is a group of functions on disk that are managed by the compiler at link time. Link libraries do not have to be opened before they are used, instead you must link your code with the library when you compile a program. The functions in a link library are actually copied into every program that uses them.
To sum it up in a simple way: Run-time libraries stored on the hard drive and are opened and closed by the program whenever needed. Link libraries are (actually it’s functions) copied into your program when you are compiling it.
I am discussing the run-time libraries here. I assume you have some understanding of the basics of C programming. If something is not clear (and in future articles) just let me know and I will explain it. Don”t worry if at first it, or something, makes no sense. Sooner or later the penny will drop and it suddenly makes sense.
So what are we going to do for a first example? We are going to open the Intuition library and check if it is opened successfully or not and in both cases display a message.
01 #include <stdio.h>
02 #include <intuition/intuition.h>
03
04 #include <proto/intuition.h>
05 #include <proto/exec.h>
06
07 struct Library *IntuitionBase = NULL;
08
09 struct IntuitionIFace *IIntuition = NULL;
10
11 int main (void)
12
13 {
14
15 /* Opening the Intuition Library */
16 IntuitionBase = IExec->OpenLibrary(“intuition.library”, 50L);
17
18 /* Did we manage to open the Intuition Library? */
19 if (IntuitionBase != NULL)
20 {
21
22 printf (“We opened the Intuition Library!!\n”);
23
24 /* Open the Intuition Interface */
25 IIntuition = (struct IntuitionIFace *) IExec->GetInterface (IntuitionBase, “main”, 1, NULL);
26
27 /* Did we get the Intuition Interface? */
28 if (IIntuition != NULL)
29 {
30
31 printf (“We did get the Intuition Interface!!\n”);
32
33 /* If the Intuition Library Interface is open, close it */
34 IExec->DropInterface((struct Interface *)IIntuition);
35 }
36
37 /* We could not open the Intuition Library Interface */
38 else
39 {
40
41 printf (“Unable to open the Intuition Library Interface!\n”);
42 }
43
44 /* If the Intuition Library is open, close it */
45 IExec->CloseLibrary(IntuitionBase);
46 }
47
48 /* We could not open the Intuition Library */
49 else
50 {
51
52 printf (“Unable to open the Intuition Library!\n”);
53 }
54
55 return 0;
56 }
Type the above code (without the line numbers) in the text editor of your choice or IDE you might use. As you can see in the below screenshot I saved it in the “RAM Disk” with the name “openlibraryos4.c”. Assuming you have installed the OS4 SDK you can compile the code by typing “gcc openlibraryos4.c” in the AmigaShell as shown in the below sceenshot. This will produce the executable with the name “a.out”. If things go as planned you will get the correct out put saying that both the Intuition library and interface could be opened when executing “a.out”.
Compiling our code
Congratulations! You just compiled your first working OS4 code. Cool! But of course you like to know what all the code is about. Time to have a look at the source code.
The first 4 lines of code are includes.
01 #include <stdio.h>
02 #include <intuition/intuition.h>
04 #include <proto/intuition.h>
05 #include <proto/exec.h>
“#include” is a preprocessor directive which sounds rather difficult but it is not. It inserts another file into our code. Take for example the <stdio.h> file which includes information regarding the printf statement we are using. The intuition includes for example contain information if you want to display a window. For a simple example as this we don’t need so much includes to get our work done but if you create a larger program you will have more includes to (pardon the pun) include. I usually have a standard set of includes I use even if not all of them are being used. You might get errors during compiling because your code uses a function for which you did not use a include. This might sound rather complicated but after some trial and error from your side it will suddenly make sense.
Before we go to our next two lines a bit of further explanation about libraries is needed. I won’t get to technical but address just enough for you to understand the concept. With the classic Amiga OS you just opened the library you wanted and that was it. With OS4 we also need to use something called a “interface”. With the classic way you open the library and you can use any function from that library. With OS4 we have the interface which sits between the library and the functions it has. Let’s say we want to use a function from the intuition library we use the interface to call/use that function. You can compare it with talking to your wife. The old way would be to directly ask her a question. With the new way we use another person to ask our wife that question. This seems like a great idea (the wife example) but is this not adding extra work (and not to forget make it more difficult) when writing our code? Not really. It is just adding the name of the interface in front of the function. But what about the extra code for getting the interface and check we got it and also close it again? Well (getting ahead now) this is something I will address in part 2 in which you will see we can skip all that opening, checking and closing. Curious? Good!
But why use that interface stuff? Well that has to do with compatibility with the classic software. There is a lot more to it but without scaring you too much we will leave it at this. Let’s have a look at the next two lines.
07 struct Library *IntuitionBase = NULL;
09 struct IntuitionIFace *IIntuition = NULL;
This is usually the part you loose it all. Includes I can follow but this? The two lines declare pointers to structures we need to open the intuition library and also the intuition interface. These structures are actually defined in the <intuition.h> file. When we open the intuition library and get the interface we need to store the value we get back from trying to open them. We can use those values to test if we succeeded in opening both library and interface. We need to set both pointers to zero (NULL) to make sure they don’t point to any random address in memory which might cause the whole system to crash. *IntuitionBase is going to hold the value we get back from trying to open the intuition library and *IIntuition is going to hold the value we get back from trying to open the Intuition interface.
The next line is the start of our program. All programs start with main. To get a better understanding of how C works (it can’t hurt to mention this again) I suggest you check out the Amiga C Programming Tutorial from Michael Ness.
11 int main (void)
The next line is going to (try) open the Intuition Library.
16 IntuitionBase = IExec->OpenLibrary(“intuition.library”, 50L);
Some of you might have spotted the “IExec” part in front of OpenLibrary. This is the interface of the Exec Library. Wait! Stop! Are we not suppose to open this first, including the Exec Library, like we are doing with the Intuition Library? We don’t have to. The Exec Library is always open when OS4 (also with the classic OS) is running. In this case we want to open version 50 or later of the Intuition Library.
Line 19 is going to check if we managed to open the Intuition Library. Since we set the IntuitionBase in the beginning of our program to NULL we know we succeeded if the value of IntuitionBase is not NULL.
19 if (IntuitionBase != NULL)
If we managed to open the Intuition Library our program is going to jump to line 22 and print on our screen that we succeeded in opening the library.
22 printf (“We opened the Intuition Library!!\n”);
If we failed to open the intuition Library the value would still be NULL. If this is the case our program is going to jump to lines 49 – 53.
49 else
50 {
51
52 printf (“Unable to open the Intuition Library!\n”);
53 }
Line 52 will print on our screen that we did not manage to open the intuition Library.
If we successfully opened the Intuition Library and also printed on the screen we did we need to get the interface of the Intuition Library.
25 IIntuition = (struct IntuitionIFace *) IExec->GetInterface (IntuitionBase, “main”, 1, NULL);
Line 25 is trying to get Intuition’s Interface. The value that is being returned after we are trying to get the interface will be stored in IIntuition. IExec->GetInterface is the function that will try and get the interface of the Intuition Library. Looking at the part (IntuitionBase, “main”, 1, NULL); we can see that we are trying to get the Interface of the (IntuitionBase) Intuition Library. Looking further at (IntuitionBase, “main”, 1, NULL); we can see that we are trying to get the main interface and the version number is 1. The last parameter (NULL) is a pointer to a tag list which we won’t discuss here.
What about the (struct IntuitionIFace *) part? Without getting to technical (and loose you all) I can tell you this is called a cast. It will make sure the value returned by IExec->GetInterface is of the type struct IntuitionIFace *.
After we tried to get the Interface we need to check if we are successful.
28 if (IIntuition != NULL)
Line 28 (just like line 19 when we checked if we managed to open the Intuition Library) will check if we got the Interface by checking if the value if IIntuition is not NULL.
If we did manage to get the Interface we will print this as we can see in line 31.
31 printf (“We did get the Intuition Interface!!\n”);
If we failed to get the Interface the program will jump to lines 38-42.
38 else
39 {
40
41 printf (“Unable to open the Intuition Library Interface!\n”);
42 }
Line 42 will print that we did not manage to get the Intuition Library Interface.
If we did manage to open the Intuition Library and get it’s Interface (and of course print it on our screen) we need to end our program which means we need to clean up. The golden rule is to close everything that you open. First part of the clean up starts at line 34.
34 IExec->DropInterface((struct Interface *)IIntuition);
First up we are going to drop the Interface of the Intuition Library. The function DropInterface speaks for itself.
Last part of the clean up starts at line 45. We need to close the Intuition Library.
45 IExec->CloseLibrary(IntuitionBase);
Our program ends at line 55.
55 return 0;
Return can be used to return error codes but we give it the value zero to keep everyone happy. Surely I don’t want to scare (if anyone is still left) what is left of our readers at the very end. That’s it! As I already mentioned earlier in part 2 I will show you how you can skip all that opening and checking of libraries and interfaces.
Happy programming!
Coder's Blog 