VirtualBox

Changeset 55583 in vbox


Ignore:
Timestamp:
May 1, 2015 7:10:32 PM (10 years ago)
Author:
vboxsync
Message:

VirtualBox.xidl: Clearified IGuestSession and associated documentation wrt environment and processes. Change all 'on the guest' to 'in the guest' as we're VirtualBox and the guest is what is in in/inside the box. (In the Dungeons & Dragons (DnD) area, you may argue that you drop something on the box, so I've left those reference for someone else to sort out.)

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Main/idl/VirtualBox.xidl

    r55535 r55583  
    40804080    <attribute name="guestAddress" type="long" readonly="yes">
    40814081      <desc>
    4082         Address of device on the guest.
     4082        Address of device in the guest.
    40834083      </desc>
    40844084    </attribute>
    … …  
    99109910      <desc>A guest user has locked its account. This might
    99119911        include running a password-protected screensaver
    9912         on the guest.
     9912        in the guest.
    99139913        <note>This property is not implemented yet!</note>
    99149914      </desc>
    … …  
    99339933        The event will be triggered if a guest user is not active for
    99349934        at least 5 seconds. This threshold can be adjusted by either altering
    9935         VBoxService's command line on the guest to
     9935        VBoxService's command line in the guest to
    99369936        <pre>--vminfo-user-idle-threshold &lt;ms&gt;</pre>
    99379937        , or by setting the per-VM guest property
    … …  
    1010810108      <desc>
    1010910109        The waiting operation timed out. Also use if the guest process has
    10110         timed out on the guest side (kill attempted).
     10110        timed out in the guest side (kill attempted).
    1011110111      </desc>
    1011210112    </const>
    … …  
    1078710787    >
    1078810788    <desc>
    10789       A guest session represents one impersonated user account on the guest, so
     10789      A guest session represents one impersonated user account in the guest, so
    1079010790      every operation will use the same credentials specified when creating
    1079110791      the session object via <link to="IGuest::createSession"/>.
    1079210792
    1079310793      There can be a maximum of 32 sessions at once per VM, whereas session 0
    10794       is reserved for the root session. This root session is controlling all
    10795       other guest sessions and also is responsible for actions which require
    10796       system level privileges. Each guest session keeps track of its started
    10797       guest processes, opened guest files or guest directories.
    10798       To work on guest files or directories a guest session offers methods to open
    10799       or create such objects (see <link to="IGuestSession::fileOpen"/> or
     10794      is reserved for the root session.
     10795<!-- r=bird: Is the root session part of the maximum of 32?? Not really clear. -->
     10796      This root session is controlling all other guest sessions and also is
     10797      responsible for actions which require system level privileges.  Each
     10798      guest session keeps track of its started guest processes, opened guest
     10799      files or guest directories.  To work on guest files or directories a
     10800      guest session offers methods to open or create such objects (see
     10801      <link to="IGuestSession::fileOpen"/> or
    1080010802      <link to="IGuestSession::directoryOpen"/> for example).
    1080110803
    … …  
    1080310805      use the appropriate close() method to let the object do its cleanup work.
    1080410806
    10805       Every guest session has its own environment variable block which gets
    10806       automatically applied when starting a new guest process via
    10807       <link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/>.
    10808       To override (or unset) certain environment variables already set by the
    10809       guest session, one can specify a per-process environment block when using
    10810       one of the both above mentioned process creation calls.
     10807      A set of environment variables changes is associated with each session.
     10808      These are applied to the standard environment of the impersonated guest
     10809      user when creating a new guest process.  For additional flexibility the
     10810      <link to="IGuestSession::processCreate"/> and
     10811      <link to="IGuestSession::processCreateEx"/> methods allows you to specify
     10812      individual environment changes for each process you create.
    1081110813    </desc>
    1081210814
    1081310815    <attribute name="user" type="wstring" readonly="yes">
    1081410816      <desc>Returns the user name used by this session to impersonate
    10815         users on the guest.
     10817        users in the guest.
    1081610818      </desc>
    1081710819    </attribute>
    1081810820    <attribute name="domain" type="wstring" readonly="yes">
    1081910821      <desc>Returns the domain name used by this session to impersonate
    10820         users on the guest.
     10822        users in the guest.
    1082110823      </desc>
    1082210824    </attribute>
    … …  
    1082910831    <attribute name="timeout" type="unsigned long">
    1083010832      <desc>
     10833<!-- r=bird: Using 'Returns' for writable attributes is misleading. -->
    1083110834        Returns the session timeout (in ms).
    1083210835        <result name="E_NOTIMPL">
    … …  
    1084310846    </attribute>
    1084410847    <attribute name="environment" type="wstring" safearray="yes">
    10845       <desc>
    10846         Returns the current session environment.
     10848      <!-- r=bird: Would probably be a great idea to rename this attribute as
     10849                   it is misleading and will cause worse confusion if we ever
     10850                   expose the default environment for session (which arguably
     10851                   would be useful in many ways).   -->
     10852      <desc>
     10853        The set of environment changes.  They are in putenv format, i.e.
     10854        "NAME=VALUE" for setting and "NAME" for unsetting.
    1084710855      </desc>
    1084810856    </attribute>
    … …  
    1087310881        processes which are not referenced by clients anymore will be
    1087410882        closed. Guest processes which fall into this category and still
    10875         are running on the guest will be terminated automatically.
     10883        are running in the guest will be terminated automatically.
    1087610884      </desc>
    1087710885    </method>
    … …  
    1088610894      </desc>
    1088710895      <param name="source" type="wstring" dir="in">
    10888         <desc>Source file on the guest to copy to the host.</desc>
     10896        <desc>Source file in the guest to copy to the host.</desc>
    1088910897      </param>
    1089010898      <param name="dest" type="wstring" dir="in">
    … …  
    1091110919      </param>
    1091210920      <param name="dest" type="wstring" dir="in">
    10913         <desc>Destination file name on the guest.</desc>
     10921        <desc>Destination file name in the guest.</desc>
    1091410922      </param>
    1091510923      <param name="flags" type="CopyFileFlag" dir="in" safearray="yes">
    … …  
    1092310931    <method name="directoryCreate">
    1092410932      <desc>
    10925         Create a directory on the guest.
     10933        Create a directory in the guest.
    1092610934
    1092710935        <result name="VBOX_E_IPRT_ERROR">
    … …  
    1094210950    <method name="directoryCreateTemp">
    1094310951      <desc>
    10944         Create a temporary directory on the guest.
     10952        Create a temporary directory in the guest.
    1094510953
    1094610954        <result name="VBOX_E_NOT_SUPPORTED">
    … …  
    1098710995    <method name="directoryExists">
    1098810996      <desc>
    10989         Checks whether a directory exists on the guest or not.
     10997        Checks whether a directory exists in the guest or not.
    1099010998
    1099110999        <result name="VBOX_E_IPRT_ERROR">
    … …  
    1102911037    <method name="directoryQueryInfo">
    1103011038      <desc>
    11031         Queries information of a directory on the guest.
     11039        Queries information about a directory in the guest.
    1103211040
    1103311041        <result name="VBOX_E_OBJECT_NOT_FOUND">
    … …  
    1107311081    <method name="directoryRename">
    1107411082      <desc>
    11075         Renames a directory on the guest.
     11083        Renames a directory in the guest.
    1107611084      </desc>
    1107711085      <param name="source" type="wstring" dir="in">
    … …  
    1110211110    </method>
    1110311111
     11112<!-- r=bird: Remove this it duplicates the 'environment' attribute. -->
    1110411113    <method name="environmentClear">
    1110511114      <desc>
    … …  
    1110711116
    1110811117        <result name="VBOX_E_IPRT_ERROR">
     11118<!-- r=bird: No, it won't return this result, because you're just doing .clear() on a vector. -->
    1110911119          Error while clearing the session environment variables.
    1111011120        </result>
    … …  
    1111311123
    1111411124    <method name="environmentGet">
    11115       <desc>
    11116         Gets the value of a session environment variable.
     11125<!-- r=bird: Remove this because the interface isn't suitable for returning
     11126'unset' or empty values, and it can easily be misunderstood.  Besides there is
     11127hardly a usecase for it as long as it just works on environment changes and
     11128there is the 'environment' attribute. -->
     11129      <desc>
     11130        Gets the value of an environment variable scheduled to be set.
    1111711131
    1111811132        <result name="VBOX_E_IPRT_ERROR">
     11133<!-- r=bird: Would never return this, only invalid input or out of memory. -->
    1111911134          Error while getting the value of the session environment variable.
    1112011135        </result>
    … …  
    1112511140      <param name="value" type="wstring" dir="return">
    1112611141        <desc>
    11127           Value of the session environment variable specified. If this variable
    11128           does not exist and empty value will be returned.
     11142          Value of the session environment variable specified.  If this variable
     11143          does not exist an empty value will be returned.
     11144          <note>
     11145            An empty value will also be return for a variable with an value or
     11146            a unset-variable entry.
     11147          </note>
    1112911148        </desc>
    1113011149      </param>
    … …  
    1113311152    <method name="environmentSet">
    1113411153      <desc>
    11135         Sets a session environment variable.
    11136 
    11137         <result name="VBOX_E_IPRT_ERROR">
    11138           Error while setting the session environment variable.
    11139         </result>
     11154        Schedules setting an environment variable when creating the next guest
     11155        process.  This affects the <link to="environment"/> attribute.
    1114011156      </desc>
    1114111157      <param name="name" type="wstring" dir="in">
    11142         <desc>Name of session environment variable to set.</desc>
     11158        <desc>Name of the environment variable to set.  This cannot be empty
     11159          nor can it contain any equal signs.</desc>
    1114311160      </param>
    1114411161      <param name="value" type="wstring" dir="in">
    … …  
    1114911166    <method name="environmentUnset">
    1115011167      <desc>
    11151         Unsets a session environment variable.
    11152 
    11153         <result name="VBOX_E_IPRT_ERROR">
    11154           Error while unsetting the session environment variable.
    11155         </result>
     11168        Schedules unsetting (removing) an environment variable when creating
     11169        the next guest process.  This affects the <link to="environment"/>
     11170        attribute.
    1115611171      </desc>
    1115711172      <param name="name" type="wstring" dir="in">
    11158         <desc>Name of session environment variable to unset (clear).</desc>
     11173        <desc>Name of the environment variable to unset.  This cannot be empty
     11174          nor can it contain any equal signs.</desc>
    1115911175      </param>
    1116011176    </method>
    … …  
    1116211178    <method name="fileCreateTemp">
    1116311179      <desc>
    11164         Creates a temporary file on the guest.
     11180        Creates a temporary file in the guest.
    1116511181
    1116611182        <result name="VBOX_E_NOT_SUPPORTED">
    … …  
    1120911225    <method name="fileExists">
    1121011226      <desc>
    11211         Checks whether a file exists on the guest or not.
     11227        Checks whether a file exists in the guest or not.
    1121211228
    1121311229        <result name="VBOX_E_IPRT_ERROR">
    … …  
    1122511241    <method name="fileRemove">
    1122611242      <desc>
    11227         Removes a single file on the guest.
     11243        Removes a single file in the guest.
    1122811244
    1122911245        <result name="VBOX_E_OBJECT_NOT_FOUND">
    … …  
    1133111347      </param>
    1133211348      <param name="sharingMode" type="wstring" dir="in">
    11333         <desc>The file sharing mode on the guest. This parameter
     11349        <desc>The file sharing mode in the guest. This parameter
    1133411350          is not implemented yet. Pass an empty string here.</desc>
    1133511351      </param>
    … …  
    1134811364    <method name="fileQueryInfo">
    1134911365      <desc>
    11350         Queries information of a file on the guest.
     11366        Queries information about a file in the guest.
    1135111367
    1135211368        <result name="VBOX_E_OBJECT_NOT_FOUND">
    … …  
    1136711383    <method name="fileQuerySize">
    1136811384      <desc>
    11369         Queries the size of a file on the guest.
     11385        Queries the size of a file in the guest.
    1137011386
    1137111387        <result name="VBOX_E_OBJECT_NOT_FOUND">
    … …  
    1138611402    <method name="fileRename">
    1138711403      <desc>
    11388         Renames a file on the guest.
     11404        Renames a file in the guest.
    1138911405      </desc>
    1139011406      <param name="source" type="wstring" dir="in">
    … …  
    1140111417    <method name="fileSetACL">
    1140211418      <desc>
    11403         Sets the ACL (Access Control List) of a file on the guest.
     11419        Sets the ACL (Access Control List) of a file in the guest.
    1140411420
    1140511421        <result name="E_NOTIMPL">
    … …  
    1141711433    <method name="processCreate">
    1141811434      <desc>
    11419         Creates a new process running on the guest. The new process will be
     11435        Creates a new process running in the guest. The new process will be
    1142011436        started asynchronously, meaning on return of this function it is not
    11421         guaranteed that the guest process is in a started state. To wait for
     11437        be guaranteed that the guest process is in a started state. To wait for
    1142211438        successful startup, use the <link to="IProcess::waitFor"/> call.
    1142311439
    1142411440        <note>
    11425           Starting at VirtualBox 4.2 guest process execution by default is limited
     11441          Starting at VirtualBox 4.2 guest process execution by is default limited
    1142611442          to serve up to 255 guest processes at a time. If all 255 guest processes
    11427           are still active and running, creating a new guest process will result in an
    11428           appropriate error message.
     11443          are active and running, creating a new guest process will result in an
     11444          error.
    1142911445
    1143011446          If ProcessCreateFlag_WaitForStdOut and/or ProcessCreateFlag_WaitForStdErr
    11431           are set, the guest process will not exit until all data from the specified
    11432           streams are read out.
     11447          are set, the guest process will not enter the terminated state until
     11448          all data from the specified streams have been read read.
    1143311449        </note>
    1143411450
    … …  
    1143911455      <param name="executable" type="wstring" dir="in">
    1144011456        <desc>
    11441           Full path name of the file to execute on the guest.  The file has to
     11457          Full path to the file to execute in the guest.  The file has to
    1144211458          exists in the guest VM with executable right to the session user in
    11443           order to be executed. If empty/null, the first entry in the
    11444           @a arguments array will be used in stead (i.e. argv[0]).
     11459          order to succeed. If empty/null, the first entry in the
     11460          @a arguments array will be used instead (i.e. argv[0]).
    1144511461        </desc>
    1144611462      </param>
    … …  
    1145111467            instead of argument 1 as in previous versions.  Whether the zeroth
    1145211468            argument can be passed to the guest depends on the VBoxService
    11453             version running there.
     11469            version running there.  If you depend on this, check that the
     11470            <link to="IGuestSession::protocolVersion"/> is 3 or higher.
    1145411471          </note>
    1145511472        </desc>
    … …  
    1145711474      <param name="environment" type="wstring" dir="in" safearray="yes">
    1145811475        <desc>
    11459           Environment variables to set or unset for the guest process,
    11460           relative to the environment of the guest session.
    11461 
    11462           The variables are in the traditional "NAME=VALUE" form with one pair
    11463           per array entry.  To unset a variable just leave out the equal sign
    11464           and the value ("NAME").
     11476          Set of environment changes to complement
     11477          <link to="IGuestSession::environment"/>.  Takes precedence over
     11478          the session ones.  The changes are in putenv format, i.e.
     11479          "NAME=VALUE" for setting and "NAME" for unsetting.
     11480
     11481          The changes are applied to the standard environment of the
     11482          impersonated guest user when creating the process.
    1146511483        </desc>
    1146611484      </param>
    … …  
    1148611504    <method name="processCreateEx">
    1148711505      <desc>
    11488         Creates a new process running on the guest. Extended version for
    11489         also setting the process priority and affinity.
     11506        Creates a new process running in the guest with the extended options
     11507        for setting the process priority and affinity.
    1149011508
    1149111509        See <link to="IGuestSession::processCreate"/> for more information.
    … …  
    1149311511      <param name="executable" type="wstring" dir="in">
    1149411512        <desc>
    11495           Full path name of the file to execute on the guest.  The file has to
     11513          Full path to the file to execute in the guest.  The file has to
    1149611514          exists in the guest VM with executable right to the session user in
    11497           order to be executed.  If empty/null, the first entry in the
    11498           @a arguments array will be used in stead (i.e. argv[0]).
     11515          order to succeed.  If empty/null, the first entry in the
     11516          @a arguments array will be used instead (i.e. argv[0]).
    1149911517        </desc>
    1150011518      </param>
    … …  
    1150511523            instead of argument 1 as in previous versions.  Whether the zeroth
    1150611524            argument can be passed to the guest depends on the VBoxService
    11507             version running there.
     11525            version running there.  If you depend on this, check that the
     11526            <link to="IGuestSession::protocolVersion"/> is 3 or higher.
    1150811527          </note>
    1150911528        </desc>
    … …  
    1151111530      <param name="environment" type="wstring" dir="in" safearray="yes">
    1151211531        <desc>
    11513           Environment variables to set or unset for the guest process,
    11514           relative to the environment of the guest session.
    11515 
    11516           The variables are in the traditional "NAME=VALUE" form with one pair
    11517           per array entry.  To unset a variable just leave out the equal sign
    11518           and the value ("NAME").
     11532          Set of environment changes to complement
     11533          <link to="IGuestSession::environment"/>.  Takes precedence over
     11534          the session ones.  The changes are in putenv format, i.e.
     11535          "NAME=VALUE" for setting and "NAME" for unsetting.
     11536
     11537          The changes are applied to the standard environment of the
     11538          impersonated guest user when creating the process.
    1151911539        </desc>
    1152011540      </param>
    1152111541      <param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes">
    1152211542        <desc>
    11523           Process creation flags;
    11524           see <link to="ProcessCreateFlag"/> for more information.
     11543          Process creation flags, see <link to="ProcessCreateFlag"/> for
     11544          detailed description of available flags.
    1152511545        </desc>
    1152611546      </param>
    … …  
    1153511555      <param name="priority" type="ProcessPriority" dir="in">
    1153611556        <desc>
    11537           Process priority to use for execution;
    11538           see see <link to="ProcessPriority"/> for more information.</desc>
     11557          Process priority to use for execution, see <link to="ProcessPriority"/>
     11558          for available priority levels.
     11559          <note>This is silently ignored if not supported by guest additions.</note>
     11560        </desc>
    1153911561      </param>
    1154011562      <param name="affinity" type="long" dir="in" safearray="yes">
    1154111563        <desc>
    11542           Process affinity to use for execution. This parameter
    11543           is not implemented yet.
     11564          Processor affinity to set for the new process.  This is a list of
     11565          guest CPU numbers the process is allowed to run on.
     11566          <note>
     11567            This is silently ignored if the guest does not support setting the
     11568            affinity of processes, or if the guest additions does not implemet
     11569            this feature.
     11570          </note>
    1154411571        </desc>
    1154511572      </param>
    … …  
    1156311590    <method name="symlinkCreate">
    1156411591      <desc>
    11565         Creates a symbolic link on the guest.
     11592        Creates a symbolic link in the guest.
    1156611593
    1156711594        <result name="E_NOTIMPL">
    … …  
    1158511612    <method name="symlinkExists">
    1158611613      <desc>
    11587         Checks whether a symbolic link exists on the guest or not.
     11614        Checks whether a symbolic link exists in the guest.
    1158811615
    1158911616        <result name="E_NOTIMPL">
    … …  
    1160111628    <method name="symlinkRead">
    1160211629      <desc>
    11603         Reads a symbolic link on the guest.
     11630        Reads a symbolic link in the guest.
    1160411631
    1160511632        <result name="E_NOTIMPL">
    … …  
    1162411651    <method name="symlinkRemoveDirectory">
    1162511652      <desc>
    11626         Removes a symbolic link on the guest if it's a directory.
     11653        Removes a symbolic link in the guest if it's a directory.
    1162711654
    1162811655        <result name="E_NOTIMPL">
    … …  
    1163711664    <method name="symlinkRemoveFile">
    1163811665      <desc>
    11639         Removes a symbolic link on the guest if it's a file.
     11666        Removes a symbolic link in the guest if it's a file.
    1164011667
    1164111668        <result name="E_NOTIMPL">
    … …  
    1171411741    </attribute>
    1171511742    <attribute name="environment" type="wstring" readonly="yes" safearray="yes">
    11716       <desc>
    11717         The environment block this process is using during execution.
     11743      <!-- r=bird: Would probably be a great idea to rename this attribute as
     11744                   it is misleading and will cause worse confusion if we ever
     11745                   expose the initial environment for processes.  -->
     11746      <desc>
     11747        The set of environment changes appled to the default environment when
     11748        starting the process.  The format is putenv style, i.e. "NAME=VALUE"
     11749        for variables that should be set and "NAME" for values that should be
     11750        unset (removed).  See also <link to="IGuestSession::environment"/>.
    1171811751      </desc>
    1171911752    </attribute>
    … …  
    1189511928    <desc>
    1189611929      Implementation of the <link to="IProcess" /> object
    11897       for processes on the guest.
     11930      for processes the host has started in the guest.
    1189811931    </desc>
    1189911932  </interface>
    … …  
    1194811981    <desc>
    1194911982      Implementation of the <link to="IDirectory" /> object
    11950       for directories on the guest.
     11983      for directories in the guest.
    1195111984    </desc>
    1195211985  </interface>
    … …  
    1216312196    <desc>
    1216412197      Implementation of the <link to="IFile" /> object
    12165       for files on the guest.
     12198      for files in the guest.
    1216612199    </desc>
    1216712200  </interface>
    … …  
    1249412527        call.
    1249512528
    12496         A guest session represents one impersonated user account on the guest, so
     12529        A guest session represents one impersonated user account in the guest, so
    1249712530        every operation will use the same credentials specified when creating
    1249812531        the session object via <link to="IGuest::createSession"/>. Anonymous
    1249912532        sessions, that is, sessions without specifying a valid
    12500         user account on the guest are not allowed due to security reasons.
     12533        user account in the guest are not allowed due to security reasons.
    1250112534
    1250212535        There can be a maximum of 32 sessions at once per VM. Each session keeps
    … …  
    1260612639          Optional command line arguments to use for the Guest Additions
    1260712640          installer. Useful for retrofitting features which weren't installed
    12608           before on the guest.
     12641          before in the guest.
    1260912642        </desc>
    1261012643      </param>
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