nsIVariant

XPConnect has magic to transparently convert between nsIVariant and JS types. We mark the interface [scriptable] so that JS can use methods that refer to this interface. But we mark all the methods and attributes [noscript] since any nsIVariant object will be automatically converted to a JS type anyway.
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Method overview

ACString getAsACString(); Native code only!
nsresult getAsArray(out PRUint16 type, out nsIID iid, out PRUint32 count, out voidPtr ptr); Violates the XPCOM interface guidelines
AString getAsAString(); Native code only!
AUTF8String getAsAUTF8String(); Native code only!
PRBool getAsBool(); Native code only!
char getAsChar(); Native code only!
DOMString getAsDOMString(); Native code only!
double getAsDouble(); Native code only!
float getAsFloat(); Native code only!
nsresult getAsID(out nsID retval); Violates the XPCOM interface guidelines
PRInt16 getAsInt16(); Native code only!
PRInt32 getAsInt32(); Native code only!
PRInt64 getAsInt64(); Native code only!
PRUint8 getAsInt8(); Native code only!
void getAsInterface(out nsIIDPtr iid, [iid_is(iid), retval] out nsQIResult iface); Native code only!
nsISupports getAsISupports(); Native code only!
jsval getAsJSVal(); Native code only!
string getAsString(); Native code only!
void getAsStringWithSize(out PRUint32 size, [size_is(size), retval] out string str); Native code only!
PRUint16 getAsUint16(); Native code only!
PRUint32 getAsUint32(); Native code only!
PRUint64 getAsUint64(); Native code only!
PRUint8 getAsUint8(); Native code only!
wchar getAsWChar(); Native code only!
wstring getAsWString(); Native code only!
void getAsWStringWithSize(out PRUint32 size, [size_is(size), retval] out wstring str); Native code only!

Attributes

Attribute Type Description
dataType PRUint16 Read only. Native code only!

Methods

Native code only!

getAsACString

ACString getAsACString();
Parameters

None.

Return value

The value is converted to an 8-bit string in the ISO-8859-1 character set. If the value was UTF16 then the high bits are lost. If the value was UTF8 then it is converted to UTF16 and the high bits are discarded. Arrays and interface pointers cannot be converted to a string.

Violates the XPCOM interface guidelines

getAsArray()

nsresult getAsArray(
  out PRUint16 type,
  out nsIID iid,
  out PRUint32 count,
  out voidPtr ptr
);
Parameters
type
The type of the array elements.
iid
The IID of the array elements, if they are interface pointers.
count
The number of elements in the array.
ptr
A copy of the array of underlying elements. (Reference counted elements are not cloned, but their reference count is increased.)
Return value

 

Native code only!

getAsAString

AString getAsAString();
Parameters

None.

Return value

The internal value is converted to a UTF16 string. Arrays and interface pointers cannot be converted to a string.

Native code only!

getAsAUTF8String

AUTF8String getAsAUTF8String();
Parameters

None.

Return value

The internal value is converted to a UTF8 string. An ISO-8859-1 string is widened to a UTF16 string first. Arrays and interface pointers cannot be converted to a string.

Native code only!

getAsBool

PRBool getAsBool();
Parameters

None.

Return value

If possible, the internal value is converted to a double, which is then compared to zero.

Native code only!

getAsChar

char getAsChar();
Parameters

None.

Return value

If the internal value is a string, it is first converted to a double, if possible. If it is of a numeric type, it is cast directly to char.

Native code only!

getAsDOMString

DOMString getAsDOMString();
Parameters

None.

Return value

This returns the same as the getAsAString method.

Native code only!

getAsDouble

double getAsDouble();
Parameters

None.

Return value

If the internal value is a string, it is converted to a double, if possible. If it is of a numeric type it is cast directly to double.

Native code only!

getAsFloat

float getAsFloat();
Parameters

None.

Return value

If the internal value is a string, it is first converted to a double, if possible. If it is of a numeric type, it is cast directly to float.

Violates the XPCOM interface guidelines

getAsID()

nsresult getAsID(
  out nsID retval
);
Parameters
retval
If the internal value is an IID then it is returned. If it is of type interface pointer then then IID of the pointer is returned. If it is of string type then an attempt is made to convert the string to an IID.
Return value

