docs/user/net/HttpForm.dox

   1 /*
   2  * Copyright 2010-2013 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Adrien Destugues, pulkomandy@pulkomandy.tk
   7  *              John Scipione, jscipione@gmail.com
   8  *
   9  * Corresponds to:
  10  *              headers/os/net/HttpForm.h hrev46314
  11  *              src/kits/network/libnetapi/HttpForm.cpp hrev46314
  12  */
  13
  14
  15 /*!
  16         \file HttpForm.h
  17         \ingroup network
  18         \brief Management of HTTP form data
  19 */
  20
  21
  22 /*!
  23         \enum form_type
  24         \ingroup network
  25 */
  26
  27
  28 /*!
  29         \var form_type B_HTTP_FORM_URL_ENCODED
  30 */
  31
  32
  33 /*!
  34         \var form_type B_HTTP_FORM_MULTIPART
  35 */
  36
  37
  38 /*!
  39         \enum form_content_type
  40         \ingroup network
  41 */
  42
  43
  44 /*!
  45         \var form_content_type B_HTTPFORM_UNKNOWN
  46 */
  47
  48
  49 /*!
  50         \var form_content_type B_HTTPFORM_STRING
  51 */
  52
  53
  54 /*!
  55         \var form_content_type B_HTTPFORM_FILE
  56 */
  57
  58
  59 /*!
  60         \var form_content_type B_HTTPFORM_BUFFER
  61 */
  62
  63
  64 /*!
  65         \class BHttpFormData
  66         \ingroup network
  67         \brief Stores a form data entry sent or received during an HTTP request.
  68
  69         Each element in a form is stored in an instance of this class. The values
  70         can be either strings, arbitrary binary buffers, or a pointer to a file.
  71
  72         The latter allows reading data from the file as it is being sent through
  73         the network, removing hte need to buffer the whole file contents in memory.
  74 */
  75
  76
  77 /*!
  78         \fn BHttpFormData::BHttpFormData(const BString& name, const BString& value)
  79         \brief Construct a BHttpFormData object with a string value.
  80 */
  81
  82
  83 /*!
  84         \fn BHttpFormData::BHttpFormData(const BString& name, const BPath& value)
  85         \brief Construct a BHttpFormData object which value is a file contents
  86 */
  87
  88
  89 /*!
  90         \fn BHttpFormData::BHttpFormData(const BString& name, const void* buffer,
  91                 ssize_t size)
  92         \brief Construct a BHttpFormData object which value is a binary buffer.
  93 */
  94
  95
  96 /*!
  97         \fn bool BHttpFormData::InitCheck() const
  98         \brief Checks the initialization of the object
  99
 100         \return \c false if attempting to construct a BHttpFormData with a \c NULL
 101                 buffer.
 102 */
 103
 104
 105 /*!
 106         \fn const BString& BHttpFormData::Name() const
 107         \brief Get the form field name
 108 */
 109
 110
 111 /*!
 112         \fn const BString& BHttpFormData::String() const
 113         \brief Get the string value of a form field.
 114
 115         \return An empty string for buffer and file based fields.
 116 */
 117
 118
 119 /*!
 120         \fn const BPath& BHttpFormData::File() const
 121         \brief Get the file path of a form field.
 122
 123         \return An empty string for buffer and string based fields.
 124 */
 125
 126
 127 /*!
 128         \fn const void* BHttpFormData::Buffer() const
 129         \brief Get a pointer to the data of a form field.
 130
 131         \return An empty string for string and file based fields
 132 */
 133
 134
 135 /*!
 136         \fn ssize_t BHttpFormData::BufferSize() const;
 137         \brief Get the buffer size
 138
 139         \return 0 for string and file based fields.
 140 */
 141
 142
 143 /*!
 144         \fn bool BHttpFormData::IsFile() const
 145         \return \c true if the field data is a file.
 146 */
 147
 148
 149 /*!
 150         \fn const BString& BHttpFormData::Filename() const;
 151         \return The name of the file, for file based fields.
 152 */
 153
 154
 155 /*!
 156         \fn const BString& BHttpFormData::MimeType() const
 157         \return The MIME type of the data.
 158 */
 159
 160
 161 /*!
 162         \fn form_content_type BHttpFormData::Type() const
 163         \return The kind of field.
 164 */
 165
 166
 167 /*!
 168         \fn status_t BHttpFormData::CopyBuffer()
 169         \brief Make a copy of the internal buffer
 170
 171         The constructor for buffer-based fields does not copy the data given to it,
 172         it just keeps a pointer. If you want to retain ownership of the data, call
 173         this method so the buffer copies and releases it.
 174 */
 175
 176
 177 /*!
 178         \fn status_t BHttpFormData::MarkAsFile(const BString& filename,
 179                 const BString& mimeType)
 180         \brief Mark a field as a file.
 181 */
 182
 183
 184 /*!
 185         \fn void BHttpFormData::UnmarkAsFile()
 186         \brief Unmark a field as a file.
 187 */
 188
 189
 190 /*!
 191         \fn status_t BHttpFormData::CopyBuffer()
 192 */
 193
 194
 195 /*!
 196         \fn BHttpFormData& BHttpFormData::operator=(const BHttpFormData& other)
 197         \brief Assignment operator.
 198 */
 199
 200
 201 /*!
 202         \class BHttpForm
 203         \ingroup network
 204         \brief Container for all the BHttpFormData instances making up an HTTP form contents.
 205 */
 206
 207
 208 /*!
 209         \fn BHttpForm::BHttpForm()
 210         \brief Create a new form object.
 211 */
 212
 213
 214 /*!
 215         \fn BHttpForm::BHttpForm(const BHttpForm& other)
 216         \brief Create a new form object as a copy of \a other.
 217 */
 218
 219
 220 /*!
 221         \fn BHttpForm::BHttpForm(const BString& formString)
 222         \brief Create a new form object and parse the \a formString.
 223 */
 224
 225
 226 /*!
 227         \fn BHttpForm::~BHttpForm()
 228         \brief Clear the form and destroy the form object.
 229 */
 230
 231
 232 /*!
 233         \fn void BHttpForm::ParseString(const BString& formString)
 234         \brief Parse the \a formString.
 235 */
 236
 237
 238 /*!
 239         \fn BString BHttpForm::RawData() const
 240         \brief Return the form's raw data as a BString.
 241 */
 242
 243
 244 /*!
 245         \fn status_t BHttpForm::AddString(const BString& fieldName,
 246                 const BString& value)
 247         \brief Add a string to the form with the specified \a fieldName and \a value.
 248 */
 249
 250
 251 /*!
 252         \fn status_t BHttpForm::AddInt(const BString& fieldName, int32 value)
 253         \brief Add an int to the form with the specified \a fieldName and \a value.
 254 */
 255
 256
 257 /*!
 258         \fn status_t BHttpForm::AddFile(const BString& fieldName, const BPath& file)
 259         \brief Add a file to the form with the specified \a fieldName and \a value.
 260 */
 261
 262
 263 /*!
 264         \fn status_t BHttpForm::AddBuffer(const BString& fieldName,
 265                 const void* buffer, ssize_t size)
 266         \brief Add a buffer to the form with the specified \a fieldName and \a buffer
 267                and \a size.
 268 */
 269
 270
 271 /*!
 272         \fn status_t BHttpForm::AddBufferCopy(const BString& fieldName,
 273                 const void* buffer, ssize_t size)
 274 */
 275
 276
 277 /*!
 278         \fn void BHttpForm::MarkAsFile(const BString& fieldName,
 279                 const BString& filename, const BString& mimeType)
 280 */
 281
 282
 283 /*!
 284         \fn void BHttpForm::MarkAsFile(const BString& fieldName,
 285                 const BString& filename)
 286         \brief Mark a field as a filename.
 287 */
 288
 289
 290 /*!
 291         \fn void BHttpForm::UnmarkAsFile(const BString& fieldName)
 292         \brief Unmark a field as a filename.
 293 */
 294
 295
 296 /*!
 297         \fn void BHttpForm::SetFormType(form_type type)
 298         \brief Change form type.
 299 */
 300
 301
 302 /*!
 303         \fn bool BHttpForm::HasField(const BString& name) const
 304         \brief Returns whether or not a form has a field with the specified \a name.
 305 */
 306
 307
 308 /*!
 309         \fn BString BHttpForm::GetMultipartHeader(const BString& fieldName) const
 310 */
 311
 312
 313 /*!
 314         \fn form_type BHttpForm::GetFormType() const
 315 */
 316
 317
 318 /*!
 319         \fn const BString& BHttpForm::GetMultipartBoundary() const
 320 */
 321
 322
 323 /*!
 324         \fn BString BHttpForm::GetMultipartFooter() const
 325 */
 326
 327
 328 /*!
 329         \fn ssize_t BHttpForm::ContentLength() const
 330 */
 331
 332
 333 /*!
 334         \fn BHttpForm::Iterator BHttpForm::GetIterator()
 335 */
 336
 337
 338 /*!
 339         \fn void BHttpForm::Clear()
 340 */
 341
 342
 343 /*!
 344         \fn BHttpFormData& BHttpForm::operator[](const BString& name)
 345 */
 346
 347
 348 /*!
 349         \fn void BHttpForm::_ExtractNameValuePair(const BString& formString, int32* index)
 350 */
 351
 352
 353 /*!
 354         \fn void BHttpForm::_GenerateMultipartBoundary()
 355 */
 356
 357
 358 /*!
 359         \fn void BHttpForm::Clear()
 360 */
 361
 362
 363 /*!
 364         \class BHttpForm::Iterator
 365         \ingroup network
 366         \brief Form Iterator.
 367 */
 368
 369
 370 /*!
 371         \fn BHttpForm::Iterator::Iterator(BHttpForm* form)
 372         \brief Constructor.
 373 */
 374
 375
 376 /*!
 377         \fn BHttpForm::Iterator::Iterator(const Iterator& other);
 378         \brief Copy contstructor.
 379 */
 380
 381
 382 /*!
 383         \fn bool BHttpForm::Iterator::HasNext() const
 384 */
 385
 386
 387 /*!
 388         \fn BHttpFormData* BHttpForm::Iterator::Next()
 389 */
 390
 391
 392 /*!
 393         \fn void BHttpForm::Iterator::Remove()
 394 */
 395
 396
 397 /*!
 398         \fn BString BHttpForm::Iterator::MultipartHeader()
 399 */
 400
 401
 402 /*!
 403         \fn BHttpForm::Iterator& BHttpForm::Iterator::operator=(const Iterator& other)
 404         \brief Assignment operator.
 405 */