VirtualBox

Changeset 20977 in vbox for trunk/src/VBox/Main/idl


Ignore:
Timestamp:
Jun 26, 2009 2:38:55 PM (16 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
49184
Message:

API: weed out NULL strings, as many clients cannot use them

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r20963 r20977  
    18811881          @a location is a not valid file name (for file-based formats only).
    18821882        </result>
    1883         <result name="E_INVALIDARG">
    1884           @a format is a @c null or empty string.
    1885         </result>
    18861883      </desc>
    18871884      <param name="format" type="wstring" dir="in">
    … …  
    23122309        Returns the global extra data key name following the supplied key.
    23132310
    2314         An error is returned if the supplied @a key does not exist. @c null is
    2315         returned in @a nextKey if the supplied key is the last key. When
     2311        An error is returned if the supplied @a key does not exist. An empty
     2312        string is returned in @a nextKey if the supplied key is the last key. When
    23162313        supplying @c null or an empty string for the @a key, the first key item
    23172314        is returned in @a nextKey (if there is any). @a nextValue is an optional
    … …  
    23392336
    23402337        If the requested data @a key does not exist, this function will
    2341         succeed and return @c null in the @a value argument.
     2338        succeed and return an empty string in the @a value argument.
    23422339
    23432340        <result name="VBOX_E_FILE_ERROR">
    … …  
    23612358        Sets associated global extra data.
    23622359
    2363         If you pass @c null as a key @a value, the given @a key will be
    2364         deleted.
     2360        If you pass @c null or empty string as a key @a value, the given @a key
     2361        will be deleted.
    23652362
    23662363        <note>
    … …  
    25382535        server's variable. If the value of the environment variable is
    25392536        omitted, this variable will be removed from the resulting environment.
    2540         If the environment string is @c null, the server environment is
    2541         inherited by the started process as is.
     2537        If the environment string is @c null or emprty, the server environment
     2538        is inherited by the started process as is.
    25422539
    25432540        <see>openExistingSession</see>
    … …  
    37363733      <desc>
    37373734        Updates the flag whether saved state is removed on a machine state
    3738         change from Saved to PowerOff.
     3735        change from Saved to PoweredOff.
    37393736      </desc>
    37403737      <param name="aRemove" type="boolean" dir="in"/>
    … …  
    44424439
    44434440        <note>
    4444           Setting this property to @c null will restore the
    4445           initial value.
     4441          Setting this property to @c null or to an empty string will restore
     4442          the initial value.
    44464443        </note>
    44474444        <note>
    … …  
    45734570        <link to="IVirtualBox::openSession"/>, or if
    45744571        <link to="#sessionState"/> is SessionClosed, the value of this
    4575         attribute is @c null.
     4572        attribute is an empty string.
    45764573      </desc>
    45774574    </attribute>
    … …  
    46064603        <note>
    46074604          When the machine is not in the Saved state, this attribute is
    4608           @c null.
     4605          an empty string.
    46094606        </note>
    46104607      </desc>
    … …  
    50335030        supplied key.
    50345031
    5035         An error is returned if the supplied @a key does not exist. @c null is
    5036         returned in @a nextKey if the supplied key is the last key. When
    5037         supplying @c null for the @a key, the first key item is returned in
    5038         @a nextKey (if there is any). @a nextValue is an optional parameter and
    5039         if supplied, the next key's value is returned in it.
     5032        An error is returned if the supplied @a key does not exist. An empty
     5033        string is returned in @a nextKey if the supplied key is the last key.
     5034        When supplying @c null or an empty string for the @a key, the first key
     5035        item is returned in @a nextKey (if there is any). @a nextValue is an
     5036        optional parameter and if supplied, the next key's value is returned in
     5037        it.
    50405038
    50415039        <result name="VBOX_E_OBJECT_NOT_FOUND">
    … …  
    50605058
    50615059        If the requested data @a key does not exist, this function will
    5062         succeed and return @c null in the @a value argument.
     5060        succeed and return an empty string in the @a value argument.
    50635061
    50645062        <result name="VBOX_E_FILE_ERROR">
    … …  
    50825080        Sets associated machine-specific extra data.
    50835081
    5084         If you pass @c null as a key @a value, the given @a key will be
    5085         deleted.
     5082        If you pass @c null or an empty string as a key @a value, the given
     5083        @a key will be deleted.
    50865084
    50875085        <note>
    … …  
    55375535          The new value of the property to set, change or delete.  If the
    55385536          property does not yet exist and value is non-empty, it will be
    5539           created.  If the value is empty, the key will be deleted if it
    5540           exists.
     5537          created.  If the value is @null or empty, the property will be
     5538          deleted if it exists.
    55415539        </desc>
    55425540      </param>
    … …  
    55755573          The new value of the property to set, change or delete.  If the
    55765574          property does not yet exist and value is non-empty, it will be
    5577           created.  If value is empty, the property will be deleted if it
    5578           exists.
     5575          created.  If the value is @null or empty, the property will be
     5576          deleted if it exists.
    55795577        </desc>
    55805578      </param>
    … …  
    69136911      <desc>
    69146912        Returns a human readable description for the drive.  This
    6915         description usually contains the product and vendor name.  A
    6916         @c null string is returned if the description is not available.
     6913        description usually contains the product and vendor name.  An
     6914        empty string is returned if the description is not available.
    69176915      </desc>
    69186916    </attribute>
    … …  
    69226920        attribute is reserved for future use instead of
    69236921        <link to="#name"/>. Currently it is not used and may return
    6924         @c null on some platforms.
     6922        an empty string on some platforms.
    69256923      </desc>
    69266924    </attribute>
    … …  
    69476945      <desc>
    69486946        Returns a human readable description for the drive.  This
    6949         description usually contains the product and vendor name.  A
    6950         @c null string is returned if the description is not available.
     6947        description usually contains the product and vendor name.  An
     6948        empty string is returned if the description is not available.
    69516949      </desc>
    69526950    </attribute>
    … …  
    69566954        attribute is reserved for future use instead of
    69576955        <link to="#name"/>. Currently it is not used and may return
    6958         @c null on some platforms.
     6956        an empty string on some platforms.
    69596957      </desc>
    69606958    </attribute>
    … …  
    72487246      <param name="description" type="wstring" dir="return">
    72497247        <desc>
    7250           Model string. A @c null string is returned if value is not known or
     7248          Model string. An empty string is returned if value is not known or
    72517249          @a cpuId is invalid.
    72527250        </desc>
    … …  
    73247322      <desc>
    73257323        Creates a new USB device filter. All attributes except
    7326         the filter name are set to @c null (any match),
     7324        the filter name are set to empty (any match),
    73277325        <i>active</i> is @c false (the filter is not active).
    73287326
    … …  
    76167614
    76177615        <note>
    7618           Setting this property to @c null will restore the
     7616          Setting this property to @c null or an empty string will restore the
    76197617          initial value.
    76207618        </note>
    … …  
    76547652
    76557653        <note>
    7656           Setting this property to @c null will restore the initial value.
     7654          Setting this property to @c null or empty string will restore the
     7655          initial value.
    76577656        </note>
    76587657        <note>
    … …  
    77267725
    77277726        <note>
    7728           Setting this property to @c null will restore the initial value.
     7727          Setting this property to @c null or empty string will restore the
     7728          initial value.
    77297729        </note>
    77307730
    … …  
    77547754
    77557755        <note>
    7756           Setting this property to @c null will restore the
     7756          Setting this property to @c null or empty string will restore the
    77577757          initial value.
    77587758        </note>
    … …  
    77817781        is the same for the webservice as it is for VBoxVRDP.
    77827782
     7783        <note>
     7784          Setting this property to @c null or empty string will restore the
     7785          initial value.
     7786        </note>
    77837787      </desc>
    77847788    </attribute>
    … …  
    85448548      <desc>
    85458549        Optional description of the medium. For newly created media, the value
    8546         of this attribute value is @c null.
     8550        of this attribute value is an empty string.
    85478551
    85488552        Media types that don't support this attribute will return E_NOTIMPL in
    … …  
    86518655
    86528656        Accessibility checks are performed each time the <link to="#state"/>
    8653         attribute is read. A @c null string is returned if the last
    8654         accessibility check was successful. A non-@c null string indicates a
     8657        attribute is read. An empty string is returned if the last
     8658        accessibility check was successful. A non-empty string indicates a
    86558659        failure and should normally describe a reason of the failure (for
    86568660        example, a file read error).
    … …  
    94149418        be obtained with <link to="IHardDiskFormat::describeProperties"/>.
    94159419
    9416         Note that if this method returns a @c null @a value, the requested
    9417         property is supported but currently not assigned any value.
     9420        Note that if this method returns an empty string in @a value, the
     9421        requested property is supported but currently not assigned any value.
    94189422
    94199423        <result name="VBOX_E_OBJECT_NOT_FOUND">
    … …  
    94379441        be obtained with <link to="IHardDiskFormat::describeProperties"/>.
    94389442
    9439         Note that setting the property value to @c null is equivalent to
    9440         deleting the existing value. A default value (if it is defined for this
    9441         property) will be used by the format backend in this case.
     9443        Note that setting the property value to @c null or an empty string is
     9444        equivalent to deleting the existing value. A default value (if it is
     9445        defined for this property) will be used by the format backend in this
     9446        case.
    94429447
    94439448        <result name="VBOX_E_OBJECT_NOT_FOUND">
    … …  
    94609465        The names of the properties to get are specified using the @a names
    94619466        argument which is a list of comma-separated property names or
    9462         @c null if all properties are to be returned. Note that currently
     9467        an empty string if all properties are to be returned. Note that currently
    94639468        the value of this argument is ignored and the method always returns all
    94649469        existing properties.
    … …  
    94749479
    94759480        Note that for properties that do not have assigned values,
    9476         @c null is returned at the appropriate index in the
     9481        an empty string is returned at the appropriate index in the
    94779482        @a returnValues array.
    94789483
    … …  
    95129517        be obtained with <link to="IHardDiskFormat::describeProperties"/>.
    95139518
    9514         Note that setting the property value to @c null is equivalent to
    9515         deleting the existing value. A default value (if it is defined for this
    9516         property) will be used by the format backend in this case.
     9519        Note that setting the property value to @c null or an empty string is
     9520        equivalent to deleting the existing value. A default value (if it is
     9521        defined for this property) will be used by the format backend in this
     9522        case.
    95179523      </desc>
    95189524      <param name="names" type="wstring" safearray="yes" dir="in">
    … …  
    1112411130      <desc>
    1112511131        Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
    11126         it to @c null, VirtualBox will generate a unique MAC address.
     11132        it to @c null or an empty string, VirtualBox will generate a unique MAC address.
    1112711133      </desc>
    1112811134    </attribute>
    … …  
    1156111567      <desc>
    1156211568        Creates a new USB device filter. All attributes except
    11563         the filter name are set to @c null (any match),
     11569        the filter name are set to empty (any match),
    1156411570        <i>active</i> is @c false (the filter is not active).
    1156511571
    … …  
    1230312309
    1230412310        Accessibility checks are performed each time the <link to="#accessible"/>
    12305         attribute is read. A @c null string is returned if the last
    12306         accessibility check was successful. A non-@c null string indicates a
     12311        attribute is read. An empty string is returned if the last
     12312        accessibility check was successful. A non-empty string indicates a
    1230712313        failure and should normally describe a reason of the failure (for
    1230812314        example, a file read error).
    … …  
    1257712583        <link to="IConsole::detachUSBDevice"/>) has completed.
    1257812584        A @c null @a error object means success, otherwise it
     12585        describes a failure.
    1257912586
    1258012587        <result name="VBOX_E_INVALID_VM_STATE">
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