The DumpProperties method returns all the properties of the object. This method builds a string showing all the properties in the form "key1 = value1; key2 = value2;...".

Syntax

C++

string DumpProperties ()

COM

HRESULT DumpProperties (/*[out,retval]*/ BSTR* bstrValue)

VB

DumpProperties() As String

Java

String DumpProperties()

.NET

System.String DumpProperties()

Parameters

bstrValue

The output parameter (return parameter in VB) containing a string listing the names and values of the object's properties.

Return Value

COM: Default HRESULT return value. For more information, see CIL Coding Conventions

All Others: The string listing the names of all the object's properties.

The GetAllProperties method returns all the object's properties and their values. For the properties that are calls, agents, or skillgroups, their string UniqueObjectIDs are returned, not the objects themselves. To get the objects themselves use GetObjectFromObjectID, explained in Session Object

Syntax

C++

bool GetAllProperties (Arguments** arguments)

COM

HRESULT GetAllProperties (/*[out]*/ IArguments** arguments, /*[out,retval]*/ VARIANT_BOOL* errorcode)

VB

GetAllProperties arguments As (CTIOSCLIENTLib.IArguments) As Bool

Java, .NET

Arguments GetAllProperties()

Parameters

C++, COM, VB: arguments

Output parameter in the form of an Arguments array that has all the property names and values of the object.

errorcode

An output parameter (return parameter in VB) that contains a boolean indicating success or lack thereof.

Return Value

C++ , VB: True upon success and false upon failure.

COM: Always returns S_OK. Use the errorcode parameter to determine success or failure of the method call.

.NET, Java: NULL if the value requested is not found or if there is an error. If the method succeeds, it returns a reference to an Arguments object containing all the properties of the object.

Given a property of type Arguments whose name is specified by the key parameter, the GetElement method returns the Arg at position element of that Arguments array.

Syntax

C++

Arg& GetElement (string& key, int element)
Arg& GetElement (int key, int element)
Arg& GetElement (char* key, int element)

COM

HRESULT GetElement /*[in]*/ VARIANT* key, /*[in]*/ int element, /*[out,retval]*/ IArg** pIArg)

VB

GetElement (key As VARIANT) As CTIOSCLIENTLib.IArg

Java

Arg GetElement(String key, int element)
Arg GetElement(int key, int element)

.NET

System.Boolean GetElement(System.String key, int element, out arg rArg)

Parameters

key

A key designating the name of the Arguments property whose element you want.

element

The integer index of the element to retrieve from the property key.

COM, VB:pIArg

An output parameter (return parameter in VB) containing an IArg with the value of the desired element.

.NET: rArg

An output parameter containing the value of the specified element. This parameter is null if the element is not found.

Return Value

An Arg reference containing the value of the desired element.

The C++ and Java versions of this method return NULL if an error occurs, such as the key or element is not found. The .NET version of this method returns true upon success and false upon error.

The GetLastError method returns the last error that occurred on the calling thread.

Syntax

Java

Integer GetLastError()

.NET

System.Boolean GetLastError(out System.Int32 nLastError)

Parameters

Java

None.

.NET

nLastError

Output parameter that is a 32-bit signed integer that contains the returned value of the last error.

Returns

Java:An Integer object containing the error, or null if the object is not found or if there is an error.

.NET:The Boolean value true if the value is successfully set; otherwise false.

Remarks

The following example code gets the last error on the current thread and logs the error message. If GetLastError fails, the code writes a warning message to the log file:

// First get the last error System.Int32 myLastError; 
bool success = GetLastError(out myLastError); 
if (!success) 
{ 
// log a message indicating that GetLastError failed 
} 
else 
{ 
//log a message that indicates what the last error was 
LOGBYID(Cisco.CtiOs.Cil.TraceLevel.WARN,"GetLastError returned
 last error" = + myLastError); 
}

The GetNumProperties method returns the number of properties in the current object.

Syntax

C++

int GetNumProperties ()

COM

HRESULT GetNumProperties (/*[out,retval]*/ int * num

VB

GetNumProperties () As Long

Java, .NET

int GetNumProperties()

Parameters

num

In the COM version, an output parameter (return value in VB, C++, Java, and .NET) that contains an integer that is the number of properties in the object.

Return Value

COM: Default CTI OS return values. See CIL Coding Conventions

All Others: An integer that is the number of properties currently a part of the object.

The GetPropertyName method returns the name of a property in a string format.

Syntax

C++

string GetPropertyName (int index)

COM

HRESULT GetPropertyName (/* [in] index, /*[out,retval]*/ name)

VB

GetPropertyName (index As Integer) As String

Java

string GetPropertyName (int iIndex)

.NET

virtual System.Boolean GetPropertyName(int iIndex, out System.String name)

Parameters

index

An integer parameter specifying the index number of the requested property.

name

A string output parameter (return value in C++, VB, and Java) containing the property's name.

Return Value

COM: Default CTI OS return values. For more information, see CIL Coding Conventions

.NET: Boolean value set to true if the method call succeeds, otherwise false.

All Others: A string that contains the property's name.

The GetPropertyType method returns the data type of the specified property.

Syntax

C++

int GetPropertyType (string& key)
int GetPropertyType (int key)
int GetPropertyType (char* key)

COM

HRESULT GetPropertyType (/*[in]*/ VARIANT* key, /*[out,retval]*/ int* value)

VB

GetPropertyType (key As VARIANT) As Int

Java

int GetPropertyType(string sPropName)
int GetPropertyType(int key)

.NET

virtual ArgDataType GetPropertyType(Enum_CtiOs eKeyID)
virtual ArgDataType GetPropertyType(System.String sPropName)

Parameters

key

Keyword ID name of the property whose type you want. In .NET, eKeyId is the Enum_CtiOs Keyword ID of the property.

COM:value

An integer pointer to the value of the type.

Return Value

COM: Default HRESULT return value. For more information, see CIL Coding Conventions

Others: An integer indicating the property's type with the following possible values:

The GetValue method returns the value of the specified property. Use this method if you do not know the type of the property. Otherwise, use the more specific GetValue methods discussed later in this chapter. When using the COM CIL, do not use this method for properties of type IDispatch*; instead, use GetCurrentCall, GetCurrentAgent, GetAllCalls, GetAllAgents, and GetAllSkillGroups as explained in Session Object

Syntax

C++

Arg& GetValue (string& key)
Arg& GetValue (int key)
Arg& GetValue (char* key)

COM

HRESULT GetValue (/*[in]*/ VARIANT* key, /*[out,retval]*/ IArg** value)

VB

GetValue (key As VARIANT) As CTIOSCLIENTLib.IArg

Java

Arg  GetValue( String key )
Arg& GetValue (int key)

.NET

virtual System.Boolean GetValue(Enum_CtiOs eKeyID, out Arg obArg)
virtual System.Boolean GetValue(System.String sKey, out Arg obArg)

Parameters

key

The name of the property whose value you want.

COM: value

An output value of type Arg** containing the property with the designated name. To get the value of the property, call GetType() on the Arg and then call the specific GetValue method, based on the type.

.NET: obArg

Output parameter (return value in C++, VB, and Java) containing the specified property, as described in the explanation of the value parameter.

Return Value

COM: Default HRESULT return value. For more information, see CIL Coding Conventions

.NET: Returns true if the value is retrieved, and false if the value is not found.

Others: An Arg containing the specified property. To get the value of the property, call GetType() on the Arg and then call the specific GetValue method, based on the type.

The GetValueArray method returns the Arguments array value of the specified property. Use this method when you know that the property is of Arguments array type, such as ECC call variables.

Syntax

C++

Arg& GetValueArray (string& key)

Arg& GetValueArray (enum_Keywords key)

Arg& GetValue (char * key)

COM

HRESULT GetValueArray (/*[in]*/ VARIANT * key, /*[out,retval]*/ IArguments ** value)

VB

GetValueArray (key As VARIANT) As CTIOSCLIENTLib.IArguments

Java

Arguments GetValueArray( String key )

GetValueArray (int key)

.NET

System.Boolean GetValueArray(Enum_CtiOs eKeyID, out Arguments arArguments)

Parameters

key

The name of the property whose value you want.

value

COM: An output parameter (return value in VB, C++, and Java) containing an arArguments** to the returned value of the property.

.NET: An output parameter containing the Arguments array value upon success. Upon failure, this parameter is set to null.

Return Value

COM: Default HRESULT return value. For more information, see CIL Coding Conventions.

.NET: Returns true if the value is retrieved. Returns false if the value is not found.

Others: A reference to an Arguments array containing the value of the specified property.

The GetValueBool method retrieves the Boolean value of the specified property.

Syntax

Boolean GetValueBoolObj(int iKey)
Boolean GetValueBoolObj(String sKey)

Parameters

Key

Key ID for the object to be retrieved.

Returns

A Boolean object representation of the contained value or null if error.

The GetValueInt method returns the integer value of the specified property. Use this method when you know that the property has an integer type.

Syntax

C++

int GetValueInt (string& key)
int GetValueInt (int key)
int GetValueInt (char* key)

COM

HRESULT GetValueInt /*[in]*/ VARIANT* key, /*[out,retval]*/ int* value)

VB

GetValueInt (key As VARIANT) As Integer

Java

Not implemented, use GetValueIntObj

.NET

System.Boolean GetValueInt(Enum_CtiOs eKeyID, out System.Int32 nValue)
System.Boolean GetValueInt(System.String sPropname, out System.Int32 nValue)

Parameters

C++: key

Depending on the method used, either a string or int that contains the name or ID of the property whose value you want to retrieve.

COM, VB: key

VARIANT containing the ID or name of the property to retrieve.

COM: value

An output parameter (return parameter in VB) containing an integer pointer to the returned value of the property.

.NET: sPropName

The name of the property.

.NET: nValue

Upon success, this output parameter contains the value of the specified property. Upon failure, this parameter is set to null.

.NET: eKeyID

Keyword ID of the property.

Return Value

COM: Default HRESULT return value. For more information, see CIL Coding Conventions.

.NET: True if the method succeeds; false if the method fails.

Gets the contained value as an integer.

Syntax

• Integer GetValueIntObj( int iKey)
• Integer GetValueIntObj( String sKey)

Parameters

key

Key ID of the value to be retrieved.

Returns

An Integer object containing a 32 bit signed integer value or null if error.

Retrieves a 16 bit short with the specified key from the array.

Syntax

Short GetValueShortObj( int iKey)
Short GetValueShortObj(short sKey)

Parameters

key

Key ID of the value to be retrieved.

Return Value

A Short object containing a 16 bit short value or null if error.

The GetValueString method returns the string value of the property with the specified name. Use this method when you know that the property is of string type. For all CILs and all types, a call to GetValueString for an argument that is of another type, for example Int, returns a string representation of the argument's Int value.

Syntax

C++

string GetValueString (string& key)
string GetValueString (int key)
string GetValueString (char* key)

COM

HRESULT GetValueString (/*[in]*/ VARIANT* key, /*[out,retval]*/ BSTR* value)

VB

GetValueString (key As VARIANT) As String

Java

String GetValueString( String key )
String GetValueString (int key)

.NET

System.Boolean GetValueString(Enum_CtiOs eKeyID, out System.String strValue)
System.Boolean GetValueString(System.String sPropName, out System.String strValue)

Parameters

C++, Java: key

Depending on the method used, either a string or int that contains the name or ID of the property whose value you want to retrieve.

COM, VB: key

VARIANT containing the ID or name of the property to retrieve.

.NET: sPropName

The name of the property values to retrieve.

.NET: strValue

Upon success, this output parameter contains the value of the specified property. Upon failure, this parameter is set to null.

.NET: eKeyID

Keyword ID of the property.

value

In COM, an output parameter (return parameter in VB) containing a BSTR pointer to the returned string value of the property.

Return Value

COM: Default HRESULT return value. For more information, see CIL Coding Conventions.

.NET:Boolean value indicating the success or failure of the method call (true, if success; otherwise false).

Others: A string containing the value of the specified property.

Retrieves a 32 bit unsigned integer with the specified key from the array.

Syntax

Long GetValueUIntObj( int key)
Long GetValueUIntObj( String sKey)

Parameters

key

Key ID of the value to be retrieved.

Returns

A Long object containing the 32 bit unsigned integer value or null if error.

Retrieves a 16 bit unsigned short with the specified key from the array.

Syntax

• Integer GetValueUShortObj( String sKey)

Parameters

key

Key ID of the value to be retrieved.

Returns

An Integer object containing the 16 bit unsigned short value or null if error.

The IsValid method tests to see if the object includes the specified property.

Syntax

C++

bool IsValid (string& key)

bool IsValid (char* key)

bool IsValid (int key)

COM

HRESULT IsValid (/*[in]*/ VARIANT* key, /*[out,retval]*/ VARIANT_BOOL* value)

VB

IsValid (key As VARIANT)as Bool

Java

boolean IsValid( String key)

boolean IsValid (int key)

.NET

virtual bool IsValid(Enum_CtiOs eKeyID)

virtual bool IsValid(System.String sKey)

Parameters

Return Value

COM: Default HRESULT return value. For more information, see CIL Coding Conventions.

Others: A boolean indicating whether or not a property with the specified name exists for the object.

The ReportError method sets the value of the LastError property to iErrCode and writes the error to the log as critical.

Syntax

int ReportError(int iError)

Parameters

Error

The error to report.

Returns

The same error code that was passed in through iErrCode.

The SetValue method adds a new property to the object's property list and gives it the provided value. If the property already exists, it replaces its value with the one provided.

Syntax

boolean SetValue(int iKeyID, Arg rArgboolean SetValue(int iKeyID, Arguments rArgs)boolean 
boolean SetValue(int iKeyID, boolean bValue) 
boolean SetValue(int iKeyID, CtiOsObject rObj)
boolean SetValue(int iKeyID, int iValue) 
boolean SetValue(int iKeyID, short nValue) 
boolean SetValue(int iKeyID, java.lang.String sValue)
boolean SetValue(java.lang.String sPropName, Arg rArg) 
boolean SetValue(java.lang.String sPropName, Arguments rArgs) 
boolean SetValue(java.lang.String sPropName, boolean bValue)
boolean SetValue(java.lang.String sPropName, CtiOsObject rObj)
boolean SetValue(java.lang.String sPropName, int iValue)
boolean SetValue(java.lang.String sPropName, short nValue) 
boolean SetValue(java.lang.String sPropName, java.lang.String sValue)
boolean SetValueUInt (int key, long value)
boolean SetValueUInt (String key, long value)
boolean SetValueUShort (int key, int value)
boolean SetValueUShort (String key, int value

Parameters

key

The key whose value is to be set.

value

The value to use in setting the element with the designated key.

Returns

True if successfully added, false if not.

The SetValue method sets the value of the specified Agent property.

Syntax

C++

bool SetValue( string& key, string& value)

bool SetValue( string& keyValuePair)

bool SetValue( string& key, int value)

bool SetValue( const char * key, const char * value)

bool SetValue( const char * keyValuePair)

bool SetValue( const char * key, int value)

COM

HRESULT SetValue (/*[in]*/ VARIANT *key, /*[in]*/ VARIANT *value, /*[out,retval]*/ VARIANT_BOOL * errorcode)

VB

SetValue (key As Variant, value As Variant) As Bool

Parameters

key

An input parameter that contains the name of the property whose value you want to set.

value

An input parameter containing the value to be used in setting the specified property.

keyValuePair

An input parameter containing a string in the format "key=value" where key is a property to set and value is the new value.

errorcode

An output parameter (return parameter in VB) that contains an error code from Table 1.

Return Values

COM

Default CTI OS return values. For more information, see CIL Coding Conventions.

All Others

A boolean indicating the success or failure of the method.

Remarks

You should only use this method when creating a new Agent in preparation for logging in. Therefore, use it to set the AgentID, AgentInstrument, AgentPassword, PeripheralID, and AutoLogin only.