# C Allocators
The header ftalloc.h defines functions to allocate and free devices and a few
utility functions. The devices' main functionality is defined in the
[ftop.h](c_operations.md) header.
| Content |
| ---------------------------------------------------------- |
| [ftop_alloc_txt](#alloc_txt) |
| [ftop_alloc_switch](#alloc_switch) |
| [ftop_alloc_digital](#alloc_digital) |
| [ftop_alloc_voltmeter](#alloc_voltmeter) |
| [ftop_alloc_ultrasonic](#alloc_ultrasonic) |
| [ftop_alloc_resistor](#alloc_resistor) |
| [ftop_alloc_ncttermistor](#alloc_ncttermistor) |
| [ftop_alloc_colorsensor](#alloc_colorsensor) |
| [ftop_alloc_trail_follower](#alloc_trail_follower) |
| [ftop_alloc_counter](#alloc_counter) |
| [ftop_alloc_lamp](#alloc_lamp) |
| [ftop_alloc_servo](#alloc_servo) |
| [ftop_alloc_motor](#alloc_motor) |
| [ftop_alloc_encoder](#alloc_encoder) |
| [ftop_alloc_motor_step_counter](#alloc_motor_step_counter) |
| [ftop_free_txt](#free_txt) |
| [ftop_free_device](#free_device) |
| [ftop_alloc_mode](#alloc_mode) |
| [ftop_alloc_code](#alloc_code) |
| [ftop_check_usage](#check_usage) |
| [ftop_get_conn](#get_conn) |
| [ftmop_get_typename](#get_typename) |
| [ftop_extend_range](#extend_range) |
| [ftop_get_txt](#get_txt) |
## Allocators
*Note*: In case of an error, all allocator functions return *NULL*! It is
advisable to check the returned pointer before continuing.
```C
#include
fttxt2 *txt = ftop_alloc_txt("auto", 65000);
if (txt == NULL) {
// error during initialization of the TXT
// handle error
return 1;
}
```
### fttxt2 *ftop_alloc_txt(const char *host, int port)
Allocates the resourses for a [TXT 4.0](devices.md#txt) object and
initializes it. The object needs to be deleted using [ftop_free_txt](#free_txt) before the program
ends to free resourses! As of now, the parameteres for host and port are unused.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | host | sting describing host, use *"auto"* (unused) |
| in | port | port (unused) |
Return:
pointer to TXT object
### ftdevice *ftop_alloc_switch(fttxt2 *txt, int num)
Allocates the resources for a [switch](devices.md#switch) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_i1 - ftdev_i8*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_i1 - ftdev_i8*] |
Return:
pointer to switch object
### ftdevice *ftop_alloc_digital(fttxt2 *txt, int num)
Allocates the resources for a [digital](devices.md#digital) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_i1 - ftdev_i8*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_i1 - ftdev_i8*] |
Return:
pointer to digital object
### ftdevice *ftop_alloc_resistor(fttxt2 *txt, int num)
Allocates the resources for a [resistor](devices.md#resistor) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_i1 - ftdev_i8*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_i1 - ftdev_i8*] |
Return:
pointer to resistor object
### ftdevice *ftop_alloc_voltmeter(fttxt2 *txt, int num)
Allocates the resources for a [voltmeter](devices.md#voltmeter) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_i1 - ftdev_i8*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_i1 - ftdev_i8*] |
Return:
pointer to voltmeter object
### ftdevice *ftop_alloc_ultrasonic(fttxt2 *txt, int num)
Allocates the resources for an [ultrasonic](devices.md#ultrasonic) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection)
enum (*ftdev_i1 - ftdev_i8*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_i1 - ftdev_i8*] |
Return:
pointer to ultrasonic object
### ftdevice *ftop_alloc_ncttermistor(fttxt2 *txt, int num)
Allocates the resources for a [ncttermistor](devices.md#ncttermistor) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_i1 - ftdev_i8*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_i1 - ftdev_i8*] |
Return:
pointer to ncttermistor object
### ftdevice *ftop_alloc_colorsensor(fttxt2 *txt, int num)
Allocates the resources for a [colorsensor](devices.md#colorsensor) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_i1 - ftdev_i8*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_i1 - ftdev_i8*] |
Return:
pointer to colorsensor object
### ftdevice *ftop_alloc_trail_follower(fttxt2 *txt, int num)
Allocates the resources for a [trail follower](devices.md#trailfollower) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_i1 - ftdev_i8*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_i1 - ftdev_i8*] |
Return:
pointer to trail follower object
### ftdevice *ftop_alloc_counter(fttxt2 *txt, int num)
Allocates the resources for a [counter](devices.md#counter) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_c1 - ftdev_c4*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_c1 - ftdev_c4*] |
Return:
pointer to counter object
### ftdevice *ftop_alloc_lamp(fttxt2 *txt, int num)
Allocates the resources for a [lamp](devices.md#output-lamp) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_o1 - ftdev_o8*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_o1 - ftdev_o8*] |
Return:
pointer to lamp object
### ftdevice *ftop_alloc_servo(fttxt2 *txt, int num)
Allocates the resources for a [servo](devices.md#servo) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_s1 - ftdev_s3*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_s1 - ftdev_s3*] |
Return:
pointer to servo object
### ftdevice *ftop_alloc_motor(fttxt2 *txt, int num)
Allocates the resources for a [motor](devices.md#motor) device.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_m1 - ftdev_m4*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_m1 - ftdev_m4*] |
Return:
pointer to motor object
### ftdevice *ftop_alloc_encoder(fttxt2 *txt, int num)
Allocates the resources for an [encoder](devices.md#lamp) device including
the corresponding counter.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_m1 - ftdev_m4*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_m1 - ftdev_m4*] |
Return:
pointer to encoder object
### ftdevice *ftop_alloc_motor_step_counter(fttxt2 *txt, int num)
Allocates the resources for a counter associated with an encoder motor. This
function is mainly for internal purposes and usually not called by the user.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_c1 - ftdev_c4*) to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number [*ftdedv_c1 - ftdev_c4*] |
Return:
pointer to counter object
## Deallocators
### void ftop_free_txt(fttxt2 *txt)
Deallocates the TXT object and frees all resources. This function **MUST** be
called before the program ends.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
### void ftop_free_device(ftdevice *device)
Frees all resources and resets connection used by device.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | devicd | pointer to device |
## Utility Functions
### int ftop_alloc_mode(fttxt2 *txt, int num)
Returns the mode of the device. For universal inputs, this function returns the
combination of [measurement mode and resolution](devices.md#inputs---generic)
and for outputs/motors the output configuration (whether it's an output or a motor).
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_i1 - ftdev_i8*, *ftdev_o1 - ftdev_o8*, *ftdev_m1 - ftdev_m4*) to specify the
pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number |
Return:
allocation mode
### int ftop_alloc_code(fttxt2 *txt, int num)
Returns the type of the device. For universal inputs, this function returns the
sensor type and for outputs/motors their type as well.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
(*ftdev_i1 - ftdev_i8*, *ftdev_o1 - ftdev_o8*, *ftdev_m1 - ftdev_m4*) to specify the
pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number |
Return:
allocation code (device type)
### int ftop_check_usage(fttxt2 *txt, int num)
Returns whether or not a device is allocated for that connector.
*Note*: Use the values from the [ftobjects_connection](c_fttypes.md#ftobjects_connection) enum
to specify the pin.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | txt | pointer to TXT object |
| in | num | pin number |
Return:
pin usage
### int ftop_get_conn(ftdevice *device)
Returns the connector number of given device.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | device | pointer to device |
Return:
pin number
### const char *ftmop_get_typename(unsigned int t)
Returns the type name as a string. Takes the device type returned by
[ftop_alloc_code](#alloc_code) as input.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | t | device type |
Return:
device name
### void ftop_extend_range(void *device, int mode)
Sets an input to normal or extended range. Pass 0 for normal detection range
(0 - 5 V) and 1 for extended range (0 - 9 V).
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | device | pointer to device |
| in | mode | new mode: 0 (normal) - 1 (extended) |
### void *ftop_get_txt(void *device)
Returns TXT object the device is connected.
| Type | Parameter | Description |
| ------- | ------------ | ---------------------- |
| in | device | pointer to device |
Return:
pointer to TXT object