<chunk>

# dkim_chunk()

[back to index]

SYNOPSIS

    #include <dkim.h>
    DKIM_STAT dkim_chunk(
    	DKIM *dkim,
    	unsigned char *chunkp,
    	size_t len
    );

Handle a chunk of message input. The input is a buffer of message data which may contain headers or body. An entire message may be fed to the API in one buffer using this function. The API will determine automatically the boundary between header fields and the body of the message and process it accordingly.

Message body content should be in canonical form (e.g., with dot-stuffing removed, if any).

Lines in the data chunk are expected to be CRLF-terminated in the standard way. For input that is not, consider setting the `DKIM_LIBFLAGS_FIXCRLF` (see `dkim_options()`), which will cause this function to attempt to auto-detect based on the first line whether the input is CRLF-terminated or not, and adapt accordingly.

`dkim_eoh()` will be called implicitly by this function upon encountering the end of the message's header block, but the caller must still use `dkim_eom()` to complete processing of the message. Also, this function should be called with a NULL value for `chunkp` and/or a zero value for `len` when no more chunks are to be passed to the API, prior to calling `dkim_eom()`.

DESCRIPTION

Called When | `dkim_chunk()` is called zero or more times between creation of the DKIM handle, using `dkim_sign()` and `dkim_verify()`, and `dkim_eom()`.

ARGUMENTS

Argument | Description
--- | ---
dkim | Message-specific handle, returned by `dkim_sign()` or `dkim_verify()`
chunkp | Pointer to the start of this block of message data. A value of NULL indicates to the API that no more chunks are to follow.
len | The amount of data pointed to by `chunkp`. A value of 0 indicates to the API that no more chunks are to follow.

RETURN VALUES

- `DKIM_STAT_INVALID` indicates the `dkim` handle was already used in by one of the non-streaming data input calls (e.g. `dkim_header()`, `dkim_eoh()` or `dkim_body()`).
- `DKIM_STAT_INVALID` may also indicate that this function was previously called with terminating arguments (see above), implying data input had finished.
- `DKIM_STAT_OK` indicates normal completion.
- May also return other values as passed through from `dkim_header()`, `dkim_eoh()` or `dkim_body()`.

NOTES

- `chunkp` points to a sequence of bytes. It is not expected to be a C string (a sequence of characters that is terminated by '\0').
- Dot stuffing and the terminating dot in the message body are expected to be removed by the caller. If they appear within `chunkp`, they are assumed to be part of the message body and will be included in the hashed data. This is true of any content modification that might be done by the MTA.

Copyright (c) 2008 Sendmail, Inc. and its suppliers. All rights reserved.
Copyright (c) 2009, 2010, 2013, 2014, The Trusted Domain Project. All rights reserved.
By using this file, you agree to the terms and conditions set forth in the respective licenses.