7.10.3 The C.Value structure

This structure provides support for foreign data values as ML data structures.

store

Type abbreviation

Specification:

type store

Description:

Equivalent to Store.store. See page 234.

object_mode

Type abbreviation

Specification:

type object_mode

Description:

Equivalent to Object.object_mode. See page 238.

c_type

Type abbreviation

Specification:

type c_type

Description:

Equivalent to Type.c_type. See page 250.

c_object

Type abbreviation

Specification:

type c_object

Description:

This is an encapsulated ML type used to represent foreign data and is equivalent to (c_type)Object.object. See page 237.

object

Function

Signature:

val object : { ctype : c_type, store : store }
-> c_object

Description:

This generates fresh c_objects, given specific type information and a particular store to contain the raw value information.

setObjectMode

Function

Signature:

val setObjectMode : c_object * object_mode -> unit

Description:

This is used to change the current object mode.

objectType

Function

Signature:

val objectType : c_object -> c_type

Description:

This is used to inspect the current c_type.

castObjectType

Function

Signature:

val castObjectType : c_object * c_type -> unit

Description:

This is used to change the current c_type.

tmpObject

Function

Signature:

val tmpObject : c_object -> c_object

Description:

This maps permanent objects into a duplicate except that the status of the duplicate is mapped to temporary. Temporary objects are simply returned.

dupObject

Function

Signature:

val dupObject : c_object -> c_object

Description:

Duplicates permanent objects, but does not duplicate objects whose status is temporary.

newObject

Function

Signature:

val newObject : c_object -> c_object

Description:

This generates a fresh foreign object, including making a duplicate type component (using dup_type()), irrespective of the object's status.

c_char

Type abbreviation

Specification:

type c_char

Description:

This ML type is compatible with the C type char.

c_short_int

Type abbreviation

Specification:

type c_short_int

Description:

This ML type is compatible with the C type short int.

c_int

Type abbreviation

Specification:

type c_int

Description:

This ML type is compatible with the C type int.

c_long_int

Type abbreviation

Specification:

type c_long_int

Description:

This ML type should be compatible with the C type long int.

c_real

Type abbreviation

Specification:

type c_real

Description:

This ML type is compatible with the C type float.

c_double

Type abbreviation

Specification:

type c_double

Description:

This ML type is compatible with the C type double.

c_long_status

Type abbreviation

Specification:

type c_long_double

Description:

This ML type should be compatible with the C type long double.

ForeignType

Exception

StoreAccess

Exception

OutOfBounds

Exception

Currency

Exception

The following are generally 'setter' functions for particular kinds of C data. In particular, they expect the foreign objects to have an appropriate c_type already set. If not, then they fail with exception ForeignType.

setChar

Function

Signature:

val setChar : c_object * c_char -> unit

Description:

This function sets the object value to a value representing a C char.

setUnsignedChar

Function

Signature:

val setUnsignedChar : c_object * c_char -> unit

Description:

This function sets the object value to a value representing an unsigned C char (that is, 0 <= char <= 255).

setSignedChar

Function

Signature:

val setSignedChar : c_object * c_char -> unit

Description:

This function sets the object value to a value representing an unsigned C character (that is -127 <= char <= 128).

setShort

Function

Signature:

val setShort : c_object * c_short_int -> unit

Description:

This function sets the object value to a value representing a C short integer.

setInt

Function

Signature:

val setInt : c_object * c_int -> unit

Description:

This function sets the object value to a value representing a C integer.

setLong

Function

Signature:

val setLong : c_object * c_long_int -> unit

Description:

This function sets the object value to a value representing a C long integer.

setUnsignedShort

Function

Signature:

val setUnsignedShort : c_object * c_short_int -> unit

Description:

This function sets the object value to a value representing a C unsigned short integer.

setUnsigned

Function

Signature:

val setUnsigned : c_object * c_int -> unit

Description:

This function sets the object value to a value representing a C unsigned integer.

setUnsignedLong

Function

Signature:

val setUnsignedLong : c_object * c_long_int
-> unit

Description:

This function sets the object value to a value representing a C unsigned long integer.

setWord32

Function

Signature:

val setWord32 : c_object * word32 -> unit

Description:

This function sets the object value from an ML 32-bit value.

setFloat

Function

Signature:

val setFloat : c_object * c_real -> unit

Description:

This function sets the object value to a value representing a C floating-point real value.

setDouble

Function

Signature:

val setDouble : c_object * c_double -> unit

Description:

This function sets the object value to a value representing a C double floating point real value.

setLongDouble

Function

Signature:

val setLongDouble : c_object * c_long_double -> unit

Description:

This function sets the object value to a value representing a C long double floating-point real value.

setString

Function

Signature:

val setString : c_object * string -> unit

Description:

This function sets the object value to a value representing a C string. In general, ML strings can contain embedded NULL characters -- so only the string up to the first NULL is significant. However, if no NULL is included then one is added. Finally, the foreign object must have a suitable string c_type whose length (including any NULL sentinel) is sufficient to contain this data.

Functions for manipulating pointer objects:

setAddr

Function

Signature:

val setAddr : { obj:c_object, addr:c_object }
-> unit

Description:

This makes the value part of the obj object coincide with the value based at the address given by the addr object. The c_type of obj may be arbitrary and the c_type of addr should be a numeric type capable of representing a machine address or an appropriate pointer type.

In a sense, this makes the obj object inspect value data at a given address.

setPtrAddr

Function

Signature:

val setPtrAddr : { ptr:c_object, addr:c_object } -> unit

Description:

This sets the given pointer object ptr to reference the address value given by addr (see above). The c_type of ptr is any pointer c_type and the c_type of addr is any numeric type capable of representing a machine address or an appropriate pointer type.

This function makes a pointer object refer to a given address.

setPtrAddrOf

Function

Signature:

val setPtrAddrOf : { ptr:c_object, data:c_object } -> unit

Description:

This sets the given pointer object, ptr, to reference the value referred to by the data object. The c_type of ptr is any pointer c_type and the c_type of data must be compatible with this.

This function makes a pointer object refer to a given piece of data of compatible type.

setPtrData

Function

Signature:

val setPtrData : { ptr:c_object, data:c_object } -> unit

Description:

This sets the data that is addressed by the pointer object, ptr, to the data specified by the object data. The c_type of ptr can be any pointer c_type and the c_type of data must be compatible with this.

This function indirectly assigns data into the space referred to by pointer.

setPtrType

Function

Signature:

val setPtrType : { ptr:c_object, data:c_object } -> unit

Description:

This sets the c_type of the data addressed by the pointer ptr to the c_type specified by the object data. The c_type of ptr can be any pointer c_type and the c_type of data can be arbitrary. The current pointer mode is preserved.

This function performs an implicit type cast of the pointer to match that of the given data object.

castPtrType

Function

Signature:

val castPtrType : { ptr : c_object, ctype : c_type } -> unit

Description:

This sets the c_type of the data addressed by the pointer ptr to the c_type specified. This function performs an explicit type cast of the given pointer, while preserving the current pointer mode.

setLocalPtr

Function

Signature:

val setLocalPtr : c_object -> unit

Description:

This converts the current pointer into a local pointer -- that is, a machine address located within the associated store workspace. This may fail if the given pointer is a remote pointer that points outside of this workspace.

setRelativePtr

Function

Signature:

val setRelativePtr : c_object -> unit

Description:

This converts the current pointer into a relative pointer -- that is, a small index value giving the relative offset from the origin address of the store workspace. This fails if the given pointer points outside the associated store workspace.

setRemotePtr

Function

Signature:

val setRemotePtr : c_object -> unit

Description:

This converts the current pointer into a remote pointer -- that is, a machine address.

Functions for manipulating structured objects:

setStruct

Function

Signature:

val setStruct : c_object * (c_object list) -> unit

Description:

This function takes an object specifying a structure and updates its fields from the given list of data items. This relies upon fields being ordered in a structure and that the c_types of corresponding items and fields are matched. If there are fewer items than fields then only the corresponding leading prefix of fields are updated. Also, if there are more items than fields then the excess items are ignored.

