Return to wt-pep.ms CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / pepsy / doc

Annotation of 43BSDReno/contrib/isode-beta/pepsy/doc/wt-pep.ms, revision 1.1

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.