Page 1 of 1

Understanding API (programming VB via (XP)COM, web services))

Posted: 11. Aug 2017, 15:04
by GDK
How to read interface specification https://www.virtualbox.org/sdkref/hierarchy.html?
I am going to use it in PowerShell 3.0 scripts. PowerShell ISE accepts VB class names without the "I" -prefix in contrast to "I"-prefixed class names in named specification.

Next point: According to "Programming Guide and Reference", http://download.virtualbox.org/virtualb ... SDKRef.pdf
the raw web services API does not feature object orientation. It loses that property even though VB web service "more or less maps the VirtualBox Main COM API" (pdf quoted) the latter in turn is object-oriented. Why the object-orientated API nature gets lost upon mapping from COM API to raw web service API?

Re: Understanding API (programming VB via (XP)COM, web services))

Posted: 11. Aug 2017, 16:03
by noteirak
GDK wrote:How to read interface specification https://www.virtualbox.org/sdkref/hierarchy.html?
I am going to use it in PowerShell 3.0 scripts. PowerShell ISE accepts VB class names without the "I" -prefix in contrast to "I"-prefixed class names in named specification.
You wouldn't use that view. Instead, the root object is IVirtualBox from which everything originates. How you get that object depends on the language.
GDK wrote:Next point: According to "Programming Guide and Reference", http://download.virtualbox.org/virtualb ... SDKRef.pdf
the raw web services API does not feature object orientation. It loses that property even though VB web service "more or less maps the VirtualBox Main COM API" (pdf quoted) the latter in turn is object-oriented. Why the object-orientated API nature gets lost upon mapping from COM API to raw web service API?
The issue in this case is you don't use an official binding (there is no Powershell bindings) which glues all this into a single consistent API. I don't know how it would work in Powershell, but maybe you can hook to one of the others binding to provide that glue abstraction?

Re: Understanding API (programming VB via (XP)COM, web services))

Posted: 11. Aug 2017, 16:22
by GDK
Thanks for information.

Yes, at script entry point the VirtualBox object is instantiated. Session object too. These are location where my question #1 arise.

Reg. 1. How to see if for given programming environment (language) the "I"-prefixed or free of "I"-prefix access to interface / class needs to be used? In my case I had to find it out by try and fail - not the optimal way as drawn by lack of matters understanding. Powershell is .NET-based, thus object-oriented. What does that "I" -prefix actually stand for? For "Interface"?
I wonder if that distinction in prefixing names is made even due to support of both (XP)COM (object oriented) and raw web service (not object oriented).

Reg. 2. Please treat this question rather generally without any connection to my plans of programming VB from PowerShell script based on VB COM API.

Re: Understanding API (programming VB via (XP)COM, web services))

Posted: 11. Aug 2017, 16:29
by noteirak
Reg 1: Each binding comes with sample code source that would show you this information. Since Powershell is not directly supported, you wouldn't have that information, which is expected. It would depends to which official binding you are actually hooking on. There is C++, Python, Java, VB, VBS and PHP. There is also one for C but is not object oriented and not the most supported. Not all bindings support all low-level connectors (Web services, XPCOM, MSCOM).
I stands for Interface yes, it's one naming convention. As for supporting both (XP)COM and Web services, see #2.

Reg 2: The generic approach is that XPCOM, MSCOM and WebServices are all low-level connectors and the official bindings come with an high-level API labelled "glue" which hides all the low-level differences. The classes described at https://www.virtualbox.org/sdkref/ are the high-level glue ones.
And to clarifiy: Web services is not restricted to low level, and you can use Objects if you use the right API/binding.

Re: Understanding API (programming VB via (XP)COM, web services))

Posted: 11. Aug 2017, 16:59
by GDK
Thanks again.
It looks like my script will connect to api layer below any binding as there are some examples and articles in web how to use Microsoft COM
within PowerShell script.

