> ## Chapter 5. Function Reference for Target Applications

> ### 5.1 TCP/IP Subsystem

> ## devmate_ip_resolve

>     int devmate_ip_resolve(uint16 * request_id, char * remote_host, uint32 * ipaddr);

> ### Description

> Perform a DNS (Domain Name Server) lookup of an internet host name. The host name is resolved into a binary IP address. Since DNS lookups can be time-consuming, this function must be called several times to complete the process of looking up one hostname. Several hostnames may be resolved simultaneously if the appropriate state information is retained.

> ### Parameters

> #### request_id

> Pointer to a "handle" that is used to identify the resolver request. This handle should be initialized to zero for the first call for a given host name. On return, the handle will be set to a unique identifier. On subsequent calls, the same handle must be passed until success or failure is declared.

> #### remote_host

> The host name to resolve. This may be an internet host name, or a "dotted quad" (e.g. "10.10.6.2"). The same host name should be passed on all calls to this function (for a particular request id) until the name is resolved.

> #### ipaddr

> Pointer to place to store the resolved IP address.

> ### Return Value

> `0`: Try again later.
> `1`: Name successfully resolved.
> `-2`: DeviceMate not initialized or no name resolver has been configured.
> Other negative values: Error.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ## devmate_sock_init

>     int devmate_sock_init(uint32 *ipaddress, uint32 *netmask, uint32 *gateway, uint32 *nameserver, char * classid, char * clientid);

> ### Description

> Establish communication link to the DeviceMate. If a link is already established, then any open sockets are aborted and the link is re-established.

> ### Parameters

> All parameters are reserved for future use. At present, `NULL` should be given for each parameter.

> ### Return Value

> 1

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_status

> ## devmate_tcp_abort

>     int devmate_tcp_abort(int socket);

> ### Description

> Close a socket forcibly. This is used to signal the peer that the stream is in error. The peer may or may not actually receive the abort indicator; however, the library considers the socket to be closed. After calling this function, `devmate_tcp_error()` will return a non-zero code.

> Note that sockets are sometimes forcibly closed by other library functions. For example, if `devmate_sock_init()` is called, then any open sockets will be aborted.

> This function is also used to close UDP sockets. In this case, there is no special meaning to "abort," since UDP sockets are not connection-oriented so either peer may close its socket at any time.

> ### Parameters

> #### socket

> The socket number as used by `devmate_tcp_open()`, `devmate_tcp_listen()` and `devmate_udp_open()`.

> ### Return Value

> `0`

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_close

> ## devmate_tcp_maxsocket

>     int devmate_tcp_maxsocket(void);

> ### Description

> Return the maximum allowable socket number. This is the minimum of the configured value for the target and DeviceMate. The value is only available after calling `devmate_sock_init()`.

> ### Return Value

> `0`: Value not yet available.

> `>0`: Maximum socket number. Valid socket numbers on future calls to the TCP/IP subsystem API must fall between 1 and this number inclusive.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_sock_init, devmate_tcp_open

> ## devmate_tcp_close

>     int devmate_tcp_close(int socket);

> ### Description

> Close a socket gracefully. Calling this function indicates that no more data will be written. The peer is notified. Data may be read until the peer performs a corresponding close, or the socket is forcibly closed using `devmate_tcp_abort()`. After calling this function, `devmate_tcp_writable()` returns 0, and `devmate_tcp_readable()` may or may not return 0.

> This function is a macro alias of `devmate_tcp_shutdown()`. It is only used for TCP sockets.

> ### Parameters

> #### socket

> The socket number as used by devmate_tcp_open/listen()

> ### Return Value

> `0`: Closed successfully.
> `1`: Socket not open, or is in the process of closing.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_abort, devmate_udp_close

> ## devmate_tcp_error

>     int devmate_tcp_error(int socket);

> ### Description

> Check the socket to see if any error has occurred. Errors may occur because of programming error, link problems with the DeviceMate, or errors on the actual TCP/IP connection.

> ### Parameters

> #### socket

> The socket number as used by devmate_tcp_open/listen() or `devmate_udp_open()`

> ### Return Value

> `0`: No error has occurred.

> `!0`: Error occurred; the socket may be immediately re-opened. The error codes are not officially defined, but may be logged for debugging purposes.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_isestablished, devmate_tcp_readable, devmate_tcp_writable, devmate_tcp_isclosed

> ## devmate_tcp_fastread

>     int devmate_tcp_fastread(int socket, void* buffer, uint16 length);

> ### Description

> Read up to `length` bytes of data from the socket receive buffer into the given buffer. In general, less than `length` bytes may be moved. In this case, the caller must recall this function to deliver the remainder of data. This is typically performed via a loop that keeps track of the total data amount to read and the amount that has been successfully read. Applications that can afford to wait until all data are available can spin on this function.

> If `devmate_tcp_readable()` returns N for a given socket, then a request for less than or equal (N-1) bytes is guaranteed to return the full amount requested.

> ### Parameters

> #### socket

> The socket number as used by devmate_tcp_open/listen()

> #### buffer

> Pointer to the first byte of the local buffer

> #### length

> Desired length of data to read

> ### Return Value

> `-1`: Error occurred; socket is not readable.
> `0`: No data is available for reading.
> `1..(length-1)`: Data was partially read.
> `length`: Data was completely read.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_readable, devmate_tcp_fastwrite, devmate_tcp_preread

> ## devmate_tcp_fastwrite

>     int devmate_tcp_fastwrite(int socket, void* buffer, uint16 length);

> ### Description

> Write up to `length` bytes of data from `buffer` into the socket transmit buffer. In general, less than `length` bytes may be buffered. In this case, the caller must recall this function to deliver the remainder of data. Typically, this is performed via a loop that keeps track of the total data amount to transmit and the amount that has been successfully buffered. Applications that can afford to wait until all data is buffered can spin on this function. Once the data is buffered, then the underlying library will ensure that it is transmitted to the DeviceMate, so long as the application keeps calling the `devmate_tick()` function.

> If `devmate_tcp_writable()` returns N for a given socket, then a request for less than or equal (N-1) bytes is guaranteed to buffer the full amount requested.

> ### Parameters

