![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to librtsap.3n CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / rtsap|
Return to librtsap.3n CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / rtsap |
1.1 root 1: .TH LIBRTSAP 3N "23 Sep 1986"
2: .\" $Header: /f/osi/rtsap/RCS/librtsap.3n,v 7.0 89/11/23 22:22:15 mrose Rel $
3: .\"
4: .\"
5: .\" $Log: librtsap.3n,v $
6: .\" Revision 7.0 89/11/23 22:22:15 mrose
7: .\" Release 6.0
8: .\"
9: .SH NAME
10: librtsap \- Reliable Transfer Services library
11: .SH SYNOPSIS
12: .B "#include <isode/rtsap.h>"
13: .sp
14: \fIcc\fR\0...\0\fB\-lisode\fR
15: .SH DESCRIPTION
16: The \fIlibrtsap\fR library contains a set of routines which implement
17: reliable transfer facilities.
18: In essence,
19: they implement a Reliable Transfer Service Point (RtSAP) interface.
20: .PP
21: The information contained herein is skeletal:
22: consult the \fIUser's Manual\fR for actual examples of how ISO servers and
23: clients are coded and interact with the \fIlibrtsap\fR library.
24: .SH ADDRESSES
25: RtSAP addresses are represented by the \fBRtSAPaddr\fR structure.
26: This contains a session address,
27: and the port number of the RtSAP as found in the \fIisoservices\fR\0(5)
28: database.
29: .SH "SERVER INITIALIZATION"
30: A program providing an ISO service is usually invoked under \fItsapd\fR\0(8c),
31: with the argument vector listed in the ISODE services database.
32: The server's very first action is to re\-capture the RtSAP state as
33: recorded by \fItsapd\fR.
34: This is accomplished by calling \fBRtBInit\fR.
35: Information returned by this call is equivalent to the parameters passed by
36: the X.410 OPEN.INDICATION event.
37: If the call is successful,
38: the program can then examine the argument vector that was passed via
39: \fIexecvp\fR
40: (it's important to call \fBRtBInit\fR prior to reading \fBargc\fR and
41: \fBargv\fR).
42: If the call to \fBRtBInit\fR is not successful,
43: information returned by the call indicates the reason for failure.
44: .PP
45: After examining the information provided by \fBRtBInit\fR
46: (and possibly the argument vector),
47: the server should either accept or reject the association.
48: If accepting, the \fBRtBeginResponse\fR routine is called with the parameter
49: \fBstatus\fR set to
50: .sp
51: .in +.5i
52: .nf
53: .ta \w'RTS_VALIDATE 'u
54: RTS_ACCEPT association accepted
55: .re
56: .fi
57: .in -.5i
58: .sp
59: (which corresponds to the accepting RT\-BEGIN.RESPONSE action).
60: If the call is successful,
61: the association has been bound.
62: If un\-successful,
63: information returned by the call indicates the reason for failure.
64: If rejecting, the \fBRtBeginResponse\fR routine is also called,
65: but with the parameter \fBstatus\fR set to one of:
66: .sp
67: .in +.5i
68: .nf
69: .ta \w'RTS_VALIDATE 'u
70: RTS_BUSY busy
71: RTS_RECOVER cannot recover
72: RTS_VALIDATE validation failure
73: RTS_MODE unacceptable dialogue mode
74: .re
75: .fi
76: .in -.5i
77: .sp
78: (which corresponds to the refusing X.410 OPEN.RESPONSE action),
79: and the program may exit.
80: .SH "CLIENT INITIALIZATION"
81: A program requesting an ISO service calls \fBRtBeginRequest\fR
82: (which corresponds to the X.410 OPEN.REQUEST action).
83: If successful (depending on the responder's choice of \fBstatus\fR),
84: the association is bound.
85: If un\-successful,
86: information returned by the call indicates the reason for failure.
87: .SH ASSOCIATION\-DESCRIPTORS
88: Once an association has been bound via a successful return from
89: \fBRtBeginResponse\fR (for servers) or \fBRtBeginRequest\fR (for clients),
90: an association is referenced by a small integer
91: (returned in a structure passed to these calls) called an
92: \fIassociation\-descriptor\fR.
93: The association\-descriptor appears as an argument to the peer routines
94: described below.
95: .PP
96: By default,
97: events associated with a association\-descriptor are synchronous in nature:
98: activity in the network won't generate an INDICATION event without program
99: first asking to be told of any activity.
100: To mark an association\-descriptor as asynchronous,
101: a call to \fBRtSetIndications\fR is made with the address of an integer
102: function to handle incoming events.
103: Upon a successful return from \fBRtSetIndications\fR,
104: the event handler will be called in this fashion:
105: .sp
106: .in +.5i
107: .B "(*handler) (sd, rti);"
108: .in -.5i
109: .sp
110: where \fBsd\fR is the association\-descriptor,
111: and \fBrti\fR is a pointer to a \fBRtSAPindication\fR structure.
112: Any value returned by the event\-handler is ignored.
113: .PP
114: Note well: the \fB\-lisode\fR library uses the \fB\-ltsap\fR library to
115: provide this interface.
116: The latter library uses the SIGEMT signal to provide this service.
117: Programs loaded with \fB\-ltsap\fR that use asynchronous
118: association\-descriptors should NOT use SIGEMT for other purposes.
119: .PP
120: For synchronous multiplexing of several associations,
121: the routine \fBRtSelectMask\fR
122: updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
123: .SH PEER
124: A fatal failure (consult the \fIUser's Manual\fR)
125: on return from any of these routines results in the association being unbound.
126: .sp
127: .in +.5i
128: .nf
129: .ta \w'\fBRtTransferRequest\fR 'u
130: \fIroutine\fR \fIaction\fR
131: \fBRtPTurnRequest\fR RT\-TURN\-PLEASE.REQUEST
132: \fBRtGTurnRequest\fR RT\-TURN\-GIVE.REQUEST
133: \fBRtTransferRequest\fR RT\-TRANSFER.REQUEST
134: \fBRtWaitRequest\fR RT\-WAIT.REQUEST (synchronous wait)
135: \fBRtEndRequest\fR X.410 CLOSE.REQUEST
136: \fBRtEndResponse\fR X.410 CLOSE.RESPONSE
137: .re
138: .fi
139: .in -.5i
140: .sp
141: Note that the \fBRtWaitRequest\fR routine returns data from the peer by
142: allocating memory.
143: It should be freed before the structure is re\-used.
144: .PP
145: Finally,
146: the routine \fBRtErrString\fR takes a failure code from a \fBRtSAPabort\fR
147: structure and returns a null\-terminated diagnostic string.
148: .SH FILES
149: .nf
150: .ta \w'\*(EDisoservices 'u
151: \*(EDisoentities ISODE entities database
152: \*(EDisobjects ISODE objects database
153: \*(EDisoservices ISODE services database
154: .re
155: .fi
156: .SH "SEE ALSO"
157: libacsap(3n), librosap (3n), isoentities(5), isobjects (5), isoservices(5)
158: .br
159: \fIThe ISO Development Environment: User's Manual\fR,
160: .br
161: ISO DIS 9066/1:
162: \fIInformation Processing Systems \-\- Text Communication \-\- MOTIS \-\-
163: Reliable Transfer Part 1: Model and Service Definition\fR,
164: .br
165: CCITT Recommendation X.410:
166: \fIMessage Handling Systems: Remote Operations and Reliable Transfer Server\fR
167: .SH DIAGNOSTICS
168: All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
169: .SH AUTHORS
170: Marshall T. Rose,
171: The Wollongong Group
172: .SH BUGS
173: Do not confuse association\-descriptors with file\-descriptors.
174: Unlike file\-descriptors which are implemented by the kernel,
175: association\-descriptors to not work across \fIfork\fRs and \fIexec\fRs.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.