I try also to find the trail on which my script can conduct error handling.
According to IVirtualBox description https://www.virtualbox.org/sdkref/inter ... l_box.html error code return is outsourced to (sub-)class members (attributes, methods). Indeed one can comprehend this if to take for instance composeMachineFilename.
However in case of IMachine.lockMachine there is no retval parameter defined but some error codes specified.
I guess IVirtualBoxErrorInfo needs to be used for that. Really? Is it an rule for API to provide error code through this object when and only if used class member does not support error code reporting?

Re: Understanding API (programming VB via (XP)COM, web services))

Posted: 11. Aug 2017, 17:08
by noteirak
The SDK reference is for the C++ binding, but once you understand the logic of each language on how things are handled, you can know what's supposed to happen.

How the error is dealt with depends on the language you are using. In Java, you would get a regular exception with an error message and the error code . There would be one extra method to get the full VirtualBox error info which would return a IVirtualBoxErrorInfo object. But in all cases, the error handling would be the same for languages others than C/C++ regardless of which method/object you use.
Once again, please refer to whatever supported binding you're actually hooking on and see how to handle errors there.

If you connect to the low-level layer and not the high-level API, then you'll be pretty much on your own as nobody goes there usually and is definitely not recommended or supported AFAIK.

Maybe it would be best to just try some code, see what happens? You can always post code here if you're stuck. Make sure you follow the posting guildelines if you do so.

Re: Understanding API (programming VB via (XP)COM, web services))

Posted: 17. Aug 2017, 17:57
by GDK
Reg. question #2 in thread's initial posting.
Me uses Programming Guide and Reference (PDF, ver. 5.1.26) and VirtualBox Main API web page as knowledge source.
PDF document, two bullets opening chapter 2.2.3.1, which Web services are being compared to COM-level Main API here?
Web services generally abstracting from every concrete software solution, or even Web services of VirtualBox?

No or very low level of expertise and experience regarding COM technology and its usage on my side (web service generally too).

Re: Understanding API (programming VB via (XP)COM, web services))

Posted: 17. Aug 2017, 18:08
by noteirak
PDF document, two bullets opening chapter 2.2.3.1, which Web services are being compared to COM-level Main API here?
Web services in general.

Section 2.1 talks about the glue layer, which is Object oriented and has the same methods for both Webservices and COM.
Section 2.2 and 2.3 talk about the low-level bindings which you should avoid.

As for your initial question, Web services are just not object oriented, they're just text, regardless of the language used. That's when the glue layer comes into play, so you can get this Object Oriented approach, like you have in COM.
It's not that web services "looses" from COM, they are just different ways to connect and deal with data.

Re: Understanding API (programming VB via (XP)COM, web services))

Posted: 21. Aug 2017, 14:36
by GDK
noteirak wrote:
PDF document, two bullets opening chapter 2.2.3.1, which Web services are being compared to COM-level Main API here?
Web services in general.
I am not able to follow this statement. As it is known that VB native web service is not object oriented. It is also known that VB raw web service deviates from standard web services in used techniques (OO vs. non-OO). 1st bullet from chapter 2.2.3.1 opening bullets literally refers to web service showing the lack of object orientation, so it must be referring to VB web service.
My point is following: If web services generally (under abstracting from any concrete software solution) are object oriented and VB web service underlying layer (XP)COM shows object orientation too why is VB raw web service losing this property.
* Starting point (underlaying layer VB (XP)COM API) features OO
* world-wide web service standard (the target) features OO I believe it is a target to align with standards
* VB raw web service does not feature OO
There must be concrete reason for VB raw web service to get lost OO. It looks like VB raw web service tranformed object-oriented API ((XP)COM) into non-OO API (VB raw web service). VB web service gets OO not until additional layer is added (mentioned binding) which comes on-top but prior to that VB raw web service elliminates OO property.

Re: Understanding API (programming VB via (XP)COM, web services))

Posted: 23. Aug 2017, 20:28
by noteirak
"Why" is for the VirtualBox devs to answer and you should direct such queries to the dev mailing list. I'm sure the answer will basically be "because it's the easiest to generate/code/deal with".