> #### socket

> The socket number as used by devmate_tcp_open/listen().

> #### buffer

> Pointer to the first byte to write to the buffer.

> #### length

> Desired length of data to write.

> ### Return Value

> `-1`: Error occurred; the socket is not writable.
> `0`: No data could be written because the transmit buffer is full.
> `1..(length-1)`: Data was partially buffered.
> `length`: Data was completely buffered.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_writable, devmate_tcp_fastread

> ## devmate_tcp_isclosed

>     int devmate_tcp_isclosed(int socket);

> ### Description

> Check the socket to see if a TCP (stream) connection is currently closed. It is necessary to call this function on a socket that has been closed using `devmate_tcp_close()` since the socket will not actually close until the peer has finished transmitting data. After this function returns 1, then `devmate_tcp_error()` should also be called to ensure that the connection closed normally i.e. all data was transferred successfully.

> ### Parameters

> #### socket

> The socket number as used by devmate_tcp_open/listen()

> ### Return Value

> `0`: Connection currently established.
> `1`: Socket completely closed, and may be immediately re-opened.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_close, devmate_tcp_readable, devmate_tcp_writable, devmate_tcp_abort, devmate_tcp_error

> ## devmate_tcp_isestablished

>     int devmate_tcp_isestablished(int socket);

> ### Description

> Check the socket to see if a TCP (stream) connection is currently, or was recently, established. After passively opening a socket with `devmate_tcp_listen()`, this function is called to determine if a connection is, or was, made. This function may also be used for actively opened TCP sockets to check that the connection is still open.

> ### Parameters

> #### socket

> The socket number as used by devmate_tcp_open/listen()

> ### Return Value

> `0`: No connection is currently established.

> `1`: Connection is currently established, or was established but immediately closed with no transfer of data. It is possible to read zero or more bytes of data.

> `-1`: Connection was established but immediately aborted. `devmate_tcp_error()` will return a non-zero code for further diagnostic information.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_listen, devmate_tcp_readable, devmate_tcp_writable, devmate_tcp_isclosed, devmate_tcp_error

> ## devmate_tcp_listen

>     int devmate_tcp_listen(uint8 socket, uint16 local_port, char * remote_host, uint16 remote_port);

> ### Description

> Open a TCP socket via the DeviceMate. This is implemented as a macro which invokes `devmate_tcp_start()`. The socket is opened passively, meaning that it waits for active connections from other host(s). The application must periodically call `devmate_tcp_isestablished()` to check whether any connection has been made.

> ### Parameters

> #### socket

> Socket number to use. This may be a number between 1 and `TCT_MAXTCPSOCK` inclusive. The application must select a socket number that is not already open or in use. This may also be 0, in which case an unused socket number will be selected (and returned as a positive number).

> #### local_port

> A local port number to use. This must be specified.

> #### remote_host

> This is normally `NULL`, to allow any remote host to establish a connection. If not `NULL`, it specifies the only host allowed to establish a connection with this socket.

> #### remote_port

> This is normally zero, which allows connections from any port on the remote host. If non-zero, then the remote host must connect from this port number.

> ### Return Value

> `0`: The open request could not be performed; try again later. This may be because the DeviceMate is not yet fully linked, or because there is temporary buffer shortage.

> `>0`: Opened successfully. The return value is the same socket number as passed in the first parameter or the assigned socket number if the parameter was 0.

> `-1`: Error; host lookup failure or DeviceMate not linked.
> `-2`: Error; DeviceMate not linked because `devmate_sock_init()` was not called.
> `-3`: Error; requested socket number out of range.
> `-4`: Error; requested socket number already in use.
> `-5`: Error; requested socket number zero, but none free.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_open, devmate_udp_open, devmate_tcp_close

> ## devmate_tcp_open

>     int devmate_tcp_open(uint8 socket, uint16 local_port, char * remote_host, uint16 remote_port);

> ### Description

> Open a TCP socket via the DeviceMate. This is implemented as a macro which invokes `devmate_tcp_start()`.

> ### Parameters

> #### socket

> Socket number to use. This may be a number between 1 and `devmate_tcp_maxsocket()` inclusive. The application must select a socket number that is not already open or in use.This may also be 0, in which case an unused socket number will be selected (and returned as a positive number).

> #### local_port

> A local port number to use. If zero, then a port number will be assigned automatically.

> #### remote_host

> The name of a remote host to connect to. This may be a dotted quad (e.g. "10.10.6.2") or a host name (e.g. "ftp.zworld.com" or "server_host"). If a host name is given, then the DeviceMate will look up the host's IP address using DNS.

> #### remote_port

> The port on the remote host to connect to.

> ### Return Value

> `0`: The open request could not be performed; try again later. This may be because the DeviceMate is not yet fully linked, or because there is temporary buffer shortage.

> `>0`: Opened successfully. The return value is the same socket number as passed in the first parameter or the assigned socket number if the parameter was 0.

> `-1`: Error; remote host not available.
> `-2`: Error; DeviceMate not linked because `devmate_sock_init()` was not called.
> `-3`: Error; requested socket number out of range.
> `-4`: Error; requested socket number already in use.
> `-5`: Error; requested socket number zero, but none free.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_listen, devmate_udp_open, devmate_tcp_close

> ## devmate_tcp_preread

>     int devmate_tcp_preread(int socket, void* buffer, uint16 length);

> ### Description

> Read up to length bytes of data from the socket receive buffer into the given buffer. In general, less than length bytes may be moved. Unlike `devmate_tcp_fastread()`, this function does not actually remove the data from the receive buffer. This function is used to give a "sneak preview" of the data in the buffer. Sequential calls to this function will return the same data each time, until `devmate_tcp_fastread()` is used to read and remove the data. Each sequential call to this function may return more data than the previous time, since there may be new data appended to the receive buffer.

> If `devmate_tcp_readable()` returns N for a given socket, then a request for less than or equal (N-1) bytes is guaranteed to return the full amount requested.

> ### Parameters

> #### socket

> The socket number as used by devmate_tcp_open/listen()

> #### buffer

> Pointer to the first byte of the local buffer

> #### length

> Desired length of data to read

> ### Return Value

