![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to wt-pep.ms 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 / pepsy / doc|
Return to wt-pep.ms CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / pepsy / doc |
1.1 root 1: \" Walk through of the pepsy library routines
2: .NH 2
3: Walk through of pepsy library routines.
4: .XS
5: Walk through of pepsy library routines.
6: .XE
7: .PP
8: Here we walk through all the pepsy library routines at least briefly.
9: If any new routines are added or a routine changed this documentation
10: is the most likely part that will need changing.
11: First we give some theory as to how the task have have been brocken
12: into routines then describe each function in detail.
13: We assume you are familiar with \fBISODE\fR's \fBPE\fR data
14: structure manipulation routines.
15: if not they are documented in the \fBISODE\fR manuals, Volume one, chapter 5,
16: "Encoding of Data-Structures" (It actually covers decoding as well).
17: .NH 3
18: Overview of pepsy library
19: .XS
20: Overview of pepsy library
21: .XE
22: .PP
23: Each seperate task is put into a different file.
24: So all the encoding stuff is in \fIenc.c\fR, all the decoding stuff is
25: in \fIdec.c\fR, printing stuff in \fIprnt.c\fR and freeing stuff in \fIfre.c\fR.
26: Actually it breaks down a little in practice, some of the routines for
27: moving around the tables are used in both \fIenc.c\fR and \fIdec.c\fR
28: for example.
29: Probably they should defined in \fIutil.c\fR so that linking one of the files
30: from the library doesn't force linking any other except \fIutil.o\fR.
31: .PP
32: There is a common structure to each of the major files as well.
33: There is a main routine which the user calls to obtain the services
34: provided by that file's routines.
35: As all the files revolve about processing the table entries their
36: structure is based on running through the table entries.
37: .PP
38: We shall call each array of entries a table or an object.
39: There is a routine, usually with a name ending in _obj, which is designed
40: to process an object.
41: For example \fBen_obj\fR is the routine called to generated an encoded
42: object.
43: Then there are routines to call on each compound type
44: such as \fBen_seq\fR for encode a SEQUENCE.
45: Finally all the primitives are handled by a one function that ends in _type.
46: This lets each routine concentrate on handling the features particular to
47: its type and call the appropriate routine to handle each type it finds
48: with in its compound type.
49: .PP
50: Most of these table processing routines have just three arguements:
51: which are called \fBparm\fR, \fBp\fR, \fBmod\fR.
52: The \fBparm\fR is char * or char ** in the encoding and decoding routines
53: respectively.
54: This points to the user's \fBC\fR structure that data to be encoded
55: is taken from when encoding.
56: When decoding it is the address of a pointer which is made to point
57: the \fBC\fR structure filled with the decode data.
58: The freeing, which is based on the decoding routines, has a char **
59: while the printing routines don't look at the user's data and so don't
60: have such a pointer.
61: The \fBp\fR points to the current table entry we are up to processing and
62: the \fBmod\fR arguement points to the \fBmodtyp\fR structure for the current
63: module we are processing.
64: .PP
65: All these processing routines return a \fBPE\fR type,
66: which is defined in \fBISODE\fR's file \fIh/psap.h\fR, and to return zero
67: if they have an error, but not always.
68: In fact the error handling is needs some work and has not
69: been tested very well.
70: Generally it tries to print out the table entry where something went wrong and
71: the name of the function it was in.
72: It then sometimes does an exit which may not be very pleasent for the
73: user.
74: .NH 3
75: The encoding routines - enc.c
76: .XS
77: The encoding routines - enc.c
78: .XE
79: .IP enc_f
80: This is the the routine made available to the user for the encoding routines.
81: It is fairly simple as it leaves all the hard things up to other routines.
82: All it does is use the type number and \fBmodtyp\fR pointer to get
83: a pointer to the table for encoding that type.
84: Then it calls the table or object encoding routine, \fBen_obj\fR,
85: on that object.
86: It first does a consistency check of making sure the first entry in the table
87: is a \fBPE_start\fR.
88: Note that it returns an integer (OK or NOTOK) instead of a \fBPE\fR pointer.
89: This is to be consitent with \fBISODE\fR functions.
90: .IP en_obj
91: We loop through the entries until we come to the end of the table and then we
92: return the \fBPE\fR we have built up from the user's data which is pointed
93: to by \fBparm\fR.
94: In looping through each entry we call the appropriate routine to encode its
95: data.
96: The default case is handled by calling \fBen_type\fR which takes care of
97: all the primitive types.
98: .PP
99: The macro \fBNEXT_TPE\fR sets its arguement to point to the next type
100: in the table, counting compound types as one type.
101: Thus if \fBNEXT_TPE\fR is called on a \fBSET_START\fR it will skip all the
102: entries up to and including the matching \fBPE_END\fR.
103: As many objects consist of one compound type and its components the main
104: loop will only be run through once.
105: Even when the object is not based on a compound type it will then consist of
106: one simple type which is processed by \fBen_type\fR, again probably
107: going through the loop only once.
108: In fact the only way it can go through the loop more than once
109: is to process entries that subsidary to the main type, e.g. \fBETAG\fB entries
110: and things like that.
111: To double check this is the case there is some code that looks for
112: the processing of more than one data generating entry.
113: .PP
114: Much of that testing could probably be eliminated with no loss.
115: Similarly prehaps the \fBIMP_OBJ\fR and \fBETAG\fR could be handled by the
116: default action of calling \fBen_type\fR.
117: As these routines have evolved after many changes there are things like
118: that which really need to be looked at closely before trying.
119: The comment /*SUPRESS 288*/ means suppress warning 288 to saber C debugging
120: tool that we use.
121: .IP en_type
122: This is one of the longest functions as it has so many cases to handle.
123: It again is structure as a loop over the types until \fBPE_END\fR but it
124: actually returns as soon as it has encoded the next type.
125: We can now look at the encoding of the primative \fBASN.1\fR types in detail.
126: .IP DFLT_F
127: Because we have arranged that for encoding tables, that we precede
128: the entry with a \fBDFLT_F\fR entry we can neatly handle all the default
129: cases.
130: All we do is check if the parameter passed in the user data, in \fBparm\fR,
131: is the same as the default value specified in the \fBDFLT_F\fR entry.
132: The function \fBsame\fR performs this check.
133: If it is the same don't encode anything just return, otherwise continue on
134: and encode it.
135: .IP ETAG
136: To handle explicit tags we merely allocate a \fBPE\fR with the right tag
137: and call \fBen_etype\fR to encode its contents, which are in the following
138: entries.
139: The switch on the \fBpe_ucode\fR field use to make a difference
140: but now it is meaningless and should be cleaned up.
141: .IP "SEQ_START, SEQOF_START, SET_START, SETOF_START"
142: We merely call the appropriate function handle them.
143: Note one \fIimportant\fR difference in the way they are called here from that
144: in \fBenc_obj\fR, the parm arguement is used as a base to index off and
145: fetch a new pointer to pass the next function.
146: This seemly bizarre action is quite straight forward when seen written as
147: it is normally in \fBC\fR, "\fBparm->offset\fR".
148: Where the field \fBoffset\fR is a pointer which has an offset from the start
149: of the structure of \fBp->pe_ucode\fR bytes.
150: .PP
151: This is the magic of how we access all the different fields
152: of the \fBC\fR data structures with the one piece of code.
153: It is also prehaps the most critical dependency of the whole system
154: on the implementation of the \fBC\fR language.
155: As the \BGNU\fR \fBC\fR compiler supports this feature then it is
156: compilerable on most machines.
157: But any porters should pay attention to this to ensure that thier compiler
158: is happy generating these offsets and compiling these casts properly.
159: .PP
160: The reason why this is different from the calls in \fBen_obj\fR is that
161: this is not the first compound type in the table.
162: The first and only the first does not have an offset and does not need to be
163: indirected through any pointers.
164: All the compound types inside this type will have
165: as their field a pointer which points to a structure.
166: From here on we shall say \fIindirection\fR to mean this
167: adding the \fBpe_ucode\fR field
168: to the pointer to the structure and using it to reference a pointer.
169: Whether to use \fIindirection\fR or not is very important matter
170: that really needs to be understood to understand how the routines are
171: structured.
172: .IP IMP_OBJ
173: Here we have to handle the case where we can encode the object then have to
174: change its tag and class after encoding.
175: At the end of this entry this is done very simply by assigning the
176: right values to the appropriate fields after the object has been built.
177: This means that if the intermeadiate form is altered this piece of code
178: may have to be altered as well.
179: There seems to be no better way of handling this.
180: .PP
181: The complication in handling this field is the handling of all the possible
182: types of object.
183: If it is an external object we have to perform a call to \fBenc_f\fR with
184: all the right arguements
185: where a normal OBJECT, the last else branch, requires a normal call
186: to \fBen_obj\fR.
187: Note the case of \fBSOBJECT\fR is the same
188: as \fBOBJECT\fR \fIexcept there is no indirection\fR.
189: .IP "SOBJECT and OBJECT"
190: Here is the code that handles the two cases sperately.
191: It is exactly as in the \fBIMP_OBJ\fR case except seperated out.
192: Note the only difference between the two cases is lack of indirection in
193: the \fBSOBJECT\fR case.
194: .IP CHOICE_START
195: This is exactly as all other compound types,
196: like \fBSEQ_START\fR and \fBOBJECT\fR, we call the appropriate routine with
197: indirection.
198: From reading the \fBISODE\fR manuals that the \fBASN.1\fR CHOICE type
199: is handled by a structure of its own like the other compund types.
200: .IP "EXTOBJ and SEXTOBJ"
201:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.