VirtualBox

Ignore:
Timestamp:
Jun 25, 2009 11:53:37 AM (16 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
49096
Message:

API/others: Renamed IConsole::discardSavedState to IConsole::forgetSavedState, added parameter. Deleted old IConsole::powerDown, renamed IConsole::powerDownAsync to IConsole::powerDown (as promised for 2.1). Implemented perl sample code for registering a hard disk. Cleaned up constant formatting in the API docs. Updated SDK changelog. Renamed com/errorprint2.h to com/errorprint.h, added a few assertion variants. Eliminated com/errorprint_legacy.h. Adjusted all files using the affected headers and APIs. Renamed tstHeadless2 to tstHeadless.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r20897 r20928  
    233233      <td>
    234234        Returned if a memory pointer for the output argument is invalid (for
    235         example, <tt>NULL</tt>). Note that when pointers representing input
     235        example, @c null). Note that when pointers representing input
    236236        arguments (such as strings) are invalid, E_INVALIDARG is returned.
    237237      </td>
    … …  
    494494        needed: for any online VM state, the condition
    495495        <tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be
    496         <tt>true</tt>. The same relates to transient states for which
     496        @c true. The same relates to transient states for which
    497497        the condition <tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be
    498         <tt>true</tt>.
     498        @c true.
    499499      </note>
    500500    </desc>
    … …  
    10271027      <desc>
    10281028        Notification when someone tries to change extra data for
    1029         either the given machine or (if null) global extra data.
     1029        either the given machine or (if @c null) global extra data.
    10301030        This gives the chance to veto against changes.
    10311031      </desc>
    … …  
    10331033        <desc>
    10341034          ID of the machine this event relates to
    1035           (null ID for global extra data change requests).
     1035          (@c null ID for global extra data change requests).
    10361036        </desc>
    10371037      </param>
    … …  
    11181118      <param name="registered" type="boolean" dir="in">
    11191119        <desc>
    1120           If true, the media was registered, otherwise it was
     1120          If @c true, the media was registered, otherwise it was
    11211121          unregistered.
    11221122        </desc>
    … …  
    11341134      <param name="registered" type="boolean" dir="in">
    11351135        <desc>
    1136           If true, the machine was registered, otherwise it was
     1136          If @c true, the machine was registered, otherwise it was
    11371137          unregistered.
    11381138        </desc>
    … …  
    11831183      <param name="snapshotId" type="wstring" dir="in">
    11841184        <desc>
    1185           ID of the discarded snapshot. <tt>null</tt> means the
    1186           current machine state has been discarded (restored from
    1187           the current snapshot).
     1185          ID of the discarded snapshot. @c null means the current machine
     1186          state has been discarded (restored from the current snapshot).
    11881187        </desc>
    11891188      </param>
    … …  
    13441343  <interface
    13451344    name="IVirtualBox" extends="$dispatched"
    1346     uuid="54bf05ec-3fa9-4735-b92e-76e7c6c7e2be"
     1345    uuid="3f4ab53a-199b-4526-a91a-93ff62e456b8"
    13471346    wsmap="managed"
    13481347  >
    … …  
    14191418          x.y-platform
    14201419        </pre>
    1421         where <tt>x</tt> and <tt>y</tt> are the major and the minor format
    1422         versions, and <tt>platform</tt> is the platform identifier.
     1420        where @c x and @c y are the major and the minor format
     1421        versions, and @c platform is the platform identifier.
    14231422
    14241423        The current version usually matches the value of the
    … …  
    14551454          x.y-platform
    14561455        </pre>
    1457         where <tt>x</tt> and <tt>y</tt> are the major and the minor format
    1458         versions, and <tt>platform</tt> is the platform identifier.
     1456        where @c x and @c y are the major and the minor format
     1457        versions, and @c platform is the platform identifier.
    14591458
    14601459        VirtualBox uses this version of the format when saving settings files
    … …  
    15821581        directory</link>.
    15831582
    1584         If @a baseFolder is a null or empty string (which is recommended), the
     1583        If @a baseFolder is a @c null or empty string (which is recommended), the
    15851584        <link to="ISystemProperties::defaultMachineFolder">default machine
    15861585        settings folder</link> will be used as a base folder for the created
    … …  
    15971596        Optionally, you may specify an UUID of to assign to the created machine.
    15981597        However, this is not recommended and you should normally pass an empty
    1599         (null) UUID to this method so that a new UUID will be automatically
     1598        (@c null) UUID to this method so that a new UUID will be automatically
    16001599        generated for every created machine. You can use UUID
    1601         00000000-0000-0000-0000-000000000000 as null value.
     1600        00000000-0000-0000-0000-000000000000 as @c null value.
    16021601
    16031602        <note>
    … …  
    16141613        </result>
    16151614        <result name="E_INVALIDARG">
    1616           @a name is empty or null.
     1615          @a name is empty or @c null.
    16171616        </result>
    16181617      </desc>
    … …  
    16741673        </result>
    16751674        <result name="E_INVALIDARG">
    1676           @a name or @a settingsFile is empty or null.
     1675          @a name or @a settingsFile is empty or @c null.
    16771676        </result>
    16781677      </desc>
    … …  
    17221721      <note>
    17231722        <link to="IMachine::settingsModified"/> will return
    1724         false for the created machine, until any of machine settings
     1723        @c false for the created machine, until any of machine settings
    17251724        are changed.
    17261725      </note>
    … …  
    18671866        installation can be obtained using
    18681867        <link to="ISystemProperties::hardDiskFormats"/>. If the @a format
    1869         attribute is empty or <tt>null</tt> then the default storage format
     1868        attribute is empty or @c null then the default storage format
    18701869        specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
    18711870        be used for creating a storage unit of the hard disk.
    … …  
    18831882        </result>
    18841883        <result name="E_INVALIDARG">
    1885           @a format is a null or empty string.
     1884          @a format is a @c null or empty string.
    18861885        </result>
    18871886      </desc>
    … …  
    20792078        <desc>
    20802079          UUID to assign to the given image within this VirtualBox installation.
    2081           If an empty (null) UUID is specified, the system will randomly
     2080          If an empty (@c null) UUID is specified, the system will randomly
    20822081          generate a new UUID.
    20832082        </desc>
    … …  
    21792178        <desc>
    21802179          UUID to assign to the given image file within this VirtualBox
    2181           installation. If an empty (null) UUID is specified, the system will
     2180          installation. If an empty (@c null) UUID is specified, the system will
    21822181          randomly generate a new UUID.
    21832182        </desc>
    … …  
    23132312        Returns the global extra data key name following the supplied key.
    23142313
    2315         An error is returned if the supplied @a key does not exist. @c NULL is
     2314        An error is returned if the supplied @a key does not exist. @c null is
    23162315        returned in @a nextKey if the supplied key is the last key. When
    2317         supplying @c NULL or an empty string for the @a key, the first key item
     2316        supplying @c null or an empty string for the @a key, the first key item
    23182317        is returned in @a nextKey (if there is any). @a nextValue is an optional
    23192318        parameter and if supplied, the next key's value is returned in it.
    … …  
    23402339
    23412340        If the requested data @a key does not exist, this function will
    2342         succeed and return @c NULL in the @a value argument.
     2341        succeed and return @c null in the @a value argument.
    23432342
    23442343        <result name="VBOX_E_FILE_ERROR">
    … …  
    23622361        Sets associated global extra data.
    23632362
    2364         If you pass @c NULL as a key @a value, the given @a key will be
     2363        If you pass @c null as a key @a value, the given @a key will be
    23652364        deleted.
    23662365
    … …  
    25212520        argument) are:
    25222521        <ul>
    2523           <li><tt>gui</tt>: VirtualBox Qt GUI session</li>
    2524           <li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>
    2525           <li><tt>sdl</tt>: VirtualBox SDL GUI session</li>
     2522          <li><tt>"gui"</tt>: VirtualBox Qt GUI session</li>
     2523          <li><tt>"vrdp"</tt>: VirtualBox VRDP Server session</li>
     2524          <li><tt>"sdl"</tt>: VirtualBox SDL GUI session</li>
    25262525        </ul>
    25272526
    … …  
    26492648
    26502649        <result name="E_INVALIDARG">
    2651           A @c NULL callback cannot be registered.
     2650          A @c null callback cannot be registered.
    26522651        </result>
    26532652
    … …  
    28072806
    28082807        If the given backup file already exists, this method will try to add the
    2809         <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
     2808        <tt>.N</tt> suffix to the backup file name (where @c N counts from
    28102809        0 to 9) and copy it again until it succeeds. If all suffixes are
    28112810        occupied, or if any other copy error occurs, this method will return a
    … …  
    36643663        the configuration remains unchanged. Please see the documentation for getDescription()
    36653664        for valid configuration values for the individual array item types. If the
    3666         corresponding item in the aEnabled array is false, the configuration value is ignored.
     3665        corresponding item in the aEnabled array is @c false, the configuration value is ignored.
    36673666      </desc>
    36683667
    … …  
    37103709  <interface
    37113710     name="IInternalMachineControl" extends="$unknown"
    3712      uuid="5595cae1-6b18-42c1-b416-bc7493a87618"
     3711     uuid="ce8087d7-de92-4bbb-8140-a22fb07f37ba"
    37133712     internal="yes"
    37143713     wsmap="suppress"
    37153714     >
     3715    <method name="setRemoveSavedState">
     3716      <desc>
     3717        Updates the flag whether saved state is removed on a machine state
     3718        change from Saved to PowerOff.
     3719      </desc>
     3720      <param name="aRemove" type="boolean" dir="in"/>
     3721    </method>
     3722
    37163723    <method name="updateState">
    37173724      <desc>
    … …  
    37583765    <method name="detachUSBDevice">
    37593766      <desc>
    3760         Notification that a VM is going to detach (done = false) or has
    3761         already detached (done = true) the given USB device.
    3762         When the done = true request is completed, the VM process will
     3767        Notification that a VM is going to detach (@a done = @c false) or has
     3768        already detached (@a done = @c true) the given USB device.
     3769        When the @a done = @c true request is completed, the VM process will
    37633770        get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
    37643771        notification.
    37653772        <note>
    3766           In the done = true case, the server must run its own filters
     3773          In the @a done = @c true case, the server must run its own filters
    37673774          and filters of all VMs but this one on the detached device
    37683775          as if it were just attached to the host computer.
    … …  
    37863793        Notification that a VM that is being powered down. The done
    37873794        parameter indicates whether which stage of the power down
    3788         we're at. When done = false the VM is announcing its
    3789         intentions, while when done = true the VM is reporting
     3795        we're at. When @a done = @c false the VM is announcing its
     3796        intentions, while when @a done = @c true the VM is reporting
    37903797        what it has done.
    37913798        <note>
    3792           In the done = true case, the server must run its own filters
     3799          In the @a done = @c true case, the server must run its own filters
    37933800          and filters of all VMs but this one on all detach devices as
    37943801          if they were just attached to the host computer.
    … …  
    38493856
    38503857      <param name="success" type="boolean" dir="in">
    3851         <desc><tt>true</tt> to indicate success and <tt>false</tt>
    3852           otherwise.
     3858        <desc>@c true to indicate success and @c false otherwise.
    38533859        </desc>
    38543860      </param>
    … …  
    39153921
    39163922      <param name="success" type="boolean" dir="in">
    3917         <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
     3923        <desc>@c true to indicate success and @c false otherwise</desc>
    39183924      </param>
    39193925    </method>
    … …  
    41974203        </ul>
    41984204
    4199         Otherwise, the value of this property is always <tt>true</tt>.
     4205        Otherwise, the value of this property is always @c true.
    42004206
    42014207        Every time this property is read, the accessibility state of
    4202         this machine is re-evaluated. If the returned value is |false|,
     4208        this machine is re-evaluated. If the returned value is @c false,
    42034209        the <link to="#accessError"/> property may be used to get the
    42044210        detailed error information describing the reason of
    … …  
    42264232        <note>
    42274233          In the current implementation, once this property returns
    4228           <tt>true</tt>, the machine will never become inaccessible
     4234          @c true, the machine will never become inaccessible
    42294235          later, even if its settings file cannot be successfully
    42304236          read/written any more (at least, until the VirtualBox
    … …  
    42414247
    42424248        Reading this property is only valid after the last call to
    4243         <link to="#accessible"/> returned <tt>false</tt> (i.e. the
    4244         machine is currently unaccessible). Otherwise, a null
     4249        <link to="#accessible"/> returned @c false (i.e. the
     4250        machine is currently unaccessible). Otherwise, a @c null
    42454251        IVirtualBoxErrorInfo object will be returned.
    42464252      </desc>
    … …  
    44164422
    44174423        <note>
    4418           Setting this property to <tt>null</tt> will restore the
     4424          Setting this property to @c null will restore the
    44194425          initial value.
    44204426        </note>
    … …  
    44834489          x.y-platform
    44844490        </pre>
    4485         where <tt>x</tt> and <tt>y</tt> are the major and the minor format
    4486         versions, and <tt>platform</tt> is the platform identifier.
     4491        where @c x and @c y are the major and the minor format
     4492        versions, and @c platform is the platform identifier.
    44874493
    44884494        The current version usually matches the value of the
    … …  
    45264532        <note>
    45274533          For newly created unregistered machines, the value of this
    4528           property is always TRUE until <link to="#saveSettings"/>
     4534          property is always @c true until <link to="#saveSettings"/>
    45294535          is called (no matter if any machine settings have been
    45304536          changed after the creation or not). For opened machines
    4531           the value is set to FALSE (and then follows to normal rules).
     4537          the value is set to @c false (and then follows to normal rules).
    45324538        </note>
    45334539      </desc>
    … …  
    45794585        the machine when it is in the <link to="MachineState_Saved"/> state.
    45804586        <note>
    4581           When the machine is not in the Saved state, this attribute
    4582           <tt>null</tt>.
     4587          When the machine is not in the Saved state, this attribute is
     4588          @c null.
    45834589        </note>
    45844590      </desc>
    … …  
    45994605        Current snapshot of this machine.
    46004606        <note>
    4601           A <tt>null</tt> object is returned if the machine doesn't
     4607          A @c null object is returned if the machine doesn't
    46024608          have snapshots.
    46034609        </note>
    … …  
    46154621    <attribute name="currentStateModified" type="boolean" readonly="yes">
    46164622      <desc>
    4617         Returns <tt>true</tt> if the current state of the machine is not
     4623        Returns @c true if the current state of the machine is not
    46184624        identical to the state stored in the current snapshot.
    46194625
    … …  
    46264632          <li><link to="IConsole::takeSnapshot"/> (issued on a
    46274633            powered off or saved machine, for which
    4628             <link to="#settingsModified"/> returns <tt>false</tt>)
     4634            <link to="#settingsModified"/> returns @c false)
    46294635          </li>
    46304636          <li><link to="IMachine::setCurrentSnapshot"/>
    … …  
    46434649        <note>
    46444650          For machines that don't have snapshots, this property is
    4645           always <tt>false</tt>.
     4651          always @c false.
    46464652        </note>
    46474653      </desc>
    … …  
    46954701      <param name="position" type="unsigned long" dir="in">
    46964702        <desc>
    4697           Position in the boot order (<tt>1</tt> to the total number of
     4703          Position in the boot order (@c 1 to the total number of
    46984704          devices the machine can boot from, as returned by
    46994705          <link to="ISystemProperties::maxBootPosition"/>).
    … …  
    47294735      <param name="position" type="unsigned long" dir="in">
    47304736        <desc>
    4731           Position in the boot order (<tt>1</tt> to the total number of
     4737          Position in the boot order (@c 1 to the total number of
    47324738          devices the machine can boot from, as returned by
    47334739          <link to="ISystemProperties::maxBootPosition"/>).
    … …  
    50075013        supplied key.
    50085014
    5009         An error is returned if the supplied @a key does not exist. @c NULL is
     5015        An error is returned if the supplied @a key does not exist. @c null is
    50105016        returned in @a nextKey if the supplied key is the last key. When
    5011         supplying @c NULL for the @a key, the first key item is returned in
     5017        supplying @c null for the @a key, the first key item is returned in
    50125018        @a nextKey (if there is any). @a nextValue is an optional parameter and
    50135019        if supplied, the next key's value is returned in it.
    … …  
    50345040
    50355041        If the requested data @a key does not exist, this function will
    5036         succeed and return @c NULL in the @a value argument.
     5042        succeed and return @c null in the @a value argument.
    50375043
    50385044        <result name="VBOX_E_FILE_ERROR">
    … …  
    50565062        Sets associated machine-specific extra data.
    50575063
    5058         If you pass @c NULL as a key @a value, the given @a key will be
     5064        If you pass @c null as a key @a value, the given @a key will be
    50595065        deleted.
    50605066
    … …  
    51495155
    51505156        If the given backup file already exists, this method will try to add the
    5151         <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
     5157        <tt>.N</tt> suffix to the backup file name (where @c N counts from
    51525158        0 to 9) and copy it again until it succeeds. If all suffixes are
    51535159        occupied, or if any other copy error occurs, this method will return a
    … …  
    52155221        to succeed.
    52165222        <note>
    5217           <link to="#settingsModified"/> will return TRUE after this
     5223          <link to="#settingsModified"/> will return @c true after this
    52185224          method successfully returns.
    52195225        </note>
    … …  
    52585264      <desc>
    52595265        Returns a snapshot of this machine with the given UUID.
    5260         A <tt>null</tt> UUID can be used to obtain the first snapshot
     5266        A @c null UUID can be used to obtain the first snapshot
    52615267        taken on this machine. This is useful if you want to traverse
    52625268        the whole tree of snapshots starting from the root.
    … …  
    53675373      <param name="canShow" type="boolean" dir="return">
    53685374        <desc>
    5369           @c true if the console window can be shown and @c
    5370           false otherwise.
     5375          @c true if the console window can be shown and @c false otherwise.
    53715376        </desc>
    53725377      </param>
    … …  
    55645569        <desc>
    55655570          The patterns to match the properties against, separated by '|'
    5566           characters.  If this is empty or NULL, all properties will match.
     5571          characters.  If this is empty or @c null, all properties will match.
    55675572        </desc>
    55685573      </param>
    … …  
    58295834      <param name="attached" type="boolean" dir="in">
    58305835        <desc>
    5831           <tt>true</tt> if the device was attached
    5832           and <tt>false</tt> otherwise.
     5836          @c true if the device was attached and @c false otherwise.
    58335837        </desc>
    58345838      </param>
    58355839      <param name="error" type="IVirtualBoxErrorInfo" dir="in">
    58365840        <desc>
    5837           <tt>null</tt> on success or an error message object on
    5838           failure.
     5841          @c null on success or an error message object on failure.
    58395842        </desc>
    58405843      </param>
    … …  
    58725875
    58735876        <b>Fatal</b> errors are indicated by the @a fatal parameter set
    5874         to <tt>true</tt>. In case of fatal errors, the virtual machine
     5877        to @c true. In case of fatal errors, the virtual machine
    58755878        execution is always paused before calling this notification, and
    58765879        the notification handler is supposed either to immediately save
    … …  
    58805883
    58815884        <b>Non-fatal</b> errors and warnings are indicated by the
    5882         @a fatal parameter set to <tt>false</tt>. If the virtual machine
     5885        @a fatal parameter set to @c false. If the virtual machine
    58835886        is in the Paused state by the time the error notification is
    58845887        received, it means that the user can <i>try to resume</i> the machine
    … …  
    59535956      <param name="canShow" type="boolean" dir="return">
    59545957        <desc>
    5955           @c true if the console window can be shown and @c
    5956           false otherwise.
     5958          @c true if the console window can be shown and @c false otherwise.
    59575959        </desc>
    59585960      </param>
    … …  
    61096111  <interface
    61106112     name="IConsole" extends="$unknown"
    6111      uuid="a7f17a42-5b64-488d-977b-4b2c639ada27"
     6113     uuid="0a51994b-cbc6-4686-94eb-d4e4023280e2"
    61126114     wsmap="managed"
    61136115     >
    … …  
    62976299    <method name="powerDown">
    62986300      <desc>
    6299         Stops the virtual machine execution.
    6300         After this operation completes, the machine will go to the
    6301         PoweredOff state.
    6302 
    6303         @deprecated This method will be removed in VirtualBox 2.1 where the
    6304         powerDownAsync() method will take its name. Do not use this method in
    6305         the code.
    6306         <result name="VBOX_E_INVALID_VM_STATE">
    6307           Virtual machine must be Running, Paused or Stuck to be powered down.
    6308         </result>
    6309         <result name="VBOX_E_VM_ERROR">
    6310           Unable to power off or destroy virtual machine.
    6311         </result>
    6312       </desc>
    6313     </method>
    6314 
    6315     <method name="powerDownAsync">
    6316       <desc>
    63176301        Initiates the power down procedure to stop the virtual machine
    63186302        execution.
    … …  
    63216305        IProgress object. After the operation is complete, the machine will go
    63226306        to the PoweredOff state.
    6323 
    6324         @warning This method will be renamed to "powerDown" in VirtualBox 2.1
    6325         where the original powerDown() method will be removed. You will need to
    6326         rename "powerDownAsync" to "powerDown" in your sources to make them
    6327         build with version 2.1.
    63286307        <result name="VBOX_E_INVALID_VM_STATE">
    63296308          Virtual machine must be Running, Paused or Stuck to be powered down.
    … …  
    64016380    <method name="getGuestEnteredACPIMode">
    64026381      <desc>Checks if the guest entered the ACPI mode G0 (working) or
    6403         G1 (sleeping). If this method returns false, the guest will
     6382        G1 (sleeping). If this method returns @c false, the guest will
    64046383        most likely not respond to external ACPI events.
    64056384        <result name="VBOX_E_INVALID_VM_STATE">
    … …  
    64836462    </method>
    64846463
    6485     <method name="discardSavedState">
    6486       <desc>
    6487         Discards (deletes) the saved state of the virtual machine
    6488         previously created by <link to="#saveState"/>. Next time the
    6489         machine is powered up, a clean boot will occur.
     6464    <method name="forgetSavedState">
     6465      <desc>
     6466        Forgets the saved state of the virtual machine previously created
     6467        by <link to="#saveState"/>. Next time the machine is powered up, a
     6468        clean boot will occur. If @a remove is @c true the saved state file
     6469        is deleted.
    64906470        <note>
    64916471          This operation is equivalent to resetting or powering off
    … …  
    64966476        </result>
    64976477      </desc>
     6478      <param name="remove" type="boolean" dir="in">
     6479        <desc>If @c true remove the saved state file.</desc>
     6480      </param>
    64986481    </method>
    64996482
    … …  
    67086691        children at all (i.e. the first snapshot is the only snapshot of
    67096692        the machine), both the current and the first snapshot of the
    6710         machine will be set to null. In all other cases, the first
     6693        machine will be set to @c null. In all other cases, the first
    67116694        snapshot cannot be discarded.
    67126695
    … …  
    67996782          If the machine state is <link to="MachineState_Saved">Saved</link>
    68006783          prior to this operation, the saved state file will be implicitly
    6801           discarded (as if <link to="IConsole::discardSavedState"/> were
     6784          discarded (as if <link to="IConsole::forgetSavedState"/> were
    68026785          called).
    68036786        </note>
    … …  
    68456828          If the machine state is <link to="MachineState_Saved">Saved</link>
    68466829          prior to this operation, the saved state file will be implicitly
    6847           discarded (as if <link to="#discardSavedState"/> were
     6830          discarded (as if <link to="#forgetSavedState"/> were
    68486831          called).
    68496832        </note>
    … …  
    72457228      <param name="description" type="wstring" dir="return">
    72467229        <desc>
    7247           Model string. A NULL string is returned if value is not known or
     7230          Model string. A @c null string is returned if value is not known or
    72487231          @a cpuId is invalid.
    72497232        </desc>
    … …  
    72727255
    72737256    <attribute name="Acceleration3DAvailable" type="boolean" readonly="yes">
    7274       <desc>Returns true when the host supports 3D hardware acceleration.</desc>
     7257      <desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
    72757258    </attribute>
    72767259
    … …  
    73217304      <desc>
    73227305        Creates a new USB device filter. All attributes except
    7323         the filter name are set to <tt>null</tt> (any match),
    7324         <i>active</i> is <tt>false</tt> (the filter is not active).
     7306        the filter name are set to @c null (any match),
     7307        <i>active</i> is @c false (the filter is not active).
    73257308
    73267309        The created filter can be added to the list of filters using
    … …  
    73457328        in the list of filters.
    73467329
    7347         Positions are numbered starting from <tt>0</tt>. If the specified
     7330        Positions are numbered starting from @c 0. If the specified
    73487331        position is equal to or greater than the number of elements in
    73497332        the list, the filter is added at the end of the collection.
    … …  
    73817364        list of filters.
    73827365
    7383         Positions are numbered starting from <tt>0</tt>. Specifying a
     7366        Positions are numbered starting from @c 0. Specifying a
    73847367        position equal to or greater than the number of elements in
    73857368        the list will produce an error.
    … …  
    76137596
    76147597        <note>
    7615           Setting this property to <tt>null</tt> will restore the
     7598          Setting this property to @c null will restore the
    76167599          initial value.
    76177600        </note>
    … …  
    76517634
    76527635        <note>
    7653           Setting this property to <tt>null</tt> will restore the
    7654           initial value.
     7636          Setting this property to @c null will restore the initial value.
    76557637        </note>
    76567638        <note>
    … …  
    77077689        The hard disk format set by this attribute is used by VirtualBox
    77087690        when the hard disk format was not specified explicitly. One example is
    7709         <link to="IVirtualBox::createHardDisk"/> with the <tt>null</tt>
     7691        <link to="IVirtualBox::createHardDisk"/> with the @c null
    77107692        format argument. A more complex example is implicit creation of
    77117693        differencing hard disks when taking a snapshot of a virtual machine:
    … …  
    77207702        unexpectedly.
    77217703
    7722         The initial value of this property is <tt>VDI</tt> in the current
     7704        The initial value of this property is <tt>"VDI"</tt> in the current
    77237705        version of the VirtualBox product, but may change in the future.
    77247706
    77257707        <note>
    7726           Setting this property to <tt>null</tt> will restore the
    7727           initial value.
     7708          Setting this property to @c null will restore the initial value.
    77287709        </note>
    77297710
    … …  
    77467727        system's default library path.
    77477728
    7748         The default value of this property is <tt>VRDPAuth</tt>. There is a library
     7729        The default value of this property is <tt>"VRDPAuth"</tt>. There is a library
    77497730        of that name in one of the default VirtualBox library directories.
    77507731
    … …  
    77537734
    77547735        <note>
    7755           Setting this property to <tt>null</tt> will restore the
     7736          Setting this property to @c null will restore the
    77567737          initial value.
    77577738        </note>
    … …  
    77697750        there is no per-VM setting for this, as the webservice is a global
    77707751        resource (if it is running). Only for this setting (for the webservice),
    7771         setting this value to a literal "null" string disables authentication,
     7752        setting this value to a literal <tt>"null"</tt> string disables authentication,
    77727753        meaning that <link to="IWebsessionManager::logon" /> will always succeed,
    77737754        no matter what user name and password are supplied.
    77747755
    7775         The initial value of this property is <tt>VRDPAuth</tt>,
     7756        The initial value of this property is <tt>"VRDPAuth"</tt>,
    77767757        meaning that the webservice will use the same authentication
    77777758        library that is used by default for VBoxVRDP (again, see
    … …  
    80107991        create and manipulate progress objects, whereas client code
    80117992        can only use the IProgress object to monitor a task's
    8012         progress and, if <link to="#cancelable" /> is true,
     7993        progress and, if <link to="#cancelable" /> is @c true,
    80137994        cancel the task by calling <link to="#cancel" />.
    80147995
    … …  
    80508031        Current progress value of the task as a whole, in percent.
    80518032        This value depends on how many operations are already complete.
    8052         Returns 100 if <link to="#completed" /> is true.
     8033        Returns 100 if <link to="#completed" /> is @c true.
    80538034      </desc>
    80548035    </attribute>
    … …  
    80798060      <desc>
    80808061        Result code of the progress task.
    8081         Valid only if <link to="#completed"/> is true.
     8062        Valid only if <link to="#completed"/> is @c true.
    80828063      </desc>
    80838064    </attribute>
    … …  
    80868067      <desc>
    80878068        Extended information about the unsuccessful result of the
    8088         progress operation. May be NULL if no extended information
     8069        progress operation. May be @c null if no extended information
    80898070        is available.
    8090         Valid only if <link to="#completed"/> is true and
     8071        Valid only if <link to="#completed"/> is @c true and
    80918072        <link to="#resultCode"/> indicates a failure.
    80928073      </desc>
    … …  
    81588139        Cancels the task.
    81598140        <note>
    8160           If <link to="#cancelable"/> is <tt>false</tt>, then
    8161           this method will fail.
     8141          If <link to="#cancelable"/> is @c false, then this method will fail.
    81628142        </note>
    81638143
    … …  
    82368216      cannot be changed.
    82378217
    8238       The current snapshot is <tt>null</tt> if the machine doesn't have
     8218      The current snapshot is @c null if the machine doesn't have
    82398219      snapshots at all; in this case the current machine state is just
    82408220      current settings of this machine plus its current execution state.
    … …  
    83378317    <attribute name="online" type="boolean" readonly="yes">
    83388318      <desc>
    8339         <tt>true</tt> if this snapshot is an online snapshot and
    8340         <tt>false</tt> otherwise.
    8341 
    8342         <note>
    8343           When this attribute is <tt>true</tt>, the
     8319        @c true if this snapshot is an online snapshot and @c false otherwise.
     8320
     8321        <note>
     8322          When this attribute is @c true, the
    83448323          <link to="IMachine::stateFilePath"/> attribute of the
    83458324          <link to="#machine"/> object associated with this snapshot
    83468325          will point to the saved state file. Otherwise, it will be
    8347           <tt>null</tt>.
     8326          @c null.
    83488327        </note>
    83498328      </desc>
    … …  
    83668345        <note>
    83678346          It's not an error to read this attribute on a snapshot
    8368           that doesn't have a parent -- a null object will be
     8347          that doesn't have a parent -- a @c null object will be
    83698348          returned to indicate this.
    83708349        </note>
    … …  
    85228501      created for the first time), all known media are in the
    85238502      <link to="MediaState_Inaccessible"/> state but the value of the <link
    8524       to="#lastAccessError"/> attribute is <tt>null</tt> because no actual
     8503      to="#lastAccessError"/> attribute is @c null because no actual
    85258504      accessibility check is made on startup. This is done to make the
    85268505      VirtualBox object ready for serving requests as
    … …  
    85458524      <desc>
    85468525        Optional description of the medium. For newly created media, the value
    8547         of this attribute value is <tt>null</tt>.
     8526        of this attribute value is @c null.
    85488527
    85498528        Media types that don't support this attribute will return E_NOTIMPL in
    … …  
    85808559        medium is <link to="MediaState_LockedRead"/> or
    85818560        <link to="MediaState_LockedWrite"/> then it remains the same, and a
    8582         non-null value of <link to="#lastAccessError"/> will indicate a failed
     8561        non-@c null value of <link to="#lastAccessError"/> will indicate a failed
    85838562        accessibility check in this case.
    85848563
    … …  
    86538632        Accessibility checks are performed each time the <link to="#state"/>
    86548633        attribute is read. A @c null string is returned if the last
    8655         accessibility check was successful. A non-null string indicates a
     8634        accessibility check was successful. A non-@c null string indicates a
    86568635        failure and should normally describe a reason of the failure (for
    86578636        example, a file read error).
    … …  
    86638642        Array of UUIDs of all machines this medium is attached to.
    86648643
    8665         A <tt>null</tt> array is returned if this medium is not attached to any
     8644        A @c null array is returned if this medium is not attached to any
    86668645        machine or to any machine's snapshot.
    86678646
    … …  
    86888667        the array will contain only snapshot IDs.
    86898668
    8690         The returned array may be <tt>null</tt> if this medium is not attached
     8669        The returned array may be @c null if this medium is not attached
    86918670        to the given machine at all, neither in the current state nor in one of
    86928671        the snapshots.
    … …  
    90289007      querying the <link to="#parent"/> attribute: base hard disks do not have
    90299008      parents they would depend on, so the value of this attribute is always
    9030       <tt>null</tt> for them. Using this attribute, it is possible to walk up
     9009      @c null for them. Using this attribute, it is possible to walk up
    90319010      the hard disk tree (from the child hard disk to its parent). It is also
    90329011      possible to walk down the tree using the <link to="#children"/>
    … …  
    93109289
    93119290        Only differencing hard disks have parents. For base (non-differencing)
    9312         hard disks, <tt>null</tt> is returned.
     9291        hard disks, @c null is returned.
    93139292      </desc>
    93149293    </attribute>
    … …  
    93179296      <desc>
    93189297        Children of this hard disk (all differencing hard disks directly based
    9319         on this hard disk). A <tt>null</tt> array is returned if this hard disk
     9298        on this hard disk). A @c null array is returned if this hard disk
    93209299        does not have any children.
    93219300      </desc>
    … …  
    93359314    <attribute name="readOnly" type="boolean" readonly="yes">
    93369315      <desc>
    9337         Returns <tt>true</tt> if this hard disk is read-only and <tt>false</tt>
    9338         otherwise.
     9316        Returns @c true if this hard disk is read-only and @c false otherwise.
    93399317
    93409318        A hard disk is considered to be read-only when its contents cannot be
    … …  
    93479325        The value of this attribute can be used to determine the kind of the
    93489326        attachment that will take place when attaching this hard disk to a
    9349         virtual machine. If the value is <tt>false</tt> then the hard disk will
    9350         be attached directly. If the value is <tt>true</tt> then the hard disk
     9327        virtual machine. If the value is @c false then the hard disk will
     9328        be attached directly. If the value is @c true then the hard disk
    93519329        will be attached indirectly by creating a new differencing child hard
    93529330        disk for that. See the interface description for more information.
    … …  
    93969374        <note>
    93979375          Reading this property on a base (non-differencing) hard disk will
    9398           always <tt>false</tt>. Changing the value of this property in this
     9376          always @c false. Changing the value of this property in this
    93999377          case is not supported.
    94009378        </note>
    … …  
    94169394        be obtained with <link to="IHardDiskFormat::describeProperties"/>.
    94179395
    9418         Note that if this method returns a <tt>null</tt> @a value, the requested
     9396        Note that if this method returns a @c null @a value, the requested
    94199397        property is supported but currently not assigned any value.
    94209398
    … …  
    94229400          Requested property does not exist (not supported by the format).
    94239401        </result>
    9424         <result name="E_INVALIDARG">@a name is NULL or empty.</result>
     9402        <result name="E_INVALIDARG">@a name is @c null or empty.</result>
    94259403      </desc>
    94269404      <param name="name" type="wstring" dir="in">
    … …  
    94399417        be obtained with <link to="IHardDiskFormat::describeProperties"/>.
    94409418
    9441         Note that setting the property value to <tt>null</tt> is equivalent to
     9419        Note that setting the property value to @c null is equivalent to
    94429420        deleting the existing value. A default value (if it is defined for this
    94439421        property) will be used by the format backend in this case.
    … …  
    94469424          Requested property does not exist (not supported by the format).
    94479425        </result>
    9448         <result name="E_INVALIDARG">@a name is NULL or empty.</result>
     9426        <result name="E_INVALIDARG">@a name is @c null or empty.</result>
    94499427      </desc>
    94509428      <param name="name" type="wstring" dir="in">
    … …  
    94629440        The names of the properties to get are specified using the @a names
    94639441        argument which is a list of comma-separated property names or
    9464         <tt>null</tt> if all properties are to be returned. Note that currently
     9442        @c null if all properties are to be returned. Note that currently
    94659443        the value of this argument is ignored and the method always returns all
    94669444        existing properties.
    … …  
    94769454
    94779455        Note that for properties that do not have assigned values,
    9478         <tt>null</tt> is returned at the appropriate index in the
     9456        @c null is returned at the appropriate index in the
    94799457        @a returnValues array.
    94809458
    … …  
    95149492        be obtained with <link to="IHardDiskFormat::describeProperties"/>.
    95159493
    9516         Note that setting the property value to <tt>null</tt> is equivalent to
     9494        Note that setting the property value to @c null is equivalent to
    95179495        deleting the existing value. A default value (if it is defined for this
    95189496        property) will be used by the format backend in this case.
    … …  
    97379715
    97389716        The @a parent argument defines which hard disk will be the parent
    9739         of the clone. Passing a NULL reference indicates that the clone will
     9717        of the clone. Passing a @c null reference indicates that the clone will
    97409718        be a base image, i.e. completely independent. It is possible to specify
    97419719        an arbitrary hard disk for this parameter, including the parent of the
    … …  
    99409918        Identifier of this format.
    99419919
    9942         The format identifier is a non-null non-empty ASCII string. Note that
     9920        The format identifier is a non-@c null non-empty ASCII string. Note that
    99439921        this string is case-insensitive. This means that, for example, all of
    99449922        the following strings:
    … …  
    99989976        The returned arrays are filled in only if the
    99999977        <link to="HardDiskFormatCapabilities_Properties"/> flag is set.
    10000         All arguments must be non-NULL.
     9978        All arguments must be non-@c null.
    100019979
    100029980        <see>DataType</see>
    … …  
    1037310351      <param name="x" type="long" dir="in">
    1037410352        <desc>
    10375           X coordinate of the pointer in pixels, starting from <tt>1</tt>.
     10353          X coordinate of the pointer in pixels, starting from @c 1.
    1037610354        </desc>
    1037710355      </param>
    1037810356      <param name="y" type="long" dir="in">
    1037910357        <desc>
    10380           Y coordinate of the pointer in pixels, starting from <tt>1</tt>.
     10358          Y coordinate of the pointer in pixels, starting from @c 1.
    1038110359        </desc>
    1038210360      </param>
    … …  
    1039710375            <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
    1039810376          </table>
    10399           A value of <tt>1</tt> means the corresponding button is pressed.
     10377          A value of @c 1 means the corresponding button is pressed.
    1040010378          otherwise it is released.
    1040110379        </desc>
    … …  
    1051010488        visible until the affected portion of IFramebuffer is updated.  The
    1051110489        overlay can be created lazily the first time it is requested.  This
    10512         attribute can also return NULL to signal that the overlay is not
     10490        attribute can also return @c null to signal that the overlay is not
    1051310491        implemented.
    1051410492      </desc>
    … …  
    1059110569        free to choose which mode to use. To indicate that this frame buffer uses
    1059210570        the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
    10593         attribute must return <tt>true</tt> and <link to="#address"/> must
     10571        attribute must return @c true and <link to="#address"/> must
    1059410572        return exactly the same address that is passed in the @a VRAM parameter
    1059510573        of this method; otherwise it is assumed that the indirect strategy is
    … …  
    1067410652        support a given video mode. In case it is not able to render
    1067510653        the video mode (or for some reason not willing), it should
    10676         return false. Usually this method is called when the guest
     10654        return @c false. Usually this method is called when the guest
    1067710655        asks the VMM device whether a given video mode is supported
    1067810656        so the information returned is directly exposed to the guest.
    … …  
    1068910667        Returns the visible region of this frame buffer.
    1069010668
    10691         If the @a rectangles parameter is <tt>NULL</tt> then the value of the
     10669        If the @a rectangles parameter is @c null then the value of the
    1069210670        @a count parameter is ignored and the number of elements necessary to
    1069310671        describe the current visible region is returned in @a countCopied.
    1069410672
    10695         If @a rectangles is not <tt>NULL</tt> but @a count is less
     10673        If @a rectangles is not @c null but @a count is less
    1069610674        than the required number of elements to store region data, the method
    1069710675        will report a failure. If @a count is equal or greater than the
    … …  
    1070810686      </desc>
    1070910687      <param name="rectangles" type="octet" mod="ptr" dir="in">
    10710         <desc>Pointer to the <tt>RTRECT</tt> array to receive region data.</desc>
     10688        <desc>Pointer to the @c RTRECT array to receive region data.</desc>
    1071110689      </param>
    1071210690      <param name="count" type="unsigned long" dir="in">
    10713         <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
     10691        <desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
    1071410692      </param>
    1071510693      <param name="countCopied" type="unsigned long" dir="return">
    … …  
    1074010718      </desc>
    1074110719      <param name="rectangles" type="octet" mod="ptr" dir="in">
    10742         <desc>Pointer to the <tt>RTRECT</tt> array.</desc>
     10720        <desc>Pointer to the @c RTRECT array.</desc>
    1074310721      </param>
    1074410722      <param name="count" type="unsigned long" dir="in">
    10745         <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
     10723        <desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
    1074610724      </param>
    1074710725    </method>
    … …  
    1087010848        after a timeout retry.
    1087110849
    10872         Specifying <tt>0</tt> for either @a width, @a height or @a bitsPerPixel
     10850        Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
    1087310851        parameters means that the corresponding values should be taken from the
    1087410852        current video mode (i.e. left unchanged).
    … …  
    1087610854        If the guest OS supports multi-monitor configuration then the @a display
    1087710855        parameter specifies the number of the guest display to send the hint to:
    10878         <tt>0</tt> is the primary display, <tt>1</tt> is the first secondary and
     10856        @c 0 is the primary display, @c 1 is the first secondary and
    1087910857        so on. If the multi-monitor configuration is not supported, @a display
    10880         must be <tt>0</tt>.
     10858        must be @c 0.
    1088110859
    1088210860        <result name="E_INVALIDARG">
    … …  
    1089710875        <note>
    1089810876          Calling this method has no effect if <link
    10899           to="IGuest::supportsSeamless"/> returns <tt>false</tt>.
     10877          to="IGuest::supportsSeamless"/> returns @c false.
    1090010878        </note>
    1090110879      </desc>
    … …  
    1112011098      <desc>
    1112111099        Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
    11122         it to NULL, VirtualBox will generate a unique MAC address.
     11100        it to @c null, VirtualBox will generate a unique MAC address.
    1112311101      </desc>
    1112411102    </attribute>
    … …  
    1155711535      <desc>
    1155811536        Creates a new USB device filter. All attributes except
    11559         the filter name are set to <tt>null</tt> (any match),
    11560         <i>active</i> is <tt>false</tt> (the filter is not active).
     11537        the filter name are set to @c null (any match),
     11538        <i>active</i> is @c false (the filter is not active).
    1156111539
    1156211540        The created filter can then be added to the list of filters using
    … …  
    1179511773        </li>
    1179611774        <li><i>Any match</i>. Any value of the corresponding device attribute
    11797           will match the given filter. An empty or <tt>null</tt> string is
     11775          will match the given filter. An empty or @c null string is
    1179811776          used to construct this type of filtering expressions.
    1179911777
    … …  
    1181611794        Visible name for this filter.
    1181711795        This name is used to visually distinguish one filter from another,
    11818         so it can neither be <tt>null</tt> nor an empty string.
     11796        so it can neither be @c null nor an empty string.
    1181911797      </desc>
    1182011798    </attribute>
    … …  
    1230012278        Accessibility checks are performed each time the <link to="#accessible"/>
    1230112279        attribute is read. A @c null string is returned if the last
    12302         accessibility check was successful. A non-null string indicates a
     12280        accessibility check was successful. A non-@c null string indicates a
    1230312281        failure and should normally describe a reason of the failure (for
    1230412282        example, a file read error).
    … …  
    1234412322        Assigns the machine object associated with this direct-type
    1234512323        session or informs the session that it will be a remote one
    12346         (if @a machine == NULL).
     12324        (if @a machine == @c null).
    1234712325
    1234812326        <result name="VBOX_E_INVALID_VM_STATE">
    … …  
    1282612804    </desc>
    1282712805    <const name="Null"         value="0">
    12828       <desc><tt>null</tt> value. Never used by the API.</desc>
     12806      <desc>@c null value. Never used by the API.</desc>
    1282912807    </const>
    1283012808    <const name="IDE"       value="1"/>
    … …  
    1284212820
    1284312821    <const name="Null"         value="0">
    12844       <desc><tt>null</tt> value. Never used by the API.</desc>
     12822      <desc>@c null value. Never used by the API.</desc>
    1284512823    </const>
    1284612824    <const name="LsiLogic"  value="1"/>
Note: See TracChangeset for help on using the changeset viewer.

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