72 replies to this topic

[Brito]

Hi everyone!

This topic is meant to discuss the implementation of a common API (Application Programming Interface) which enables developers to create their scripts in a simpler way.


One pratical use of an API is the reduction of code lines needed to get tasks done like creating shortcuts for example and the simplification of coding making it easier to understand for others.

Also worth mentioning that using common functions also enables scripts to survive longer to overall project changes, meaning that a script done today will probably still work next year if a common method is adopted.

Please note that this API is mostly meant for Application scripts - the scripts which are supposed to add third party programs already supported on different platforms like Win9x, WinXP and Vista.

Both nativeEx and VistaPE already have their built-in API which is already used for some of the tasks described here - but we should work to create a common set of functions that can be used on both projects and eventually on the next projects to appear.


Flexibility and Expandability are good keywords to describe the future of these scripts.


So let the discussion start and see if we can in fact achieve this goal.





How do we build an API function under WinBuilder?

Using the [variables] section from the script.project file on each project it is possible to define new "commands" - so imagine this example:

[variables]

MakeDesktopShortcut=run,%API%,CreateDesktopShortcut

on the %API% file:

[CreateDesktopShortcut]

....

...

..

and while running:

[process]

MakeDesktopShortcut,This is an Example,myExampleFolder\myExample.exe

Or even a FileCopyExpand command which looks for a file from txtsetup.sif and decides whether to Cab Extract or copy the file from source.

There are a lot of ways to use this API and the best part is that Application scripts could then be used on any supported projects without much worries.

Meaning also that .script developers code once and others can use it on the project they prefer without changes..

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

Proposed API

Global Variables
%Shell% - to know which shell is being used (using explorer as default)


Functions
Shortcut_Desktop - to create shortcut on desktop
Shortcut_StartMenu - same as above for Start Menu (allows to specify folder)
Shortcut_Startup - Add shortcut on startup list

Files_Extract - Extract all files inside the script on "folder" to the programs's folder

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

Script Template


[variables]
%application%=myExample.exe
%shortcut_name%=This is my Example
%application_dir%=myExampleDir


[process]
Shortcut_Desktop
Shortcut_StartMenu,Applications
Files_Extract
---------------------------------------------------------------------------------------------



What does the community think about this?

Edited by Nuno Brito, 06 May 2007 - 06:40 PM.

[pscEx]

Using the [variables] section from the script.project file on each project it is possible to define new "commands" - so imagine this example:

[variables]

  MakeDesktopShortcut=run,%API%,CreateDesktopShortcut

I'm very sure that it should be the [variables] section of WinBuilder.ini, in order to pass between projects.
For different code in different project types we use Nunos %ProjectType% suggestion.

Or ????

Peter

[Brito]

It should probably be inside script.project because "run,%API%,CreateDesktopShortcut" could allow to be adapted for each project needs - and some projects might not even implement the whole common API for their own specific reasons.

[pscEx]

Or even a FileCopyExpand command which looks for a file from txtsetup.sif and decides whether to Cab Extract or copy the file from source.

As a practical sample: This is what I already use, but not yet published:

[process]

// basic files, compressed to target

echo,"Copying Driver files.."

Run,%ScriptFile%,Load-Driver,acpi.sy

...

[Load-Driver]

If,ExistFile,"%SourceDir%\I386\%spFile%",ShellExecute,"hide","expand.exe","#$q%SourceDir%\I386\%spFile%#$q -F:#1s #$q%TargetDir%\i386\system32\drivers#$q"

If,NotExistFile,"%TargetDir%\i386\system32\drivers\#1s",ShellExecute,"hide","expand.exe","#$q%SourceDir%\I386\%drFile%#$q -F:#1s #$q%TargetDir%\i386\system32\drivers1#$q"

If,NotExistFile,%TargetDir%\i386\system32\drivers\#1s,If,ExistFile,"%SourceDir%\I386\#1_",Expand,"%SourceDir%\I386\#1_","%TargetDir%\i386\system32\drivers"

If,NotExistFile,%TargetDir%\i386\system32\drivers\#1s,FileCopy,"%SourceDir%\I386\#1s","%TargetDir%\i386\system32\drivers"

