VirtualBox

Changeset 26370 in vbox for trunk/src/VBox/Main/webservice


Ignore:
Timestamp:
Feb 9, 2010 1:56:55 PM (15 years ago)
Author:
vboxsync
Message:

Webservice: code documentation

Location:
trunk/src/VBox/Main/webservice
Files:
9 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Main/webservice/Makefile.kmk

    r26023 r26370  
    77
    88#
    9 # Copyright (C) 2006-2009 Sun Microsystems, Inc.
     9# Copyright (C) 2006-2010 Sun Microsystems, Inc.
    1010#
    1111# This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    2626
    2727#
    28 # Here's a temporary outline how all this works.
    29 
     28# Here's an overview how all this works. It's complicated. Essentially,
     29# lots of files get generated automatically from our XML XIDL file that
     30# describes the VirtualBox API (../idl/VirtualBox.xidl); as a result,
     31# no manual coding is necessary when the API changes. All generated
     32# web service code gets adjusted automatically.
     33#
     34# In more detail:
     35#
    3036# 1) We use xsltproc and websrv-wsdl.xsl to generate a WSDL file from
    31 #    our XML IDL file (../idl/VirtualBox.xidl). This WSDL describes the
    32 #    web service to third-party clients; for example, one can feed it to
    33 #    perl and thus easily write a short script that connects to the web
    34 #    service properly.
     37#    our XML IDL file. WSDL (Web Service Description language) is an XML
     38#    industry standard that publicly describes a web service.
     39#    So, the WSDL generated here describes the VirtualBox web
     40#    service to third-party clients; for example, one can feed it to
     41#    Java or Perl or some other toolkit that understands WSDL and thus
     42#    easily write a short script that connects to the web service properly.
    3543#    This WSDL file ends up in $(VBOXWEB_OUT_DIR)/vboxweb.wsdl.
    3644#
    37 # 2) We use xsltproc and websrv-gsoapH.xsl to generate a gSoap header
    38 #    file: $(VBOXWEB_OUT_DIR)/gsoapH_from_xslt.h.
    39 #       This file looks like a C header file, but really isn't meant
     45# 2) We use xsltproc and websrv-gsoapH.xsl to generate a so-called
     46#    "gSoap header file": $(VBOXWEB_OUT_DIR)/gsoapH_from_xslt.h.
     47#   This file looks like a C header file, but really isn't meant
    4048#    to be included by a C compiler. Instead, it just happens to be the
    41 #    format that gSOAP uses to specify SOAP interfaces instead of WSDL
    42 #    (apparently because gSOAP was written before the advent of WSDL).
    43 #
    44 #        Note that gSOAP comes with its own WSDL-to-gsoap.h converter, but
    45 #    the readme mentions some funny license restrictions, so instead we
     49#    format that gSOAP uses to specify SOAP interfaces instead of WSDL.
     50#    (The reason for this appears to be that gSOAP predates WSDL and
     51#    thus needed some format to describe the syntax of a web service.)
     52#
     53#        Note that gSOAP now also comes with its own WSDL-to-gsoap.h converter,
     54#    but the readme mentions some funny license restrictions, so instead we
    4655#    have our own converter in XSLT.
    4756#
    48 # 3) We then feed that header file to gsoap's soapcpp2, which generates
    49 #    a ton of files in $(VBOXWEB_OUT_DIR), most importantly:
     57# 3) We then feed that pseudo-header file to gSOAP's soapcpp2 compiler,
     58#    which generates a ton of files in $(VBOXWEB_OUT_DIR), most importantly:
    5059#
    5160#    SOAP_CLIENT_H = $(VBOXWEB_OUT_DIR)/soapStub.h (header file for webservice clients)
    … …  
    5867#
    5968# 4) We use xsltproc to generate tons of c++ code directly from the XIDL that
    60 #    maps each soap method to our COM methods. This large c++ file is
     69#    maps each SOAP method to our COM methods. This large C++ file is
    6170#    $(VBOXWEB_OUT_DIR)/methodmaps.cpp. The actual webservice executable (vboxwebsrv,
    62 #    which acts as an http server) is composed of this file, plus hard-coded
     71#    which acts as an HTTP server) is composed of this file, plus hard-coded
    6372#    method implementations in vboxweb.cpp, plus gSOAP library code for the HTTP
    6473#    server.

  • trunk/src/VBox/Main/webservice/websrv-cpp.xsl

    r24679 r26370  
    99        web service; our generated code automatically maps
    1010        all SOAP calls into COM/XPCOM method calls.
    11 
    12      Copyright (C) 2006-2009 Sun Microsystems, Inc.
     11        See webservice/Makefile.kmk for an overview of all the things
     12        generated for the webservice.
     13
     14     Copyright (C) 2006-2010 Sun Microsystems, Inc.
    1315
    1416     This file is part of VirtualBox Open Source Edition (OSE), as

  • trunk/src/VBox/Main/webservice/websrv-gsoapH.xsl

    r16122 r26370  
    88        soapcpp2 to create web service client headers and server
    99        stubs.
    10 
    11         (The reason for this appears to be that gSOAP predates
    12         WSDL and thus needed some format to describe the syntax
    13         of a web service. gSOAP these days comes with wsdl2h,
    14         which converts a WSDL file to gSOAP's "header" format,
    15         but that has license problems and so we generate the
    16         gSOAP "header" ourselves via XSLT.)
    17 
    18      Copyright (C) 2006-2008 Sun Microsystems, Inc.
     10        See webservice/Makefile.kmk for an overview of all the things
     11        generated for the webservice.
     12
     13     Copyright (C) 2006-2010 Sun Microsystems, Inc.
    1914
    2015     This file is part of VirtualBox Open Source Edition (OSE), as

  • trunk/src/VBox/Main/webservice/websrv-nsmap.xsl

    r16122 r26370  
    77        VirtualBox.xidl, which gets included from C++ client and
    88        server code.
     9        See webservice/Makefile.kmk for an overview of all the things
     10        generated for the webservice.
    911
    10      Copyright (C) 2006-2007 Sun Microsystems, Inc.
     12     Copyright (C) 2006-2010 Sun Microsystems, Inc.
    1113
    1214     This file is part of VirtualBox Open Source Edition (OSE), as

  • trunk/src/VBox/Main/webservice/websrv-shared.inc.xsl

    r23223 r26370  
    44        so we can share some definitions that must be the same for
    55        all of them (like method prefixes/suffices).
    6 
    7      Copyright (C) 2006-2007 Sun Microsystems, Inc.
     6        See webservice/Makefile.kmk for an overview of all the things
     7        generated for the webservice.
     8
     9     Copyright (C) 2006-2010 Sun Microsystems, Inc.
    810
    911     This file is part of VirtualBox Open Source Edition (OSE), as

  • trunk/src/VBox/Main/webservice/websrv-typemap.xsl

    r16122 r26370  
    66        XSLT stylesheet that generates a typemap file from
    77        VirtualBox.xidl for use with the gSOAP compilers.
     8        See webservice/Makefile.kmk for an overview of all the things
     9        generated for the webservice.
    810
    9      Copyright (C) 2006-2007 Sun Microsystems, Inc.
     11     Copyright (C) 2006-2010 Sun Microsystems, Inc.
    1012
    1113     This file is part of VirtualBox Open Source Edition (OSE), as

  • trunk/src/VBox/Main/webservice/websrv-wsdl-service.xsl

    r16122 r26370  
    77        VirtualBox.xidl. That extra WSDL file includes the big
    88        vboxweb.wsdl file and adds a "service" section.
     9        See webservice/Makefile.kmk for an overview of all the things
     10        generated for the webservice.
    911
    10      Copyright (C) 2006-2007 Sun Microsystems, Inc.
     12     Copyright (C) 2006-2010 Sun Microsystems, Inc.
    1113
    1214     This file is part of VirtualBox Open Source Edition (OSE), as

  • trunk/src/VBox/Main/webservice/websrv-wsdl.xsl

    r20888 r26370  
    77        VirtualBox.xidl. This WSDL file represents our
    88        web service API..
    9 
    10      Copyright (C) 2006-2007 Sun Microsystems, Inc.
     9        See webservice/Makefile.kmk for an overview of all the things
     10        generated for the webservice.
     11
     12     Copyright (C) 2006-2010 Sun Microsystems, Inc.
    1113
    1214     This file is part of VirtualBox Open Source Edition (OSE), as

  • trunk/src/VBox/Main/webservice/websrv-wsdl2gsoapH.xsl

    r16122 r26370  
    33<!--
    44    websrv-gsoapH.xsl:
    5         XSLT stylesheet that generates vboxweb_gsoapH.h from
    6         VirtualBox.xidl.Such "header" files can be fed into
    7         gSOAP's soapcpp2 to create web service client headers
    8         and server stubs. (The reason for this appears to be
    9         that gSOAP predates WSDL and thus needed some format
    10         to describe the syntax of a web service. gSOAP these
    11         days comes with wsdl2h, which converts a WSDL file
    12         to gSOAP's "header" format, but that has license
    13         problems and so we generate the gSOAP "header" via
    14         XSLT.)
    15 
    16      Copyright (C) 2006-2007 Sun Microsystems, Inc.
     5        XSLT stylesheet that generates a gSOAP pseudo-header
     6        file from VirtualBox.xidl. Such a pseudo-header files
     7        can be fed into gSOAP's soapcpp2 to create web service
     8        client headers and server stubs.
     9        See webservice/Makefile.kmk for an overview of all the things
     10        generated for the webservice.
     11
     12     Copyright (C) 2006-2010 Sun Microsystems, Inc.
    1713
    1814     This file is part of VirtualBox Open Source Edition (OSE), as
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette