<?php

namespace Safe;

use Safe\Exceptions\MailparseException;

/**
* Extracts/decodes a message section from the supplied filename.
*
* The contents of the section will be decoded according to their transfer
* encoding - base64, quoted-printable and uuencoded text are supported.
*
* @param resource $mimemail A valid MIME resource, created with
* mailparse_msg_create.
* @param mixed $filename Can be a file name or a valid stream resource.
* @param callable $callbackfunc If set, this must be either a valid callback that will be passed the
* extracted section, or NULL to make this function return the
* extracted section.
*
* If not specified, the contents will be sent to "stdout".
* @return string If callbackfunc is not NULL returns TRUE on
* success.
*
* If callbackfunc is set to NULL, returns the
* extracted section as a string.
* @throws MailparseException
*
*/
function mailparse_msg_extract_part_file($mimemail, $filename, callable $callbackfunc = null): string
{
error_clear_last();
if ($callbackfunc !== null) {
$result = \mailparse_msg_extract_part_file($mimemail, $filename, $callbackfunc);
} else {
$result = \mailparse_msg_extract_part_file($mimemail, $filename);
}
if ($result === false) {
throw MailparseException::createFromPhpError();
}
return $result;
}


/**
* Frees a MIME resource.
*
* @param resource $mimemail A valid MIME resource allocated by
* mailparse_msg_create or
* mailparse_msg_parse_file.
* @throws MailparseException
*
*/
function mailparse_msg_free($mimemail): void
{
error_clear_last();
$result = \mailparse_msg_free($mimemail);
if ($result === false) {
throw MailparseException::createFromPhpError();
}
}


/**
* Parses a file.
* This is the optimal way of parsing a mail file that you have on disk.
*
* @param string $filename Path to the file holding the message.
* The file is opened and streamed through the parser.
*
* The message contained in filename is supposed to end with a newline
* (CRLF); otherwise the last line of the message will not be parsed.
* @return resource Returns a MIME resource representing the structure.
* @throws MailparseException
*
*/
function mailparse_msg_parse_file(string $filename)
{
error_clear_last();
$result = \mailparse_msg_parse_file($filename);
if ($result === false) {
throw MailparseException::createFromPhpError();
}
return $result;
}


/**
* Incrementally parse data into the supplied mime mail resource.
*
* This function allow you to stream portions of a file at a time, rather
* than read and parse the whole thing.
*
* @param resource $mimemail A valid MIME resource.
* @param string $data The final chunk of data is supposed to end with a newline
* (CRLF); otherwise the last line of the message will not be parsed.
* @throws MailparseException
*
*/
function mailparse_msg_parse($mimemail, string $data): void
{
error_clear_last();
$result = \mailparse_msg_parse($mimemail, $data);
if ($result === false) {
throw MailparseException::createFromPhpError();
}
}


/**
* Streams data from the source file pointer, apply
* encoding and write to the destination file pointer.
*
* @param resource $sourcefp A valid file handle. The file is streamed through the parser.
* @param resource $destfp The destination file handle in which the encoded data will be written.
* @param string $encoding One of the character encodings supported by the
* mbstring module.
* @throws MailparseException
*
*/
function mailparse_stream_encode($sourcefp, $destfp, string $encoding): void
{
error_clear_last();
$result = \mailparse_stream_encode($sourcefp, $destfp, $encoding);
if ($result === false) {
throw MailparseException::createFromPhpError();
}
}