Changeset 34395 in project


Ignore:
Timestamp:
08/26/17 23:35:45 (3 months ago)
Author:
kon
Message:

rel 3.4

File:
1 edited

Legend:

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

    r34303 r34395  
    1717This extension is split into many modules. The extension module ''message-digest''
    1818exports every other modules except ''message-digest-port''.
     19
    1920
    2021=== Message Digest Primitive
     
    3839==== message-digest-primitive Accessors
    3940
    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>
     41<procedure>(message-digest-primitive-context-info PRIM) => *</procedure>
     42<procedure>(message-digest-primitive-digest-length PRIM) => fixnum</procedure>
     43<procedure>(message-digest-primitive-init PRIM) => procedure</procedure>
     44<procedure>(message-digest-primitive-update PRIM) => procedure</procedure>
     45<procedure>(message-digest-primitive-raw-update PRIM) => (or #f procedure)</procedure>
     46<procedure>(message-digest-primitive-final PRIM) => procedure</procedure>
     47<procedure>(message-digest-primitive-block-length PRIM) => fixnum</procedure>
     48<procedure>(message-digest-primitive-name PRIM) => symbol</procedure>
    4749
    4850==== make-message-digest-primitive
    4951
    50 <procedure>(make-message-digest-primitive CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [BLOCK-LENGTH [NAME]]) => message-digest-primitive</procedure>
    51 
    52 Create a {{message-digest-primitive}} object. The reification of a message digest
    53 algorithm.
     52<procedure>(make-message-digest-primitive CONTEXT-INFO DIGEST-LENGTH INIT UPDATE FINAL [BLOCK-LENGTH [NAME [RAW-UPDATE]]]) => message-digest-primitive</procedure>
     53
     54Create a {{message-digest-primitive}} object. The reification of a message
     55digest algorithm.
    5456
    5557{{CONTEXT-INFO}} is either a {{(procedure () <context>)}}, or a
     
    5860
    5961{{<context>}} is an opaque object, except when the {{CONTEXT-INFO}} is an
    60 {{integer}}. In which case it is known that the object is a {{pointer}} to a block
    61 of uninitialized memory.
    62 
    63 The {{<context>}} should be a unique object. At least the object cannot be shared
    64 with another ''activated'' primitive.
     62{{integer}}. In which case it is known that the object is a {{pointer}} to a
     63block of uninitialized memory.
     64
     65The {{<context>}} should be a unique object. At least the object cannot be
     66shared with another ''activated'' primitive.
    6567
    6668{{DIGEST-LENGTH}} is the count of bytes in the result.
     
    6870The processing of a message digest is split into three phases: initialization,
    6971update & finalization. These are represented by three procedures: {{INIT}},
    70 {{UPDATE}} & {{FINAL}}, respectively.
    71 
    72 {{INIT}} is a {{(procedure (<CONTEXT>))}}. Sets up the {{<CONTEXT>}}. (Technically
    73 the creation of a new {{<CONTEXT>}} is part of the initialization phase but this
    74 detail is hidden from the user.)
    75 
    76 {{UPDATE}} is a {{(procedure (<CONTEXT> <BLOB> <COUNT>))}}. Must accumulate the
    77 {{<BLOB>}}. Will be called zero or more times.
     72{{UPDATE}}/{{RAW-UPDATE}} & {{FINAL}}, respectively.
     73
     74{{INIT}} is a {{(procedure (<CONTEXT>))}}. Sets up the {{<CONTEXT>}}.
     75(Technically the creation of a new {{<CONTEXT>}} is part of the initialization
     76phase but this detail is hidden from the user.)
     77
     78{{UPDATE}} is a {{(procedure (<CONTEXT> <BLOB> <COUNT>))}}. Must accumulate
     79the {{<BLOB>}}. Will be called zero or more times.
    7880
    7981The foreign type specifier {{scheme-pointer}} is suitable as a foreign-lambda
    80 argument type for the {{<BLOB>}} argument since the data-region is a contiguous
    81 array of bytes.
    82 
    83 {{<COUNT>}} is the actual number of bytes in the {{<BLOB>}}. Since this value is
    84 supplied it means only the first {{<COUNT>}} bytes in the {{<BLOB>}} are valid.
    85 
    86 {{FINAL}} is a {{(procedure (<CONTEXT> <BLOB>))}}. Must build the message-digest
    87 result in the supplied result {{<BLOB>}}, which will have a length of at least
    88 {{DIGEST-LENGTH}}.
    89 
    90 ('''Note''' that {{INIT}}, {{UPDATE}} & {{FINAL}} are side-effecting procedures!)
     82argument type for the {{<BLOB>}} argument since the data-region is a
     83contiguous array of bytes.
     84
     85{{<COUNT>}} is the actual number of bytes in the {{<BLOB>}}. Since this value
     86is supplied it means only the first {{<COUNT>}} bytes in the {{<BLOB>}} are
     87valid.
     88
     89{{FINAL}} is a {{(procedure (<CONTEXT> <BLOB>))}}. Must build the
     90message-digest result in the supplied result {{<BLOB>}}, which will have a
     91length of at least {{DIGEST-LENGTH}}.
     92
     93('''Note''' that {{INIT}}, {{UPDATE}}/{{RAW-UPDATE}} & {{FINAL}} are side-effecting
     94procedures!)
    9195
    9296{{BLOCK-LENGTH}} must be a positive {{fixnum}} and identifies the message
    9397digest algorithm accumulator length in bytes. The default is {{4}}.
    9498
    95 {{NAME}} must be a {{symbol}} or a {{string}} and identifies the message digest
    96 algorithm. The suggested form is {{<algorithm name>-primitive}}. Example:
    97 {{'md5-primitive}}. The default is a nearly useless generated, uninterned
    98 {{symbol}}.
     99{{NAME}} must be a {{symbol}} or a {{string}} and identifies the message
     100digest algorithm. The suggested form is {{<algorithm name>-primitive}}.
     101Example: {{'md5-primitive}}. The default is a nearly useless generated,
     102uninterned {{symbol}}.
     103
     104{{RAW-UPDATE}} is a {{(procedure (<CONTEXT> <POINTER> <COUNT>))}}. Must
     105accumulate the memory at {{<POINTER>}}. Will be called zero or more times.
     106
    99107
    100108=== Message Digest Type
     
    186194Ensure the {{DIGEST}} has a buffer of at least {{SIZE}} bytes.
    187195
    188 === Message Digest Parameters
    189 
    190 Common handlers.
    191 
    192 Not thread specific.
    193 
    194 ==== Usage
    195 
     196
     197=== Message Digest Chunk
     198
     199''Chunking'' API
     200
     201==== Usage
     202
     203<enscript highlight=scheme>
     204(use message-digest-chunk)
     205</enscript>
     206
     207or
     208
     209'''DEPRECATED'''
    196210<enscript highlight=scheme>
    197211(use message-digest-parameters)
    198212</enscript>
    199213
    200 ==== message-digest-chunk-read-maker
    201 
    202 <parameter>(message-digest-chunk-read-maker [CONSTRUCTOR]) => procedure</parameter>
     214==== message-digest-chunk-port-read-maker
     215
     216<parameter>(message-digest-chunk-port-read-maker [CONSTRUCTOR]) => procedure</parameter>
    203217
    204218Supplies the procedure used to create an input procedure.
     
    211225{{INPUT-PORT}} in {{(message-digest-chunk-size)}} bytes.
    212226
     227==== message-digest-chunk-read-maker
     228
     229<parameter>(message-digest-chunk-read-maker [CONSTRUCTOR]) => procedure</parameter>
     230
     231Synonym for {{message-digest-chunk-port-read-maker}}.
     232
     233'''DEPRECATED'''
     234
     235==== message-digest-chunk-fileno-read-maker
     236
     237<parameter>(message-digest-chunk-fileno-read-maker [CONSTRUCTOR]) => procedure</parameter>
     238
     239Supplies the procedure used to create an input procedure.
     240
     241{{CONSTRUCTOR}} is a {{(procedure (FD #!optional SIZE) (procedure ()
     242<byte-source>))}}. The first argument is the chunk source open fileno and the
     243second argument is the size of chunks.
     244
     245The default {{CONSTRUCTOR}} will return a procedure that reads from {{FD}} in
     246{{(file-size FD)}} bytes.
     247
    213248==== message-digest-chunk-size
    214249
     
    233268Should the {{CONVERTER}} be {{#f}} or return {{#f}} then no translation is attempted.
    234269
     270
    235271=== Message Digest BV
    236272
     
    283319Performs all three phases.
    284320
     321
    285322=== Message Digest Int
    286323
     
    387424
    388425Update the {{DIGEST}} with a 64-bit integer {{U64}} treated as little-endian.
     426
    389427
    390428=== Message Digest Update Item
     
    432470can convert into a {{<byte-source>}}.
    433471
     472
    434473=== Message Digest Item
    435474
     
    473512{{RESULT-FORM}} default is {{(message-digest-result-form)}}.
    474513
     514
    475515=== Message Digest SRFI 4
    476516
     
    515555
    516556Performs all three phases.
     557
    517558
    518559=== Message Digest Port
     
    623664as expected with a {{digest-output-port}}.
    624665
    625 * The chunk-converter and port-reader interface is clumsy.
     666* The chunk-converter and source-reader interface is clumsy.
    626667
    627668
     
    631672cannot be built upon the existing public API please contact the maintainer.
    632673There are some routines that can be exported to aid in such a project. It must
    633 be pointed out that the message-digest port API is implemented using only the
    634 existing public API.
     674be pointed out that the message-digest port/file API is implemented using only
     675the existing public API.
    635676
    636677
     
    651692== Version history
    652693
     694; 3.4.0 : Deprecate {{message-digest-chunk-read-maker}}. Add {{message-digest-chunk-port-read-maker}}, {{message-digest-chunk-fileno-read-maker}}. Add {{message-digest-primitive-raw-update}}.
    653695; 3.3.0 : Deprecate {{message-digest-default-result-type}}. Add {{message-digest-result-form}}.
    654696; 3.2.0 : Add {{message-digest-default-result-type}}. {{message-digest-chunk-*}} are parameters.
Note: See TracChangeset for help on using the changeset viewer.