Changeset 34301 in project


Ignore:
Timestamp:
08/20/17 21:28:08 (3 months ago)
Author:
kon
Message:

rel 3.2

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/message-digest

    r33168 r34301  
    2828==== Common Argument Definitions
    2929
    30 {{PRIMITIVE}} is a {{message-digest-primitive}}
     30{{PRIM}} is a {{message-digest-primitive}}
    3131
    3232==== message-digest-primitive?
     
    3838==== message-digest-primitive Accessors
    3939
    40 <procedure>(message-digest-primitive-context-info PRIMITIVE)</procedure>
    41 <procedure>(message-digest-primitive-digest-length PRIMITIVE)</procedure>
    42 <procedure>(message-digest-primitive-init PRIMITIVE)</procedure>
    43 <procedure>(message-digest-primitive-update PRIMITIVE)</procedure>
    44 <procedure>(message-digest-primitive-final PRIMITIVE)</procedure>
    45 <procedure>(message-digest-primitive-block-length PRIMITIVE)</procedure>
    46 <procedure>(message-digest-primitive-name PRIMITIVE)</procedure>
     40<procedure>(message-digest-primitive-context-info PRIM)</procedure>
     41<procedure>(message-digest-primitive-digest-length PRIM)</procedure>
     42<procedure>(message-digest-primitive-init PRIM)</procedure>
     43<procedure>(message-digest-primitive-update PRIM)</procedure>
     44<procedure>(message-digest-primitive-final PRIM)</procedure>
     45<procedure>(message-digest-primitive-block-length PRIM)</procedure>
     46<procedure>(message-digest-primitive-name PRIM)</procedure>
    4747
    4848==== make-message-digest-primitive
     
    110110{{RESULT-FORM}} is one of:
    111111
    112 ; {{'string}} : the result bytes as a string; these are raw bytes, not characters!
    113 ; {{'hex}} : the result bytes encoded as a string of lower-case hexadecimal digits.
     112; {{'byte-string}} {{'string}} : the result bytes as a string; these are raw bytes, not characters!
     113; {{'hex-string}} {{'hex}} {{'hexstring}} : the result bytes encoded as a string of lower-case hexadecimal digits.
    114114; {{'blob}} : the result bytes as a blob.
    115115; {{'u8vector}} : the result bytes as a u8vector.
     
    135135A {{<byte-source>}} is one of {{string}}, {{blob}}, or {{srfi-4-vector}}.
    136136
     137==== message-digest-default-result-type
     138
     139<parameter>(message-digest-default-result-type [RESULT-FORM]) => symbol</parameter>
     140
     141The initial {{RESULT-FORM}} value is {{'hex-string}}.
     142
     143A {{RESULT-FORM}} of {{#f}} resets to the initial value.
     144
    137145==== initialize-message-digest
    138146
    139 <procedure>(initialize-message-digest PRIMITIVE) => message-digest</procedure>
     147<procedure>(initialize-message-digest PRIM) => message-digest</procedure>
    140148
    141149Returns a new, initialized {{message-digest}} for the supplied algorithm
    142 {{PRIMITIVE}}.
     150{{PRIM}}.
    143151
    144152Initialized here means the intialization phase is completed.
     
    163171==== finalize-message-digest
    164172
    165 <procedure>(finalize-message-digest DIGEST [RESULT-FORM]) => <result></procedure>
     173<procedure>(finalize-message-digest DIGEST [RESULT-FORM]) => *</procedure>
    166174
    167175Finalize the {{DIGEST}} and return the {{<result>}} in the {{RESULT-FORM}}.
    168176
    169 {{RESULT-FORM}} default is {{'hex}}.
     177{{RESULT-FORM}} default is {{(message-digest-default-result-type)}}.
    170178
    171179Finalize here means the finalization phase is completed. The {{DIGEST}} is not
     
    192200==== message-digest-chunk-read-maker
    193201
    194 <procedure>(message-digest-chunk-read-maker) => CONSTRUCTOR</procedure>
    195 <procedure>(message-digest-chunk-read-maker CONSTRUCTOR)</procedure>
     202<parameter>(message-digest-chunk-read-maker [CONSTRUCTOR]) => procedure</parameter>
    196203
    197204Supplies the procedure used to create an input procedure.
     
    206213==== message-digest-chunk-size
    207214
    208 <procedure>(message-digest-chunk-size) => SIZE</procedure>
    209 <procedure>(message-digest-chunk-size [SIZE])</procedure>
     215<parameter>(message-digest-chunk-size [SIZE]) => positive-integer</parameter>
    210216
    211217The number of bytes to read from a binary-stream during the message-digest
     
    216222==== message-digest-chunk-converter
    217223
    218 <procedure>(message-digest-chunk-converter) => CONVERTER</procedure>
    219 <procedure>(message-digest-chunk-converter CONVERTER)</procedure>
     224<parameter>(message-digest-chunk-converter [CONVERTER]) => (or #f procedure)</parameter>
    220225
    221226The procedure used to translate an arbitrary object into something
    222227suitable for an {{UPDATE}} procedure. See {{make-message-digest-primitive}}.
    223228
    224 {{CONVERTER}} is a {{(procedure (*) <byte-source>)}}.
    225 
    226 Should the {{CONVERTER}} be {{#f}} or return {{#f}} then no translation is attempted. The
    227 default {{CONVERTER}} is {{#f}}.
     229{{CONVERTER}} is a {{(procedure (*) <byte-source>)}} or {{#f}}.
     230
     231The default {{CONVERTER}} is {{#f}}.
     232
     233Should the {{CONVERTER}} be {{#f}} or return {{#f}} then no translation is attempted.
    228234
    229235=== Message Digest BV
     
    257263==== message-digest-string
    258264
    259 <procedure>(message-digest-string PRIMITIVE STRING [RESULT-FORM]) => <result></procedure>
    260 
    261 Returns the {{RESULT}} for the digest algorithm {{PRIMITIVE}} applied to
     265<procedure>(message-digest-string PRIM STRING [RESULT-FORM]) => *</procedure>
     266
     267Returns the {{RESULT}} for the digest algorithm {{PRIM}} applied to
    262268{{STRING}} in the {{RESULT-FORM}}.
    263269
    264 {{RESULT-FORM}} default is {{'hex}}.
     270{{RESULT-FORM}} default is {{(message-digest-default-result-type)}}.
    265271
    266272Performs all three phases.
     
    268274==== message-digest-blob
    269275
    270 <procedure>(message-digest-blob PRIMITIVE BLOB [RESULT-FORM]) => <result></procedure>
    271 
    272 Returns the {{<result>}} for the digest algorithm {{PRIMITIVE}} applied to
     276<procedure>(message-digest-blob PRIM BLOB [RESULT-FORM]) => *</procedure>
     277
     278Returns the {{<result>}} for the digest algorithm {{PRIM}} applied to
    273279{{BLOB}} in the {{RESULT-FORM}}.
    274280
    275 {{RESULT-FORM}} default is {{'hex}}.
     281{{RESULT-FORM}} default is {{(message-digest-default-result-type)}}.
    276282
    277283Performs all three phases.
     
    438444==== message-digest-object
    439445
    440 <procedure>(message-digest-object PRIMITIVE SOURCE [RESULT-FORM]) => <result></procedure>
    441 
    442 Returns the {{RESULT}} for the digest algorithm {{PRIMITIVE}} applied to
     446<procedure>(message-digest-object PRIM SOURCE [RESULT-FORM]) => *</procedure>
     447
     448Returns the result for the digest algorithm {{PRIM}} applied to
    443449{{SOURCE}} in the {{RESULT-FORM}}.
    444450
    445 {{RESULT-FORM}} default is {{'hex}}.
     451{{RESULT-FORM}} default is {{(message-digest-default-result-type)}}.
    446452
    447453Performs all three phases.
     
    449455==== message-digest-file
    450456
    451 <procedure>(message-digest-file PRIMITIVE FILENAME [RESULT-FORM]) => <result></procedure>
    452 
    453 Returns the {{<result>}} for the digest algorithm {{PRIMITIVE}} applied to
    454 the file {{FILENAME}} in the {{RESULT-FORM}}. Reads until {{#!eof}} encountered.
    455 
    456 {{RESULT-FORM}} default is {{'hex}}.
     457<procedure>(message-digest-file PRIM FILENAME [RESULT-FORM]) => *</procedure>
     458
     459Returns the result for the digest algorithm {{PRIM}} applied to the file
     460{{FILENAME}} in the {{RESULT-FORM}}. Reads until {{#!eof}} encountered.
     461
     462{{RESULT-FORM}} default is {{(message-digest-default-result-type)}}.
    457463
    458464Performs all three phases.
     
    460466==== message-digest-port
    461467
    462 <procedure>(message-digest-port PRIMITIVE INPUT-PORT [RESULT-FORM]) => <result></procedure>
    463 
    464 Returns the {{<result>}} for the digest algorithm {{PRIMITIVE}} applied to
     468<procedure>(message-digest-port PRIM INPUT-PORT [RESULT-FORM]) => *</procedure>
     469
     470Returns the result for the digest algorithm {{PRIM}} applied to
    465471{{INPUT-PORT}} in the {{RESULT-FORM}}. Reads until {{#!eof}} encountered.
    466472
    467 {{RESULT-FORM}} default is {{'hex}}.
     473{{RESULT-FORM}} default is {{(message-digest-default-result-type)}}.
    468474
    469475=== Message Digest SRFI 4
     
    501507==== message-digest-u8vector
    502508
    503 <procedure>(message-digest-u8vector PRIMITIVE U8VECTOR [RESULT-FORM]) => <result></procedure>
    504 
    505 Returns the {{<result>}} for the digest algorithm {{PRIMITIVE}} applied to
     509<procedure>(message-digest-u8vector PRIM U8VECTOR [RESULT-FORM]) => *</procedure>
     510
     511Returns the result for the digest algorithm {{PRIM}} applied to
    506512{{U8VECTOR}} in the {{RESULT-FORM}}.
    507513
    508 {{RESULT-FORM}} default is {{'hex}}.
     514{{RESULT-FORM}} default is {{(message-digest-default-result-type)}}.
    509515
    510516Performs all three phases.
     
    533539==== open-output-digest
    534540
    535 <procedure>(open-output-digest PRIMITIVE) => digest-output-port</procedure>
    536 
    537 Returns a message digest output port for the supplied algorithm {{PRIMITIVE}}.
     541<procedure>(open-output-digest PRIM) => digest-output-port</procedure>
     542
     543Returns a message digest output port for the supplied algorithm {{PRIM}}.
    538544
    539545The initialization phase.
     
    541547==== get-output-digest
    542548
    543 <procedure>(get-output-digest PORT [RESULT-TYPE 'hex]) => string</procedure>
    544 
    545 Closes the {{PORT}} and returns the result as a {{RESULT-TYPE}}.
     549<procedure>(get-output-digest PORT [RESULT-FORM]) => string</procedure>
     550
     551Closes the {{PORT}} and returns the result as a {{RESULT-FORM}}.
     552
     553{{RESULT-FORM}} default is {{(message-digest-default-result-type)}}.
    546554
    547555The finalization phase.
     
    549557==== call-with-output-digest
    550558
    551 <procedure>(call-with-output-digest PRIMITIVE PROCEDURE/1 [RESULT-FORM]) => <result></procedure>
    552 
    553 Invoke the procedure {{PROCEDURE PORT}} with {{digest-output-port}} and return
    554 {{<result>}} in the {{RESULT-FORM}}.
    555 
    556 {{RESULT-FORM}} default is {{'hex}}.
     559<procedure>(call-with-output-digest PRIM PROC [RESULT-FORM]) => *</procedure>
     560
     561Returns the result of the call of {{PROC}} with an {{open-output-digest}} for
     562{{PRIM}} in the {{RESULT-FORM}}.
     563
     564{{RESULT-FORM}} default is {{(message-digest-default-result-type)}}.
    557565
    558566Performs all three phases.
     
    560568==== with-output-to-digest
    561569
    562 <procedure>(with-output-to-digest PRIMITIVE THUNK [RESULT-FORM]) => <result></procedure>
     570<procedure>(with-output-to-digest PRIM THUNK [RESULT-FORM]) => *</procedure>
    563571
    564572Invoke the procedure {{THUNK}} with {{(current-output-port)}} bound to a
    565573{{digest-output-port}} and return {{<result>}} in the {{RESULT-FORM}}.
    566574
    567 {{RESULT-FORM}} default is {{'hex}}.
     575{{RESULT-FORM}} default is {{(message-digest-default-result-type)}}.
    568576
    569577Performs all three phases.
     
    602610== Bugs and Limitations
    603611
    604 * Only messages on a byte-boundary supported. Bit-boundary messages are not handled.
    605 
    606 * The number update routines will not process an {{integer}} represented
    607 as anything other than a {{fixnum}} or {{flonum}}.
    608 
    609 * Since Chicken does not really have a binary port the {{digest-output-port}} will
    610 only accumulate strings.
    611 
    612 For example, writing a 16-bit integer is actually writing the result of
    613 {{number->string}} and not the 16-bit value itself! To get this effect the
    614 value must first be packed into a {{string}} and then written.
    615 
    616 However, the {{extras#write-byte}} routine should function as expected with a
    617 {{digest-output-port}}.
     612* Only messages on a byte-boundary supported. Bit-boundary messages are not
     613handled.
     614
     615* The number update routines will not process an {{integer}} represented as
     616anything other than a {{fixnum}} or {{flonum}}.
     617
     618* Since Chicken does not really have a binary port the {{digest-output-port}}
     619will only accumulate strings. For example, writing a 16-bit integer is
     620actually writing the result of {{number->string}} and not the 16-bit value
     621itself! To get this effect the value must first be packed into a {{string}}
     622and then written. However, the {{extras#write-byte}} routine should function
     623as expected with a {{digest-output-port}}.
    618624
    619625* The chunk-converter and port-reader interface is clumsy.
     626
     627* {{message-digest-result-type}} should be renamed
     628{{message-digest-result-form}}.
    620629
    621630
     
    624633* If someone needs to construct a {{message-digest}} phase procedure that
    625634cannot be built upon the existing public API please contact the maintainer.
    626 There are some routines that can be exported to aid in such a project.
    627 
    628 It must be pointed out, though, that the message-digest port API is implemented
    629 using only the existing public API.
    630 
    631 * Should the default message-digest result-form be held by a ''"parameter"''
    632 object?
     635There are some routines that can be exported to aid in such a project. It must
     636be pointed out that the message-digest port API is implemented using only the
     637existing public API.
    633638
    634639
    635640== Requirements
    636641
     642[[setup-helper|setup-helper]]
    637643[[miscmacros|miscmacros]]
    638644[[check-errors|check-errors]]
     645[[blob-utils|blob-utils]]
     646[[string-utils|string-utils]]
    639647
    640648
     
    646654== Version history
    647655
     656; 3.2.0 : Add {{message-digest-default-result-type}}. {{message-digest-chunk-*}} are parameters.
    648657; 3.1.1 : Fix {{check-u8vector}} import.
    649658; 3.1.0 : Added optional {{message-digest-primitive-block-length}}.
     
    672681== License
    673682
    674   Copyright (C) 2006-2014 Kon Lovett.  All rights reserved.
     683  Copyright (C) 2006-2017 Kon Lovett.  All rights reserved.
    675684
    676685  Permission is hereby granted, free of charge, to any person obtaining a
Note: See TracChangeset for help on using the changeset viewer.