If the conversion succeeds, NS_OK is returned, otherwise NS_ERROR_CANNOT_CONVERT_DATA is returned.

Native code only!

getAsInt16

PRInt16 getAsInt16();
Parameters

None.

Return value

If the internal value is a string, it is first converted to a double, if possible. If it within the numeric limits of a PRInt16 then the value is returned.

Native code only!

getAsInt32

PRInt32 getAsInt32();
Parameters

None.

Return value

If the internal value is a string, it is first converted to a double, if possible. If it within the numeric limits of a PRInt32 then the value is returned.

Native code only!

getAsInt64

PRInt64 getAsInt64();
Parameters

None.

Return value

If the internal value is a string, it is first converted to a double, if possible. If it is of a numeric type, it is cast directly to PRInt64.

Native code only!

getAsInt8

PRUint8 getAsInt8();
Parameters

None.

Return value

If the internal value is a string, it is first converted to a double, if possible. If it within the numeric limits of a PRInt8 then the value is returned.

Native code only!

getAsInterface

void getAsInterface(
  out nsIIDPtr iid,
  [iid_is(iid), retval] out nsQIResult iface
);
Parameters
iid
The IID of the interface pointer, or nsISupports if no IID was provided.
iface
The interface pointer. (The reference count of the object is incremented.)

Native code only!

getAsISupports

nsISupports getAsISupports();
Parameters

None.

Return value

The interface pointer. (The reference count of the object is incremented.)

Native code only!

getAsJSVal

jsval getAsJSVal();
Parameters

None.

Return value

Returns the underlying JS value, if the variant was created by passing a JS object into XPConnect.

Native code only!

getAsString

string getAsString();
Parameters

None.

Return value

The value is converted to an 8-bit string in the ISO-8859-1 character set. If the value was UTF16 then the high bits are lost. If the value was UTF8 then it is converted to UTF16 and the high bits are discarded. Arrays and interface pointers cannot be converted to a string.

Native code only!

getAsStringWithSize

void getAsStringWithSize(
  out PRUint32 size,
  [size_is(size), retval] out string str
);
Parameters
size
The length of the returned string. Useful in case the string contains embedded null characters.
str
The value is converted to an 8-bit string in the ISO-8859-1 character set. If the value was UTF16 then the high bits are lost. If the value was UTF8 then it is converted to UTF16 and the high bits are discarded. Arrays and interface pointers cannot be converted to a string.

Native code only!

getAsUint16

PRUint16 getAsUint16();
Parameters

None.

Return value

If the internal value is a string, it is first converted to a double, if possible. If it within the numeric limits of a PRUint16 then the value is returned.

Native code only!

getAsUint32

PRUint32 getAsUint32();
Parameters

None.

Return value

If the internal value is a string, it is first converted to a double, if possible. If it within the numeric limits of a PRUint64 then the value is returned.

Native code only!

getAsUint64

PRUint64 getAsUint64();
Parameters

None.

Return value

If the internal value is a string, it is first converted to a double, if possible. If it is of a numeric type, it is cast to PRInt64 and then to PRUint64. Note that this will do strange things with negative numbers, and float and double values greater than the numeric limits of a PRInt64 will not convert correctly.

Native code only!

getAsUint8

PRUint8 getAsUint8();
Parameters

None.

Return value

If the internal value is a string, it is first converted to a double, if possible. If it within the numeric limits of a PRUint8 then the value is returned.

Native code only!

getAsWChar

wchar getAsWChar();
Parameters

None.

Return value

If the internal value is a string, it is first converted to a double, if possible. If it is of a numeric type, it is cast directly to PRUnichar.

Native code only!

getAsWString

wstring getAsWString();
Parameters

None.

Return value

The internal value is converted to a UTF16 string. Arrays and interface pointers cannot be converted to a string.

Native code only!

getAsWStringWithSize

void getAsWStringWithSize(
  out PRUint32 size,
  [size_is(size), retval] out wstring str
);
Parameters
size
The length of the returned string. Useful in case the string contains embedded null characters.
str
The internal value is converted to a UTF16 string. Arrays and interface pointers cannot be converted to a string.

Document Tags and Contributors

 Contributors to this page: Sheppy, Neil, trevorh, Brettz9
 Last updated by: Sheppy,