If,NotExistFile,%TargetDir%\i386\system32\drivers\#1s,echo,"Missing: #1s"

Of course that does not match Nuno's global definition, but could be made simply to match it.

Peter

[smiley]

It should probably be inside script.project because "run,%API%,CreateDesktopShortcut" could allow to be adapted for each project needs - and some projects might not even implement the whole common API for their own specific reasons.

We can also use the following command in every script that we want to use the api commands:

AddVariables,"%Api%","ApiCommands"

Where %Api% is a variable holding the path to the api script and ApiCommands is a Variables section, renamed to ApiCommands .

So you can declare in a script many apis with only one command.

[Brito]

Those are very good ideas - the sort of things that really pushes coding forward..

[pscEx]

Those are very good ideas - the sort of things that really pushes coding forward..

But please, have a look at my signature

Peter

[Brito]

Posted on first topic a few API suggestions..

[NightMan]

HELLO!

Common API is very good idea, recently i thik how make scripts for programs is more simple and my ideas is very closely with yours

For program scripts we are really need:
0. program name
1. executable name ("sample.exe" or "folder\sample.exe")
2. program source folder (or archive name, or ...)
3. startup parameters ("/1234")
4. where place shortcut (desktop, start menu, quick lanch)
5. program category (antivirus, disk tools and etc)
6. registry setting (reg file or command at WB language)
7. common files (dll) from distributive
8. autorun commands...
9. program icon file
10. target type (RAM or CD)
11. target folder (may be == program name)



How it will be work

[process]

Echo,"Processing program name..."

CopyApp,executable name,program source folder,target type\target folder

Extract,acrhive name,target type\target folder

Shortcut,"StartMenu\program category\program name","target type\target folder\executable name","startup parameters","program icon file"

Shortcut,"DeskTop\program category\program name","target type\target folder\executable name","startup parameters","program icon file"

AutoRun,target type\target folder\executable name,startup parameters

CopyRegSetting,source,target

AddRegFile,reg file

CopyApp - check source folder and copy program

it's very very basic

Next think

Will be very good idea create program for searching all programs on computer and automatically make scripts for known programs, we need make only one big ini (or xml) file with setting and descriptions for all program and all other will be automatically

[NightMan]

Nuno Brito

[variables]
MakeDesktopShortcut=run,%API%,CreateDesktopShortcut

it's not working (WB 068 and 069 beta6)

[variables]

%MakeDesktopShortcut%=run,%API%,CreateDesktopShortcut

it's working good, but looking not very good

[Brito]

Thanks for joining our talks!!

I will test it and see why it isn't working..

[Alexei]

APIs are good
The only "danger" is to make them "too convenient" What I mean is that it should be small, but complete set of APIs.
The principle I use in such situations: simple things - easy, but tricky stuff - hard.
What I mean is that doing something in a "wrong way" should be not easy, just because there is no API for it

Alexei

[NightMan]

[url="http://www.boot-land.net/forums/Future-pro...-API-t2198.html"]http://www.boot-land...-API-t2198.html[/url]

What do you think?

[Brito]

Hi,

I've continued my testings with API and started with the very most simple functions expected from an application script - create one or two shortcuts and extract all files inside the script into the respective folder.


Using sudoku as template, we can use something like this:

[variables]

%ProgramTitle%=Sudoku

%ProgramEXE%=sudoku.exe

%ProgramFolder%=Sudoku



[process]

Add_Shortcut,Desktop

Add_Shortcut,AutoStart

Add_Shortcut,StartMenu,Games and Fun

unpack

Inside script.project:

[variables]

%api%=%projectdir%\Basic\Build\api.script

Add_Shortcut=Run,%api%,AddShortcut

Unpack=Run,%api%,depack

Inside api.script:

[AddShortcut]

echo,""

echo,"API - Creating a new shortcut for %programTitle%.. [%programFolder%\%programExe%]"

If,#1,Equal,,Set,"%shortcut_type%","DE"

If,#1,Equal,Desktop,Set,"%shortcut_type%","DE"

If,#1,Equal,StartMenu,Set,"%shortcut_type%","SM"

If,#1,Equal,QuickLaunch,Set,"%shortcut_type%","QL"

If,#1,Equal,AutoStart,Set,"%shortcut_type%","AU"