> `-1`: Error occurred; socket not readable.
> `0`: No data available for reading.
> `1..(length-1)`: Data partially copied.
> `length`: Data completely copied.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_readable, devmate_tcp_fastread

> ## devmate_tcp_readable

>     uint16 devmate_tcp_readable(int socket);

> ### Description

> Return the number of data bytes which may be read from the socket receive buffer. The return value is encoded such that it can be interpreted as a boolean indicator of whether the socket is in a readable state, or as the actual number of bytes which can be read with one call to `devmate_tcp_fastread()`.

> ### Parameters

> #### socket

> The socket number as used by devmate_tcp_open/listen().

> ### Return Value

> `0`: the socket is not readable e.g. it is not open, or encountered an error.

> `!0`: the number of bytes which can be read, plus 1. E.g. if the return value is 5, then 4 bytes can be read immediately using `devmate_tcp_fastread()`. If the return value is 1, then the socket is readable but there is currently no data in the receive buffer.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_isestablished, devmate_tcp_fastread, devmate_tcp_writable, devmate_tcp_isclosed

> ## devmate_tcp_status

>     int devmate_tcp_status(void);

> ### Description

> Test communication link to the DeviceMate. The link status indicates whether TCP/IP functions can be accessed on the DeviceMate.

> ### Return Value

> `0`: The link is currently being established.
> `1`: The link is successfully established.

> `-1`: An error has occurred. Call `devmate_sock_init()` to re-establish the link. An error typically occurs because there is either no DeviceMate, or because the DeviceMate is not configured for TCP/IP support.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_sock_init

> ## devmate_tcp_writable

>     uint16 devmate_tcp_writable(int socket);

> ### Description

> Return the number of data bytes that may be written to the socket transmit buffer. The return value is encoded such that it can be interpreted as a boolean indicator of whether the socket is in a writable state, or as the actual number of bytes which can be written with one call to `devmate_tcp_fastwrite()`.

> ### Parameters

> #### socket

> The socket number as used by devmate_tcp_open/listen().

> ### Return Value

> `0`: The socket is not writable e.g. it is not open, or encountered an error.

> `!0`: The number of bytes which can be written, plus 1. E.g. if the return value is 200, then 199 bytes can be written immediately using `devmate_tcp_fastwrite()`. If the return value is 1, then the socket is writable but there is currently no space for new data in the transmit buffer. The latter situation occurs when new data is being generated faster than it can be transmitted to the DeviceMate or remote host.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_isestablished, devmate_tcp_readable, devmate_tcp_fastwrite, devmate_tcp_isclosed

> ## devmate_udp_close

>     int devmate_udp_close(int socket);

> ### Description

> Close a UDP socket. This is actually a macro alias for `devmate_tcp_abort()`. UDP sockets are normally opened for the lifetime of the application; however, if it is desired to re-use the socket number taken by a UDP socket, then it is necessary to first close the UDP socket to release resources held for it on the target and DeviceMate processors.

> ### Parameters

> #### socket

> The socket number as used by `devmate_udp_open()`.

> ### Return Value

> `0`

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_close, devmate_tcp_abort

> ## devmate_udp_open

>     int devmate_udp_open(uint8 socket, uint16 local_port, char * remote_host, uint16 remote_port);

> ### Description

> Open a UDP socket via the DeviceMate. This is implemented as a macro which invokes `devmate_tcp_start()`. UDP datagrams are delivered reliably (via an XTC channel) to the DeviceMate, which then sends the datagram using normal UDP which, by its nature, is an unreliable delivery service.

> ### Parameters

> #### socket

> Socket number to use. This must be a number between 1 and `devmate_tcp_maxsocket()` inclusive. The application must select a socket number that is not already open or in use. This may also be 0, in which case an unused socket number will be selected (and returned as a positive number).

> #### local_port

> A local port number to use. If zero, then a port number will be assigned automatically.

> #### remote_host

> The name of a remote host to connect to. This may be a dotted quad (e.g. "10.10.6.2") or a host name (e.g. "ftp.zworld.com" or "server_host"). If a host name is given, then the DeviceMate will look up the host's IP address using DNS. For UDP, this parameter may also be `NULL`. In this case, no host is selected as a default; `devmate_udp_sendto()` must be used to specify a remote host on a call-by-call basis. If a non-`NULL` host is specified, then that host is used as a default destination if `devmate_udp_send()` is used; however `devmate_udp_sendto()` may still be used to direct datagrams to other hosts.

> #### remote_port

> The port on the remote host to connect to. This may be zero if `devmate_udp_sendto()` is used consistently to specify the remote port on a call-by-call basis.

> ## devmate_udp_open (continued)

> ### Return Value

> `0`: The open request could not be performed; try again later. This may be because the DeviceMate is not yet fully linked, or because there is temporary buffer shortage.

> `>0`: Opened successfully. The return value is the same socket number as passed in the first parameter.

> `-1`: Error; remote host not available.
> `-2`: Error; DeviceMate not linked because devmate_sock_init has not been called.
> `-3`: Error; requested socket number out of range.
> `-4`: Error; requested socket number already in use.
> `-5`: Error; requested socket number zero, but none free.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_tcp_listen, devmate_tcp_open, devmate_udp_close

> ## devmate_udp_recvdata

>     int devmate_udp_recvdata(int socket, void* buffer, uint16 max_length, uint16 recv);

> ### Description

> Receive datagram payload data. This function may be called after `devmate_udp_recvfrom()` indicates that a datagram has arrived. It should be called repeatedly (updating `recv`) until all required data has been read. It is not necessary to read all data before calling `devmate_udp_recvfrom()` again. When re-calling, do not change any of the passed parameters except for `recv`.

> ### Parameters

> #### socket

> The socket number as used by `devmate_udp_open()`

> #### buffer

> Pointer to start of datagram buffer

> #### max_length

> Maximum length of the datagram buffer

> #### recv

> Number of bytes transferred by previous calls to this function. This should be zero for the first call, then should be the returned value from the previous call. This allows the datagram to be transferred piecemeal.

> ### Return Value

> `-1`: Error occurred.

