Common API not understood?

Since some months there exists a very good description of API functions by homes32

I tried the single functions and have had a couple of disappointments. In my project the described functions were not in the API.

I looked into the reboot download section, to download the API.

But there is none!

A search through all projects in the reboot download section, did not bring me any API defining the functions in question, described in the "official help".

I suggest to clean up this task:

As known, sbaeder is currently smoothing a lot of items, including the "help".
He should revise and actualize the current API help description (@sbaeder: I hope not to have attacked you by this suggestion)
Then he uploads a certified version of the API, which is the base of all reboot forum's downloadable projects.

Of course, the help and the API can be dynamically changed when necessary.

Peter

I think (in general) this is a good idea...We need to have BOTH a working definition of what the API should implement - and possibly a reference implementation. I say "possibly", since just as with other run-time libraries, especially ones that exist cross platform (like Java), it is the API, and not the actual code that matters...

So, I am OK with the fact that any project may need (or just want) to implement things differently. For example, I know your project wants to define all the shortcuts at BUILD of the PE, while others may choose to create them when the PE boots up. Both would be OK from a scripting perspective, since "Add_shortcut" doesn't care how it is created, just the parameters that are needed to define a shortcut.

So I think the first place to start is with the definitions - let's make sure that we agree that they are the correct ones to have for a "formally recognized" project...Maybe you can start by expanding more on your "disappointments"...either things not working as they should or confusing docs, etc.

