By convention, active participant lists (those used in xOpen)
have the remote participant(s)
first followed by an optional local participant. The local
participant can often be omitted, in which case the protocol tries to
use a reasonable default. For example, a UDP participant contains a
UDP port and an IP host. If the local participant is missing from an
active participant list, UDP selects an available port for the local
participant.
In some cases, it is necessary to specify part of the information in a
participant, but it is convenient to allow the lower protocol to
``fill in'' the rest. To allow this flexibility, one can use the
constant pointer ANY_HOSTto specify ``wildcard'' hosts. For
example, if one wants to open UDP with a specific local port, but does
not care which local host number is used, one could construct a local
participant with the specific local port but with the pointer
ANY_HOSTpushed on the stack. The protocol that interprets the host
part of the participant stack could then choose a reasonable default.
Similarly, a wildcard value ANY_PORTexists for protocols that use ports
on their stacks. Protocols that support wildcards indicate this
in their manual page.
The following example illustrates how a protocol that is about to invoke
xOpen on a low-level protocol initializes the participant list, and
then how the low-level protocol extracts that information from the
participant list.
Notice in this example how the high-level protocol pushes two
items (a host address and a port number) onto each participant's
address stack, but the low-level protocol pops only one item off.
This is because the low-level protocol does not interpret the first
item (the host address);
it just passes it on to its low-level protocol. Also note
that when using participants that have been passed from other
protocols, the user must keep in mind that the address pointers may be
valid only for the duration of the current subroutine. Data that is
needed beyond this time should be explicitly copied into static
storage. In addition, because the participant structure is passed by
reference in the xOpen call, the caller should consider the
contents invalid after the return.
In general, passive participant lists (those used in xOpenEnable) contain only the local participant, with no remote
participant specified. This indicates that an upper protocol is
willing to accept connections from any remote participant, as long as
the connection is addressed to the correct local participant.
Protocols which provide different semantics for their openEnable
participants will indicate this explicitly in their manual page in
appendix A.
{
Part p[2];
...
/* set participant addresses before calling low-level protocol's open */
partInit(p, 2);
partPush(p[0], &ServerHostAddr, sizeof(IPhost)); /* remote */
partPush(p[0], &ServerPort, sizeof(long)); /* remote */
partPush(p[1], ANY_HOST, 0); /* local */
partPush(p[1], &ClientPort, sizeof(long)); /* local */
xOpen(self, self, llp, p);
...
}
llpOpen( XObj self, XObj hlpRcv, XObj hlpType, Part *p )
{
/* get participant addresses within low-level protocol's open */
remoteport = (long *) partPop(p[0]);
localport = (long *) partPop(p[1]);
...
}
Next: Message Library
Up: Participant Library
Previous: Relative Protocol Numbers