> ³ `0`: The total number of bytes transferred so far. If this is less than the length originally returned by `devmate_udp_recvfrom()`, then this function may be called again (with this return value passed as the `recv` parameter) to get the remainder of the datagram.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_udp_sendto, devmate_udp_open, devmate_udp_recvfrom

> ## devmate_udp_recvfrom

>     int devmate_udp_recvfrom(int socket, uint32* remote_host, uint16* remote_port);

> ### Description

> Receive notification of UDP datagram availability from the given socket. If a datagram is available, the data may be retrieved using one or more calls to `devmate_udp_recvdata()`. This two-phase receive process is a consequence of the reliable transport between the target and DeviceMate processors, and the possibly limited buffer space on the target.

> This function only provides notification of the presence of a new datagram. Usually the data would be retrieved using `devmate_udp_recvdata()`. However, if this function is called again before reading the data (or partially reading it), then the rest of the previous datagram will be discarded. It is thus not necessary to call `devmate_udp_recvdata()`if the actual data is not important.

> ### Parameters

> #### socket

> The socket number as used by `devmate_udp_open()`.

> #### remote_host

> Pointer to storage for the IP address of the sender. This may be `NULL` if the sender's address is not required.

> #### remote_port

> Pointer to storage for the sender's port number. May be `NULL` if not required, however if `NULL` it is not possible to distinguish between reception of a zero-length datagram and no datagram at all.

> ### Return Value

> `-1`: Error occurred.

> `0`: Datagram not available (try again later), or a zero-length datagram is available. These two cases are distinguished by examining the returned remote port: this will be zero if there is no datagram, or non-zero if there is a zero-length datagram.

> ³ `0`: The received datagram length.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_udp_sendto, devmate_udp_open, devmate_udp_recvdata

> ## devmate_udp_sendto

>     int devmate_udp_sendto(int socket, void* buffer, uint16 length, uint16 trans, uint32 remote_host, uint16 remote_port);

> ### Description

> Transmit a UDP datagram to the specified remote host and port number. UDP datagrams are sent in two phases: the data is reliably transmitted to the DeviceMate, then the DeviceMate sends the entire datagram on the network. The initial phase may require sending the datagram in more than one chunk, if the local transmit buffer is not large enough to contain the entire datagram (and header). This requires that the application call this function repeatedly until the return value indicates that all data has been buffered. When re-calling, do not change any of the passed parameter values except for trans.

> ### Parameters

> #### socket

> The socket number as used by `devmate_udp_open()`.

> #### buffer

> Pointer to the start of the datagram to transmit

> #### length

> Total length of the datagram

> #### trans

> Zero on first call to transmit a new datagram. Subsequently, this parameter is the number of bytes that have been transferred so far; i.e. the return value from the previous call to this function.

> #### remote_host

> IP address of the remote host. This may be zero to use the host selected on the initial call to open the UDP socket. Otherwise, this must be a binary IP address either hard-coded or obtained from `devmate_ip_resolve()`.

> #### remote_port

> Remote UDP port number. May be zero to use the port selected on the initial call to open the UDP socket

> ### Return Value

> `-1`: Error occurred.

> ³ `0`: The total number of bytes that have been successfully transferred from this datagram. If this is less than `length`, then this return value should be provided to a subsequent call to this function to complete the transfer of this datagram. If equal to `length`, then the datagram has been fully transferred so that a new datagram may be transmitted.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_udp_send, devmate_udp_open, devmate_udp_recvfrom, devmate_udp_recvdata

> ## devmate_udp_send

>     int devmate_udp_send(int socket, void* buffer, uint16 length, uint16 trans);

> ### Description

> Transmit a UDP datagram to the remote host and port number which were specified on the original call to `devmate_udp_open()` for this socket. This is implemented as a macro which invokes `devmate_udp_sendto()` with zero remote host and port numbers. See the description of `devmate_udp_sendto()` for more details.

> ### Parameters

> #### socket

> The socket number as used by `devmate_udp_open()`

> #### buffer

> Pointer to the start of the datagram to transmit

> #### length

> Total length of the datagram

> #### trans

> Zero on first call to transmit a new datagram. Subsequently, this parameter is the number of bytes that have been transferred so far; i.e. the return value from the previous call to this function.

> ### Return Value

> `-1`: Error occurred.
> ³ `0`: Total number of bytes successfully transferred from this datagram.

> ### Library

> dm_tcp.lib (Rabbit-based targets)
> dm_tcp.c (nonRabbit-based targets)

> ### See Also

> devmate_udp_sendto, devmate_udp_open, devmate_udp_recvfrom, devmate_udp_recvdata

> ### 5.2 E-Mail Subsystem

> ## devmate_smtp_mailtick

>     int16 devmate_smtp_mailtick(void);

> ### Description

> Repetitively call this function until e-mail is completely sent. For a small message, this function will need to be called about 20 times to send the message. The number of times will vary depending on the latency of the connection to the mail server and the size of your message.

> This function should be called repeatedly to iterate through the steps of the SMTP protocol after calling one of the sendmail functions.

> ### Return Value

> `DM_SMTP_SUCCESS`: E-mail sent successfully.
> `DM_SMTP_PENDING`: E-mail not sent, call `devmate_smtp_mailtick()` again.
> `DM_SMTP_TIME`: E-mail not sent within `DM_SMTP_TIMEOUT` seconds.
> `DM_SMTP_UNEXPECTED`: Received an invalid response from SMTP server.

> ### Library

> dm_smtp.lib (Rabbit-based target)
> dm_smtp.c (nonRabbit-based target)

> ### See Also

> devmate_smtp_sendmail, devmate_smtp_status

> ## devmate_smtp_sendmail

>     void devmate_smtp_sendmail(char* to, char* from, char* subject, char* message);

> ### Description

> Begin sending an e-mail message. The sum of the string lengths of `to`, `from` and `subject` must be less than or equal to 224. You must call `devmate_smtp_mailtick()` to complete processing.

> The parameter strings must be held constant until the `devmate_smtp_mailtick()` returns something other than `DM_SMTP_PENDING`.

> ### Parameters

> #### to

> String containing the e-mail address of the recipient, or a comma-delimited list of recipients (e.g. "nobody@nowhere.org" or "foo@bar.com,baz@bar.com").

