The following contribution is from Shawn Tassie.

Thanks Shawn!

quote:

Sometimes it helps to have an abstract mental picture of how things work. I'll tell you my mental picture in terms of how KiXtart COM (KOM) works. I think of COM objects as sort of like smart DOS programs. For example, lets say you wanted to add a new user account to your local workstation. There are two ways to do it in kixtart:

1) Shell-out to the NET command
2) Use the ADSI COM object

Using the Shell method, we would code:

code:
--------------------------------------------------------------------------------

shell "%comspec% /c net user john.doe /add"

--------------------------------------------------------------------------------

and what happens here ? net.exe is loaded into memory and run. net.exe then queries the command line for the parameters passed to it then simply creates the account. Then it exits, the process is unloaded from memory and your kixtart script carrys on. Pretty basic stuff eh ? If you wanted to create another user, you would have to shell out again and create another running instance of net.exe and so it goes, again and again. And the only way to communicate with these programs (specify what we want done) is with commandline parameters on the input side. And to extract information on the output side, use temporary files and read them back into our script. You know the whole story

Well with COM, things are a little different. Instead of shelling-out and running the program every time you need it, you create an instance of the running program that is always "running" in the background, waiting at all times to recieve (service) our requests. And sending information in and out of the "program" is handled much, much more eloquently. Oh yeah, and instead of calling them programs, we call them OBJECTS.

With COM, instead of using the SHELL command, we use a kixtart function called CREATEOBJECT(). For example, if I wanted to create a running instance of Internet Explorer, I would code this:

code:
--------------------------------------------------------------------------------

$IE = CreateObject("InternetExplorer.Application")

--------------------------------------------------------------------------------

This one function does a whole lot. Here's the blow-by-blow play (start regedit and follow along):

1) COM first looks in the registry for a key in HKEY_CLASSES_ROOT called "InternetExplorer.Application" (try finding it yourself). If you crack open that key, there's a subkey called CLSID which is basically an unique identifer for this application. Every COM object has one and they are all differnet from one another. They have to be or else COM couldn't locate your object. The string "InternetExplorer.Application" is like a shortcut, or a friendly name for the object. Heres the CLSID I have for Internet Explorer:

{0002DF01-0000-0000-C000-000000000046}

2) If you copy the value of this CLSID into your clipboard, then go back up to the top and select HKEY_CLASSES_ROOT again, then scroll down until you find a key called "CLSID", then do a find on this identifier, it should take you to a very strange place in the registry where all the identifiers are kept. Crack it open and look for LocalSever32 - whats the value there ? Look familiar ? Here's what I have:

LocalServer32 = "F:\Program Files\Internet Explorer\iexplore.exe"

COM then starts Internet Explorer using this path, but it puts it into a mode (via simple commandline switches) where it is continually running in the background. If you create an InternetExplorer object, then look at taskmgr, you will see iexplore.exe running. So like using the SHELL command, CREATEOBJECT() just starts the program.

But then here's where the fun starts. iexplore.exe is running in the background, along side your kix script and it's just waiting for requests. How does one talk to the object ? Well if you remember, the CreateObject() function returns a variable, here it is again:

code:
--------------------------------------------------------------------------------

$IE = CreateObject("InternetExplorer.Application")

--------------------------------------------------------------------------------

What is $IE ? $IE is a pointer to your running instance of iexplore.exe that you just created. It's like a channel or a pipe to the process (proper term is an address of an interface). Sometimes for whatever reason, the object your trying to create doesn't get created. We used to be able to test for this by querying the value of the object pointer itself, like this:

code:
--------------------------------------------------------------------------------

$IE = CreateObject("InternetExplorer.Application")
If $IE = 0
?"Some error occurred"
Endif

--------------------------------------------------------------------------------

With the introduction of Kixtart 4.10, we now test for object creation like this:

code:
--------------------------------------------------------------------------------

$IE = CreateObject("InternetExplorer.Application")
If @ERROR <> 0
? "Some error occurred"
Endif

--------------------------------------------------------------------------------

CreateObject() will either return the address of the object, or return a 0 (zero) if it fails. Try creating an object that doesn't exist and see what i mean. So this object pointer or interface pointer, in simple terms, consists of the following two things:

1) Properties
2) Methods

Properties are "attributes" of the currently running object. The syntax is like this:

Setting a property:

code:
--------------------------------------------------------------------------------

$Object.Property = 1

--------------------------------------------------------------------------------

Querying a property:

code:
--------------------------------------------------------------------------------

$Variable = $Object.Property

--------------------------------------------------------------------------------

We can set these attributes and/or we can query them. For example, IE has a property called "Visible" that tells wether the browser window is actually visible to the user or not (by default, when you create an IE object, it is *not* visible). I tend to think of properties as simply variables maintained by the object, inside the object itself. And in order for us to get at them, we have to specifically ask the object to set or get them for us. So, to make IE visible we must "set the Visible property", in this case to TRUE (1)

code:
--------------------------------------------------------------------------------

$IE = CreateObject("InternetExplorer.Application")
$IE.Visible = 1

--------------------------------------------------------------------------------

So not only does IE set it's internal variable "Visible" to 1 (on our behalf), it actually went ahead and made itself visible. So now that its visible, we can query the value of this property (read it back in) to see if it really did set it.

code:
--------------------------------------------------------------------------------

If $IE.Visible = 1
? "Yup, it is visible..."
Endif

--------------------------------------------------------------------------------

or, since the value 1 is "true", we could just as easily code it this way:

code:
--------------------------------------------------------------------------------

If $IE.Visible
? "Yup, it is..."
Endif

--------------------------------------------------------------------------------

Methods calls are simply function calls that you can invoke within the running instance of IE. The syntax of invoking a method call is like this:

code:
--------------------------------------------------------------------------------

$Object.Method(Parm1,Parm2,...ParmN)

--------------------------------------------------------------------------------

So for example, continuing our IE script:

code:
--------------------------------------------------------------------------------

$IE = CreateObject("InternetExplorer.Application")
$IE.Navigate("http://www.kixtart.org")

--------------------------------------------------------------------------------

so we have just told IE to navigate to the best little KiXtart board on the Internet. There just like any other function call, but they are implemented inside the object. And since the IE object is always running in the background, we need a way to stop it. We do that in kixtart like this:

code:
--------------------------------------------------------------------------------

$IE.Quit() ; another method call - gracefully closes the browser: $IE = 0

--------------------------------------------------------------------------------

Just set the variable to 0 (zero). What that does is to stop the running instance of iexplore.exe and unload it from memory. So here's our little example script in it's full form:

code:
--------------------------------------------------------------------------------

Break On
$IE = CreateObject("InternetExplorer.Application")
$IE.Visible=1
$IE.Navigate("http://www.kixtart.org")
GetS $ ; just pause for now
$IE = 0

--------------------------------------------------------------------------------

Hope this helps.