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)