native_dynamic_multipart.h

Go to the documentation of this file.

/**
 * @file
 * @brief Pharos-owned multipart form-data parsing for in-process dynamic handling.
 *
 * Provides boundary extraction, part lookup, filename extraction, and
 * file-part extraction so that the dynamic runtime can process multipart
 * uploads without delegating to a child process or relying on app-owned
 * shell logic.
 */
 
#ifndef PHAROS_NATIVE_DYNAMIC_MULTIPART_H
#define PHAROS_NATIVE_DYNAMIC_MULTIPART_H
 
#include <stddef.h>
 
/** @name Boundary extraction
 * @{
 */
 
/**
 * @brief Extracts the MIME boundary string from a Content-Type header.
 *
 * @param content_type  The full Content-Type header value.
 * @return Newly allocated boundary string (without the leading @c -- ),
 *         or NULL when the boundary cannot be determined.
 *         Caller must free.
 */
char *native_dynamic_multipart_boundary(const char *content_type);
 
/** @} */
 
/** @name Part lookup
 * @{
 */
 
/**
 * @brief Finds a named part in a multipart request body.
 *
 * Searches @p body for a part whose Content-Disposition name matches
 * @p field_name.  When found, optionally returns the text content,
 * the uploaded filename, and/or the raw content range within @p body.
 *
 * @param body            Raw multipart body bytes.
 * @param body_len        Byte length of @p body.
 * @param content_type    The full Content-Type header (must contain the boundary).
 * @param field_name      The form field name to locate.
 * @param out_text        Receives a NUL-terminated copy of the part content
 *                        (may be NULL to skip).
 * @param out_filename    Receives the uploaded filename (may be NULL to skip).
 * @param out_content_start  Receives a pointer into @p body at the content start
 *                          (may be NULL to skip).
 * @param out_content_len    Receives the content byte length (may be NULL to skip).
 * @return 1 when a matching part was found, 0 otherwise.
 */
int native_dynamic_multipart_find_part(
  const unsigned char *body,
  size_t body_len,
  const char *content_type,
  const char *field_name,
  char **out_text,
  char **out_filename,
  const unsigned char **out_content_start,
  size_t *out_content_len
);
 
/** @} */
 
/** @name Filename extraction
 * @{
 */
 
/**
 * @brief Extracts the uploaded filename for a named multipart file part.
 *
 * @param body            Raw multipart body bytes.
 * @param body_len        Byte length of @p body.
 * @param content_type    The full Content-Type header.
 * @param field_name      The form field name of the file input.
 * @return Newly allocated filename string, or NULL when not found.
 *         Caller must free.
 */
char *native_dynamic_multipart_filename(
  const unsigned char *body,
  size_t body_len,
  const char *content_type,
  const char *field_name
);
 
/** @} */
 
/** @name Text extraction
 * @{
 */
 
/**
 * @brief Extracts a text value from a multipart form field.
 *
 * @param body            Raw multipart body bytes.
 * @param body_len        Byte length of @p body.
 * @param content_type    The full Content-Type header.
 * @param field_name      The form field name to extract.
 * @return Newly allocated text value, or NULL when not found.
 *         Caller must free.
 */
char *native_dynamic_multipart_extract_text(
  const unsigned char *body,
  size_t body_len,
  const char *content_type,
  const char *field_name
);
 
/** @} */
 
/** @name File extraction
 * @{
 */
 
/**
 * @brief Extracts file content from a multipart file part and writes it to disk.
 *
 * @param body            Raw multipart body bytes.
 * @param body_len        Byte length of @p body.
 * @param content_type    The full Content-Type header.
 * @param field_name      The form field name of the file input.
 * @param output_path     Destination file path on disk.
 * @return 0 on success, non-zero on failure.
 */
int native_dynamic_multipart_extract_file(
  const unsigned char *body,
  size_t body_len,
  const char *content_type,
  const char *field_name,
  const char *output_path
);
 
/** @} */
 
#endif