setField

Function

Signature:

val setField : { record : c_object, field:name, data : c_object } -> unit

Description:

This function updates a specific field of a C struct with the given data.

setMember

Function

Signature:

val setMember : { union : c_object, member : name } -> unit

Description:

This updates an object with union c_type by selecting a particular member. The selected member must be one of the known options.

setUnion

Function

Signature:

val setUnion : { union : c_object, data : c_object } -> unit

Description:

This updates an object with union c_type with given data. The c_type of the current member of the union object must be compatible with the c_type of the data.

setArray

Function

Signature:

val setArray : c_object * (c_object list) * int -> unit

Description:

This updates an array object with a 'slice' of items, based at a given index. This allows several elements of an array to be updated together. The array elements updated begin with the given index and continue with consecutive indices until either the list is exhausted or the array ends.

setEnum

Function

Signature:

val setEnum : c_object * int -> unit

Description:

This updates an object containing enumerated values. The integer must be in the appropriate range defined by the c_type of the object. The c_type of the object should be an enumerated type.

The following are particular selection functions for particular kinds of structured C data -- they expect the foreign objects to have an appropriate c_type already set. If not, they fail with exception ForeignType.

indexObject

Function

Signature:

val indexObject : { array:c_object, tgt:c_object, index:int } -> unit

Description:

This selects an array element from the given array at the given index and copies the data to the target object, tgt. The index must be in the range of the array; the c_type of array should be an array type; and the target object should have compatible c_type.

derefObject

Function

Signature:

val derefObject : { ptr:c_object, tgt:c_object } -> unit

Description:

This locates the data pointed at by the pointer object and copies it to the target object.

selectObject

Function

Signature:

val selectObject : { record:c_object, tgt:c_object, field:name } -> unit

Description:

This selects data from a field of a given record and copies it to the target object. The field has to be one of those associated with the C struct type of the record; the c_type of the target object must also be compatible with the field.

coerceObject

Function

Signature:

val coerceObject : { union:c_object, tgt:c_object } -> unit

Description:

This extracts the content of the union object and copies it to the target object. The c_types of the union and the target do not have to match (that is, implicit coercion).

copyIndexObject

Function

Signature:

val copyIndexObject : c_object * int -> c_object

Description:

As indexObject (page 266), but generates a new object to provide the result.

copyDerefObject

Function

Signature:

val copyDerefObject : c_object -> c_object

Description:

As derefObject (page 266), but generates a new object to provide the result.

copySelectObject

Function

Signature:

val copySelectObject : c_object * name -> c_object

Description:

As selectObject (page 266), but generates a new object to provide the result.

copyCoerceObject

Function

Signature:

val copyCoerceObject : c_object -> c_object

Description:

As for coerceObject() above, but generates a new object to provide the result.

indexObjectType

Function

Signature:

val indexObjectType : c_object -> c_type

Description:

This gives the c_type of an element of the array.

derefObjectType

Function

Signature:

val derefObjectType : c_object -> c_type

Description:

This gives the c_type of the value pointed at by the pointer object.

selectObjectType

Function

Signature:

val selectObjectType : c_object * name -> c_type

Description:

This gives the c_type of the field selected from the C struct object.

coerceObjectType

Function

Signature:

val coerceObjectType : c_object -> c_type

Description:

This gives the c_type of the current member of the C union object.

indexObjectSize

Function

Signature:

val indexObjectSize : c_object -> int

Description:

This gives the size (in bytes) of an element of the specified array.

derefObjectSize

Function

Signature:

val derefObjectSize : c_object -> int

Description:

This gives the size (in bytes) of the value pointed at by the pointer object.

selectObjectSize

Function

Signature:

val selectObjectSize : c_object * name -> int

Description:

This gives the size (in bytes) of the field selected from the C struct object.

coerceObjectSize

Function

Signature:

val coerceObjectSize : c_object -> int

Description:

This gives the size (in bytes) of the current member for the C union object.

nextArrayItem

Function

Signature:

val nextArrayItem : c_object -> unit

Description:

This shifts the object forwards through the workspace by an amount equal to its size. This is useful when stepping through an array.

prevArrayItem

Function

Signature:

val prevArrayItem : c_object -> unit

Description:

As for nextArrayItem, except that the object is shifted backwards.

The following are generally 'getter' functions for particular kinds of C data -- as for the related setter functions, they expect the object objects to have an appropriate c_type already set. If not, then they fail with exception ForeignType.

getChar

Function

Signature:

val getChar : c_object -> c_char

Description:

Extracts a C character (represented as an ML value) from an object with appropriate c_type.

getUnsignedChar

Function

Signature:

val getUnsignedChar : c_object -> c_char

Description:

Extracts a C unsigned character (represented as an ML value in the range 0-255) from an object with appropriate c_type.

getSignedChar

Function

Signature:

val getSignedChar : c_object -> c_char

Description:

Extracts a C signed character represented as an ML value (-127-127) from an object with appropriate c_type.

getShort

Function

Signature:

val getShort : c_object -> c_short_int

Description:

Extracts a C short value (represented as an ML value) from an object with appropriate c_type.

getInt

Function

Signature:

val getInt : c_object -> c_int

Description:

Extracts a C int value (represented as an ML value) from an object with appropriate c_type.

getLong

Function

Signature:

val getLong : c_object -> c_long_int

Description:

Extracts a C long value (represented as an ML value) from an object with appropriate c_type.

getUnsignedShort

Function

Signature:

val getUnsignedShort : c_object -> c_short_int

Description:

Extracts a C unsigned short value (represented as an ML value) from an object with appropriate c_type.

getUnsigned

Function

Signature:

val getUnsigned : c_object -> c_int

Description:

Extracts a C unsigned int value (represented as an ML value) from an object with appropriate c_type.

getUnsignedLong

Function

Signature:

val getUnsignedLong : c_object -> c_long_int

Description:

Extracts a C unsigned long value (represented as an ML value) from an object with appropriate c_type.

getWord32

Function

Signature:

val getWord32 : c_object -> word32

Description:

Extracts a 4-byte quantity (that is, C unsigned) from an object with appropriate c_type. The quantity is represented as a Word32 ML value.

getFloat

Function

Signature:

val getFloat : c_object -> c_real

Description:

Extracts a C float (represented as an ML value) from an object with appropriate c_type.

getDouble

Function

Signature:

val getDouble : c_object -> c_double

Description:

Extracts a C double float (represented as an ML value) from an object with appropriate c_type.

getLongDouble

Function

Signature:

val getLongDouble : c_object -> c_long_double

Description:

Extracts a C long double float (represented as an ML value) from an object with appropriate c_type.

getString

Function

Signature:

val getString : c_object -> string

Description:

Extracts an ASCII character string (represented as an ML value) from an object with appropriate c_type.

getData

Function

Signature:

val getData : c_object -> c_object

Description:

Yields an object containing the dereferenced value of the given pointer. This is a synonym for the copyDerefObject function. See page 267.

getStruct

Function

Signature:

val getStruct : c_object -> c_object list

Description:

Yields a list of objects each corresponding to a field of the given C struct object.

getField

Function

Signature:

val getField : c_object * name -> c_object

Description:

Yields the value of a given field. This is a synonym for the copySelectObject function. See page 267.

getUnion

Function

Signature:

val getUnion : c_object -> c_object

Description:

Yields an object whose value and c_type correspond to the current member of the given union object. This is a synonym for the copyCoerceObject function. See page 268.

getArray

Function

Signature:

val getArray : c_object -> c_object list

Description:

Yields a list of objects corresponding to the elements of the given array object.

getEnum

Function

Signature:

val getEnum : c_object -> int

Description:

Yields an integer corresponding to the enumerated value represented by the object given.

---

MLWorks Reference Manual version 2.0 - 29 Jul 1998

Generated with Harlequin WebMaker