> #### from

> String containing the e-mail address of the sender, or at least an address of a mailbox for the server to post back any error messages.

> #### subject

> A subject string

> #### message

> A string containing the message body. This string must NOT contain the byte sequence "\r\n.\r\n" (CRLF.CRLF), as this is used to mark the end of the e-mail, and will be appended to the e-mail automatically. The maximum length of this string is limited by the lesser of root data space, or 32k. For strict RFC compliance, lines should be delimited with "\r\n" sequences, not just "\n". For longer messages, see `devmate_smtp_sendmailxmem()`.

> ### Library

> dm_smtp.lib (Rabbit-based target)
> dm_smtp.c (nonRabbit-based target)

> ### See Also

> devmate_smtp_mailtick, devmate_smtp_status, devmate_smtp_sendmailxmem

> ## devmate_smtp_sendmailxmem

>     void devmate_smtp_sendmailxmem(char* to, char* from, char* subject, faraddr_t message, uint32 messagelen);

> ### Description

> Begin sending an e-mail message. The sum of the string lengths of to, from and subject must be less than or equal to 224 bytes. You must call `devmate_smtp_mailtick()` to complete processing.

> This function is identical to `devmate_smtp_sendmail()` except that longer messages can be contained in extended ("far") memory.

> ### Parameters

> #### to

> String containing the e-mail address of the recipient, or a comma-delimited list of recipients (e.g. "nobody@nowhere.org" or "foo@bar.com,baz@bar.com").

> #### from

> String containing the e-mail address of the sender, or at least an address of a mailbox for the server to post back any error messages.

> #### subject

> Subject string

> #### message

> String containing the message. This string must NOT contain the byte sequence "\r\n.\r\n" (CRLF.CRLF), as this is used to mark the end of the e-mail, and will be appended to the e-mail automatically. The maximum length of this string is limited by the lesser of root data space, or 32k. This string resides in far memory, and does not have to be null-terminated since the length is specified in the next parameter.

> #### messagelen

> Number of bytes of message body

> ### Library

> dm_smtp.lib (Rabbit-based target)
> dm_smtp.c (nonRabbit-based target)

> ### See Also

> devmate_smtp_mailtick, devmate_smtp_status, devmate_smtp_sendmail

> ## devmate_smtp_setdomain

>     int devmate_smtp_setdomain(char* domain);

> ### Description

> Sets the SMTP domain. This value overrides `DEVMATE_SMTP_DOMAIN`. Note that this value should be set to the sender's domain name, since some SMTP servers may be configured to perform a reverse DNS query to verify the identity of the sender. If `DEVMATE_SMTP_DOMAIN` is defined to a suitable default (in tc_conf.lib/h) then there is no need to set the domain using this function.

> ### Parameter

> #### domain

> String containing the domain name e.g. "bunny.org"

> ### Return Value

> `DM_SMTP_OK`: Domain name set successfully.
> `DM_SMTP_NAMETOOLONG`: Domain name was too long (more than `DM_SMTP_MAX_SRVLEN`=100 chars).

> ### Library

> dm_smtp.lib (Rabbit-based target)
> dm_smtp.c (nonRabbit-based target)

> ### See Also

> devmate_smtp_sendmail, devmate_smtp_setserver

> ## devmate_smtp_setsocket

>     int devmate_smtp_setsocket(uint8 socket);

> ### Description

> Sets the DeviceMate socket number to use for SMTP. A socket needs to be set since sockets are shared between SMTP and any direct use of the TCP/IP subsystem by the application. If this function is not called, the socket number will default to that defined in `tc_conf.lib`; currently 2. The socket is used only while sending mail. When `devmate_smtp_mailtick()` returns a value other than `DM_SMTP_PENDING`, the socket may be used for other TCP connections, until it is desired to send another e-mail.

> ### Parameter

> #### socket

> Socket number

> ### Return Value

> `DM_SMTP_OK`: Socket number set successfully.

> `DM_SMTP_BADSOCKNO`: Socket number is invalid. The requested socket number must be between 1 and `devmate_tcp_maxsocket()` inclusive.

> ### Library

> dm_smtp.lib (Rabbit-based target)
> dm_smtp.c (nonRabbit-based target)

> ### See Also

> devmate_smtp_sendmail, devmate_smtp_setserver

> ## devmate_smtp_setserver

>     int16 devmate_smtp_setserver(char* server);

> ### Description

> Sets the SMTP server. This value overrides `DEVMATE_SMTP_SERVER`. If `DEVMATE_SMTP_SERVER` is defined to a suitable default (in tc_conf.lib/h) then there is no need to set the server using this function.

> ### Parameter

> #### server

> String containing the server name e.g. "mail.foo.org"

> ### Return Value

> `DM_SMTP_OK`: Server name was set successfully.
> `DM_SMTP_NAMETOOLONG`: Server name was too long.

> ### Library

> dm_smtp.lib (Rabbit-based target)
> dm_smtp.c (nonRabbit-based target)

> ### See Also

> devmate_smtp_sendmail, devmate_smtp_setdomain

> ## devmate_smtp_status

>     int devmate_smtp_status(void);

> ### Description

> Returns a status code for the current message being sent.

> ### Return Value

> `DM_SMTP_SUCCESS`: E-mail sent.
> `DM_SMTP_PENDING`: E-mail not sent, call `devmate_smtp_mailtick()` again.
> `DM_SMTP_TIME`: E-mail not sent within `DM_SMTP_TIMEOUT` seconds.
> `DM_SMTP_UNEXPECTED`: Received an invalid response from SMTP server.

> ### Library

> dm_smtp.lib (Rabbit-based target)
> dm_smtp.c (nonRabbit-based target)

> ### See Also

> devmate_smtp_sendmail

> ### 5.3 Web Page Variables Subsystem

> ## devmate_var_add

>     int devmate_var_add(char* name, void* variable, uint16 type, char* format, uint16 maxvarlen, uint16 servermask);

> ### Description

> Add a variable entry to be sent to the DeviceMate. The variable is queued for transmission to the DeviceMate. The status of the addition can be checked with `devmate_var_check_status()`.

> ### Parameters

