Programming Guide: Byte Arrays

# Programming Guide

## Byte Arrays

Byte arrays are used to read from and write to storage units. The functions and macros in this section are used to manipulate byte arrays, or read and write byte arrays in a storage unit or storage unit view. They are available as samples in the UTILS subdirectory.

The following lists the byte array functions and macros in alphabetic order.

- AreByteArraysEqual
- CopyByteArray
- CopyByteArrayStruct
- CreateByteArray
- CreateByteArrayStruct
- CreateEmptyByteArray
- CreateEmptyByteArrayStruct
- DisposeByteArray
- DisposeByteArrayStruct
- StorageUnitGetValue
- StorageUnitSetPromiseValue
- StorageUnitSetValue
- StorageUnitViewGetValue
- StorageUnitViewSetValue
- UseByteArray

### AreByteArraysEqual

This function tests if two byte arrays are equal.

Signature

    #include <BArray.h>

    ODBoolean AreByteArraysEqual (ODByteArray *ba1,
                                  ODByteArray *ba2)

Parameters

ba1 (ODByteArray *) - input

  The first byte array to be compared.

ba2 (ODByteArray *) - input

  The second byte array to be compared.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the byte arrays are equal in content and size.

  kODTrue | The byte arrays are equal.
  kODFalse | The byte arrays are not equal.

### CopyByteArray

This function copies a byte array and returns a pointer to that copy.

Signature

    #include <BArray.h>
         .
    ODByteArray *CopyByteArray (ODByteArray *fromBA)

Parameters

fromBA (ODByteArray *) - input

  The byte array to be copied.

Returns

rv (ODByteArray *) - returns

  A pointer to a copy of the specified byte array.

### CopyByteArrayStruct

This function copies a buffer into a byte array.

Signature

    #include <BArray.h>

    ODByteArray CopyByteArrayStruct (ODByteArray *fromBA)

Parameters

fromBA (ODByteArray *) - input

  The byte array to be copied.

Returns

rv (ODByteArray) - returns

  A copy of the specified byte array.

### CreateByteArray

This function creates a byte array from a buffer of a specified length.

Signature

    #include <BArray.h>

    ODByteArray *CreateByteArray (void *buffer, ODULong size)

Parameters

buffer (void *) - input

  A buffer containing data to be copied into the byte array.

size (ODULong) - input

  The size of the specified buffer.

Returns

rv (ODByteArray *) - returns

  A pointer to the new byte array.

### CreateByteArrayStruct

This function creates a byte array from a buffer of a specified length.

Signature

    #include <BArray.h>

    ODByteArray CreateByteArrayStruct (void *buffer, ODULong size)

Parameters

buffer (void *) - input

  A buffer containing data to be copied into the byte array.

size (ODULong) - input

  The size of the specified buffer.

Returns

rv (ODByteArray) - returns

  A new byte array.

### CreateEmptyByteArray

This function creates an empty byte array.

Signature

    #include <BArray.h>

    ODByteArray *CreateEmptyByteArray (ODULong maximum)

Parameters

maximum (ODULong) - input

  The maximum size of the byte array to be created.

Returns

rv (ODByteArray *) - returns

  A pointer to the new byte array.

### CreateEmptyByteArrayStruct

This function creates an empty byte array.

Signature

    #include <BArray.h>

    ODByteArray CreateEmptyByteArrayStruct (ODULong maximum)

Parameters

maximum (ODULong) - input

  The maximum size of the byte array to be created.

Returns

rv (ODByteArray) - returns

  A new byte array.

### DisposeByteArray

This function deletes the specified byte array and its content.

Signature

    #include <BArray.h>

    void DisposeByteArray (ODByteArray *byteArray)

Parameters

byteArray (ODByteArray *) - input

  A pointer to the byte array to be deleted.

Returns

None.

### DisposeByteArrayStruct

This macro deletes the specified byte array and its content.

Signature

    #include <BArray.h>

    void DisposeByteArrayStruct (ODByteArray byteArray)