Run,%BuildModelScript%,Add-Shortcut,"%shortcut_type%\#2","#$pProgramFiles#$p\%programFolder%\%programExe%","%ProgramTitle%","-SW:#$pProgramFiles#$p\%programFolder%"



[depack]

echo,"API - Unpacking files and settings.."

IniRead,"%ProjectInfo%","TargetPaths","Program_Files",%WorkDir%

Run,%api%,depack_extract,#1



[depack_extract]

If,#1,Equal,,Set,"%folder_name%","Folder"

If,#1,NotEqual,,Set,"%folder_name%","#1"

//

DirMake,"%targetDir%\%workDir%"

DirMake,"%targetDir%\%workDir%\%ProgramFolder%"

echo,"Extracting %ProgramTitle%.."

ExtractAllFiles,"%ScriptFile%","%folder_name%","%targetDir%\%workDir%\%ProgramFolder%"

The overall idea is to stay away from any modification on the interface section and keep scripts very flexible until this part is properly discussed.

These shortcuts are very customizable and easy to add, you can Add_Shortcut for just adding an icon on desktop, use Add_Shortcut,StartMenu to add an entry on start menu or use Add_Shortcut,StartMenu,Games and Fun to be specific on which folder inside the start menu it should be grouped.

Other type of shortcuts are possible such as AutoStart and QuickLaunch which are all provided internally by BuildModel on nativeEx.


Now the goal is providing these same two functions for VistaPE - which I will be the next step if time allows or perhaps Nighman has some time to work them for properly working under VistaPE.


I'm not covering any file copy functions or checking the support for using other shells (yet), just the basic API steps to add files inside a script and then extract them inside the folder.


Notice that unpack is very flexible and can be adapted for more tasks than just extracting files, at this moment it extract all files inside a specified encoded folder into the program folder - if none is specified then it will use the "Folder" as default.

No checks are done, but this should only be added inside the API to keep the template script as uncluttered as possible. Users shouldn't have to add too many items, just the basic information is more than enough for most cases. If a script is more advanced and requires other features, then the developer should also be able to create his scripts understanding the basis of this API and then we can also move to more advanced functions.


Also remember that adding more variables on script.project files only make the whole project gets slower performance since the variables list will become bigger and sluggier - so there should be as less "fixed" variables as possible.




You can also download api.script, just place it on %projectdir%\Basic\Build

Attached Files

•  api.script   2.08KB   410 downloads

[NightMan]

Hello Nuno Brito!!!

First, BIG BIG THANKS!