> #### name

> A pointer to a text identifier for the variable. This name must match the name given in the HTML page that references the variable.

> #### variable

> A pointer to the actual variable

> #### type

> The type of the variable`:` `VAR_UINT8``,` `VAR_INT16``,` `VAR_INT32``,` `VAR_FLOAT32``, or` `VAR_STRING`

> #### format

> The printf-style specifier that will be used to display the variable in a web page.

> #### maxvarlen

> Maximum length of the variable's contents. Only necessary for `VAR_STRING`-type variables; for all other variable types it is ignored.

> #### servermask

> A bitmask selecting which servers may use this variable:

> `VAR_SERVER_HTTP
> VAR_SERVER_USER`

> ### Return Value

> `0`: Success.
> `1`: Error (e.g. the variable table is full).

> ### Library

> dm_var.lib (Rabbit-based targets)
> dm_var.c (nonRabbit-based targets)

> ### See Also

> devmate_var_update, devmate_var_check_status

> ## devmate_var_check_status

>     int devmate_var_check_status(char* name);

> ### Description

> Returns the status of a given variable.

> ### Parameters

> #### name

> The name of the variable to check

> ### Return Value

> `DEVMATE_VAR_STATUS_OK``:` Variable has no updates pending and last operation succeeded.
> `DEVMATE_VAR_STATUS_UPDATE_PENDING`: Variable has an update pending.
> `DEVMATE_VAR_STATUS_UPDATE_SENT`: Update sent, but no rely received yet.
> `DEVMATE_VAR_ERROR_FULL``:` Last operation failed --DeviceMate variable table is full.
> `DEVMATE_VAR_ERROR_MISC``:` Last operation failed because of miscellaneous error (such as a communications problem).
> `DEVMATE_VAR_BAD_VARIABLE``:` The given variable name does not exist.

> ### Library

> dm_var.lib (Rabbit-based targets)
> dm_var.c (nonRabbit-based targets)

> ### See Also

> devmate_var_add, devmate_var_update

> ## devmate_var_update

>     int devmate_var_update(char* name);

> ### Description

> Schedules an update of the given variable.

> ### Parameters

> #### name

> The name of the variable to update

> ### Return Values

> `0`: Success.
> `1`: Error (e.g. the variable name does not exist in the internal variable table).

> ### Library

> dm_var.lib (Rabbit-based targets)
> dm_var.c (nonRabbit-based targets)

> ### See Also

> devmate_var_add, devmate_var_check_status

> ### 5.4 File System Subsystem

> Many of these API functions require a subsequent call to `devmate_fs_finish()`, which is noted in the relevant function descriptions.

> ## devmate_fs_append

>     int devmate_fs_append(DMFile *file, char *buf, int length);

> ### Description

> This function will write the data in the specified buffer to the specified file. It works similarly to a standard "write" function.

> `devmate_fs_append()` must be called as part of a transaction: flanked by calls to `devmate_fs_open()` and `devmate_fs_close()`.

> Files can be built piece by piece as part of one transaction, i.e., multiple calls to `devmate_fs_append()` flanked by the open/close functions. Once `devmate_fs_close()` has been called and has returned successfully, that file can not be written to again.

> If this function is called on a file that already exists, an error is returned. On error, the entire transaction has been terminated and must begin from the beginning i.e., starting with the call to `devmate_fs_open()`.

> ### Parameters

> #### file

> Pointer to data structure that identifies the transaction

> #### buf

> Pointer to user's data

> #### length

> The number of bytes from `buf` to append to the specified file

> ### Return Value

> ³ `0`: The number of bytes actually written.
> `-1`: Error, the transaction has been terminated.

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ## devmate_fs_close

>     int devmate_fs_close(DMFile *file, FNumber *id);

> ### Description

> Spin on this function while it returns `TC_PENDING`. This will flush any remaining data and complete the transaction. The number that identifies the file is stored at the location pointed to by the 2nd parameter, `id`, when the transaction is complete.

> ### Parameters

> #### file

> Pointer to transaction identifier

> #### id

> Pointer to number that identifies the file

> ### Return Value

> `TC_PENDING`: File is still closing, call function again
> `TC_ERROR`: Entire transaction must be redone
> `TC_SUCCESS`: Transaction completed

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ## devmate_fs_delete

>     int devmate_fs_delete(DMFile *file, FNumber id);

> ### Description

> This function causes the specified file to be deleted on the DeviceMate. A subsequent call to `devmate_fs_finish()` is required.

> ### Parameters

> #### file

> Pointer to transaction identifier

> #### id

> File to delete

> ### Return Value

> `TC_PENDING`: Call `devmate_fs_finish()` again.
> `TC_ERROR`: File doesn't exit or some other error occurred.
> `TC_SUCCESS`: File removal succeeded.

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ## devmate_fs_deleteB

>     int devmate_fs_deleteB(DMFile *file, FNumber id, long timeout);

> ### Description

> Blocking version of `devmate_fs_delete()`: causes the specified file to be deleted on the DeviceMate.

> ### Parameters

> #### file

> Pointer to transaction identifier

> #### id

> File to delete

> #### timeout

> Number of milliseconds to wait before timing out. Zero means wait forever.

> ### Return Value

> `TC_ERROR`: File doesn't exit or some other error occurred.
> `TC_SUCCESS`: File removal succeeded.

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ## devmate_fs_finish

>     int devmate_fs_finish(DMFile *file);

> ### Description

> This function is required by some of the other functions to complete their requests. After one of these functions is called:

> - `devmate_fs_init()`
> - `devmate_fs_rename()`
> - `devmate_fs_delete()`
> - `devmate_fs_idlookup()`

> a call to `devmate_fs_finish()` should be made until it stops returning `TC_PENDING` and returns the return value of the function that required its use.

> ### Parameters

> #### file

> Pointer to transaction identifier: identifies the command that was requested.

> ### Return Value

> `TC_PENDING`: The transaction is still being processed.
> `TC_ERROR`: Error, e.g., unknown file command.
> `Other`: Return value of function that needed call to `devmate_fs_finish()`.

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ## devmate_fs_idlookup

>     int devmate_fs_idlookup(DMFile *file, char *name, FNumber *id);

