Protocol fields contain data supplied to the net daemon, the DBM, or to the client host. Definitions about fields may be found in puidnetd.h. The symbol names begin with PUIDNETD. The protocol fields described here are common to all three DBMs. Fields and field records unique to the authentication DBM are described here.
A field has three parts:
- A field identifier - A single ASCII character (PUIDNETD_DATA_symbols)
- Field data -- ASCII printable characters (base 64 encoding required for non-printable characters. Leading and trailing spaces are usually discarded, but see Leading and Trailing Space Removal.)
- A field terminator -- a TAB, ASCII Vertical TAB, decimal value 11, C representation "\t", and symbol PUIDNETD_MSGTERM.
Leading and Trailing Space Removal
With the exception of message fields ('
M' -- PUIDNETD_DATA_MSG),
leading and trailing spaces are removed from field data.
Caution: removal of leading and trailing spaces can reduce a field that has only spaces to an empty field. I2A2 protocol handlers ignore empty fields. When the field is a lookup key -- an alias or a PUID, for example -- the removal of leading and trailing spaces from a key that contains only spaces means the key will be ignored. If it's the only key and a key is required, the net daemon or the DBM will complain about a missing key.
Here's an example of a field that contains the alias "foo". 'a' is the field identifier. It is followed immediately by the field data. The field data ends at the terminating TAB, represented here in the "\t" C language convention.
a -- the alias field identifier (PUIDNETD_DATA_AKA).
foo -- the field data, an alias.
-- the field terminator (PUIDNETD_MSGTERM),
What Fields Go Where?
Fields accompany commands and replies. Check the individual command descriptions for information on the fields that accompany their command and reply messages.
The Sequence Field
There is a private field reserved for client applications. It is a sequence
field that the client may supply in any request and the field will be returned
in whatever reply is appropriate,
The client may use the value in the sequence field to connect its commands to the replies it receives from the net daemon. That allows client applications to send a block of commands with distinct sequence field values and connect the replies received to the commands by their sequence field values.
The only restriction on the sequence field is that its value must not contain control characters, including a TAB ('
Here's an example:
Field Identifier List:
Here are lists of all
field identifiers used in the I2A2 external protocol, sorted by
field identifier character,
description, and the
symbol name from
Continuation Field Identifier: When a message is too full to contain another field, the last field may be followed by the continuation field identifier, '+' (PUIDNETD_DATA_CONT). The continuation field must not be followed by a field terminating PUIDNETD_MSGTERM.
The next message must begin with a continuation command, '+' (PUIDNETD_CMD_CONT).
The last message ends without the continuation field identifier.
Here's an example of a continued authorizer DBM lookup command:
l p18 +
Second Message (redundant and containing no useful information):
Last message, containing a PUIDNETD_DATA_EXP characteristics Boolean expression:
Note how the PUID field is repeated in the messages. That's optional,
but is a useful way to identify message parts.
In rare cases the sender of a continued message may encounter an error before sending its last part. To identify the error a last message is sent that begins with a PUIDNETD_REPL_NAK reply character instead of a PUIDNETD_CMD_CONT command character. The sender includes an error code field in the PUIDNETD_REPL_NAK message. If the sender of the previous example were to signal error number 123 after sending the first two messages, it would send this last message:
Field records are used to allow field identifiers to be repeated inside a message without causing conflicts in their meaning. For example, the alias field identifier, PUIDNETD_DATA_AKA, might be used at the beginning of the message as a key, and subsequently might be used to identify a change to the alias. Here's an example, using a modify field, PUIDNETD_DATA_MDFY, in a modify command, PUIDNETD_CMD_MODIFY.
m afoobar q9876 Ya nfoobar1 Y
'm' -- is the modify command, PUIDNETD_CMD_MODIFY.
'a' -- is the alias lookup key in a PUIDNETD_DATA_AKA field
'q' -- is a private sequence number, 9876, in a PUIDNETD_DATA_SEQ field.
'Y' -- is the modify field identifier, PUIDNETD_DATA_MDFY, starting the modification field record.
'a' -- is a repeat of the alias field identifier, PUIDNETD_DATA_AKA, this time indicating what is to be modified by the modification field record.
'n' -- is the new value field identifier, PUIDNETD_BATA_NEW; "foobar1", the new alias.
'Y' -- is a repeat of PUIDNETD_DATA_MDFY to end the modification record.