haiku/docs/user/net/HttpForm.dox

/*
 * Copyright 2010-2013 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Adrien Destugues, pulkomandy@pulkomandy.tk
 *		John Scipione, jscipione@gmail.com
 *
 * Corresponds to:
 *		headers/os/net/HttpForm.h hrev46314
 *		src/kits/network/libnetapi/HttpForm.cpp hrev46314
 */


/*!
	\file HttpForm.h
	\ingroup network
	\brief Management of HTTP form data
*/


/*!
	\enum form_type
	\ingroup network
*/


/*!
	\var form_type B_HTTP_FORM_URL_ENCODED
*/


/*!
	\var form_type B_HTTP_FORM_MULTIPART
*/


/*!
	\enum form_content_type
	\ingroup network
*/


/*!
	\var form_content_type B_HTTPFORM_UNKNOWN
*/


/*!
	\var form_content_type B_HTTPFORM_STRING
*/


/*!
	\var form_content_type B_HTTPFORM_FILE
*/


/*!
	\var form_content_type B_HTTPFORM_BUFFER
*/


/*!
	\class BHttpFormData
	\ingroup network
	\brief Stores a form data entry sent or received during an HTTP request.

	Each element in a form is stored in an instance of this class. The values
	can be either strings, arbitrary binary buffers, or a pointer to a file.

	The latter allows reading data from the file as it is being sent through
	the network, removing hte need to buffer the whole file contents in memory.
*/


/*!
	\fn BHttpFormData::BHttpFormData(const BString& name, const BString& value)
	\brief Construct a BHttpFormData object with a string value.
*/


/*!
	\fn BHttpFormData::BHttpFormData(const BString& name, const BPath& value)
	\brief Construct a BHttpFormData object which value is a file contents
*/


/*!
	\fn BHttpFormData::BHttpFormData(const BString& name, const void* buffer,
		ssize_t size)
	\brief Construct a BHttpFormData object which value is a binary buffer.
*/


/*!
	\fn bool BHttpFormData::InitCheck() const
	\brief Checks the initialization of the object

	\return \c false if attempting to construct a BHttpFormData with a \c NULL
	        buffer.
*/


/*!
	\fn const BString& BHttpFormData::Name() const
	\brief Get the form field name
*/


/*!
	\fn const BString& BHttpFormData::String() const
	\brief Get the string value of a form field.

	\return An empty string for buffer and file based fields.
*/


/*!
	\fn const BPath& BHttpFormData::File() const
	\brief Get the file path of a form field.

	\return An empty string for buffer and string based fields.
*/


/*!
	\fn const void* BHttpFormData::Buffer() const
	\brief Get a pointer to the data of a form field.

	\return An empty string for string and file based fields
*/


/*!
	\fn ssize_t BHttpFormData::BufferSize() const;
	\brief Get the buffer size

	\return 0 for string and file based fields.
*/


/*!
	\fn bool BHttpFormData::IsFile() const
	\return \c true if the field data is a file.
*/


/*!
	\fn const BString& BHttpFormData::Filename() const;
	\return The name of the file, for file based fields.
*/


/*!
	\fn const BString& BHttpFormData::MimeType() const
	\return The MIME type of the data.
*/


/*!
	\fn form_content_type BHttpFormData::Type() const
	\return The kind of field.
*/


/*!
	\fn status_t BHttpFormData::CopyBuffer()
	\brief Make a copy of the internal buffer

	The constructor for buffer-based fields does not copy the data given to it,
	it just keeps a pointer. If you want to retain ownership of the data, call
	this method so the buffer copies and releases it.
*/


/*!
	\fn status_t BHttpFormData::MarkAsFile(const BString& filename,
		const BString& mimeType)
	\brief Mark a field as a file.
*/


/*!
	\fn void BHttpFormData::UnmarkAsFile()
	\brief Unmark a field as a file.
*/


/*!
	\fn status_t BHttpFormData::CopyBuffer()
*/


/*!
	\fn BHttpFormData& BHttpFormData::operator=(const BHttpFormData& other)
	\brief Assignment operator.
*/