> ### Description

> Look up the ID of the file based on its name. When the results arrive, they will be stored at `*id`. A subsequent call to `devmate_fs_finish()` is required.

> ### Parameters

> #### file

> Pointer to transaction identifier

> #### name

> The name of the file

> #### id

> Pointer to where file ID number will be if the function calls returns successfully.

> ### Return Value

> `TC_PENDING`: Call `devmate_fs_finish()` again.
> `TC_ERROR`: File doesn't exit or some other error occurred.
> `TC_SUCCESS`: Success, ID of the file is in `*id`.

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ## devmate_fs_idlookupB

>     int devmate_fs_idlookupB(DMFile *file, char *name, FNumber *id long timeout);

> ### Description

> Blocking version of `devmate_fs_idlookup()`: look up the ID of the file based on its name. When the results arrive, they will be stored at `*id`.

> ### Parameters

> #### file

> Pointer to transaction identifier

> #### name

> The name of the file

> #### id

> Pointer to where file ID will be if the function calls returns successfully.

> #### timeout

> Number of milliseconds to wait before timing out. Zero means wait forever.

> ### Return Value

> `TC_ERROR`: File doesn't exit or some other error occurred.
> `TC_SUCCESS`: Success, ID of the file is at `*id`.

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ## devmate_fs_open

>     int devmate_fs_open( DMFile *file, FNumber id, char *name, int flags );

> ### Description

> This function starts a transaction. This will initiate a file download and will associate a name with the downloaded file. After this functions returns `TC_SUCCESS`, the transaction is in progress and `devmate_fs_append()` may be called for this file. No blocking version exists for a transaction, as errors are reported on subsequent calls automagically.

> ### Parameters

> #### file

> Pointer to transaction identifier

> #### id

> The file's id number

> #### name

> The file's name

> #### flags

> - `TC_FS_FLAGS_NEWID`: recommended value for this parameter, causes DeviceMate to issue a file id number for the specified file that is guaranteed to be unique.
> - `TC_FS_FLAGS_REPLACE`: Replaces an existing file.

> ### Return Value

> `TC_SUCCESS`: Transaction has started successfully.
> `TC_PENDING`: Couldn't store the filename - try again later.
> `TC_ERROR`: Error, e.g., filename too long.

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ## devmate_fs_rename

>     int devmate_fs_rename(DMFile *file, FNumber id, char *name);

> ### Description

> Rename the specified file to the new name. A subsequent call to `devmate_fs_finish()` is required.

> ### Parameters

> #### file

> Pointer to transaction identifier

> #### id

> Number internal to the file system that identifies the file

> #### name

> New name for the file

> ### Return Value

> `TC_PENDING`: Call `devmate_fs_finish()`.
> `TC_ERROR`: Error, e.g. file doesn't exist.
> `TC_SUCCESS`: Success, file was renamed.

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ## devmate_fs_renameB

>     int devmate_fs_renameB(DMFile *file, FNumber id, char *name, long timeout);

> ### Description

> A blocking version of `devmate_fs_rename()`: rename the specified file to the given name.

> ### Parameters

> #### file

> Pointer to transaction identifier

> #### id

> Number internal to the file system that identifies the file

> #### name

> New name for the file

> #### timeout

> Number of milliseconds to wait before timing out. Zero means wait forever.

> ### Return Value

> `TC_ERROR`: Error, e.g. file doesn't exist.
> `TC_SUCCESS`: Success, file was renamed.

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ## devmate_fs_sync

>     int devmate_fs_sync(DMFile *file, int flags);

> ### Description

> Initialize the file system on the DeviceMate. This function does a handshake between the target and the DeviceMate, so that both sides know that everything has reset and is starting from the beginning. A subsequent call to `devmate_fs_finish()` is required.

> ### Parameters

> #### file

> Pointer to transaction identifier

> #### flags

> These are the options that the target can request from the DeviceMate. Initially:

> - `TC_FS_FORMAT`: Erase the file system
> - `0x0000`: Do not erase the file system

> ### Return Value

> `TC_ERROR`: Something is wrong.
> `TC_PENDING` : The finish function should be used.
> `TC_SUCCESS`: The file system was successfully initialized.

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ## devmate_fs_syncB

>     int devmate_fs_syncB(DMFile *file, int flags, long timeout);

> ### Description

> Blocking version of `devmate_fs_sync()`: initialize the file system on the DeviceMate. This function does a handshake between the target and the DeviceMate, so that both sides know that everything has reset and is starting from the beginning.

> ### Parameters

> #### file

> Pointer to transaction identifier

> #### flags

> These are the options that the target can request from the DeviceMate. Initially:

> - `TC_FS_FORMAT`: Erase the file system
> - `0x0000`: Do not erase the file system

> #### timeout

> Number of milliseconds to wait before timing out. Zero means wait forever.

> ### Return Value

> `TC_ERROR`: Something is wrong.
> `TC_SUCCESS`: The file system was successfully initialized.

> ### Library

> dm_fs.lib (Rabbit-based targets)
> dm_fs.c (nonRabbit-based targets)

> ### 5.5 Message Logging Subsystem

> All the functions in `dm_log.lib` are non-blocking, i.e. they all set some internal state, but return immediately. A call to `devmate_log_put()` may return without actually accomplishing its intended goal; it may be necessary to call it multiple times in order to complete the desired action.

> ## devmate_log_init

>     int devmate_log_init(void);

> ### Description

> Establish communication link to the DeviceMate unit. If a link is already established, then it is re-established.

> ### Return Value

> `1`

> ### Library

> dm_log.lib

> ### See Also

> devmate_log_status

> ## devmate_log_put

>     int devmate_log_put(uint16 ffp, char * data, int length);

> ### Description

> Write a log message. Note that if the message is filtered, then the return code is zero, which is the same as "successfully buffered."

> Priority codes are not defined, however you may wish to use the standard "syslog" encoding as follows:

> 0: Emergency; 1: Alert; 2: Critical; 3: Error; 4: Warning; 5: Notice; 6: Informational; 7: Debug.

