1 #ifndef TRF_H 2 #define TRF_H 3 /* -*- c -*- 4 * 5 * transform.h - externally visible facilities of data transformers 6 * 7 * Distributed at MAY-06-2009. 8 * 9 * Copyright (c) 1995 Andreas Kupries (andreas_kupries@users.sourceforge.net) 10 * All rights reserved. 11 * 12 * Permission is hereby granted, without written agreement and without 13 * license or royalty fees, to use, copy, modify, and distribute this 14 * software and its documentation for any purpose, provided that the 15 * above copyright notice and the following two paragraphs appear in 16 * all copies of this software. 17 * 18 * IN NO EVENT SHALL I BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, 19 * INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS 20 * SOFTWARE AND ITS DOCUMENTATION, EVEN IF I HAVE BEEN ADVISED OF THE 21 * POSSIBILITY OF SUCH DAMAGE. 22 * 23 * I SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 24 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 25 * PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND 26 * I HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, 27 * ENHANCEMENTS, OR MODIFICATIONS. 28 * 29 * CVS: $Id: transform.h,v 1.23 2009/05/07 05:30:35 andreas_kupries Exp $ 30 */ 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 #include <tcl.h> 37 38 /* 39 * Definition of module version 40 */ 41 42 /* 43 #define TRF_VERSION "2.1" 44 #define TRF_MAJOR_VERSION 2 45 #define TRF_MINOR_VERSION 1 46 */ 47 48 /* 49 * Definitions to enable the generation of a DLL under Windows. 50 * Taken from 'ftp://ftp.sunlabs.com/pub/tcl/example.zip(example.c)' 51 */ 52 53 #if defined(__WIN32__) 54 # define WIN32_LEAN_AND_MEAN 55 # include <windows.h> 56 # undef WIN32_LEAN_AND_MEAN 57 58 /* 59 * VC++ has an alternate entry point called DllMain, so we need to rename 60 * our entry point. 61 */ 62 63 64 #ifdef TCL_STORAGE_CLASS 65 # undef TCL_STORAGE_CLASS 66 #endif 67 #ifdef BUILD_Trf 68 # define TCL_STORAGE_CLASS DLLEXPORT 69 #else 70 # define TCL_STORAGE_CLASS DLLIMPORT 71 #endif 72 73 # if defined(_MSC_VER) 74 # define TRF_EXPORT(a,b) TCL_STORAGE_CLASS a b 75 # else 76 # if defined(__BORLANDC__) 77 # define TRF_EXPORT(a,b) a _export b 78 # else 79 # define TRF_EXPORT(a,b) a b 80 # endif 81 # endif 82 #else 83 # define TRF_EXPORT(a,b) a b 84 #endif 85 86 /* 87 * Exported tcl level procedures. 88 * 89 * ATTENTION: 90 * due to the fact that cpp - processing with gcc 2.5.8 removes any comments 91 * in macro-arguments (even if called with option '-C') i have to use the 92 * predefined macro __C2MAN__ to distinguish real compilation and manpage 93 * generation, removing _ANSI_ARGS_ in the latter case. 94 */ 95 96 /* 97 * Initialize extension in standard interpreter. 98 * Extends the interpreter with extension-specific 99 * structures and installs the globally visible 100 * command of Tcl-TRF. Will catch attempts for 101 * multiple initialization of an interpreter. 102 */ 103 104 #ifdef __C2MAN__ 105 int 106 Trf_Init (Tcl_Interp* interp /* interpreter to initialize */); 107 #else 108 TRF_EXPORT (int,Trf_Init) _ANSI_ARGS_ ((Tcl_Interp* interp)); 109 #endif 110 111 /* 112 * Initialize extension in SAFE interpreter. 113 * Same as --> Trf_Init. The only security 114 * relevant operations are reading from and 115 * writing to a file. As Tcl-Handles are 116 * given to these commands it is assumed that 117 * they were checked and cleared beforehand. 118 */ 119 120 #ifdef __C2MAN__ 121 int 122 Trf_SafeInit (Tcl_Interp* interp /* interpreter to initialize */); 123 #else 124 TRF_EXPORT (int,Trf_SafeInit) _ANSI_ARGS_ ((Tcl_Interp* interp)); 125 #endif 126 127 /* 128 * Check initialization state of specified interpreter. 129 * Check, wether this extension was initialized for the 130 * specified interpreter or not. 131 */ 132 133 #ifdef __C2MAN__ 134 int 135 Trf_IsInitialized (Tcl_Interp* interp /* interpreter to check for initialization */); 136 #else 137 #ifndef TRF_USE_STUBS 138 TRF_EXPORT (int,Trf_IsInitialized) _ANSI_ARGS_ ((Tcl_Interp* interp)); 139 #endif 140 #endif 141 /* 142 * Exported C level facilities. 143 */ 144 145 /* 146 * Interface to registry of conversion procedures. 147 */ 148 149 /* 150 * Structure used to remember the values of fundamental option(s). 151 * The values currently defined remember: 152 * * Handle and access-mode of the channel specified as argument 153 * to option '-attach'. 154 * * Handle of channel specified as argument to '-in'. 155 * * Handle of channel specified as argument to '-out'. 156 * * Name of the seek policy requested by the user. 157 */ 158 159 typedef struct _Trf_BaseOptions_ { 160 Tcl_Channel attach; /* NULL => immediate mode */ 161 int attach_mode; /* access mode of 'attach' (if not NULL) */ 162 163 /* Relevant in immediate mode only! (attach == NULL) */ 164 Tcl_Channel source; /* NULL => use non option argument as input */ 165 Tcl_Channel destination; /* NULL => leave transformation result in 166 * interpreter result area */ 167 168 Tcl_Obj* policy; /* Refers to string object containing the seek policy 169 * to use, if overiding the chosen one is allowed! */ 170 } Trf_BaseOptions; 171 172 173 174 /* 175 * prototypes for procedures used to specify a data transformer. 176 * 177 * 1) vectors for option processing 178 * 2) vectors for data encode/decode. 179 */ 180 181 /* 182 * opaque type for access to option structures. 183 * mainly defined for more readability of the prototypes following. 184 */ 185 186 typedef ClientData Trf_Options; 187 188 /* 189 * Interface to procedures to create a container holding option values. 190 * It is the responsibility of the procedure to create and 191 * initialize a container to hold option values. An opaque 192 * handle to the new container has to be returned. 193 */ 194 195 #ifdef __C2MAN__ 196 typedef Trf_Options Trf_CreateOptions (ClientData clientData /* arbitrary information, as defined in 197 * Trf_TypeDefinition.clientData */); 198 #else 199 typedef Trf_Options Trf_CreateOptions _ANSI_ARGS_ ((ClientData clientData)); 200 #endif 201 202 203 /* 204 * Interface to proceduress to delete a container made with 'Trf_CreateOptions'. 205 * It is the responsibility of this procedure to clear and release 206 * all memory of the specified container (which must have been 207 * created by the corresponding procedure of type 'Trf_CreateOptions'). 208 */ 209 210 #ifdef __C2MAN__ 211 typedef void Trf_DeleteOptions (Trf_Options options, /* the container to destroy */ 212 ClientData clientData /* arbitrary information, as defined in 213 * Trf_TypeDefinition.clientData */); 214 #else 215 typedef void Trf_DeleteOptions _ANSI_ARGS_ ((Trf_Options options, 216 ClientData clientData)); 217 #endif 218 219 220 /* 221 * Interface to procedures to check an option container. 222 * The procedure has to check the contents of the specified 223 * container for errors, consistency, etc. It is allowed to 224 * set default values into unspecified slots. Return value 225 * is a standard tcl error code. In case of failure and interp 226 * not NULL an error message should be left in the result area 227 * of the specified interpreter. 228 */ 229 230 #ifdef __C2MAN__ 231 typedef int Trf_CheckOptions (Trf_Options options, /* container with options to check */ 232 Tcl_Interp* interp, /* interpreter to write error 233 * messages to (NULL possible!) */ 234 CONST Trf_BaseOptions* baseOptions, /* info about common options */ 235 ClientData clientData /* arbitrary information, as defined 236 * in 237 * Trf_TypeDefinition.clientData */); 238 #else 239 typedef int Trf_CheckOptions _ANSI_ARGS_ ((Trf_Options options, 240 Tcl_Interp* interp, 241 CONST Trf_BaseOptions* baseOptions, 242 ClientData clientData)); 243 #endif 244 245 /* 246 * Interface to procedures to define the value of an option. 247 * The procedure takes the specified optionname (rejecting 248 * illegal ones) and places the given optionvalue into the 249 * container. All necessary conversions from a string to the 250 * required type should be done here. Return value is a standard 251 * tcl error code. In case of failure and interp not NULL an 252 * error message should be left in the result area of the 253 * specified interpreter. 254 */ 255 256 #ifdef __C2MAN__ 257 typedef int Trf_SetOption (Trf_Options options, /* container to place the value into */ 258 Tcl_Interp* interp, /* interpreter for error messages 259 * (NULL possible) */ 260 CONST char* optname, /* name of option to define */ 261 CONST char* optvalue, /* value to set into the container */ 262 ClientData clientData /* arbitrary information, as defined in 263 * Trf_TypeDefinition.clientData */); 264 #else 265 typedef int Trf_SetOption _ANSI_ARGS_ ((Trf_Options options, 266 Tcl_Interp* interp, 267 CONST char* optname, 268 CONST char* optvalue, 269 ClientData clientData)); 270 #endif 271 272 #if (TCL_MAJOR_VERSION < 8) 273 #define Tcl_Obj VOID /* create dummy for missing definition */ 274 #endif 275 276 /* 277 * Interface to procedures to define the value of an option. 278 * The procedure takes the specified optionname (rejecting 279 * illegal ones) and places the given optionvalue into the 280 * container. All necessary conversions from a Tcl_Obj to the 281 * required type should be done here. Return value is a standard 282 * tcl error code. In case of failure and interp not NULL an 283 * error message should be left in the result area of the 284 * specified interpreter. This procedure makes sense for tcl 285 * version 8 and above only 286 */ 287 288 #ifdef __C2MAN__ 289 typedef int Trf_SetObjOption (Trf_Options options, /* container to place the value into */ 290 Tcl_Interp* interp, /* interpreter for error messages 291 * (NULL possible) */ 292 CONST char* optname, /* name of option to define */ 293 CONST Tcl_Obj* optvalue, /* value to set into the container */ 294 ClientData clientData /* arbitrary information, as defined in 295 * Trf_TypeDefinition.clientData */); 296 #else 297 typedef int Trf_SetObjOption _ANSI_ARGS_ ((Trf_Options options, 298 Tcl_Interp* interp, 299 CONST char* optname, 300 CONST Tcl_Obj* optvalue, 301 ClientData clientData)); 302 #endif 303 304 305 306 307 /* 308 * Interface to procedures to query an option container. 309 * The result value decides wether the encoder- or decoder-set of vectors 310 * must be used during immediate execution of the transformer configured 311 * with the container contents. 312 * 313 * Returns: 314 * 0: use decoder. 315 * 1: use encoder. 316 */ 317 318 #ifdef __C2MAN__ 319 typedef int Trf_QueryOptions (Trf_Options options, /* option container to query */ 320 ClientData clientData /* arbitrary information, as defined in 321 * Trf_TypeDefinition.clientData */); 322 #else 323 typedef int Trf_QueryOptions _ANSI_ARGS_ ((Trf_Options options, 324 ClientData clientData)); 325 #endif 326 327 328 typedef struct _Trf_SeekInformation_ Trf_SeekInformation; 329 330 /* 331 * Interface to procedures to query an option container. 332 * The procedure is allowed to change the natural seek policy defined for the 333 * transformation according to the current configuration. 334 * 335 * Returns: 336 * Nothing. 337 */ 338 339 #ifdef __C2MAN__ 340 typedef void Trf_SeekQueryOptions (Tcl_Interp* interp /* Interpreter to use 341 * for reflecting the 342 * query up into tcl, 343 * if necessary */, 344 Trf_Options options, /* option container 345 * to query */ 346 Trf_SeekInformation* seekInfo, /* The policy to modify */ 347 ClientData clientData /* arbitrary 348 * information, as 349 * defined in 350 * Trf_TypeDefinition.clientData */); 351 #else 352 typedef void Trf_SeekQueryOptions _ANSI_ARGS_ ((Tcl_Interp* interp, 353 Trf_Options options, 354 Trf_SeekInformation* seekInfo, 355 ClientData clientData)); 356 #endif 357 358 /* 359 * Structure to hold all vectors describing the processing of a specific 360 * option set. The 5 vectors are used to create and delete containers, to 361 * check them for errors, to set option values and to query them for usage 362 * of encoder or decoder vectors. 363 */ 364 365 typedef struct _Trf_OptionVectors_ { 366 Trf_CreateOptions* createProc; /* create container for option information */ 367 Trf_DeleteOptions* deleteProc; /* delete option container */ 368 Trf_CheckOptions* checkProc; /* check defined options for consistency, errors, ... */ 369 Trf_SetOption* setProc; /* define an option value */ 370 Trf_SetObjOption* setObjProc; /* define an option value via Tcl_Obj (Tcl 8.x) */ 371 Trf_QueryOptions* queryProc; /* query, wether encode (1) / decode (0) requested by options */ 372 Trf_SeekQueryOptions* seekQueryProc; /* query options about changes to the natural seek policy */ 373 } Trf_OptionVectors; 374 375 376 377 378 /* 379 * opaque type for access to the control structures of an encoder/decoder. 380 * mainly defined for more readability of the following prototypes. 381 */ 382 383 typedef ClientData Trf_ControlBlock; 384 385 /* 386 * Interface to procedures used by an encoder/decoder to write its transformation results. 387 * Procedures of this type are called by an encoder/decoder to write 388 * (partial) transformation results, decoupling the final destination 389 * from result generation. Return value is a standard tcl error code. In 390 * case of failure and interp not NULL an error message should be left 391 * in the result area of the specified interpreter. 392 */ 393 394 #ifdef __C2MAN__ 395 typedef int Trf_WriteProc (ClientData clientData /* arbitrary information, defined during 396 * controlblock creation */, 397 unsigned char* outString /* buffer with characters to write */, 398 int outLen /* number of characters in buffer */, 399 Tcl_Interp* interp /* interpreter for error messages 400 * (NULL possible) */); 401 #else 402 typedef int Trf_WriteProc _ANSI_ARGS_ ((ClientData clientData, 403 unsigned char* outString, 404 int outLen, 405 Tcl_Interp* interp)); 406 #endif 407 408 /* 409 * Interface to procedure for creation of encoder/decoder control structures. 410 * The procedure has to create a control structure for an encoder/decoder. The 411 * structure must be initialized with the contents of the the option 412 * container. Return value is an opaque handle aof the control structure or NULL 413 * in case of failure. An error message should be left in the result area 414 * of the specified interpreter then. 415 */ 416 417 #ifdef __C2MAN__ 418 typedef Trf_ControlBlock Trf_CreateCtrlBlock (ClientData writeClientData /* arbitrary information 419 * given as clientdata 420 * to 'fun' */, 421 Trf_WriteProc* fun /* vector to use for writing 422 * generated results */, 423 Trf_Options optInfo /* options to configure the 424 * control */, 425 Tcl_Interp* interp /* interpreter for error 426 * messages */, 427 ClientData clientData /* arbitrary information, 428 * as defined in 429 * Trf_TypeDefinition.clientData 430 */); 431 #else 432 typedef Trf_ControlBlock Trf_CreateCtrlBlock _ANSI_ARGS_ ((ClientData writeClientData, 433 Trf_WriteProc* fun, 434 Trf_Options optInfo, 435 Tcl_Interp* interp, 436 ClientData clientData)); 437 #endif 438 439 /* 440 * Interface to procedure for destruction of encoder/decoder control structures. 441 * It is the responsibility of the procedure to clear and release all memory 442 * associated to the specified control structure (which must have been created 443 * by the appropriate procedure of type 'Trf_CreateCtrlBlock'). 444 */ 445 446 #ifdef __C2MAN__ 447 typedef void Trf_DeleteCtrlBlock (Trf_ControlBlock ctrlBlock /* control structure to destroy */, 448 ClientData clientData /* arbitrary information, as defined in 449 * Trf_TypeDefinition.clientData */); 450 #else 451 typedef void Trf_DeleteCtrlBlock _ANSI_ARGS_ ((Trf_ControlBlock ctrlBlock, 452 ClientData clientData)); 453 #endif 454 455 /* 456 * Interface to procedures for transformation of a single character. 457 * A procedure of this type is called to encode/decode a single 458 * character. Return value is a standard tcl error code. In case of 459 * failure and interp not NULL an error message should be left in the 460 * result area of the specified interpreter. Only one of 'Trf_TransformCharacter' 461 * and 'Trf_TransformBuffer' must be provided. This one is easier to 462 * implement, the second one should be faster. If both are 463 * provided, -> 'Trf_TransformBuffer' takes precedence. 464 */ 465 466 #ifdef __C2MAN__ 467 typedef int Trf_TransformCharacter (Trf_ControlBlock ctrlBlock /* state of encoder/decoder */, 468 unsigned int character /* character to transform */, 469 Tcl_Interp* interp /* interpreter for error messages 470 * (NULL possible) */, 471 ClientData clientData /* arbitrary information, as defined 472 * in Trf_TypeDefinition.clientData */); 473 #else 474 typedef int Trf_TransformCharacter _ANSI_ARGS_ ((Trf_ControlBlock ctrlBlock, 475 unsigned int character, 476 Tcl_Interp* interp, 477 ClientData clientData)); 478 #endif 479 480 /* 481 * Interface to procedures for transformation of character sequences. 482 * A procedure of this type is called to encode/decode a complete buffer. Return 483 * value is a standard tcl error code. In case of failure and interp not 484 * NULL an error message should be left in the result area of the specified 485 * interpreter. Only one of 'Trf_TransformCharacter' and 'Trf_TransformBuffer' 486 * must be provided. The first named is easier to implement, this one should be 487 * faster. If both are provided, -> 'Trf_TransformBuffer' takes precedence. 488 */ 489 490 #ifdef __C2MAN__ 491 typedef int Trf_TransformBuffer (Trf_ControlBlock ctrlBlock /* state of encoder/decoder */, 492 unsigned char* buf /* characters to transform */, 493 int bufLen /* number of characters */, 494 Tcl_Interp* interp /* interpreter for error messages 495 * (NULL possible) */, 496 ClientData clientData /* arbitrary information, as defined 497 * in Trf_TypeDefinition.clientData */); 498 #else 499 typedef int Trf_TransformBuffer _ANSI_ARGS_ ((Trf_ControlBlock ctrlBlock, 500 unsigned char* buf, 501 int bufLen, 502 Tcl_Interp* interp, 503 ClientData clientData)); 504 #endif 505 506 /* 507 * Interface to procedures used to flush buffered characters. 508 * An encoder/decoder is allowed to buffer characters internally. A procedure 509 * of this type is called just before destruction to invoke special processing 510 * of such characters. Return value is a standard tcl error code. In case of 511 * failure and interp not NULL an error message should be left in the result 512 * area of the specified interpreter. 513 */ 514 515 #ifdef __C2MAN__ 516 typedef int Trf_FlushTransformation (Trf_ControlBlock ctrlBlock /* state of encoder/decoder */, 517 Tcl_Interp* interp /* interpreter for error messages 518 * (NULL posssible) */, 519 ClientData clientData /* arbitrary information, as defined in 520 * Trf_TypeDefinition.clientData */); 521 #else 522 typedef int Trf_FlushTransformation _ANSI_ARGS_ ((Trf_ControlBlock ctrlBlock, 523 Tcl_Interp* interp, 524 ClientData clientData)); 525 #endif 526 527 /* 528 * Interface for procedures to reset the internal state of an encoder/decoder. 529 * The generic io layer of tcl sometimes discards its input buffer. A procedure 530 * of this type will be called in such a case to reset the internal state of 531 * the control structure and to discard buffered characters. 532 */ 533 534 #ifdef __C2MAN__ 535 typedef void Trf_ClearCtrlBlock (Trf_ControlBlock ctrlBlock /* state of 536 * encoder/decoder 537 */, 538 ClientData clientData /* arbitrary 539 * information, 540 * as defined in 541 * Trf_TypeDefinition.clientData */); 542 #else 543 typedef void Trf_ClearCtrlBlock _ANSI_ARGS_ ((Trf_ControlBlock ctrlBlock, 544 ClientData clientData)); 545 #endif 546 547 /* 548 * Interface for procedures to query a transformation about the max. number of bytes to read in the next call to the down channel. 549 * This procedure will be called by the generic trf layer just before reading 550 * data from the channel below the transformation. This way a transformation 551 * is able to control its consumption of characters. An example would be 552 * 'identity with stop after n characters'. This would transfer at most n 553 * characters and then basically fake higher transformations into believing 554 * that EOF occured. Then popping it would reveal the truth. Pattern matching 555 * could be used here too (internet protocols !). 556 */ 557 558 #ifdef __C2MAN__ 559 typedef int Trf_QueryMaxRead (Trf_ControlBlock ctrlBlock /* state of 560 * encoder/decoder */, 561 ClientData clientData /* arbitrary 562 * information, as 563 * defined in 564 * Trf_TypeDefinition.clientData */); 565 #else 566 typedef int Trf_QueryMaxRead _ANSI_ARGS_ ((Trf_ControlBlock ctrlBlock, 567 ClientData clientData)); 568 #endif 569 570 /* 571 * Structure to hold all vectors describing a specific encoder/decoder. 572 * The 5 vectors are ussed to create and delete the controlblock of the 573 * encoder/coder, to transform a single character, to flush all internal 574 * buffers and to reset the control. 575 */ 576 577 typedef struct _Trf_Vectors_ { 578 Trf_CreateCtrlBlock* createProc; /* create control structure */ 579 Trf_DeleteCtrlBlock* deleteProc; /* delete control structure */ 580 Trf_TransformCharacter* convertProc; /* process a single character */ 581 Trf_TransformBuffer* convertBufProc; /* process a buffer of characters */ 582 Trf_FlushTransformation* flushProc; /* flush possibly buffered 583 * characters */ 584 Trf_ClearCtrlBlock* clearProc; /* reset internal control, clear 585 * buffers */ 586 Trf_QueryMaxRead* maxReadProc; /* Query max. number of characters 587 * to read next time. Possibly NULL. 588 */ 589 } Trf_Vectors; 590 591 592 /* 593 * Information about a seek policy. Just the ratio of input to output, if 594 * attached with encode on write. If either one of the values is 595 * zero, the transformation is considered to be unseekable. 596 */ 597 598 struct _Trf_SeekInformation_ { 599 int numBytesTransform; /* #Bytes used by the transformation as input */ 600 int numBytesDown; /* #Bytes produced for every 'numBytesTransform' */ 601 }; 602 603 604 /* 605 * Structure describing a complete transformation. 606 * Consists of option processor and vectors for encoder, decoder. 607 */ 608 609 typedef struct _Trf_TypeDefinition_ { 610 CONST char* name; /* name of transformation, also name of 611 * created command */ 612 ClientData clientData; /* reference to arbitrary information. 613 * This information is given to all vectors 614 * mentioned below. */ 615 Trf_OptionVectors* options; /* reference to option description, can be 616 * shared between transformation descriptions 617 */ 618 Trf_Vectors encoder; /* description of encoder */ 619 Trf_Vectors decoder; /* description of decoder */ 620 621 Trf_SeekInformation naturalSeek; /* Information about the natural seek 622 * policy. Compile time configuration. */ 623 } Trf_TypeDefinition; 624 625 626 #define TRF_UNSEEKABLE {0, 0} 627 #define TRF_RATIO(in,out) {in, out} 628 629 630 /* 631 * Register the specified transformation at the given interpreter. 632 * Extends the given interpreter with a new command giving access 633 * to the transformation described in 'type'. 'type->name' is used 634 * as name of the command. 635 */ 636 637 #ifdef __C2MAN__ 638 int 639 Trf_Register (Tcl_Interp* interp, /* interpreter to register at */ 640 CONST Trf_TypeDefinition* type /* transformation to register */); 641 #else 642 #ifndef TRF_USE_STUBS 643 TRF_EXPORT (int,Trf_Register) _ANSI_ARGS_ ((Tcl_Interp* interp, 644 CONST Trf_TypeDefinition* type)); 645 #endif 646 #endif 647 648 /* 649 * Interfaces for easier creation of certain classes of 650 * transformations (message digests) 651 */ 652 653 /* 654 * transformer class: conversions. 655 * 656 * There is no easier way to create a conversion transformer than 657 * to create it from scratch (use template/cvt_template.c as 658 * template). Additionally the option processor returned below must 659 * be used. 660 */ 661 662 /* 663 * Return the set of option processing procedures required by conversion transformers. 664 */ 665 666 #ifdef __C2MAN__ 667 Trf_OptionVectors* 668 Trf_ConverterOptions (void); 669 #else 670 TRF_EXPORT (Trf_OptionVectors*,Trf_ConverterOptions) _ANSI_ARGS_ ((void)); 671 #endif 672 673 /* 674 * Structure to hold the option information required by conversion transformers. 675 * A structure of this type is created and manipulated by the set of procedures 676 * returned from 'Trf_ConverterOptions'. 677 */ 678 679 typedef struct _Trf_ConverterOptionBlock { 680 int mode; /* converter mode */ 681 } Trf_ConverterOptionBlock; 682 683 /* 684 * Posssible modes of a conversions transformer: 685 * 686 * UNKNOWN: initial value, unspecified mode 687 * ENCODE: encode characters 688 * DECODE: decode characters 689 */ 690 691 #define TRF_UNKNOWN_MODE (0) 692 #define TRF_ENCODE_MODE (1) 693 #define TRF_DECODE_MODE (2) 694 695 696 /* 697 * transformer class: message digests. 698 * 699 * The implementation of a message digest algorithm requires 700 * 3 procedures interfacing the special MD-code with the common 701 * code contained in this module (dig_opt.c, digest.c). 702 */ 703 704 /* 705 * Interface to procedures for initialization of a MD context. 706 * A procedure of this type is called to initialize the structure 707 * containing the state of a special message digest algorithm. The 708 * memory block was allocated by the caller, with the size as specified 709 * in the 'Trf_MessageDigestDescription' structure of the algorithm. 710 */ 711 712 #ifdef __C2MAN__ 713 typedef void Trf_MDStart (VOID* context /* state to initialize */); 714 #else 715 typedef void Trf_MDStart _ANSI_ARGS_ ((VOID* context)); 716 #endif 717 718 /* 719 * Interface to procedures for update of a MD context. 720 * A procedure of this type is called for every character to hash 721 * into the final digest. 722 */ 723 724 #ifdef __C2MAN__ 725 typedef void Trf_MDUpdate (VOID* context /* state to update */, 726 unsigned int character /* character to hash into the state */); 727 #else 728 typedef void Trf_MDUpdate _ANSI_ARGS_ ((VOID* context, unsigned int character)); 729 #endif 730 731 /* 732 * Interface to procedures for update of a MD context. 733 * A procedure of this type is called for character buffer to hash 734 * into the final digest. This procedure is optional, its definition 735 * has precedence over 'Trf_MDUpdate'. 736 */ 737 738 #ifdef __C2MAN__ 739 typedef void Trf_MDUpdateBuf (VOID* context /* state to update */, 740 unsigned char* buf /* buffer to hash into the state */, 741 size_t bufLen /* number of characters in the buffer */); 742 #else 743 typedef void Trf_MDUpdateBuf _ANSI_ARGS_ ((VOID* context, 744 unsigned char* buffer, 745 size_t bufLen)); 746 #endif 747 748 /* 749 * Interface to procedures for generation of the final digest from a MD state. 750 * A procedure of this type is called after processing the final character. It 751 * is its responsibility to finalize the internal state of the MD algorithm and 752 * to generate the resulting digest from this. 753 */ 754 755 #ifdef __C2MAN__ 756 typedef void Trf_MDFinal (VOID* digest /* result area to fill */, 757 VOID* context /* state to finalize */); 758 #else 759 typedef void Trf_MDFinal _ANSI_ARGS_ ((VOID* context, VOID* digest)); 760 #endif 761 762 /* 763 * Interface to procedures for check/manipulation of the environment (shared libraries, ...). 764 * A procedure of this type is called before doing any sort of processing. 765 */ 766 767 #ifdef __C2MAN__ 768 typedef int Trf_MDCheck (Tcl_Interp* interp /* the interpreter for error messages */); 769 #else 770 typedef int Trf_MDCheck _ANSI_ARGS_ ((Tcl_Interp* interp)); 771 #endif 772 773 /* 774 * Structure describing a message digest algorithm. 775 * All information required by the common code to interface a message 776 * digest algorithm with it is stored in structures of this type. 777 */ 778 779 typedef struct _Trf_MessageDigestDescription { 780 char* name; /* name of message digest, also name 781 * of command on tcl level */ 782 unsigned short context_size; /* size of the MD state structure 783 * maintained by 'startProc', 'updateProc' 784 * and 'finalProc' (in byte) */ 785 unsigned short digest_size; /* size of the digest generated by the 786 * described algorithm (in byte) */ 787 Trf_MDStart* startProc; /* initialize a MD state structure */ 788 Trf_MDUpdate* updateProc; /* update the MD state for a single character */ 789 Trf_MDUpdateBuf* updateBufProc; /* update the MD state for a character 790 buffer */ 791 Trf_MDFinal* finalProc; /* generate digest from MD state */ 792 Trf_MDCheck* checkProc; /* check enviroment */ 793 794 } Trf_MessageDigestDescription; 795 796 /* 797 * Procedure to register a message digest algorithm in an interpreter. 798 * The procedure registers the described MDA at the given interpreter. Return 799 * value is a standard tcl error code. In case of failure an error message 800 * should be left in the result area of the given interpreter. 801 */ 802 803 #ifdef __C2MAN__ 804 int 805 Trf_RegisterMessageDigest (Tcl_Interp* interp /* interpreter to register the MD algorithm at */, 806 CONST Trf_MessageDigestDescription* md_desc /* description of the MD 807 * algorithm */); 808 #else 809 #ifndef TRF_USE_STUBS 810 TRF_EXPORT (int,Trf_RegisterMessageDigest) _ANSI_ARGS_ ((Tcl_Interp* interp, 811 CONST Trf_MessageDigestDescription* md_desc)); 812 #endif 813 #endif 814 815 /* 816 * Internal helper procedures worth exporting. 817 */ 818 819 /* 820 * General purpose library loader functionality. 821 * Used by -> TrfLoadZlib, -> TrfLoadLibdes. 822 */ 823 824 #ifndef TRF_USE_STUBS 825 TRF_EXPORT (int,Trf_LoadLibrary) _ANSI_ARGS_ ((Tcl_Interp* interp, 826 CONST char* libName, 827 VOID** handlePtr, char** symbols, int num)); 828 829 TRF_EXPORT (void,Trf_LoadFailed) _ANSI_ARGS_ ((VOID** handlePtr)); 830 #endif 831 832 /* 833 * XOR the bytes in a buffer with a mask. 834 * Internally used by the implementation of the 835 * various stream modes available to blockciphers. 836 */ 837 838 #ifdef __C2MAN__ 839 void 840 Trf_XorBuffer (VOID* buffer, /* buffer to xor the mask with */ 841 VOID* mask, /* mask bytes xor'ed into the buffer */ 842 int length /* length of mask and buffer (in byte) */); 843 #else 844 #ifndef TRF_USE_STUBS 845 TRF_EXPORT (void,Trf_XorBuffer) _ANSI_ARGS_ ((VOID* buffer, VOID* mask, 846 int length)); 847 #endif 848 #endif 849 850 /* 851 * Shift the register. 852 * The register is shifted 'shift' bytes to the left. The same 853 * number of bytes from the left of the 2nd register ('in') is 854 * inserted at the right of 'buffer' to replace the lost bytes. 855 */ 856 857 #ifdef __C2MAN__ 858 void 859 Trf_ShiftRegister (VOID* buffer, /* data shifted to the left */ 860 VOID* in, /* 2nd register shifted into the buffer */ 861 int shift, /* number of bytes to shift out (and in) */ 862 int buffer_length /* length of buffer and in (in byte) */); 863 #else 864 #ifndef TRF_USE_STUBS 865 TRF_EXPORT (void,Trf_ShiftRegister) _ANSI_ARGS_ ((VOID* buffer, VOID* in, 866 int shift, 867 int buffer_length)); 868 #endif 869 #endif 870 871 /* 872 * Swap the bytes of all 2-byte words contained in the buffer. 873 */ 874 875 #ifdef __C2MAN__ 876 void 877 Trf_FlipRegisterShort (VOID* buffer, /* data to swap */ 878 int length /* length of buffer (in byte) */); 879 #else 880 #ifndef TRF_USE_STUBS 881 TRF_EXPORT (void,Trf_FlipRegisterShort) _ANSI_ARGS_ ((VOID* buffer, 882 int length)); 883 #endif 884 #endif 885 886 /* 887 * Swap the bytes of all 4-byte words contained in the buffer. 888 */ 889 890 #ifdef __C2MAN__ 891 void 892 Trf_FlipRegisterLong (VOID* buffer, /* data to swap */ 893 int length /* length of buffer (in byte) */); 894 #else 895 #ifndef TRF_USE_STUBS 896 TRF_EXPORT (void,Trf_FlipRegisterLong) _ANSI_ARGS_ ((VOID* buffer, int length)); 897 #endif 898 #endif 899 /* 900 * End of exported interface 901 */ 902 903 #ifndef __C2MAN__ 904 #ifndef TRF_USE_STUBS 905 #include "trfDecls.h" 906 #endif 907 #endif 908 909 /* 910 * Convenience declaration of Trf_InitStubs. 911 * This function is not *implemented* by the trf library, so the storage 912 * class is neither DLLEXPORT nor DLLIMPORT 913 */ 914 915 #undef TCL_STORAGE_CLASS 916 #define TCL_STORAGE_CLASS 917 918 EXTERN CONST char *Trf_InitStubs _ANSI_ARGS_((Tcl_Interp *interp, CONST char *version, int exact)); 919 920 #ifndef USE_TRF_STUBS 921 922 #define Trf_InitStubs(interp, version, exact) \ 923 Tcl_PkgRequire(interp, "Trf", version, exact) 924 925 #endif 926 927 #undef TCL_STORAGE_CLASS 928 #define TCL_STORAGE_CLASS DLLIMPORT 929 930 #ifdef __cplusplus 931 } 932 #endif /* C++ */ 933 #endif /* TRF_H */ 934