p.s. Homes32 and I both worked on writing that definition! (you can see the history if you go into the SVN part of the google code project

So, I am OK with the fact that any project may need (or just want) to implement things differently. For example, I know your project wants to define all the shortcuts at BUILD of the PE, while others may choose to create them when the PE boots up. Both would be OK from a scripting perspective, since "Add_shortcut" doesn't care how it is created, just the parameters that are needed to define a shortcut.

You explain very well one of the (common) API's disadvantages!
Currently the shortcut is processed:

• In case of nativeEx based (PE1) projects using my ICE-age recommendation to call a function in the project's shell (Run,%ActiveShell%,%ExplorerShortcut%) Here even with third party shells, the correct shortcut generation can be done.
• In case of "wim based" projects by writing something into a ???.cfg file. Here third party shells get the friendly(?) request to resolve a ???.cfg file with unknown syntax during boot.

MultiPE PE2 and PE3 projects do not really need this unknown ???.cfg file( This is only history introduced by Nightman). They should get during build time a message with the necessary parameters. And if they want to use the ???.cfg file during boot, they can create that file by themselves.
That was the reason, that my project hooks the "Common"_API and leads the function call to my own processing.

Peter

Hi Peter,

I looked into the reboot download section, to download the API.

But there is none!

There is some confusion here. API stands for "Application Programming Interface" and not for "one-size-fits-all-shoe".

It is a set of definitions, there should be nothing to download except for the documentation itself.


As said before, each project decides how to implement the API commands.


I think that you are assuming API to be somewhat similar to an SDK. Be careful as they are different things.

The last time i checked, the CommonAPI was a single unified script, which works across all projects.

Has this been changed? Are we back to a bunch of project specific API scripts, like in the beginning?

Things always change ... But to be more serious, I think we are just trying to clarify things and also deal with reality.

We all seem to agree that from a script writers perspective, it is important to have an expanded set of functionality (over and above what is native to the WinBuilder EXE) and we want that to be well defined and well behaved! So, to restate what Nuno said above, an API is NOT the same as and SDK...

The API has always defined the syntax and behavior. As I pointed out above, the most important part of the "Common API" for Winbuilder is the definition. Originally, the file/script originally maintained by Galapo served BOTH purposes - it was the defacto definition and also provided the implementation. It was both an API and an SDK. As the whole ECO-System of "WinBuilder" continued to evolve, it became clear that we should separate the two aspects.

If you recall, there was a lot of discussion on the internals of the "commonAPI.script" file, and which "version" was really the "master" copy...The file already had code inside it to determine if the project was a PE1 or PE2/3 style project (and choose very different code depending on the selection)...There were even different versions floating around, with different optimizations, etc. Some versions even had different functionality being added for project specific reasons.

So, to avoid any real "battles" over the implementation of the functionality, and given the reality that Galapo hasn't really been driving the API (or the SDK aspects of the script), I decided (at least for the purpose of the official docs) to just call it the WinBuilder Scripting API (see this page http://code.google.c...iki/wbcommonapi ). For now, this helps keep a semblance of "peace"...and clarifies that the really important thing is the definition, and as an "application" script writer, you should be able to write a script, and have it work without modification in more than one project. I deliberately avoided the whole issue of implementation.

And I think this is exactly what Peter was getting at...i.e. you can go look at the docs, BUT there isn't a place on the download section where anyone who wanted to create a totally new project from scratch can go to download an implementation of this API - IMHO, this is also a deliberate decision given that we have differing views on how best to implement some of the functionality. On the other hand, it doesn't stop anyone from creating a SDK script and posting it (with full disclosure of where it works, and with which project, etc.

In fact, that is what happens today...The Win7PE_SE project has it's version of the script file, Peters MultiPE has it's version, Leopard has it's, etc...each of them can be different - as long as they support the functions defined by the API...

So while we may be back to individual, independent scripts, it is NOT like the beginning, since they should be following the same API definitions.


Scott

In fact, that is what happens today...The Win7PE_SE project has it's version of the script file, Peters MultiPE has it's version, Leopard has it's, etc...each of them can be different - as long as they support the functions defined by the API...

In other words the "Common API" is as "Common" as "Common Sense"



Wonko

Yep, totally agree, Wonko. (Has hell already frozen over? )

Can't wait till the first windows based project is called a Linux.

Yep, totally agree, Wonko. (Has hell already frozen over? )

Naaah, over time you are bettering - slowly - but bettering.

Being frozen hell an oximoron, I feel authorized to use "unuseful utility" to define the apparent current status of the API:
http://encyclopedia2...ogram Interface
or maybe I got the wrong acronym here:
http://www.acronymfinder.com/API.html
http://encyclopedia....ction Institute
maybe we could rename it from "Common API" to "Free Uninterchangeable Documented Library" (Fud-L)....


Wonko

...define the apparent current status of the API:
http://encyclopedia2...ogram+Interface

That seems like a VERY GOOD definition of what we are talking about...Not really sure what all the "fuss" is about...If the %API% variable is defined (which means it is hooked into the winbuilder project and processing, since the way it hooks in is "special", then any script should be able to make sue of the defined functionality.

If it operates as it should, then do we really care HOW it accomplishes the task?

I got it!

But I have two suggestions requirements:

• An %API% called "Common_API" should not exist. New users are lead to the wrong opinion, that there is one API SDK for all projects. I extend to: Also "API" should not exist in the name. Maybe a name like <project>Macros.script is reasonable.
• Before an API command is added to the WinBuilder documentation it should be discussed in the forum.

Let me give an example: ScriptInterface.
I do not want to criticise ScriptInterface. ScriptInterface is a really sophisticated and useful function. Congratulations for Homes32
I want to criticise the procedere.
This command became public first in a post about a new release of win7pe_se

Posted 16 May 2011 - 03:03 PM
Project Updated: Win7PE_SE_2011_05_16
Common_Api : added new api command ScriptInterface{Read|Write|State} - Removed Getinterface, ShowComponent, WriteInterface (depreciated). Thanks Homes32.

Anywhen and anyhow this win7pe_se proprietary function appeared silently in the official WinBuilder documentation, w/o any previous presentation / discussion in the forum.
Following the logic: In order to be further able to process all "App-Scripts", all project authors are forced to add the implementation to their projects.
What makes this task especially interesting: No example source code about implementation is published anywhere in the reboot forum

Peter

Anywhen and anyhow this win7pe_se proprietary function appeared silently in the official WinBuilder documentation, w/o any previous presentation / discussion in the forum.
Following the logic: In order to be further able to process all "App-Scripts", all project authors are forced to add the implementation to their projects.
What makes this task especially interesting: No example source code about implementation is published anywhere in the reboot forum

Hmmm.... strangely enough this reminds me of Deuteronomy 17:7 and John 8:7

IF I get it right you are saying that the procedure of:

• introducing a change without a prior discussion in the forum
• doing this without providing a full documentation of it
• forcing any other Author to use a given (actually NOT given) different syntax

is not advisable?


Wonko

I only want to prevent, that mistakes done in the past (including by me) are becoming standard.

Peter

This discussion drifts to be about everything except simple commands to create app scripts.


Some want to start flaming other's people effort, others want to add whatever and call it "official". Some just want to stain someone else's work and wash dirty laundry in public. Really sad picture going on here, some might enjoy it as a way of life but this is not the way how we roll at reboot.

Topic closed my friends, no more trolling please.