/*!
	\class BHttpForm
	\ingroup network
	\brief Container for all the BHttpFormData instances making up an HTTP form contents.
*/


/*!
	\fn BHttpForm::BHttpForm()
	\brief Create a new form object.
*/


/*!
	\fn BHttpForm::BHttpForm(const BHttpForm& other)
	\brief Create a new form object as a copy of \a other.
*/


/*!
	\fn BHttpForm::BHttpForm(const BString& formString)
	\brief Create a new form object and parse the \a formString.
*/


/*!
	\fn BHttpForm::~BHttpForm()
	\brief Clear the form and destroy the form object.
*/


/*!
	\fn void BHttpForm::ParseString(const BString& formString)
	\brief Parse the \a formString.
*/


/*!
	\fn BString BHttpForm::RawData() const
	\brief Return the form's raw data as a BString.
*/


/*!
	\fn status_t BHttpForm::AddString(const BString& fieldName,
		const BString& value)
	\brief Add a string to the form with the specified \a fieldName and \a value.
*/


/*!
	\fn status_t BHttpForm::AddInt(const BString& fieldName, int32 value)
	\brief Add an int to the form with the specified \a fieldName and \a value.
*/


/*!
	\fn status_t BHttpForm::AddFile(const BString& fieldName, const BPath& file)
	\brief Add a file to the form with the specified \a fieldName and \a value.
*/


/*!
	\fn status_t BHttpForm::AddBuffer(const BString& fieldName,
		const void* buffer, ssize_t size)
	\brief Add a buffer to the form with the specified \a fieldName and \a buffer
	       and \a size.
*/


/*!
	\fn status_t BHttpForm::AddBufferCopy(const BString& fieldName,
		const void* buffer, ssize_t size)
*/


/*!
	\fn void BHttpForm::MarkAsFile(const BString& fieldName,
		const BString& filename, const BString& mimeType)
*/


/*!
	\fn void BHttpForm::MarkAsFile(const BString& fieldName,
		const BString& filename)
	\brief Mark a field as a filename.
*/


/*!
	\fn void BHttpForm::UnmarkAsFile(const BString& fieldName)
	\brief Unmark a field as a filename.
*/


/*!
	\fn void BHttpForm::SetFormType(form_type type)
	\brief Change form type.
*/


/*!
	\fn bool BHttpForm::HasField(const BString& name) const
	\brief Returns whether or not a form has a field with the specified \a name.
*/


/*!
	\fn BString BHttpForm::GetMultipartHeader(const BString& fieldName) const
*/


/*!
	\fn form_type BHttpForm::GetFormType() const
*/


/*!
	\fn const BString& BHttpForm::GetMultipartBoundary() const
*/


/*!
	\fn BString BHttpForm::GetMultipartFooter() const
*/


/*!
	\fn ssize_t BHttpForm::ContentLength() const
*/


/*!
	\fn BHttpForm::Iterator BHttpForm::GetIterator()
*/


/*!
	\fn void BHttpForm::Clear()
*/


/*!
	\fn BHttpFormData& BHttpForm::operator[](const BString& name)
*/


/*!
	\fn void BHttpForm::_ExtractNameValuePair(const BString& formString, int32* index)
*/


/*!
	\fn void BHttpForm::_GenerateMultipartBoundary()
*/


/*!
	\fn void BHttpForm::Clear()
*/


/*!
	\class BHttpForm::Iterator
	\ingroup network
	\brief Form Iterator.
*/


/*!
	\fn BHttpForm::Iterator::Iterator(BHttpForm* form)
	\brief Constructor.
*/


/*!
	\fn BHttpForm::Iterator::Iterator(const Iterator& other);
	\brief Copy contstructor.
*/


/*!
	\fn bool BHttpForm::Iterator::HasNext() const
*/


/*!
	\fn BHttpFormData* BHttpForm::Iterator::Next()
*/


/*!
	\fn void BHttpForm::Iterator::Remove()
*/


/*!
	\fn BString BHttpForm::Iterator::MultipartHeader()
*/


/*!
	\fn BHttpForm::Iterator& BHttpForm::Iterator::operator=(const Iterator& other)
	\brief Assignment operator.
*/