Protocol Fields
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.
Field Format
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.
Examples
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.
afoo
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,
ACK or
NAK.
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 (' '). Hint: if it must contain
control characters, consider encoding the value in
base 64 notation.
Here's an example:
qMy-sequence 0001
Field Identifier List:
Here are lists of all
field identifiers used in the I2A2 external protocol, sorted by
field identifier character,
field
description, and the
symbol name from
puidnetd.h
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:
First Message:
l p18 +
Second Message (redundant and containing no useful information):
+p18 +
Last message, containing a PUIDNETD_DATA_EXP characteristics Boolean expression:
+p18 X0
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:
np18 e123
Field Records
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
Where:
'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.