(it's anwer to your personal messenger)

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

Second, i can not send PM to you:

This message can not be sent because the recipient has their personal messenger disabled 

or they are in a member group not allowed to use the personal messenger.



This personal message has not been sent

ps i have some questions about API, but only in PM

[thunn]

Likewise, cannot send any PM to Nuno..

[pscEx]

To solve the issues Sherpya has (see here), I created two new API commands:

Copy_Expand,#1,#2,#3
//#1: source file with missing 3rd character in extention
//#2: 3rd character in extention
//#3: target directory

If in the source there is a compressed file, it is decompressed and copied to the target
If in the source there is an uncompressed file, it is just copied to the target

Copy_Both,#1,#2,#3
//#1: source file with missing 3rd character in extention
//#2: 3rd character in extention
//#3: target directory

The file is copied to the target, idependent whether it is compressed or not.

To implement these functions, you need:

• Add to script.Project:
  

  [Variables]
  
  ...
  
  Copy_Expand=Run,%api%,CopyOrExpand
  
  Copy_Both=Run,%api%,CopyBoth

• Add to api.script:
  

  [CopyOrExpand]
  
  //#1: source file with missing 3rd character in extention
  
  //#2: 3rd character in ectention
  
  //#3: target directory
  
  If,ExistFile,#1_,Expand,#1_,#3
  
  If,NotExistFile,#1_,FileCopy,#1#2,#3
  
  
  
  [CopyBoth]
  
  //#1: source file with missing 3rd character in extention
  
  //#2: 3rd character in ectention
  
  //#3: target directory
  
  If,ExistFile,#1_,FileCopy,#1_,#3
  
  If,NotExistFile,#1_,FileCopy,#1#2,#3

The new API functions are actually used in nativeEx_barebone, Copy%Expand script.

Peter

[Brito]

Good work, but we still need a way to support x64 sources..

These sources seem quite similar to x86 but use an AMD64 folder to fetch specific files - would be preferable to read txtsetup.sif to know from where the file should be copied or expanded since this is the "roadmap" to let us know which configuration is correct for the source to work and thus leading to a more reliable method..

Maybe a small binary to speed up txtsetup interpretation?

[thunn]

Nuno,
a little off topic, but--
Do you have a command that mirrors the funtionality of the NT cmdline "&&"?
Using "&&", statement is only exicuted if it will work, else no error. (Of course it follows something on the same line)

Some of my scripts use multiple IF statements in one line.

[pscEx]

Good work, but we still need a way to support x64 sources..

These sources seem quite similar to x86 but use an AMD64 folder to fetch specific files - would be preferable to read txtsetup.sif to know from where the file should be copied or expanded since this is the "roadmap" to let us know which configuration is correct for the source to work and thus leading to a more reliable method..

Maybe a small binary to speed up txtsetup interpretation?

Can you post a txtsetup.sif with reference to such x64 folder?
And the source directory structure of a x64 CD?
I do not have one.

Peter

[smiley]

Can you post a txtsetup.sif with reference to such x64 folder?
And the source directory structure of a x64 CD?
I do not have one.

Peter

What Nuno suggests ,is not posible because txtsetup.sif is in the AMD64folder and not in i386

[Brito]

Nuno,
a little off topic, but--
Do you have a command that mirrors the funtionality of the NT cmdline "&&"?
Using "&&", statement is only exicuted if it will work, else no error. (Of course it follows something on the same line)

Some of my scripts use multiple IF statements in one line.

Would you mind posting this request as a new topic?

This way we can discuss it further and see if a good solution can be found - I know it can be coded, but I'm just a bit unsure about enough time to implement it properly..

Please bump this new topic after the next beta when I hope to have finished recoding the download methods..

Can you post a txtsetup.sif with reference to such x64 folder?
And the source directory structure of a x64 CD?
I do not have one.

Peter

Unfortunately I don't have any source here at home - never also needed to use any x64 install CD so I've based my comment on holger's feedback from here: http://www.boot-land...?...ost&p=14365 and wrongly assumed the same location for txtsetup.sif based on setupldr.bin which is also present on I386 folders..

Holger also refers that you can download a x64 2003 trial from MS and test on vmware..


Smiley - thanks for the correction, do you know from where we can read the location of txtsetup.sif on the source disk?

Thanks!

[smiley]

thanks for the correction, do you know from where we can read the location of txtsetup.sif on the source disk?

Well, txtsetup.sif must be in one of the three folders: i386 , amd64 and ia64. A simple if command can solve this.

If,ExistFile,"%SourceDir%\i386\txtsetup.sif",Set,"%Architecture%","i386"

If,ExistFile,"%SourceDir%\amd64\txtsetup.sif",Set,"%Architecture%","amd64"

If,ExistFile,"%SourceDir%\ia64\txtsetup.sif",Set,"%Architecture%","ia64"

If,%Architecture%,Equal,"",Halt,"Invalid source!"

IniWrite,"%ProjectDir%\script.project","Variables","#$pArchitecture#$p","%Architecture%"

IniWrite,"%ProjectDir%\script.project","Variables","#$pArchSource#$p","#$pSourceDir#$p\#$pArchitecture#$p"

System,RefreshVars

This should work fine define foundamentals. So every script know where to find the files it needs with the %ArchSource% variable.


Can you also have a look at my api project that I posted here?

[pscEx]

@smiley:

I tested (and debugged a little bit ):

Result:

One question:

Why putting the main definitions into [ApiDeclarations] of ProjectApi.script and not into [Variables] of script.project?

Peter

[smiley]

Why putting the main definitions into [ApiDeclarations] of ProjectApi.script and not into [Variables] of script.project?

Because they have to be cleaned at every run. If I put it on script.project I have to delete one by one the api entries wile now I just only have to delete this section and delte it from scrach.

My first idea was that every script should be able to write an api in thelist so it can be used by other scripts. If this happen it will be impossible to clean up completely.