Parameters

byteArray (ODByteArray) - input

  The byte array to be deleted.

Returns

None.

### StorageUnitGetValue

This function reads a value from a storage unit, starting at the offset.

Signature

    #include <StorUtil.h>

    ODULong StorageUnitGetValue (ODStorageUnit *su,
                                 Environment *ev,
                                 ODULong size,
                                 ODPtr buffer)

Parameters

su (ODStorageUnit *) - input

  The storage unit whose value is to be read. This storage unit is prefocussed to the appropriate property and value.

ev (Environment *) - input

  The SOM environment.

size (ODULong) - input

  The size of the buffer.

buffer (ODPtr) - input

  The buffer to read data into.

Returns

rv (ODULong) - returns

  The number of bytes read.

### StorageUnitSetPromiseValue

This macro writes a promise into a storage unit, starting at the offset.

Signature

    #include <StorUtil.h>

    void StorageUnitSetPromiseValue (ODStorageUnit *su,
                                     Environment *ev,
                                     ODULong type,
                                     ODULong offset,
                                     ODULong size,
                                     void *buffer,
                                     ODPart sourcePart)

Parameters

su (ODStorageUnit *) - input

  The storage unit into which to write the promise. This storage unit is prefocussed to the appropriate property and value.

ev (Environment *) - input

  The SOM environment.

type (ODULong) - input

  The type of value to contain the promise.

offset (ODULong) - input

  The offset at which the promise data is to be written in the storage unit.

size (ODULong) - input

  The size of the promise to be written.

buffer (void *) - input

  A pointer to a buffer containing the promise data.

sourcePart (ODPart) - input

  A reference to the part that made the promise.

Returns

None.

### StorageUnitSetValue

This macro writes a value into a storage unit, starting at the offset.

Signature

    #include <StorUtil.h>

    void StorageUnitSetValue (ODStorageUnit *su,
                              Environment *ev,
                              ODULong size,
                              void *buffer)

Parameters

su (ODStorageUnit *) - input

  The storage unit to write the value into. This storage unit is prefocussed to the appropriate property and value.

ev (Environment *) - input

  The SOM environment.

size (ODULong) - input

  The size of the buffer.

buffer (void *) - input

  A pointer to the buffer containing the value to be written.

Returns

None.

### StorageUnitViewGetValue

This function reads data from the currently focused value in the specified storage unit, starting at the offset.

Signature

    #include <StorUtil.h>

    ODULong StorageUnitViewGetValue (ODStorageUnitView *suv,
                                     Environment *ev,
                                     ODULong size,
                                     ODPtr buffer)

Parameters

suv (ODStorageUnitView *) - input

  The storage unit to be queried.

ev (Environment *) - input

  The SOM environment.

size (ODULong) - input

  The size of the buffer.

buffer (ODPtr) - input

  A pointer to a buffer to read data into.

Returns

rv (ODULong) - returns

  The number of bytes read.

### StorageUnitViewSetValue

This macro writes data to the currently focused value in the specified storage unit, starting at the offset.

Signature

    #include <StorUtil.h>

    void StorageUnitViewSetValue (ODStorageUnitView *suv,
                                  Environment *ev,
                                  ODULong size,
                                  void *buffer)

Parameters

suv (ODStorageUnitView *) - output

  The storage unit to be queried.

ev (Environment *) - input

  The SOM environment.

size (ODULong) - input

  The size of the buffer.

buffer (void *) - input

  A pointer to the buffer containing the data to be written.

Returns

None.

### UseByteArray

This function instantiates a byte array to the specified buffer of a specified size.

Signature

    #include <BArray.h>

    void UseByteArray (ODByteArray *ba,
                       void *buffer,
                       ODULong size)

Parameters

ba (ODByteArray *) - input

  The byte array to be instantiated.

buffer (void *) - input

  A buffer containing the data.

size (ODULong) - input

  The size of the specified buffer.

Returns

None.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]