> The facility number is decoded by the DeviceMate into the appropriate actual destination - see filesystem\log.lib for details. Unless configured otherwise, facility 0 goes to the filesystem; 1 goes to "stdout" (for debugging); 2 goes to both FS and stdout. Other facilities are discarded unless specifically configured.

> ### Parameters

> #### ffp

> Format, facility and priority coded as a 16-bit word:
> bits 0-2: priority (0-7)
> bits 3-7: facility (0-31)
> bits 8-15: format (0 for ASCII string; others as defined by user)

> #### data

> Pointer to the first byte of log message

> #### length

> Length of log message. Must be £115

> ### Return Value

> `-1`: Error occurred. Logging not available.
> `-2`: Message too long (more than 115 chars).
> `0`: Message buffered for sending (or filtered out).
> `1`: Message could not be buffered. Retry same message later if desired.

> ### Library

> dm_log.lib

> ### Example

>     devmate_log_put(7, "Hello log", 9)
> writes "Hello log" as a priority 7 message to facility 0. The format is also 0 (ASCII string). Note that the null terminator need not be included, since the log basically treats all data as binary. If the length was given as '10' in the above example then the null terminator would be included in the log, however this would waste one byte of space.

> ## devmate_log_setfacilityfilter

>     uint32 devmate_log_setfacilityfilter(uint32 filter_allow, uint32 filter_prevent);

> ### Description

> Set local log message filtering, based on message facility. The parameters are bit masks. If bit 0 (the LSB) is set, this corresponds to facility 0; bit 31 corresponds to facility 31. For example:

>      devmate_log_setfacilityfilter(1L<<1, 1L<<9)

> allows facility 1 and prevents facility 9. All other facilities are left in their previous state. Initially, all facilities are allowed.

> ### Parameters

> #### filter_allow

> Each bit set to '1' allows the corresponding facility messages to be sent

> #### filter_prevent

> Each bit set to '1' prevents the corresponding facility messages from being sent. If the same bit is set in both parameters, then the message is prevented.

> ### Return Value

> The previous "allow" mask.

> ### Library

> dm_log.lib

> ## devmate_log_setpriorityfilter

>     uint8 devmate_log_setpriorityfilter(uint8 filter_allow, uint8 filter_prevent);

> ### Description

> Set local log message filtering, based on message priority. The parameters are bit masks. If bit 0 (the LSB) is set, this corresponds to priority 0 (highest priority); bit 7 corresponds to the lowest priority (7). For example:

>     devmate_log_setpriorityfilter(1<<3, 1<<5)

> allows priority 3 and prevents priority 5. Other priorities are left in their previous state. Initially, all priorities are allowed.

> ### Parameters

> #### filter_allow

> Each bit set to '1' allows the corresponding priority messages to be sent

> #### filter_prevent

> Each bit set to '1' prevents the corresponding priority messages from being sent. If the same bit is set in both parameters, then the message is prevented.

> ### Return Value

> The previous "allow" mask.

> ### Library

> dm_log.lib

> ## devmate_log_status

>     int devmate_log_status(void)

> ### Description

> Test communication link to the DeviceMate. The link status indicates whether logging functions can be accessed on the DeviceMate.

> ### Return Value

> `0`: The link is currently being established
> `1`: The link is successfully established

> `-1`: An error has occurred. Call `devmate_log_init()` to re-establish the link. An error typically occurs because there is either no DeviceMate, or because the DeviceMate is not configured for logging support.

> ### Library

> dm_log.lib

> ### See Also

> devmate_log_init

> ### 5.6 Watchdog Subsystem

> ## devmate_wd_init

>     int devmate_wd_init(int block_ms);

> ### Description

> This function initializes the watchdogs. It will clear any watchdogs on the DeviceMate.

> ### Parameters

> #### block_ms

> Number of milliseconds to wait before timing out.

> ### Return Value

> `0`: Success.
> `-1`: Error (eg, timeout occurred).

> ### Library

> dm_wd.lib (Rabbit-based targets)
> dm_wd.c (nonRabbit-based targets)

> ## devmate_wd_add

>     int devmate_wd_add(char* name, long updatewith, int block_ms);

> ### Description

> This adds a watchdog on the DeviceMate and the countdown begins. If `updatewith` amount of time passes before a `devmate_wd_hit()` call is received from the target, the DeviceMate resets the target. If this function is called on an existing watchdog, the amount of time to wait for a `devmate_wd_hit()` is changed to the new `updatewith` value.

> ### Parameters

> #### name

> Text identifier for watchdog instance

> #### updatewith

> Maximum number of milliseconds that can pass without the target hitting the watchdog. Exceeding this time causes a reset of the target.

> #### block_ms

> Number of milliseconds function to wait before timing out

> ### Return Value

> `0`: Success.
> `-1`: Error (eg, timeout occurred).

> ### Library

> dm_wd.lib (Rabbit-based targets)
> dm_wd.c (nonRabbit-based targets)

> ## devmate_wd_hit

>     int devmate_wd_hit(char* name);

> ### Description

> Reset the watchdog. This function returns immediately after attempting to send the hitwd message. If there are no buffers available or if the transmission gets corrupted, the message will not reach the DeviceMate. To guard against this, this function should be called a number of times within the `updatewith` time period. If the occasional message gets lost, the system will continue to operate.

> ### Parameters

> #### name

> The text identifier for the watchdog-- it must match the one passed to `devmate_wd_add()`

> ### Return Value

> `0`: Success.
> `-1`: Error.

> ### Library

> dm_wd.lib (Rabbit-based targets)
> dm_wd.c (nonRabbit-based targets)

> ## devmate_wd_rmv

>     int devmate_wd_rmv(char* name, int block_ms);

> ### Description

> This function removes the watchdog from the list on the DeviceMate.

> ### Parameters

> #### name

> The text identifier for the watchdog-- it must match the one passed to `devmate_wd_add()`

> #### block_ms

> Number of milliseconds to wait before timing out

> ### Return Value

> `0`: Success.
> `-1`: Error (eg, timeout occurred).

> ### Library

> dm_wd.lib (Rabbit-based targets)
> dm_wd.c (nonRabbit-based targets)

Z-World http://www.zworld.com Voice: (530) 757-3737 FAX: (530) 757-3792 sales@zworld.com