diff options
| author | Zhang zhengguang <zhengguang.zhang@intel.com> | 2014-11-04 11:12:11 +0800 |
|---|---|---|
| committer | Zhang zhengguang <zhengguang.zhang@intel.com> | 2014-11-04 11:12:11 +0800 |
| commit | 9f52ffa8b526e717e324fe0835ab794478650f11 (patch) | |
| tree | 4c1ec36d951519b39e0e1e7acd90bccfcd6fc2ff /docs | |
| parent | 39e527cdc1af04afdf13207f5503afa7b772043e (diff) | |
| download | libsoup-9f52ffa8b526e717e324fe0835ab794478650f11.tar.gz libsoup-9f52ffa8b526e717e324fe0835ab794478650f11.tar.bz2 libsoup-9f52ffa8b526e717e324fe0835ab794478650f11.zip | |
Imported Upstream version 2.46.0upstream/2.46.0
Diffstat (limited to 'docs')
127 files changed, 45410 insertions, 38463 deletions
diff --git a/docs/Makefile.in b/docs/Makefile.in new file mode 100644 index 00000000..c0a497b9 --- /dev/null +++ b/docs/Makefile.in @@ -0,0 +1,671 @@ +# Makefile.in generated by automake 1.13.4 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2013 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ +VPATH = @srcdir@ +am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)' +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = docs +DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/glibtests.m4 \ + $(top_srcdir)/m4/gtk-doc.m4 $(top_srcdir)/m4/intltool.m4 \ + $(top_srcdir)/m4/introspection.m4 $(top_srcdir)/m4/libtool.m4 \ + $(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \ + $(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +SOURCES = +DIST_SOURCES = +RECURSIVE_TARGETS = all-recursive check-recursive cscopelist-recursive \ + ctags-recursive dvi-recursive html-recursive info-recursive \ + install-data-recursive install-dvi-recursive \ + install-exec-recursive install-html-recursive \ + install-info-recursive install-pdf-recursive \ + install-ps-recursive install-recursive installcheck-recursive \ + installdirs-recursive pdf-recursive ps-recursive \ + tags-recursive uninstall-recursive +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \ + distclean-recursive maintainer-clean-recursive +am__recursive_targets = \ + $(RECURSIVE_TARGETS) \ + $(RECURSIVE_CLEAN_TARGETS) \ + $(am__extra_recursive_targets) +AM_RECURSIVE_TARGETS = $(am__recursive_targets:-recursive=) TAGS CTAGS \ + distdir +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +# Read a list of newline-separated strings from the standard input, +# and print each of them once, without duplicates. Input order is +# *not* preserved. +am__uniquify_input = $(AWK) '\ + BEGIN { nonempty = 0; } \ + { items[$$0] = 1; nonempty = 1; } \ + END { if (nonempty) { for (i in items) print i; }; } \ +' +# Make sure the list of sources is unique. This is necessary because, +# e.g., the same source file might be shared among _SOURCES variables +# for different programs/libraries. +am__define_uniq_tagged_files = \ + list='$(am__tagged_files)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | $(am__uniquify_input)` +ETAGS = etags +CTAGS = ctags +DIST_SUBDIRS = $(SUBDIRS) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +am__relativize = \ + dir0=`pwd`; \ + sed_first='s,^\([^/]*\)/.*$$,\1,'; \ + sed_rest='s,^[^/]*/*,,'; \ + sed_last='s,^.*/\([^/]*\)$$,\1,'; \ + sed_butlast='s,/*[^/]*$$,,'; \ + while test -n "$$dir1"; do \ + first=`echo "$$dir1" | sed -e "$$sed_first"`; \ + if test "$$first" != "."; then \ + if test "$$first" = ".."; then \ + dir2=`echo "$$dir0" | sed -e "$$sed_last"`/"$$dir2"; \ + dir0=`echo "$$dir0" | sed -e "$$sed_butlast"`; \ + else \ + first2=`echo "$$dir2" | sed -e "$$sed_first"`; \ + if test "$$first2" = "$$first"; then \ + dir2=`echo "$$dir2" | sed -e "$$sed_rest"`; \ + else \ + dir2="../$$dir2"; \ + fi; \ + dir0="$$dir0"/"$$first"; \ + fi; \ + fi; \ + dir1=`echo "$$dir1" | sed -e "$$sed_rest"`; \ + done; \ + reldir="$$dir2" +ACLOCAL = @ACLOCAL@ +ALL_LINGUAS = @ALL_LINGUAS@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APACHE_HTTPD = @APACHE_HTTPD@ +APACHE_MODULE_DIR = @APACHE_MODULE_DIR@ +APACHE_PHP_MODULE = @APACHE_PHP_MODULE@ +APACHE_PHP_MODULE_DIR = @APACHE_PHP_MODULE_DIR@ +APACHE_SSL_MODULE_DIR = @APACHE_SSL_MODULE_DIR@ +AR = @AR@ +AS = @AS@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CURL = @CURL@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +GETTEXT_PACKAGE = @GETTEXT_PACKAGE@ +GLIB_CFLAGS = @GLIB_CFLAGS@ +GLIB_COMPILE_RESOURCES = @GLIB_COMPILE_RESOURCES@ +GLIB_GENMARSHAL = @GLIB_GENMARSHAL@ +GLIB_LIBS = @GLIB_LIBS@ +GLIB_MAKEFILE = @GLIB_MAKEFILE@ +GLIB_MKENUMS = @GLIB_MKENUMS@ +GMSGFMT = @GMSGFMT@ +GOBJECT_QUERY = @GOBJECT_QUERY@ +GREP = @GREP@ +GTKDOC_CHECK = @GTKDOC_CHECK@ +GTKDOC_CHECK_PATH = @GTKDOC_CHECK_PATH@ +GTKDOC_DEPS_CFLAGS = @GTKDOC_DEPS_CFLAGS@ +GTKDOC_DEPS_LIBS = @GTKDOC_DEPS_LIBS@ +GTKDOC_MKPDF = @GTKDOC_MKPDF@ +GTKDOC_REBASE = @GTKDOC_REBASE@ +HAVE_GNOME = @HAVE_GNOME@ +HTML_DIR = @HTML_DIR@ +IF_HAVE_PHP = @IF_HAVE_PHP@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +INTLTOOL_EXTRACT = @INTLTOOL_EXTRACT@ +INTLTOOL_MERGE = @INTLTOOL_MERGE@ +INTLTOOL_PERL = @INTLTOOL_PERL@ +INTLTOOL_UPDATE = @INTLTOOL_UPDATE@ +INTLTOOL_V_MERGE = @INTLTOOL_V_MERGE@ +INTLTOOL_V_MERGE_OPTIONS = @INTLTOOL_V_MERGE_OPTIONS@ +INTLTOOL__v_MERGE_ = @INTLTOOL__v_MERGE_@ +INTLTOOL__v_MERGE_0 = @INTLTOOL__v_MERGE_0@ +INTROSPECTION_CFLAGS = @INTROSPECTION_CFLAGS@ +INTROSPECTION_COMPILER = @INTROSPECTION_COMPILER@ +INTROSPECTION_GENERATE = @INTROSPECTION_GENERATE@ +INTROSPECTION_GIRDIR = @INTROSPECTION_GIRDIR@ +INTROSPECTION_LIBS = @INTROSPECTION_LIBS@ +INTROSPECTION_MAKEFILE = @INTROSPECTION_MAKEFILE@ +INTROSPECTION_SCANNER = @INTROSPECTION_SCANNER@ +INTROSPECTION_TYPELIBDIR = @INTROSPECTION_TYPELIBDIR@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MKDIR_P = @MKDIR_P@ +MSGFMT = @MSGFMT@ +MSGMERGE = @MSGMERGE@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PHP = @PHP@ +PKG_CONFIG = @PKG_CONFIG@ +PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ +PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SOUP_AGE = @SOUP_AGE@ +SOUP_API_VERSION = @SOUP_API_VERSION@ +SOUP_CURRENT = @SOUP_CURRENT@ +SOUP_DEBUG_FLAGS = @SOUP_DEBUG_FLAGS@ +SOUP_MAJOR_VERSION = @SOUP_MAJOR_VERSION@ +SOUP_MICRO_VERSION = @SOUP_MICRO_VERSION@ +SOUP_MINOR_VERSION = @SOUP_MINOR_VERSION@ +SOUP_REVISION = @SOUP_REVISION@ +SQLITE_CFLAGS = @SQLITE_CFLAGS@ +SQLITE_LIBS = @SQLITE_LIBS@ +STRIP = @STRIP@ +USE_NLS = @USE_NLS@ +VERSION = @VERSION@ +XGETTEXT = @XGETTEXT@ +XML_CFLAGS = @XML_CFLAGS@ +XML_LIBS = @XML_LIBS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +installed_test_metadir = @installed_test_metadir@ +installed_testdir = @installed_testdir@ +intltool__v_merge_options_ = @intltool__v_merge_options_@ +intltool__v_merge_options_0 = @intltool__v_merge_options_0@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +ntlm_auth = @ntlm_auth@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +SUBDIRS = reference +all: all-recursive + +.SUFFIXES: +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign docs/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign docs/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs + +# This directory's subdirectories are mostly independent; you can cd +# into them and run 'make' without going through this Makefile. +# To change the values of 'make' variables: instead of editing Makefiles, +# (1) if the variable is set in 'config.status', edit 'config.status' +# (which will cause the Makefiles to be regenerated when you run 'make'); +# (2) otherwise, pass the desired values on the 'make' command line. +$(am__recursive_targets): + @fail=; \ + if $(am__make_keepgoing); then \ + failcom='fail=yes'; \ + else \ + failcom='exit 1'; \ + fi; \ + dot_seen=no; \ + target=`echo $@ | sed s/-recursive//`; \ + case "$@" in \ + distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \ + *) list='$(SUBDIRS)' ;; \ + esac; \ + for subdir in $$list; do \ + echo "Making $$target in $$subdir"; \ + if test "$$subdir" = "."; then \ + dot_seen=yes; \ + local_target="$$target-am"; \ + else \ + local_target="$$target"; \ + fi; \ + ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ + || eval $$failcom; \ + done; \ + if test "$$dot_seen" = "no"; then \ + $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \ + fi; test -z "$$fail" + +ID: $(am__tagged_files) + $(am__define_uniq_tagged_files); mkid -fID $$unique +tags: tags-recursive +TAGS: tags + +tags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files) + set x; \ + here=`pwd`; \ + if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \ + include_option=--etags-include; \ + empty_fix=.; \ + else \ + include_option=--include; \ + empty_fix=; \ + fi; \ + list='$(SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" = .; then :; else \ + test ! -f $$subdir/TAGS || \ + set "$$@" "$$include_option=$$here/$$subdir/TAGS"; \ + fi; \ + done; \ + $(am__define_uniq_tagged_files); \ + shift; \ + if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \ + test -n "$$unique" || unique=$$empty_fix; \ + if test $$# -gt 0; then \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + "$$@" $$unique; \ + else \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + $$unique; \ + fi; \ + fi +ctags: ctags-recursive + +CTAGS: ctags +ctags-am: $(TAGS_DEPENDENCIES) $(am__tagged_files) + $(am__define_uniq_tagged_files); \ + test -z "$(CTAGS_ARGS)$$unique" \ + || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \ + $$unique + +GTAGS: + here=`$(am__cd) $(top_builddir) && pwd` \ + && $(am__cd) $(top_srcdir) \ + && gtags -i $(GTAGS_ARGS) "$$here" +cscopelist: cscopelist-recursive + +cscopelist-am: $(am__tagged_files) + list='$(am__tagged_files)'; \ + case "$(srcdir)" in \ + [\\/]* | ?:[\\/]*) sdir="$(srcdir)" ;; \ + *) sdir=$(subdir)/$(srcdir) ;; \ + esac; \ + for i in $$list; do \ + if test -f "$$i"; then \ + echo "$(subdir)/$$i"; \ + else \ + echo "$$sdir/$$i"; \ + fi; \ + done >> $(top_builddir)/cscope.files + +distclean-tags: + -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + @list='$(DIST_SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" = .; then :; else \ + $(am__make_dryrun) \ + || test -d "$(distdir)/$$subdir" \ + || $(MKDIR_P) "$(distdir)/$$subdir" \ + || exit 1; \ + dir1=$$subdir; dir2="$(distdir)/$$subdir"; \ + $(am__relativize); \ + new_distdir=$$reldir; \ + dir1=$$subdir; dir2="$(top_distdir)"; \ + $(am__relativize); \ + new_top_distdir=$$reldir; \ + echo " (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) top_distdir="$$new_top_distdir" distdir="$$new_distdir" \\"; \ + echo " am__remove_distdir=: am__skip_length_check=: am__skip_mode_fix=: distdir)"; \ + ($(am__cd) $$subdir && \ + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$$new_top_distdir" \ + distdir="$$new_distdir" \ + am__remove_distdir=: \ + am__skip_length_check=: \ + am__skip_mode_fix=: \ + distdir) \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-recursive +all-am: Makefile +installdirs: installdirs-recursive +installdirs-am: +install: install-recursive +install-exec: install-exec-recursive +install-data: install-data-recursive +uninstall: uninstall-recursive + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-recursive +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-recursive + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-recursive + -rm -f Makefile +distclean-am: clean-am distclean-generic distclean-tags + +dvi: dvi-recursive + +dvi-am: + +html: html-recursive + +html-am: + +info: info-recursive + +info-am: + +install-data-am: + +install-dvi: install-dvi-recursive + +install-dvi-am: + +install-exec-am: + +install-html: install-html-recursive + +install-html-am: + +install-info: install-info-recursive + +install-info-am: + +install-man: + +install-pdf: install-pdf-recursive + +install-pdf-am: + +install-ps: install-ps-recursive + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-recursive + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-recursive + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-recursive + +pdf-am: + +ps: ps-recursive + +ps-am: + +uninstall-am: + +.MAKE: $(am__recursive_targets) install-am install-strip + +.PHONY: $(am__recursive_targets) CTAGS GTAGS TAGS all all-am check \ + check-am clean clean-generic clean-libtool cscopelist-am ctags \ + ctags-am distclean distclean-generic distclean-libtool \ + distclean-tags distdir dvi dvi-am html html-am info info-am \ + install install-am install-data install-data-am install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + installdirs-am maintainer-clean maintainer-clean-generic \ + mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \ + ps ps-am tags tags-am uninstall uninstall-am + + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index d36977ec..d47693a1 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -29,7 +29,7 @@ HFILE_GLOB= CFILE_GLOB= # Header files to ignore when scanning. -IGNORE_HFILES= soup.h soup-marshal.h soup-enum-types.h \ +IGNORE_HFILES= soup.h soup-enum-types.h \ soup-message-private.h soup-session-private.h \ soup-auth-basic.h soup-auth-digest.h soup-auth-ntlm.h \ soup-connection.h soup-connection-auth.h \ @@ -43,7 +43,9 @@ IGNORE_HFILES= soup.h soup-marshal.h soup-enum-types.h \ soup-content-sniffer-stream.h soup-io-stream.h \ soup-cache-input-stream.h soup-filter-input-stream.h \ soup-cookie-jar-sqlite.h soup-requester.h soup-tld-private.h \ - soup-misc-private.h + soup-misc-private.h soup-proxy-uri-resolver.h \ + soup-proxy-resolver-wrapper.h soup-proxy-uri-resolver.h \ + soup-cache-private.h # Images to copy into HTML directory. HTML_IMAGES = @@ -52,6 +54,7 @@ HTML_IMAGES = content_files = \ build-howto.xml \ client-howto.xml \ + request-howto.xml \ server-howto.xml \ session-porting.xml diff --git a/docs/reference/Makefile.in b/docs/reference/Makefile.in new file mode 100644 index 00000000..dc68e8f4 --- /dev/null +++ b/docs/reference/Makefile.in @@ -0,0 +1,873 @@ +# Makefile.in generated by automake 1.13.4 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2013 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# -*- mode: makefile -*- + +#################################### +# Everything below here is generic # +#################################### +VPATH = @srcdir@ +am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)' +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +DIST_COMMON = $(top_srcdir)/gtk-doc.make $(srcdir)/Makefile.in \ + $(srcdir)/Makefile.am +subdir = docs/reference +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/glibtests.m4 \ + $(top_srcdir)/m4/gtk-doc.m4 $(top_srcdir)/m4/intltool.m4 \ + $(top_srcdir)/m4/introspection.m4 $(top_srcdir)/m4/libtool.m4 \ + $(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \ + $(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +SOURCES = +DIST_SOURCES = +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +ALL_LINGUAS = @ALL_LINGUAS@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +APACHE_HTTPD = @APACHE_HTTPD@ +APACHE_MODULE_DIR = @APACHE_MODULE_DIR@ +APACHE_PHP_MODULE = @APACHE_PHP_MODULE@ +APACHE_PHP_MODULE_DIR = @APACHE_PHP_MODULE_DIR@ +APACHE_SSL_MODULE_DIR = @APACHE_SSL_MODULE_DIR@ +AR = @AR@ +AS = @AS@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CURL = @CURL@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +GETTEXT_PACKAGE = @GETTEXT_PACKAGE@ +GLIB_CFLAGS = @GLIB_CFLAGS@ +GLIB_COMPILE_RESOURCES = @GLIB_COMPILE_RESOURCES@ +GLIB_GENMARSHAL = @GLIB_GENMARSHAL@ +GLIB_LIBS = @GLIB_LIBS@ +GLIB_MAKEFILE = @GLIB_MAKEFILE@ +GLIB_MKENUMS = @GLIB_MKENUMS@ +GMSGFMT = @GMSGFMT@ +GOBJECT_QUERY = @GOBJECT_QUERY@ +GREP = @GREP@ +GTKDOC_CHECK = @GTKDOC_CHECK@ +GTKDOC_CHECK_PATH = @GTKDOC_CHECK_PATH@ +GTKDOC_DEPS_CFLAGS = @GTKDOC_DEPS_CFLAGS@ +GTKDOC_DEPS_LIBS = @GTKDOC_DEPS_LIBS@ +GTKDOC_MKPDF = @GTKDOC_MKPDF@ +GTKDOC_REBASE = @GTKDOC_REBASE@ +HAVE_GNOME = @HAVE_GNOME@ +HTML_DIR = @HTML_DIR@ +IF_HAVE_PHP = @IF_HAVE_PHP@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +INTLTOOL_EXTRACT = @INTLTOOL_EXTRACT@ +INTLTOOL_MERGE = @INTLTOOL_MERGE@ +INTLTOOL_PERL = @INTLTOOL_PERL@ +INTLTOOL_UPDATE = @INTLTOOL_UPDATE@ +INTLTOOL_V_MERGE = @INTLTOOL_V_MERGE@ +INTLTOOL_V_MERGE_OPTIONS = @INTLTOOL_V_MERGE_OPTIONS@ +INTLTOOL__v_MERGE_ = @INTLTOOL__v_MERGE_@ +INTLTOOL__v_MERGE_0 = @INTLTOOL__v_MERGE_0@ +INTROSPECTION_CFLAGS = @INTROSPECTION_CFLAGS@ +INTROSPECTION_COMPILER = @INTROSPECTION_COMPILER@ +INTROSPECTION_GENERATE = @INTROSPECTION_GENERATE@ +INTROSPECTION_GIRDIR = @INTROSPECTION_GIRDIR@ +INTROSPECTION_LIBS = @INTROSPECTION_LIBS@ +INTROSPECTION_MAKEFILE = @INTROSPECTION_MAKEFILE@ +INTROSPECTION_SCANNER = @INTROSPECTION_SCANNER@ +INTROSPECTION_TYPELIBDIR = @INTROSPECTION_TYPELIBDIR@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MKDIR_P = @MKDIR_P@ +MSGFMT = @MSGFMT@ +MSGMERGE = @MSGMERGE@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PHP = @PHP@ +PKG_CONFIG = @PKG_CONFIG@ +PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ +PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SOUP_AGE = @SOUP_AGE@ +SOUP_API_VERSION = @SOUP_API_VERSION@ +SOUP_CURRENT = @SOUP_CURRENT@ +SOUP_DEBUG_FLAGS = @SOUP_DEBUG_FLAGS@ +SOUP_MAJOR_VERSION = @SOUP_MAJOR_VERSION@ +SOUP_MICRO_VERSION = @SOUP_MICRO_VERSION@ +SOUP_MINOR_VERSION = @SOUP_MINOR_VERSION@ +SOUP_REVISION = @SOUP_REVISION@ +SQLITE_CFLAGS = @SQLITE_CFLAGS@ +SQLITE_LIBS = @SQLITE_LIBS@ +STRIP = @STRIP@ +USE_NLS = @USE_NLS@ +VERSION = @VERSION@ +XGETTEXT = @XGETTEXT@ +XML_CFLAGS = @XML_CFLAGS@ +XML_LIBS = @XML_LIBS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +installed_test_metadir = @installed_test_metadir@ +installed_testdir = @installed_testdir@ +intltool__v_merge_options_ = @intltool__v_merge_options_@ +intltool__v_merge_options_0 = @intltool__v_merge_options_0@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +ntlm_auth = @ntlm_auth@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +AUTOMAKE_OPTIONS = 1.6 + +# The name of the module +DOC_MODULE = libsoup-2.4 + +# The top-level SGML file. +DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.sgml + +# The directory containing the source code. Relative to $(srcdir). +# gtk-doc will search all .c & .h files beneath here for inline comments +# documenting functions and macros. +DOC_SOURCE_DIR = ../../libsoup + +# Extra options to supply to gtkdoc-scan. +SCAN_OPTIONS = --deprecated-guards=SOUP_DISABLE_DEPRECATED --rebuild-types --ignore-decorators='SOUP_DEPRECATED\w*\s*\([^)]*\)|SOUP_DEPRECATED\w*|SOUP_AVAILABLE\w*' + +# Extra options to supply to gtkdoc-scangobj. +SCANGOBJ_OPTIONS = + +# Extra options to supply to gtkdoc-mkdb. +MKDB_OPTIONS = --sgml-mode --output-format=xml + +# Extra options to supply to gtkdoc-fixref. +FIXXREF_OPTIONS = + +# Used for dependencies. +HFILE_GLOB = +CFILE_GLOB = + +# Header files to ignore when scanning. +IGNORE_HFILES = soup.h soup-enum-types.h \ + soup-message-private.h soup-session-private.h \ + soup-auth-basic.h soup-auth-digest.h soup-auth-ntlm.h \ + soup-connection.h soup-connection-auth.h \ + soup-message-queue.h soup-path-map.h soup-gnome-features.h \ + soup-proxy-resolver.h soup-proxy-resolver-gnome.h \ + soup-proxy-resolver-static.h soup-directory-input-stream.h \ + soup-http-input-stream.h soup-password-manager.h \ + soup-password-manager-gnome.h soup-converter-wrapper.h \ + soup-body-input-stream.h soup-body-output-stream.h \ + soup-client-input-stream.h soup-content-processor.h \ + soup-content-sniffer-stream.h soup-io-stream.h \ + soup-cache-input-stream.h soup-filter-input-stream.h \ + soup-cookie-jar-sqlite.h soup-requester.h soup-tld-private.h \ + soup-misc-private.h soup-proxy-uri-resolver.h \ + soup-proxy-resolver-wrapper.h soup-proxy-uri-resolver.h \ + soup-cache-private.h + + +# Images to copy into HTML directory. +HTML_IMAGES = + +# Extra XML files that are included by $(DOC_MAIN_SGML_FILE). +content_files = \ + build-howto.xml \ + client-howto.xml \ + request-howto.xml \ + server-howto.xml \ + session-porting.xml + + +# Other files to distribute. +extra_files = + +# CFLAGS and LDFLAGS for compiling scan program. Only needed +# if $(DOC_MODULE).types is non-empty. +GTKDOC_CFLAGS = \ + -I$(top_srcdir) \ + -I$(top_builddir) \ + $(GLIB_CFLAGS) \ + $(XML_CFLAGS) \ + $(GNUTLS_CFLAGS) + +GTKDOC_LIBS = \ + $(top_builddir)/libsoup/libsoup-2.4.la \ + $(GLIB_LIBS) + +@GTK_DOC_USE_LIBTOOL_FALSE@GTKDOC_CC = $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +@GTK_DOC_USE_LIBTOOL_TRUE@GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +@GTK_DOC_USE_LIBTOOL_FALSE@GTKDOC_LD = $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) +@GTK_DOC_USE_LIBTOOL_TRUE@GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) +@GTK_DOC_USE_LIBTOOL_FALSE@GTKDOC_RUN = +@GTK_DOC_USE_LIBTOOL_TRUE@GTKDOC_RUN = $(LIBTOOL) --mode=execute + +# We set GPATH here; this gives us semantics for GNU make +# which are more like other make's VPATH, when it comes to +# whether a source that is a target of one rule is then +# searched for in VPATH/GPATH. +# +GPATH = $(srcdir) +TARGET_DIR = $(HTML_DIR)/$(DOC_MODULE) +SETUP_FILES = \ + $(content_files) \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE)-sections.txt \ + $(DOC_MODULE)-overrides.txt + +EXTRA_DIST = \ + $(HTML_IMAGES) \ + $(SETUP_FILES) + +DOC_STAMPS = setup-build.stamp scan-build.stamp tmpl-build.stamp sgml-build.stamp \ + html-build.stamp pdf-build.stamp \ + tmpl.stamp sgml.stamp html.stamp pdf.stamp + +SCANOBJ_FILES = \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).interfaces \ + $(DOC_MODULE).prerequisites \ + $(DOC_MODULE).signals + +REPORT_FILES = \ + $(DOC_MODULE)-undocumented.txt \ + $(DOC_MODULE)-undeclared.txt \ + $(DOC_MODULE)-unused.txt + +CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) gtkdoc-check.test +@GTK_DOC_BUILD_HTML_FALSE@HTML_BUILD_STAMP = +@GTK_DOC_BUILD_HTML_TRUE@HTML_BUILD_STAMP = html-build.stamp +@GTK_DOC_BUILD_PDF_FALSE@PDF_BUILD_STAMP = +@GTK_DOC_BUILD_PDF_TRUE@PDF_BUILD_STAMP = pdf-build.stamp + +#### setup #### +GTK_DOC_V_SETUP = $(GTK_DOC_V_SETUP_$(V)) +GTK_DOC_V_SETUP_ = $(GTK_DOC_V_SETUP_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_SETUP_0 = @echo " DOC Preparing build"; + +#### scan #### +GTK_DOC_V_SCAN = $(GTK_DOC_V_SCAN_$(V)) +GTK_DOC_V_SCAN_ = $(GTK_DOC_V_SCAN_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_SCAN_0 = @echo " DOC Scanning header files"; +GTK_DOC_V_INTROSPECT = $(GTK_DOC_V_INTROSPECT_$(V)) +GTK_DOC_V_INTROSPECT_ = $(GTK_DOC_V_INTROSPECT_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_INTROSPECT_0 = @echo " DOC Introspecting gobjects"; + +#### templates #### +GTK_DOC_V_TMPL = $(GTK_DOC_V_TMPL_$(V)) +GTK_DOC_V_TMPL_ = $(GTK_DOC_V_TMPL_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_TMPL_0 = @echo " DOC Rebuilding template files"; + +#### xml #### +GTK_DOC_V_XML = $(GTK_DOC_V_XML_$(V)) +GTK_DOC_V_XML_ = $(GTK_DOC_V_XML_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_XML_0 = @echo " DOC Building XML"; + +#### html #### +GTK_DOC_V_HTML = $(GTK_DOC_V_HTML_$(V)) +GTK_DOC_V_HTML_ = $(GTK_DOC_V_HTML_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_HTML_0 = @echo " DOC Building HTML"; +GTK_DOC_V_XREF = $(GTK_DOC_V_XREF_$(V)) +GTK_DOC_V_XREF_ = $(GTK_DOC_V_XREF_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_XREF_0 = @echo " DOC Fixing cross-references"; + +#### pdf #### +GTK_DOC_V_PDF = $(GTK_DOC_V_PDF_$(V)) +GTK_DOC_V_PDF_ = $(GTK_DOC_V_PDF_$(AM_DEFAULT_VERBOSITY)) +GTK_DOC_V_PDF_0 = @echo " DOC Building PDF"; +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(top_srcdir)/gtk-doc.make $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign docs/reference/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign docs/reference/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; +$(top_srcdir)/gtk-doc.make: + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +tags TAGS: + +ctags CTAGS: + +cscope cscopelist: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-hook +check-am: all-am +check: check-am +@ENABLE_GTK_DOC_FALSE@all-local: +all-am: Makefile all-local +installdirs: +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean-am: clean-generic clean-libtool clean-local mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic distclean-local + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: install-data-local + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic \ + maintainer-clean-local + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-local + +.MAKE: install-am install-strip + +.PHONY: all all-am all-local check check-am clean clean-generic \ + clean-libtool clean-local cscopelist-am ctags-am dist-hook \ + distclean distclean-generic distclean-libtool distclean-local \ + distdir dvi dvi-am html html-am info info-am install \ + install-am install-data install-data-am install-data-local \ + install-dvi install-dvi-am install-exec install-exec-am \ + install-html install-html-am install-info install-info-am \ + install-man install-pdf install-pdf-am install-ps \ + install-ps-am install-strip installcheck installcheck-am \ + installdirs maintainer-clean maintainer-clean-generic \ + maintainer-clean-local mostlyclean mostlyclean-generic \ + mostlyclean-libtool pdf pdf-am ps ps-am tags-am uninstall \ + uninstall-am uninstall-local + + +gtkdoc-check.test: Makefile + $(AM_V_GEN)echo "#!/bin/sh -e" > $@; \ + echo "$(GTKDOC_CHECK_PATH) || exit 1" >> $@; \ + chmod +x $@ + +all-gtk-doc: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) +.PHONY: all-gtk-doc + +@ENABLE_GTK_DOC_TRUE@all-local: all-gtk-doc + +docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) + +$(REPORT_FILES): sgml-build.stamp + +setup-build.stamp: + -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ + files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ + if test "x$$files" != "x" ; then \ + for file in $$files ; do \ + destdir=`dirname $(abs_builddir)/$$file` ;\ + test -d "$$destdir" || mkdir -p "$$destdir"; \ + test -f $(abs_srcdir)/$$file && \ + cp -pf $(abs_srcdir)/$$file $(abs_builddir)/$$file || true; \ + done; \ + fi; \ + test -d $(abs_srcdir)/tmpl && \ + { cp -pR $(abs_srcdir)/tmpl $(abs_builddir)/; \ + chmod -R u+w $(abs_builddir)/tmpl; } \ + fi + $(AM_V_at)touch setup-build.stamp + +scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) + $(GTK_DOC_V_SCAN)_source_dir='' ; \ + for i in $(DOC_SOURCE_DIR) ; do \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ + done ; \ + gtkdoc-scan --module=$(DOC_MODULE) --ignore-headers="$(IGNORE_HFILES)" $${_source_dir} $(SCAN_OPTIONS) $(EXTRA_HFILES) + $(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ + scanobj_options=""; \ + gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \ + if test "$(?)" = "0"; then \ + if test "x$(V)" = "x1"; then \ + scanobj_options="--verbose"; \ + fi; \ + fi; \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" \ + gtkdoc-scangobj $(SCANGOBJ_OPTIONS) $$scanobj_options --module=$(DOC_MODULE); \ + else \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ + fi + $(AM_V_at)touch scan-build.stamp + +$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp + @true + +tmpl-build.stamp: setup-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt + $(GTK_DOC_V_TMPL)gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS) + $(AM_V_at)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ + if test -w $(abs_srcdir) ; then \ + cp -pR $(abs_builddir)/tmpl $(abs_srcdir)/; \ + fi \ + fi + $(AM_V_at)touch tmpl-build.stamp + +tmpl.stamp: tmpl-build.stamp + @true + +$(srcdir)/tmpl/*.sgml: + @true + +sgml-build.stamp: tmpl.stamp $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files) + -$(GTK_DOC_V_XML)chmod -R u+w $(srcdir) && _source_dir='' ; \ + for i in $(DOC_SOURCE_DIR) ; do \ + _source_dir="$${_source_dir} --source-dir=$$i" ; \ + done ; \ + gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $${_source_dir} $(MKDB_OPTIONS) + $(AM_V_at)touch sgml-build.stamp + +sgml.stamp: sgml-build.stamp + @true + +html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) + $(GTK_DOC_V_HTML)rm -rf html && mkdir html && \ + mkhtml_options=""; \ + gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-verbose"; \ + if test "$(?)" = "0"; then \ + if test "x$(V)" = "x1"; then \ + mkhtml_options="$$mkhtml_options --verbose"; \ + fi; \ + fi; \ + gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-path"; \ + if test "$(?)" = "0"; then \ + mkhtml_options="$$mkhtml_options --path=\"$(abs_srcdir)\""; \ + fi; \ + cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + -@test "x$(HTML_IMAGES)" = "x" || \ + for file in $(HTML_IMAGES) ; do \ + if test -f $(abs_srcdir)/$$file ; then \ + cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ + fi; \ + if test -f $(abs_builddir)/$$file ; then \ + cp $(abs_builddir)/$$file $(abs_builddir)/html; \ + fi; \ + done; + $(GTK_DOC_V_XREF)gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) + $(AM_V_at)touch html-build.stamp + +pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) + $(GTK_DOC_V_PDF)rm -f $(DOC_MODULE).pdf && \ + mkpdf_options=""; \ + gtkdoc-mkpdf 2>&1 --help | grep >/dev/null "\-\-verbose"; \ + if test "$(?)" = "0"; then \ + if test "x$(V)" = "x1"; then \ + mkpdf_options="$$mkpdf_options --verbose"; \ + fi; \ + fi; \ + if test "x$(HTML_IMAGES)" != "x"; then \ + for img in $(HTML_IMAGES); do \ + part=`dirname $$img`; \ + echo $$mkpdf_options | grep >/dev/null "\-\-imgdir=$$part "; \ + if test $$? != 0; then \ + mkpdf_options="$$mkpdf_options --imgdir=$$part"; \ + fi; \ + done; \ + fi; \ + gtkdoc-mkpdf --path="$(abs_srcdir)" $$mkpdf_options $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) + $(AM_V_at)touch pdf-build.stamp + +############## + +clean-local: + @rm -f *~ *.bak + @rm -rf .libs + @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \ + rm -f $(DOC_MODULE).types; \ + fi + +distclean-local: + @rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \ + $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt + @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ + rm -f $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types; \ + rm -rf tmpl; \ + fi + +maintainer-clean-local: + @rm -rf xml html + +install-data-local: + @installfiles=`echo $(builddir)/html/*`; \ + if test "$$installfiles" = '$(builddir)/html/*'; \ + then echo 1>&2 'Nothing to install' ; \ + else \ + if test -n "$(DOC_MODULE_VERSION)"; then \ + installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ + else \ + installdir="$(DESTDIR)$(TARGET_DIR)"; \ + fi; \ + $(mkinstalldirs) $${installdir} ; \ + for i in $$installfiles; do \ + echo ' $(INSTALL_DATA) '$$i ; \ + $(INSTALL_DATA) $$i $${installdir}; \ + done; \ + if test -n "$(DOC_MODULE_VERSION)"; then \ + mv -f $${installdir}/$(DOC_MODULE).devhelp2 \ + $${installdir}/$(DOC_MODULE)-$(DOC_MODULE_VERSION).devhelp2; \ + fi; \ + $(GTKDOC_REBASE) --relative --dest-dir=$(DESTDIR) --html-dir=$${installdir}; \ + fi + +uninstall-local: + @if test -n "$(DOC_MODULE_VERSION)"; then \ + installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ + else \ + installdir="$(DESTDIR)$(TARGET_DIR)"; \ + fi; \ + rm -rf $${installdir} + +# +# Require gtk-doc when making dist +# +@HAVE_GTK_DOC_TRUE@dist-check-gtkdoc: docs +@HAVE_GTK_DOC_FALSE@dist-check-gtkdoc: +@HAVE_GTK_DOC_FALSE@ @echo "*** gtk-doc is needed to run 'make dist'. ***" +@HAVE_GTK_DOC_FALSE@ @echo "*** gtk-doc was not found when 'configure' ran. ***" +@HAVE_GTK_DOC_FALSE@ @echo "*** please install gtk-doc and rerun 'configure'. ***" +@HAVE_GTK_DOC_FALSE@ @false + +dist-hook: dist-check-gtkdoc all-gtk-doc dist-hook-local + @mkdir $(distdir)/tmpl + @mkdir $(distdir)/html + @-cp ./tmpl/*.sgml $(distdir)/tmpl + @cp ./html/* $(distdir)/html + @-cp ./$(DOC_MODULE).pdf $(distdir)/ + @-cp ./$(DOC_MODULE).types $(distdir)/ + @-cp ./$(DOC_MODULE)-sections.txt $(distdir)/ + @cd $(distdir) && rm -f $(DISTCLEANFILES) + @$(GTKDOC_REBASE) --online --relative --html-dir=$(distdir)/html + +.PHONY : dist-hook-local docs + +# include common portion ... + +# kludges +$(srcdir)/tmpl/*.sgml: + +clean: clean-am + rm -rf tmpl + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/docs/reference/client-howto.xml b/docs/reference/client-howto.xml index 3cf5a4e1..e694cb72 100644 --- a/docs/reference/client-howto.xml +++ b/docs/reference/client-howto.xml @@ -3,16 +3,26 @@ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> <refentry id="libsoup-client-howto"> <refmeta> -<refentrytitle>Soup Client Basics</refentrytitle> +<refentrytitle>libsoup Client Basics</refentrytitle> <manvolnum>3</manvolnum> <refmiscinfo>LIBSOUP Library</refmiscinfo> </refmeta> <refnamediv> -<refname>Soup Client Basics</refname><refpurpose>Client-side tutorial</refpurpose> +<refname>libsoup Client Basics</refname><refpurpose>Client-side tutorial</refpurpose> </refnamediv> <refsect2> +<para> +This section explains how to use <application>libsoup</application> as +an HTTP client using several new APIs introduced in version 2.42. If +you want to be compatible with older versions of +<application>libsoup</application>, consult the documentation for that +version. +</para> +</refsect2> + +<refsect2> <title>Creating a <type>SoupSession</type></title> <para> @@ -24,35 +34,8 @@ authentication information, etc. </para> <para> -There are two subclasses of <link -linkend="SoupSession"><type>SoupSession</type></link> that you can use, with -slightly different behavior: -</para> - -<itemizedlist> - <listitem><para> - <link linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>, - which uses callbacks and the glib main loop to provide - asynchronous I/O. - </para></listitem> - - <listitem><para> - <link linkend="SoupSessionSync"><type>SoupSessionSync</type></link>, - which uses blocking I/O rather than callbacks, making it more - suitable for threaded applications. - </para></listitem> -</itemizedlist> - -<para> -If you want to do a mix of mainloop-based and blocking I/O, you will -need to create two different session objects. -</para> - -<para> -When you create the session (with <link -linkend="soup-session-async-new-with-options"><function>soup_session_async_new_with_options</function></link> -or <link -linkend="soup-session-sync-new-with-options"><function>soup_session_sync_new_with_options</function></link>), +When you create the session with <link +linkend="soup-session-new-with-options"><function>soup_session_new_with_options</function></link>, you can specify various additional options: </para> @@ -64,7 +47,7 @@ you can specify various additional options: the session will have open at one time. (Once it reaches this limit, it will either close idle connections, or wait for existing connections to free up before starting - new requests.) + new requests.) The default value is 10. </para></listitem> </varlistentry> <varlistentry> @@ -72,44 +55,61 @@ you can specify various additional options: <listitem><para> Allows you to set the maximum total number of connections the session will have open <emphasis>to a single - host</emphasis> at one time. + host</emphasis> at one time. The default value is 2. </para></listitem> </varlistentry> <varlistentry> - <term><link linkend="SOUP-SESSION-USE-NTLM:CAPS"><literal>SOUP_SESSION_USE_NTLM</literal></link></term> + <term><link linkend="SOUP-SESSION-USER-AGENT:CAPS"><literal>SOUP_SESSION_USER_AGENT</literal></link></term> <listitem><para> - If <literal>TRUE</literal>, then Microsoft NTLM - authentication will be used if available (and will be - preferred to HTTP Basic or Digest authentication). - If <literal>FALSE</literal>, NTLM authentication won't be - used, even if it's the only authentication type available. - (NTLM works differently from the standard HTTP - authentication types, so it needs to be handled - specially.) + Allows you to set a User-Agent string that will be sent + on all outgoing requests. </para></listitem> </varlistentry> <varlistentry> - <term><link linkend="SOUP-SESSION-SSL-CA-FILE:CAPS"><literal>SOUP_SESSION_SSL_CA_FILE</literal></link></term> + <term><link linkend="SOUP-SESSION-ACCEPT-LANGUAGE:CAPS"><literal>SOUP_SESSION_ACCEPT_LANGUAGE</literal></link> + and <link linkend="SOUP-SESSION-ACCEPT-LANGUAGE-AUTO:CAPS"><literal>SOUP_SESSION_ACCEPT_LANGUAGE_AUTO</literal></link></term> <listitem><para> - Points to a file containing certificates for recognized - SSL Certificate Authorities. If this is set, then HTTPS - connections will be checked against these authorities, and - rejected if they can't be verified. (Otherwise all SSL - certificates will be accepted automatically.) + Allow you to set an Accept-Language header on all outgoing + requests. <literal>SOUP_SESSION_ACCEPT_LANGUAGE</literal> + takes a list of language tags to use, while + <literal>SOUP_SESSION_ACCEPT_LANGUAGE_AUTO</literal> + automatically generates the list from the user's locale + settings. </para></listitem> </varlistentry> <varlistentry> - <term><link linkend="SOUP-SESSION-ASYNC-CONTEXT:CAPS"><literal>SOUP_SESSION_ASYNC_CONTEXT</literal></link></term> + <term><link linkend="SOUP-SESSION-HTTP-ALIASES:CAPS"><literal>SOUP_SESSION_HTTP_ALIASES</literal></link> + and <link linkend="SOUP-SESSION-HTTPS-ALIASES:CAPS"><literal>SOUP_SESSION_HTTPS_ALIASES</literal></link></term> <listitem><para> - A <link - linkend="GMainContext"><type>GMainContext</type></link> - which the session will use for asynchronous operations. - This can be set if you want to use a - <type>SoupSessionAsync</type> in a thread other than the - main thread. + Allow you to tell the session to recognize additional URI + schemes as aliases for "<literal>http</literal>" or + <literal>https</literal>. You can set this if you are + using URIs with schemes like "<literal>dav</literal>" or + "<literal>webcal</literal>" (and in particular, you need + to set this if the server you are talking to might return + redirects with such a scheme). </para></listitem> </varlistentry> <varlistentry> + <term><link linkend="SOUP-SESSION-PROXY-RESOLVER:CAPS"><literal>SOUP_SESSION_PROXY_RESOLVER</literal></link> and <link linkend="SOUP-SESSION-PROXY-URI:CAPS"><literal>SOUP_SESSION_PROXY_URI</literal></link></term> + <listitem> + <para> + <link linkend="SOUP-SESSION-PROXY-RESOLVER:CAPS"><literal>SOUP_SESSION_PROXY_RESOLVER</literal></link> + specifies a <link + linkend="GProxyResolver"><type>GProxyResolver</type></link> + to use to determine the HTTP proxies to use. By default, + this is set to the resolver returned by <link + linkend="g-proxy-resolver-get-default"><function>g_proxy_resolver_get_default</function></link>, + so you do not need to set it yourself. + </para> + <para> + Alternatively, if you want all requests to go through a + single proxy, you can set <link + linkend="SOUP-SESSION-PROXY-URI:CAPS"><literal>SOUP_SESSION_PROXY_URI</literal></link>. + </para> + </listitem> + </varlistentry> + <varlistentry> <term><link linkend="SOUP-SESSION-ADD-FEATURE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE</literal></link> and <link linkend="SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS"><literal>SOUP_SESSION_ADD_FEATURE_BY_TYPE</literal></link></term> <listitem><para> These allow you to specify <link @@ -121,10 +121,15 @@ you can specify various additional options: </variablelist> <para> +Other properties are also available; see the <link +linkend="SoupSession"><type>SoupSession</type></link> documentation for +more details. +</para> + +<para> If you don't need to specify any options, you can just use <link -linkend="soup-session-async-new"><function>soup_session_async_new</function></link> or -<link linkend="soup-session-sync-new"><function>soup_session_sync_new</function></link>, -which take no arguments. +linkend="soup-session-new"><function>soup_session_new</function></link>, +which takes no arguments. </para> </refsect2> @@ -143,8 +148,19 @@ options at session-construction-time, or afterward via the <link linkend="soup-session-add-feature"><function>soup_session_add_feature</function></link> and <link linkend="soup-session-add-feature-by-type"><function>soup_session_add_feature_by_type</function></link> -functions. Some of the features available in -<application>libsoup</application> are: +functions. +</para> + +<para> +A <link +linkend="SoupContentDecoder"><type>SoupContentDecoder</type></link> is +added for you automatically. This advertises to servers that the +client supports compression, and automatically decompresses compressed +responses. +</para> + +<para> +Some other available features that you can add include: </para> <variablelist> @@ -156,26 +172,27 @@ functions. Some of the features available in </para></listitem> </varlistentry> <varlistentry> - <term><link linkend="SoupCookieJar"><type>SoupCookieJar</type></link> and <link linkend="SoupCookieJarText"><type>SoupCookieJarText</type></link></term> + <term> + <link linkend="SoupCookieJar"><type>SoupCookieJar</type></link>, + <link linkend="SoupCookieJarText"><type>SoupCookieJarText</type></link>, + and <link linkend="SoupCookieJarDB"><type>SoupCookieJarDB</type></link> + </term> <listitem><para> Support for HTTP cookies. <type>SoupCookieJar</type> provides non-persistent cookie storage, while <type>SoupCookieJarText</type> uses a text file to keep - track of cookies between sessions. - </para></listitem> - </varlistentry> - <varlistentry> - <term><link linkend="SoupProxyResolverDefault"><type>SoupProxyResolverDefault</type></link></term> - <listitem><para> - A feature that automatically determines the correct HTTP - proxy to use for requests. + track of cookies between sessions, and + <type>SoupCookieJarDB</type> uses a + <application>SQLite</application> database. </para></listitem> </varlistentry> <varlistentry> - <term><link linkend="SoupCookieJarDB"><type>SoupCookieJarDB</type></link></term> + <term><link linkend="SoupContentSniffer"><type>SoupContentSniffer</type></link></term> <listitem><para> - Support for HTTP cookies stored in an - <application>SQLite</application> database. + Uses the HTML5 sniffing rules to attempt to + determine the Content-Type of a response when the + server does not identify the Content-Type, or appears to + have provided an incorrect one. </para></listitem> </varlistentry> </variablelist> @@ -183,7 +200,7 @@ functions. Some of the features available in <para> Use the "add_feature_by_type" property/function to add features that don't require any configuration (such as <link -linkend="SoupProxyResolverDefault"><type>SoupProxyResolverDefault</type></link>), +linkend="SoupContentSniffer"><type>SoupContentSniffer</type></link>), and the "add_feature" property/function to add features that must be constructed first (such as <link linkend="SoupLogger"><type>SoupLogger</type></link>). For example, an @@ -191,11 +208,10 @@ application might do something like the following: </para> <informalexample><programlisting> - session = soup_session_async_new_with_options ( -#ifdef HAVE_LIBSOUP_GNOME - SOUP_SESSION_ADD_FEATURE_BY_TYPE, SOUP_TYPE_PROXY_RESOLVER_DEFAULT, -#endif + session = soup_session_new_with_options ( + SOUP_SESSION_ADD_FEATURE_BY_TYPE, SOUP_TYPE_CONTENT_SNIFFER, NULL); + if (debug_level) { SoupLogger *logger; @@ -211,7 +227,7 @@ application might do something like the following: <title>Creating and Sending SoupMessages</title> <para> -Once you have a session, you do HTTP traffic using <link +Once you have a session, you send HTTP requests using <link linkend="SoupMessage"><type>SoupMessage</type></link>. In the simplest case, you only need to create the message and it's ready to send: </para> @@ -235,7 +251,7 @@ request headers and body of the message: msg = soup_message_new ("POST", "http://example.com/form.cgi"); soup_message_set_request (msg, "application/x-www-form-urlencoded", - SOUP_MEMORY_COPY, formdata, strlen (formdata)); + SOUP_MEMORY_COPY, formdata, strlen (formdata)); soup_message_headers_append (msg->request_headers, "Referer", referring_url); </programlisting></informalexample> @@ -262,28 +278,56 @@ flag. <para> To send a message and wait for the response, use <link -linkend="soup-session-send-message"><function>soup_session_send_message</function></link>: +linkend="soup-session-send"><function>soup_session_send</function></link>: </para> <informalexample><programlisting> - guint status; + GInputStream *stream; + GError *error = NULL; - status = soup_session_send_message (session, msg); + stream = soup_session_send (session, msg, cancellable, &error); </programlisting></informalexample> <para> -(If you use <function>soup_session_send_message</function> with a -<link linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>, -it will run the main loop itself until the message is complete.) +At the point when <function>soup_session_send</function> returns, the +request will have been sent, and the response headers read back in; +you can examine the message's <structfield>status_code</structfield>, +<structfield>reason_phrase</structfield>, and +<structfield>response_headers</structfield> fields to see the response +metadata. To get the response body, read from the returned <link +linkend="GInputStream"><type>GInputStream</type></link>, and close it +when you are done. </para> <para> -The return value from <function>soup_session_send_message</function> -is a <link linkend="libsoup-2.4-soup-status">libsoup status code</link>, -indicating either a transport error that prevented the message from -being sent, or the HTTP status that was returned by the server in -response to the message. (The status is also available as -<literal>msg->status_code</literal>.) +Note that <function>soup_session_send</function> only returns an error +if a transport-level problem occurs (eg, it could not connect to the +host, or the request was cancelled). Use the message's +<structfield>status_code</structfield> field to determine whether the +request was successful or not at the HTTP level (ie, "<literal>200 +OK</literal>" vs "<literal>401 Bad Request</literal>"). +</para> + +<para> +If you would prefer to have <application>libsoup</application> gather +the response body for you and then return it all at once, you can use +the older +<link linkend="soup-session-send-message"><function>soup_session_send_message</function></link> +API: +</para> + +<informalexample><programlisting> + guint status; + + status = soup_session_send_message (session, msg); +</programlisting></informalexample> + +<para> +In this case, the response body will be available in the message's +<structfield>response_body</structfield> field, and transport-level +errors will be indicated in the <structfield>status_code</structfield> +field via special pseudo-HTTP-status codes like <link +linkend="SOUP-STATUS-CANT-CONNECT:CAPS"><literal>SOUP_STATUS_CANT_CONNECT</literal></link>. </para> </refsect3> @@ -293,51 +337,63 @@ response to the message. (The status is also available as <para> To send a message asynchronously, use <link -linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>: +linkend="soup-session-send-async"><function>soup_session_send_async</function></link>: </para> <informalexample><programlisting> +{ ... - soup_session_queue_message (session, msg, my_callback, my_callback_data); + soup_session_send_async (session, msg, cancellable, my_callback, my_callback_data); ... } static void -my_callback (SoupSession *session, SoupMessage *msg, gpointer user_data) +my_callback (GObject *object, GAsyncResult *result, gpointer user_data) { - /* Handle the response here */ + GInputStream *stream; + GError *error = NULL; + + stream = soup_session_send_finish (SOUP_SESSION (object), result, &error); + ... } </programlisting></informalexample> <para> The message will be added to the session's queue, and eventually (when control is returned back to the main loop), it will be sent and the -response be will be read. When the message is complete, -<literal>callback</literal> will be invoked, along with the data you -passed to <function>soup_session_queue_message</function>. +response be will be read. When the message has been sent, and its +headers received, the callback will be invoked, in the standard +<link linkend="GAsyncReadyCallback"><type>GAsyncReadyCallback</type></link> +style. </para> <para> -<link -linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link> -steals a reference to the message object, and unrefs it after the last -callback is invoked on it. So in the usual case, messages sent -asynchronously will be automatically freed for you without you needing -to do anything. (Of course, this wouldn't work when using the synchronous -API, since you will usually need continue working with the message -after calling <link -linkend="soup-session-send-message"><function>soup_session_send_message</function></link>, -so in that case, you must unref it explicitly when you are done with -it.) +As with synchronous sending, there is also an alternate API, <link +linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link>, +in which your callback is not invoked until the response has been +completely read: </para> +<informalexample><programlisting> +{ + ... + soup_session_queue_message (session, msg, my_callback, my_callback_data); + ... +} + +static void +my_callback (SoupSession *session, SoupMessage *msg, gpointer user_data) +{ + /* msg->response_body contains the response */ +} +</programlisting></informalexample> + <para> -(If you use <link +<link linkend="soup-session-queue-message"><function>soup_session_queue_message</function></link> -with a <link -linkend="SoupSessionSync"><type>SoupSessionSync</type></link>, the -message will be sent in another thread, with the callback eventually -being invoked in the session's <link linkend="SOUP-SESSION-ASYNC-CONTEXT:CAPS"><literal>SOUP_SESSION_ASYNC_CONTEXT</literal></link>.) +is slightly unusual in that it steals a reference to the message +object, and unrefs it after the last callback is invoked on it. So +when using this API, you should not unref the message yourself. </para> </refsect3> @@ -348,19 +404,17 @@ being invoked in the session's <link linkend="SOUP-SESSION-ASYNC-CONTEXT:CAPS">< <title>Processing the Response</title> <para> -Once you have received the response from the server, synchronously or -asynchronously, you can look at the response fields in the -<literal>SoupMessage</literal> to decide what to do next. The -<structfield>status_code</structfield> and +Once you have received the initial response from the server, +synchronously or asynchronously, streaming or not, you can look at the +response fields in the <literal>SoupMessage</literal> to decide what +to do next. The <structfield>status_code</structfield> and <structfield>reason_phrase</structfield> fields contain the numeric status and textual status response from the server. <structfield>response_headers</structfield> contains the response headers, which you can investigate using <link -linkend="soup-message-headers-get"><function>soup_message_headers_get</function></link> and -<link - linkend="soup-message-headers-foreach"><function>soup_message_headers_foreach</function></link>. -The response body (if any) is in the -<structfield>response_body</structfield> field. +linkend="soup-message-headers-get"><function>soup_message_headers_get</function></link> +and <link +linkend="soup-message-headers-foreach"><function>soup_message_headers_foreach</function></link>. </para> <para> @@ -383,41 +437,6 @@ headers much better than functions like </refsect2> <refsect2> -<title>Intermediate/Automatic Processing</title> - -<para> -You can also connect to various <type>SoupMessage</type> signals to do -processing at intermediate stages of HTTP I/O. Eg, the <link -linkend="SoupMessage-got-chunk"><literal>got-chunk</literal></link> -signal is emitted as each piece of the response body is read (allowing -you to provide progress information when receiving a large response, -for example). <type>SoupMessage</type> also provides two convenience -methods, <link -linkend="soup-message-add-header-handler"><function>soup_message_add_header_handler</function></link>, -and <link -linkend="soup-message-add-status-code-handler"><function>soup_message_add_status_code_handler</function></link>, -which allow you to set up a signal handler that will only be invoked -for messages with certain response headers or status codes. -<type>SoupSession</type> uses this internally to handle authentication -and redirection. -</para> - -<para> -When using the synchronous API, the callbacks and signal handlers will -be invoked during the call to <link -linkend="soup-session-send-message"><function>soup_session_send_message</function></link>. -</para> - -<para> -To automatically set up handlers on all messages sent via a session, -you can connect to the session's <link -linkend="SoupSession-request-started"><literal>request_started</literal></link> -signal, and add handlers to each message from there. -</para> - -</refsect2> - -<refsect2> <title>Handling Authentication</title> <para> @@ -467,38 +486,39 @@ linkend="soup-session-unpause-message"><function>soup_session_unpause_message</f to resume the paused message. </para> +<para> +By default, NTLM authentication is not enabled. To add NTLM support to +a session, call: +</para> + +<informalexample><programlisting> + soup_session_add_feature_by_type (session, SOUP_TYPE_AUTH_NTLM); +</programlisting></informalexample> + +<para> +(You can also disable Basic or Digest authentication by calling <link +linkend="soup-session-remove-feature-by-type"><function>soup_session_remove_feature_by_type</function></link> +on <link linkend="SOUP-TYPE-AUTH-BASIC:CAPS"><literal>SOUP_TYPE_AUTH_BASIC</literal></link> +or <link linkend="SOUP-TYPE-AUTH-DIGEST:CAPS"><literal>SOUP_TYPE_AUTH_DIGEST</literal></link>.) +</para> + </refsect2> <refsect2> <title>Multi-threaded usage</title> <para> -The only explicitly thread-safe operations in -<application>libsoup</application> are <link -linkend="SoupSessionSync"><type>SoupSessionSync</type></link>'s -implementations of the <link -linkend="SoupSession"><type>SoupSession</type></link> methods. So -after creating a <type>SoupSessionSync</type>, you can call <link -linkend="soup-session-send-message"><function>soup_session_send_message</function></link> -and <link -linkend="soup-session-cancel-message"><function>soup_session_cancel_message</function></link> -on it from any thread. But, eg, while the session is processing a -message, you should not call any <link -linkend="SoupMessage"><type>SoupMessage</type></link> methods on it -from any thread other than the one in which it is being sent. (That -is, you should not call any <type>SoupMessage</type> methods on it -except from a message or session callback or signal handler.) +A <link linkend="SoupSession"><type>SoupSession</type></link> can be +used from multiple threads. However, if you are using the async APIs, +then each thread you use the session from must have its own +thread-default <link linkend="GMainContext"><type>GMainContext</type></link>. </para> <para> -All other objects (including <link -linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link>) -should only be used from a single thread, with objects that are also -only be used from that thread. (And in particular, if you set a -non-default <link -linkend="GMainContext"><type>GMainContext</type></link> on a session, -socket, etc, then you can only use that object from the thread in -which that <type>GMainContext</type> is running.) +<link linkend="SoupMessage"><type>SoupMessage</type></link> is +<emphasis>not</emphasis> thread-safe, so once you send a message on +the session, you must not interact with it from any thread other than +the one where it was sent. </para> </refsect2> @@ -508,7 +528,8 @@ which that <type>GMainContext</type> is running.) <para> A few sample programs are available in the -<application>libsoup</application> sources: +<application>libsoup</application> sources, in the +<literal>examples</literal> directory: </para> <itemizedlist> @@ -518,21 +539,6 @@ A few sample programs are available in the </para></listitem> <listitem><para> - <emphasis role="bold"><literal>getbug</literal></emphasis> is a trivial - demonstration of the <link - linkend="libsoup-2.4-XMLRPC-Support">XMLRPC</link> interface. - (<emphasis - role="bold"><literal>xmlrpc-test</literal></emphasis> provides - a slightly more complicated example.) - </para></listitem> - - <listitem><para> - <emphasis role="bold"><literal>auth-test</literal></emphasis> shows how to use - authentication handlers and status-code handlers, although in - a fairly unusual way. - </para></listitem> - - <listitem><para> <emphasis role="bold"><literal>simple-proxy</literal></emphasis> uses both the client and server APIs to create a simple (and not very RFC-compliant) proxy server. It shows how to use the <link @@ -544,11 +550,7 @@ A few sample programs are available in the </itemizedlist> <para> -More complicated examples are available in GNOME CVS. The <ulink -url="http://live.gnome.org/LibSoup"><application>libsoup</application> -pages</ulink> on the GNOME wiki include a <ulink -url="http://live.gnome.org/LibSoup/Users">list of applications using -<application>libsoup</application></ulink>. +More complicated examples are available in GNOME git. </para> </refsect2> diff --git a/docs/reference/html/SoupAddress.html b/docs/reference/html/SoupAddress.html new file mode 100644 index 00000000..87f4251d --- /dev/null +++ b/docs/reference/html/SoupAddress.html @@ -0,0 +1,1090 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupAddress</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch05.html" title="Low-level Networking API"> +<link rel="prev" href="ch05.html" title="Low-level Networking API"> +<link rel="next" href="SoupSocket.html" title="SoupSocket"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupAddress.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupAddress.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupAddress.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupAddress.properties" class="shortcut">Properties</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch05.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="ch05.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupSocket.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupAddress"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupAddress.top_of_page"></a>SoupAddress</span></h2> +<p>SoupAddress — DNS support</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupAddress.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-new" title="soup_address_new ()">soup_address_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-new-from-sockaddr" title="soup_address_new_from_sockaddr ()">soup_address_new_from_sockaddr</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-new-any" title="soup_address_new_any ()">soup_address_new_any</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupAddress.html#SoupAddressCallback" title="SoupAddressCallback ()">*SoupAddressCallback</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-resolve-async" title="soup_address_resolve_async ()">soup_address_resolve_async</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-resolve-sync" title="soup_address_resolve_sync ()">soup_address_resolve_sync</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-is-resolved" title="soup_address_is_resolved ()">soup_address_is_resolved</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-get-name" title="soup_address_get_name ()">soup_address_get_name</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">struct <span class="returnvalue">sockaddr</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-get-sockaddr" title="soup_address_get_sockaddr ()">soup_address_get_sockaddr</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">GSocketAddress</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-get-gsockaddr" title="soup_address_get_gsockaddr ()">soup_address_get_gsockaddr</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-get-physical" title="soup_address_get_physical ()">soup_address_get_physical</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-get-port" title="soup_address_get_port ()">soup_address_get_port</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-equal-by-name" title="soup_address_equal_by_name ()">soup_address_equal_by_name</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-hash-by-name" title="soup_address_hash_by_name ()">soup_address_hash_by_name</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-equal-by-ip" title="soup_address_equal_by_ip ()">soup_address_equal_by_ip</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAddress.html#soup-address-hash-by-ip" title="soup_address_hash_by_ip ()">soup_address_hash_by_ip</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAddress.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"><a class="link" href="SoupAddress.html#SoupAddressFamily" title="enum SoupAddressFamily"><span class="type">SoupAddressFamily</span></a></td> +<td class="property_name"><a class="link" href="SoupAddress.html#SoupAddress--family" title="The “family” property">family</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupAddress.html#SoupAddress--name" title="The “name” property">name</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupAddress.html#SoupAddress--physical" title="The “physical” property">physical</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a></td> +<td class="property_name"><a class="link" href="SoupAddress.html#SoupAddress--port" title="The “port” property">port</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupAddress.html#SoupAddress--protocol" title="The “protocol” property">protocol</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupAddress.html#SoupAddress--sockaddr" title="The “sockaddr” property">sockaddr</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAddress.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupAddress.html#SoupAddress-struct" title="SoupAddress">SoupAddress</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupAddress.html#SoupAddressFamily" title="enum SoupAddressFamily">SoupAddressFamily</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAddress.html#SOUP-ADDRESS-ANY-PORT:CAPS" title="SOUP_ADDRESS_ANY_PORT">SOUP_ADDRESS_ANY_PORT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAddress.html#SOUP-ADDRESS-FAMILY:CAPS" title="SOUP_ADDRESS_FAMILY">SOUP_ADDRESS_FAMILY</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAddress.html#SOUP-ADDRESS-NAME:CAPS" title="SOUP_ADDRESS_NAME">SOUP_ADDRESS_NAME</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAddress.html#SOUP-ADDRESS-PHYSICAL:CAPS" title="SOUP_ADDRESS_PHYSICAL">SOUP_ADDRESS_PHYSICAL</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAddress.html#SOUP-ADDRESS-PORT:CAPS" title="SOUP_ADDRESS_PORT">SOUP_ADDRESS_PORT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAddress.html#SOUP-ADDRESS-SOCKADDR:CAPS" title="SOUP_ADDRESS_SOCKADDR">SOUP_ADDRESS_SOCKADDR</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAddress.html#SOUP-ADDRESS-PROTOCOL:CAPS" title="SOUP_ADDRESS_PROTOCOL">SOUP_ADDRESS_PROTOCOL</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAddress.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupAddress +</pre> +</div> +<div class="refsect1"> +<a name="SoupAddress.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupAddress implements + GSocketConnectable.</p> +</div> +<div class="refsect1"> +<a name="SoupAddress.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupAddress.description"></a><h2>Description</h2> +<p><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> represents the address of a TCP connection endpoint: +both the IP address and the port. (It is somewhat like an +object-oriented version of struct sockaddr.)</p> +<p>Although <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> is still used in some libsoup API's, it +should not be used in new code; use GLib's <span class="type">GNetworkAddress</span> or +<span class="type">GSocketAddress</span> instead.</p> +</div> +<div class="refsect1"> +<a name="SoupAddress.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-address-new"></a><h3>soup_address_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +soup_address_new (<em class="parameter"><code>const <span class="type">char</span> *name</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> port</code></em>);</pre> +<p>Creates a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> from <em class="parameter"><code>name</code></em> + and <em class="parameter"><code>port</code></em> +. The <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a>'s IP +address may not be available right away; the caller can call +<a class="link" href="SoupAddress.html#soup-address-resolve-async" title="soup_address_resolve_async ()"><code class="function">soup_address_resolve_async()</code></a> or <a class="link" href="SoupAddress.html#soup-address-resolve-sync" title="soup_address_resolve_sync ()"><code class="function">soup_address_resolve_sync()</code></a> to +force a DNS resolution.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>a hostname or physical address</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>port</p></td> +<td class="parameter_description"><p>a port number</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.2.6"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-new-from-sockaddr"></a><h3>soup_address_new_from_sockaddr ()</h3> +<pre class="programlisting"><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +soup_address_new_from_sockaddr (<em class="parameter"><code><span class="type">struct sockaddr</span> *sa</code></em>, + <em class="parameter"><code><span class="type">int</span> len</code></em>);</pre> +<p>Returns a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> equivalent to <em class="parameter"><code>sa</code></em> + (or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if <em class="parameter"><code>sa</code></em> +'s +address family isn't supported)</p> +<div class="refsect3"> +<a name="id-1.6.2.10.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sa</p></td> +<td class="parameter_description"><p>a pointer to a sockaddr</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>len</p></td> +<td class="parameter_description"><p>size of <em class="parameter"><code>sa</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.3.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a>. </p> +<p><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-new-any"></a><h3>soup_address_new_any ()</h3> +<pre class="programlisting"><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +soup_address_new_any (<em class="parameter"><code><a class="link" href="SoupAddress.html#SoupAddressFamily" title="enum SoupAddressFamily"><span class="type">SoupAddressFamily</span></a> family</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> port</code></em>);</pre> +<p>Returns a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> corresponding to the "any" address +for <em class="parameter"><code>family</code></em> + (or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if <em class="parameter"><code>family</code></em> + isn't supported), suitable for +using as a listening <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a>.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>family</p></td> +<td class="parameter_description"><p>the address family</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>port</p></td> +<td class="parameter_description"><p>the port number (usually <a class="link" href="SoupAddress.html#SOUP-ADDRESS-ANY-PORT:CAPS" title="SOUP_ADDRESS_ANY_PORT"><code class="literal">SOUP_ADDRESS_ANY_PORT</code></a>)</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.4.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a>. </p> +<p><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAddressCallback"></a><h3>SoupAddressCallback ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +<span class="c_punctuation">(</span>*SoupAddressCallback<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *addr</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> status</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>The callback function passed to <a class="link" href="SoupAddress.html#soup-address-resolve-async" title="soup_address_resolve_async ()"><code class="function">soup_address_resolve_async()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>addr</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> that was resolved</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>status</p></td> +<td class="parameter_description"><p><a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-OK:CAPS"><code class="literal">SOUP_STATUS_OK</code></a>, <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANT-RESOLVE:CAPS"><code class="literal">SOUP_STATUS_CANT_RESOLVE</code></a>, or +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANCELLED:CAPS"><code class="literal">SOUP_STATUS_CANCELLED</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the user data that was passed to +<a class="link" href="SoupAddress.html#soup-address-resolve-async" title="soup_address_resolve_async ()"><code class="function">soup_address_resolve_async()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-resolve-async"></a><h3>soup_address_resolve_async ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_address_resolve_async (<em class="parameter"><code><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *addr</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> *async_context</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><a class="link" href="SoupAddress.html#SoupAddressCallback" title="SoupAddressCallback ()"><span class="type">SoupAddressCallback</span></a> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Asynchronously resolves the missing half of <em class="parameter"><code>addr</code></em> + (its IP address +if it was created with <a class="link" href="SoupAddress.html#soup-address-new" title="soup_address_new ()"><code class="function">soup_address_new()</code></a>, or its hostname if it +was created with <a class="link" href="SoupAddress.html#soup-address-new-from-sockaddr" title="soup_address_new_from_sockaddr ()"><code class="function">soup_address_new_from_sockaddr()</code></a> or +<a class="link" href="SoupAddress.html#soup-address-new-any" title="soup_address_new_any ()"><code class="function">soup_address_new_any()</code></a>.)</p> +<p>If <em class="parameter"><code>cancellable</code></em> + is non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, it can be used to cancel the +resolution. <em class="parameter"><code>callback</code></em> + will still be invoked in this case, with a +status of <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANCELLED:CAPS"><code class="literal">SOUP_STATUS_CANCELLED</code></a>.</p> +<p>It is safe to call this more than once on a given address, from the +same thread, with the same <em class="parameter"><code>async_context</code></em> + (and doing so will not +result in redundant DNS queries being made). But it is not safe to +call from multiple threads, or with different <em class="parameter"><code>async_contexts</code></em> +, or +mixed with calls to <a class="link" href="SoupAddress.html#soup-address-resolve-sync" title="soup_address_resolve_sync ()"><code class="function">soup_address_resolve_sync()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.6.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>addr</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>async_context</p></td> +<td class="parameter_description"><p> the <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> to call <em class="parameter"><code>callback</code></em> +from. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span> object, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p> callback to call with the result. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>data for <em class="parameter"><code>callback</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-resolve-sync"></a><h3>soup_address_resolve_sync ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_address_resolve_sync (<em class="parameter"><code><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *addr</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>);</pre> +<p>Synchronously resolves the missing half of <em class="parameter"><code>addr</code></em> +, as with +<a class="link" href="SoupAddress.html#soup-address-resolve-async" title="soup_address_resolve_async ()"><code class="function">soup_address_resolve_async()</code></a>.</p> +<p>If <em class="parameter"><code>cancellable</code></em> + is non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, it can be used to cancel the +resolution. <a class="link" href="SoupAddress.html#soup-address-resolve-sync" title="soup_address_resolve_sync ()"><code class="function">soup_address_resolve_sync()</code></a> will then return a status +of <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANCELLED:CAPS"><code class="literal">SOUP_STATUS_CANCELLED</code></a>.</p> +<p>It is safe to call this more than once, even from different +threads, but it is not safe to mix calls to +<a class="link" href="SoupAddress.html#soup-address-resolve-sync" title="soup_address_resolve_sync ()"><code class="function">soup_address_resolve_sync()</code></a> with calls to +<a class="link" href="SoupAddress.html#soup-address-resolve-async" title="soup_address_resolve_async ()"><code class="function">soup_address_resolve_async()</code></a> on the same address.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.7.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>addr</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span> object, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.7.8"></a><h4>Returns</h4> +<p> <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-OK:CAPS"><code class="literal">SOUP_STATUS_OK</code></a>, <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANT-RESOLVE:CAPS"><code class="literal">SOUP_STATUS_CANT_RESOLVE</code></a>, or +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANCELLED:CAPS"><code class="literal">SOUP_STATUS_CANCELLED</code></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-is-resolved"></a><h3>soup_address_is_resolved ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_address_is_resolved (<em class="parameter"><code><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *addr</code></em>);</pre> +<p>Tests if <em class="parameter"><code>addr</code></em> + has already been resolved. Unlike the other +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> "get" methods, this is safe to call when <em class="parameter"><code>addr</code></em> + might +be being resolved in another thread.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>addr</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.8.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>addr</code></em> +has been resolved.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-get-name"></a><h3>soup_address_get_name ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_address_get_name (<em class="parameter"><code><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *addr</code></em>);</pre> +<p>Returns the hostname associated with <em class="parameter"><code>addr</code></em> +.</p> +<p>This method is not thread-safe; if you call it while <em class="parameter"><code>addr</code></em> + is being +resolved in another thread, it may return garbage. You can use +<a class="link" href="SoupAddress.html#soup-address-is-resolved" title="soup_address_is_resolved ()"><code class="function">soup_address_is_resolved()</code></a> to safely test whether or not an address +is resolved before fetching its name or address.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.9.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>addr</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.9.7"></a><h4>Returns</h4> +<p> the hostname, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if it is not known. </p> +<p><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-get-sockaddr"></a><h3>soup_address_get_sockaddr ()</h3> +<pre class="programlisting">struct <span class="returnvalue">sockaddr</span> * +soup_address_get_sockaddr (<em class="parameter"><code><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *addr</code></em>, + <em class="parameter"><code><span class="type">int</span> *len</code></em>);</pre> +<p>Returns the sockaddr associated with <em class="parameter"><code>addr</code></em> +, with its length in +*<em class="parameter"><code>len</code></em> +. If the sockaddr is not yet known, returns <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</p> +<p>This method is not thread-safe; if you call it while <em class="parameter"><code>addr</code></em> + is being +resolved in another thread, it may return garbage. You can use +<a class="link" href="SoupAddress.html#soup-address-is-resolved" title="soup_address_is_resolved ()"><code class="function">soup_address_is_resolved()</code></a> to safely test whether or not an address +is resolved before fetching its name or address.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.10.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>addr</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>len</p></td> +<td class="parameter_description"><p>return location for sockaddr length</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.10.7"></a><h4>Returns</h4> +<p> the sockaddr, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p> +<p><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-get-gsockaddr"></a><h3>soup_address_get_gsockaddr ()</h3> +<pre class="programlisting"><span class="returnvalue">GSocketAddress</span> * +soup_address_get_gsockaddr (<em class="parameter"><code><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *addr</code></em>);</pre> +<p>Creates a new <span class="type">GSocketAddress</span> corresponding to <em class="parameter"><code>addr</code></em> + (which is assumed +to only have one socket address associated with it).</p> +<div class="refsect3"> +<a name="id-1.6.2.10.11.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>addr</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.11.6"></a><h4>Returns</h4> +<p> a new <span class="type">GSocketAddress</span>. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-get-physical"></a><h3>soup_address_get_physical ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_address_get_physical (<em class="parameter"><code><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *addr</code></em>);</pre> +<p>Returns the physical address associated with <em class="parameter"><code>addr</code></em> + as a string. +(Eg, "127.0.0.1"). If the address is not yet known, returns <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</p> +<p>This method is not thread-safe; if you call it while <em class="parameter"><code>addr</code></em> + is being +resolved in another thread, it may return garbage. You can use +<a class="link" href="SoupAddress.html#soup-address-is-resolved" title="soup_address_is_resolved ()"><code class="function">soup_address_is_resolved()</code></a> to safely test whether or not an address +is resolved before fetching its name or address.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.12.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>addr</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.12.7"></a><h4>Returns</h4> +<p> the physical address, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p> +<p><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-get-port"></a><h3>soup_address_get_port ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_address_get_port (<em class="parameter"><code><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *addr</code></em>);</pre> +<p>Returns the port associated with <em class="parameter"><code>addr</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.13.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>addr</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.13.6"></a><h4>Returns</h4> +<p> the port</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-equal-by-name"></a><h3>soup_address_equal_by_name ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_address_equal_by_name (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> addr1</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> addr2</code></em>);</pre> +<p>Tests if <em class="parameter"><code>addr1</code></em> + and <em class="parameter"><code>addr2</code></em> + have the same "name". This method can be +used with <a class="link" href="SoupAddress.html#soup-address-hash-by-name" title="soup_address_hash_by_name ()"><code class="function">soup_address_hash_by_name()</code></a> to create a <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> that +hashes on address "names".</p> +<p>Comparing by name normally means comparing the addresses by their +hostnames. But if the address was originally created using an IP +address literal, then it will be compared by that instead.</p> +<p>In particular, if "www.example.com" has the IP address 10.0.0.1, +and <em class="parameter"><code>addr1</code></em> + was created with the name "www.example.com" and <em class="parameter"><code>addr2</code></em> + +was created with the name "10.0.0.1", then they will compare as +unequal for purposes of <a class="link" href="SoupAddress.html#soup-address-equal-by-name" title="soup_address_equal_by_name ()"><code class="function">soup_address_equal_by_name()</code></a>.</p> +<p>This would be used to distinguish hosts in situations where +different virtual hosts on the same IP address should be considered +different. Eg, for purposes of HTTP authentication or cookies, two +hosts with the same IP address but different names are considered +to be different hosts.</p> +<p>See also <a class="link" href="SoupAddress.html#soup-address-equal-by-ip" title="soup_address_equal_by_ip ()"><code class="function">soup_address_equal_by_ip()</code></a>, which compares by IP address +rather than by name.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.14.9"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>addr1</p></td> +<td class="parameter_description"><p> a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> with a resolved name. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> Soup.Address]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>addr2</p></td> +<td class="parameter_description"><p> another <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> with a resolved +name. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> Soup.Address]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.14.10"></a><h4>Returns</h4> +<p> whether or not <em class="parameter"><code>addr1</code></em> +and <em class="parameter"><code>addr2</code></em> +have the same name</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-hash-by-name"></a><h3>soup_address_hash_by_name ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_address_hash_by_name (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> addr</code></em>);</pre> +<p>A hash function (for <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>) that corresponds to +<a class="link" href="SoupAddress.html#soup-address-equal-by-name" title="soup_address_equal_by_name ()"><code class="function">soup_address_equal_by_name()</code></a>, qv</p> +<div class="refsect3"> +<a name="id-1.6.2.10.15.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>addr</p></td> +<td class="parameter_description"><p> a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> Soup.Address]</span></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.15.6"></a><h4>Returns</h4> +<p> the named-based hash value for <em class="parameter"><code>addr</code></em> +.</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-equal-by-ip"></a><h3>soup_address_equal_by_ip ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_address_equal_by_ip (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> addr1</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> addr2</code></em>);</pre> +<p>Tests if <em class="parameter"><code>addr1</code></em> + and <em class="parameter"><code>addr2</code></em> + have the same IP address. This method +can be used with <a class="link" href="SoupAddress.html#soup-address-hash-by-ip" title="soup_address_hash_by_ip ()"><code class="function">soup_address_hash_by_ip()</code></a> to create a +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> that hashes on IP address.</p> +<p>This would be used to distinguish hosts in situations where +different virtual hosts on the same IP address should be considered +the same. Eg, if "www.example.com" and "www.example.net" have the +same IP address, then a single connection can be used to talk +to either of them.</p> +<p>See also <a class="link" href="SoupAddress.html#soup-address-equal-by-name" title="soup_address_equal_by_name ()"><code class="function">soup_address_equal_by_name()</code></a>, which compares by name +rather than by IP address.</p> +<div class="refsect3"> +<a name="id-1.6.2.10.16.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>addr1</p></td> +<td class="parameter_description"><p> a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> with a resolved IP +address. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> Soup.Address]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>addr2</p></td> +<td class="parameter_description"><p> another <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> with a resolved +IP address. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> Soup.Address]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.16.8"></a><h4>Returns</h4> +<p> whether or not <em class="parameter"><code>addr1</code></em> +and <em class="parameter"><code>addr2</code></em> +have the same IP +address.</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-address-hash-by-ip"></a><h3>soup_address_hash_by_ip ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_address_hash_by_ip (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> addr</code></em>);</pre> +<p>A hash function (for <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>) that corresponds to +<a class="link" href="SoupAddress.html#soup-address-equal-by-ip" title="soup_address_equal_by_ip ()"><code class="function">soup_address_equal_by_ip()</code></a>, qv</p> +<div class="refsect3"> +<a name="id-1.6.2.10.17.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>addr</p></td> +<td class="parameter_description"><p> a <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> Soup.Address]</span></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.2.10.17.6"></a><h4>Returns</h4> +<p> the IP-based hash value for <em class="parameter"><code>addr</code></em> +.</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupAddress.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupAddress-struct"></a><h3>SoupAddress</h3> +<pre class="programlisting">typedef struct _SoupAddress SoupAddress;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAddressFamily"></a><h3>enum SoupAddressFamily</h3> +<p>The supported address families.</p> +<div class="refsect3"> +<a name="id-1.6.2.11.3.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-ADDRESS-FAMILY-INVALID:CAPS"></a>SOUP_ADDRESS_FAMILY_INVALID</p></td> +<td class="enum_member_description"> +<p>an invalid <a class="link" href="SoupAddress.html" title="SoupAddress"><code class="literal">SoupAddress</code></a></p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-ADDRESS-FAMILY-IPV4:CAPS"></a>SOUP_ADDRESS_FAMILY_IPV4</p></td> +<td class="enum_member_description"> +<p>an IPv4 address</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-ADDRESS-FAMILY-IPV6:CAPS"></a>SOUP_ADDRESS_FAMILY_IPV6</p></td> +<td class="enum_member_description"> +<p>an IPv6 address</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-ADDRESS-ANY-PORT:CAPS"></a><h3>SOUP_ADDRESS_ANY_PORT</h3> +<pre class="programlisting">#define SOUP_ADDRESS_ANY_PORT 0 +</pre> +<p>This can be passed to any <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> method that expects a port, +to indicate that you don't care what port is used.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-ADDRESS-FAMILY:CAPS"></a><h3>SOUP_ADDRESS_FAMILY</h3> +<pre class="programlisting">#define SOUP_ADDRESS_FAMILY "family" +</pre> +<p>Alias for the <a class="link" href="SoupAddress.html#SoupAddress--family" title="The “family” property"><span class="type">“family”</span></a> property. (The +<a class="link" href="SoupAddress.html#SoupAddressFamily" title="enum SoupAddressFamily"><span class="type">SoupAddressFamily</span></a> for this address.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-ADDRESS-NAME:CAPS"></a><h3>SOUP_ADDRESS_NAME</h3> +<pre class="programlisting">#define SOUP_ADDRESS_NAME "name" +</pre> +<p>Alias for the <a class="link" href="SoupAddress.html#SoupAddress--name" title="The “name” property"><span class="type">“name”</span></a> property. (The hostname for +this address.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-ADDRESS-PHYSICAL:CAPS"></a><h3>SOUP_ADDRESS_PHYSICAL</h3> +<pre class="programlisting">#define SOUP_ADDRESS_PHYSICAL "physical" +</pre> +<p>An alias for the <a class="link" href="SoupAddress.html#SoupAddress--physical" title="The “physical” property"><span class="type">“physical”</span></a> property. (The +stringified IP address for this address.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-ADDRESS-PORT:CAPS"></a><h3>SOUP_ADDRESS_PORT</h3> +<pre class="programlisting">#define SOUP_ADDRESS_PORT "port" +</pre> +<p>An alias for the <a class="link" href="SoupAddress.html#SoupAddress--port" title="The “port” property"><span class="type">“port”</span></a> property. (The port for +this address.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-ADDRESS-SOCKADDR:CAPS"></a><h3>SOUP_ADDRESS_SOCKADDR</h3> +<pre class="programlisting">#define SOUP_ADDRESS_SOCKADDR "sockaddr" +</pre> +<p>An alias for the <a class="link" href="SoupAddress.html#SoupAddress--sockaddr" title="The “sockaddr” property"><span class="type">“sockaddr”</span></a> property. (A pointer +to the struct sockaddr for this address.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-ADDRESS-PROTOCOL:CAPS"></a><h3>SOUP_ADDRESS_PROTOCOL</h3> +<pre class="programlisting">#define SOUP_ADDRESS_PROTOCOL "protocol" +</pre> +<p>Alias for the <a class="link" href="SoupAddress.html#SoupAddress--protocol" title="The “protocol” property"><span class="type">“protocol”</span></a> property. (The URI scheme +used with this address.)</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupAddress.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupAddress--family"></a><h3>The <code class="literal">“family”</code> property</h3> +<pre class="programlisting"> “family” <a class="link" href="SoupAddress.html#SoupAddressFamily" title="enum SoupAddressFamily"><span class="type">SoupAddressFamily</span></a></pre> +<p>Address family for this address.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: SOUP_ADDRESS_FAMILY_INVALID</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAddress--name"></a><h3>The <code class="literal">“name”</code> property</h3> +<pre class="programlisting"> “name” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>Hostname for this address.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAddress--physical"></a><h3>The <code class="literal">“physical”</code> property</h3> +<pre class="programlisting"> “physical” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>IP address for this address.</p> +<p>Flags: Read</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAddress--port"></a><h3>The <code class="literal">“port”</code> property</h3> +<pre class="programlisting"> “port” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a></pre> +<p>Port for this address.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Allowed values: [-1,65535]</p> +<p>Default value: -1</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAddress--protocol"></a><h3>The <code class="literal">“protocol”</code> property</h3> +<pre class="programlisting"> “protocol” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>URI scheme for this address.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAddress--sockaddr"></a><h3>The <code class="literal">“sockaddr”</code> property</h3> +<pre class="programlisting"> “sockaddr” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>struct sockaddr for this address.</p> +<p>Flags: Read / Write / Construct Only</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupAuth.html b/docs/reference/html/SoupAuth.html new file mode 100644 index 00000000..794d1ff3 --- /dev/null +++ b/docs/reference/html/SoupAuth.html @@ -0,0 +1,855 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupAuth</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="ch02.html" title="Core API"> +<link rel="next" href="SoupAuthDomain.html" title="SoupAuthDomain"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupAuth.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupAuth.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupAuth.properties" class="shortcut">Properties</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="ch02.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupAuthDomain.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupAuth"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupAuth.top_of_page"></a>SoupAuth</span></h2> +<p>SoupAuth — HTTP client-side authentication support</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupAuth.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupAuth.html" title="SoupAuth"><span class="returnvalue">SoupAuth</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-new" title="soup_auth_new ()">soup_auth_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-update" title="soup_auth_update ()">soup_auth_update</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuth.html#SOUP-TYPE-AUTH-BASIC:CAPS" title="SOUP_TYPE_AUTH_BASIC">SOUP_TYPE_AUTH_BASIC</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuth.html#SOUP-TYPE-AUTH-DIGEST:CAPS" title="SOUP_TYPE_AUTH_DIGEST">SOUP_TYPE_AUTH_DIGEST</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuth.html#SOUP-TYPE-AUTH-NTLM:CAPS" title="SOUP_TYPE_AUTH_NTLM">SOUP_TYPE_AUTH_NTLM</a></td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-is-for-proxy" title="soup_auth_is_for_proxy ()">soup_auth_is_for_proxy</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-get-scheme-name" title="soup_auth_get_scheme_name ()">soup_auth_get_scheme_name</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-get-host" title="soup_auth_get_host ()">soup_auth_get_host</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-get-realm" title="soup_auth_get_realm ()">soup_auth_get_realm</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-get-info" title="soup_auth_get_info ()">soup_auth_get_info</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-authenticate" title="soup_auth_authenticate ()">soup_auth_authenticate</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-is-authenticated" title="soup_auth_is_authenticated ()">soup_auth_is_authenticated</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-is-ready" title="soup_auth_is_ready ()">soup_auth_is_ready</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-get-authorization" title="soup_auth_get_authorization ()">soup_auth_get_authorization</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-get-protection-space" title="soup_auth_get_protection_space ()">soup_auth_get_protection_space</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupAuth.html#soup-auth-free-protection-space" title="soup_auth_free_protection_space ()">soup_auth_free_protection_space</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuth.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupAuth.html#SoupAuth--host" title="The “host” property">host</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupAuth.html#SoupAuth--is-authenticated" title="The “is-authenticated” property">is-authenticated</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupAuth.html#SoupAuth--is-for-proxy" title="The “is-for-proxy” property">is-for-proxy</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupAuth.html#SoupAuth--realm" title="The “realm” property">realm</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupAuth.html#SoupAuth--scheme-name" title="The “scheme-name” property">scheme-name</a></td> +<td class="property_flags">Read</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuth.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupAuth.html#SoupAuth-struct" title="SoupAuth">SoupAuth</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuth.html#SOUP-AUTH-SCHEME-NAME:CAPS" title="SOUP_AUTH_SCHEME_NAME">SOUP_AUTH_SCHEME_NAME</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuth.html#SOUP-AUTH-REALM:CAPS" title="SOUP_AUTH_REALM">SOUP_AUTH_REALM</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuth.html#SOUP-AUTH-HOST:CAPS" title="SOUP_AUTH_HOST">SOUP_AUTH_HOST</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuth.html#SOUP-AUTH-IS-FOR-PROXY:CAPS" title="SOUP_AUTH_IS_FOR_PROXY">SOUP_AUTH_IS_FOR_PROXY</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuth.html#SOUP-AUTH-IS-AUTHENTICATED:CAPS" title="SOUP_AUTH_IS_AUTHENTICATED">SOUP_AUTH_IS_AUTHENTICATED</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuth.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupAuth +</pre> +</div> +<div class="refsect1"> +<a name="SoupAuth.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupAuth.description"></a><h2>Description</h2> +<p><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> objects store the authentication data associated with a +given bit of web space. They are created automatically by +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>.</p> +</div> +<div class="refsect1"> +<a name="SoupAuth.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-auth-new"></a><h3>soup_auth_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="returnvalue">SoupAuth</span></a> * +soup_auth_new (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *auth_header</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> of type <em class="parameter"><code>type</code></em> + with the information from +<em class="parameter"><code>msg</code></em> + and <em class="parameter"><code>auth_header</code></em> +.</p> +<p>This is called by <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>; you will normally not create auths +yourself.</p> +<div class="refsect3"> +<a name="id-1.3.2.9.2.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>the type of auth to create (a subtype of <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a>)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> the auth is being created for</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>auth_header</p></td> +<td class="parameter_description"><p>the WWW-Authenticate/Proxy-Authenticate header</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.2.9.2.7"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if it could not be +created</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-update"></a><h3>soup_auth_update ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_auth_update (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *auth_header</code></em>);</pre> +<p>Updates <em class="parameter"><code>auth</code></em> + with the information from <em class="parameter"><code>msg</code></em> + and <em class="parameter"><code>auth_header</code></em> +, +possibly un-authenticating it. As with <a class="link" href="SoupAuth.html#soup-auth-new" title="soup_auth_new ()"><code class="function">soup_auth_new()</code></a>, this is +normally only used by <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.2.9.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> <em class="parameter"><code>auth</code></em> +is being updated for</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>auth_header</p></td> +<td class="parameter_description"><p>the WWW-Authenticate/Proxy-Authenticate header</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.2.9.3.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>auth</code></em> +is still a valid (but potentially +unauthenticated) <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a>. <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if something about <em class="parameter"><code>auth_params</code></em> +could not be parsed or incorporated into <em class="parameter"><code>auth</code></em> +at all.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-TYPE-AUTH-BASIC:CAPS"></a><h3>SOUP_TYPE_AUTH_BASIC</h3> +<pre class="programlisting">#define SOUP_TYPE_AUTH_BASIC (soup_auth_basic_get_type ()) +</pre> +<p>A <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> corresponding to HTTP "Basic" authentication. +<a href="SoupSession.html"><span class="type">SoupSessions</span></a> support this by default; if you want to disable +support for it, call <a class="link" href="SoupSession.html#soup-session-remove-feature-by-type" title="soup_session_remove_feature_by_type ()"><code class="function">soup_session_remove_feature_by_type()</code></a>, +passing <a class="link" href="SoupAuth.html#SOUP-TYPE-AUTH-BASIC:CAPS" title="SOUP_TYPE_AUTH_BASIC"><code class="literal">SOUP_TYPE_AUTH_BASIC</code></a>.</p> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-TYPE-AUTH-DIGEST:CAPS"></a><h3>SOUP_TYPE_AUTH_DIGEST</h3> +<pre class="programlisting">#define SOUP_TYPE_AUTH_DIGEST (soup_auth_digest_get_type ()) +</pre> +<p>A <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> corresponding to HTTP "Digest" authentication. +<a href="SoupSession.html"><span class="type">SoupSessions</span></a> support this by default; if you want to disable +support for it, call <a class="link" href="SoupSession.html#soup-session-remove-feature-by-type" title="soup_session_remove_feature_by_type ()"><code class="function">soup_session_remove_feature_by_type()</code></a>, +passing <a class="link" href="SoupAuth.html#SOUP-TYPE-AUTH-DIGEST:CAPS" title="SOUP_TYPE_AUTH_DIGEST"><code class="literal">SOUP_TYPE_AUTH_DIGEST</code></a>.</p> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-TYPE-AUTH-NTLM:CAPS"></a><h3>SOUP_TYPE_AUTH_NTLM</h3> +<pre class="programlisting">#define SOUP_TYPE_AUTH_NTLM (soup_auth_ntlm_get_type ()) +</pre> +<p>A <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> corresponding to HTTP-based NTLM authentication. +<a href="SoupSession.html"><span class="type">SoupSessions</span></a> do not support this type by default; if you want to +enable support for it, call <a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()"><code class="function">soup_session_add_feature_by_type()</code></a>, +passing <a class="link" href="SoupAuth.html#SOUP-TYPE-AUTH-NTLM:CAPS" title="SOUP_TYPE_AUTH_NTLM"><code class="literal">SOUP_TYPE_AUTH_NTLM</code></a>.</p> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-is-for-proxy"></a><h3>soup_auth_is_for_proxy ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_auth_is_for_proxy (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>);</pre> +<p>Tests whether or not <em class="parameter"><code>auth</code></em> + is associated with a proxy server rather +than an "origin" server.</p> +<div class="refsect3"> +<a name="id-1.3.2.9.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.2.9.7.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-get-scheme-name"></a><h3>soup_auth_get_scheme_name ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_auth_get_scheme_name (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>);</pre> +<p>Returns <em class="parameter"><code>auth</code></em> +'s scheme name. (Eg, "Basic", "Digest", or "NTLM")</p> +<div class="refsect3"> +<a name="id-1.3.2.9.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.2.9.8.6"></a><h4>Returns</h4> +<p> the scheme name</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-get-host"></a><h3>soup_auth_get_host ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_auth_get_host (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>);</pre> +<p>Returns the host that <em class="parameter"><code>auth</code></em> + is associated with.</p> +<div class="refsect3"> +<a name="id-1.3.2.9.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.2.9.9.6"></a><h4>Returns</h4> +<p> the hostname</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-get-realm"></a><h3>soup_auth_get_realm ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_auth_get_realm (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>);</pre> +<p>Returns <em class="parameter"><code>auth</code></em> +'s realm. This is an identifier that distinguishes +separate authentication spaces on a given server, and may be some +string that is meaningful to the user. (Although it is probably not +localized.)</p> +<div class="refsect3"> +<a name="id-1.3.2.9.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.2.9.10.6"></a><h4>Returns</h4> +<p> the realm name</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-get-info"></a><h3>soup_auth_get_info ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_auth_get_info (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>);</pre> +<p>Gets an opaque identifier for <em class="parameter"><code>auth</code></em> +, for use as a hash key or the +like. <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> objects from the same server with the same +identifier refer to the same authentication domain (eg, the URLs +associated with them take the same usernames and passwords).</p> +<div class="refsect3"> +<a name="id-1.3.2.9.11.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.2.9.11.6"></a><h4>Returns</h4> +<p> the identifier</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-authenticate"></a><h3>soup_auth_authenticate ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_auth_authenticate (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *username</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *password</code></em>);</pre> +<p>Call this on an auth to authenticate it; normally this will cause +the auth's message to be requeued with the new authentication info.</p> +<div class="refsect3"> +<a name="id-1.3.2.9.12.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>username</p></td> +<td class="parameter_description"><p>the username provided by the user or client</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>password</p></td> +<td class="parameter_description"><p>the password provided by the user or client</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-is-authenticated"></a><h3>soup_auth_is_authenticated ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_auth_is_authenticated (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>);</pre> +<p>Tests if <em class="parameter"><code>auth</code></em> + has been given a username and password</p> +<div class="refsect3"> +<a name="id-1.3.2.9.13.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.2.9.13.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>auth</code></em> +has been given a username and password</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-is-ready"></a><h3>soup_auth_is_ready ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_auth_is_ready (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Tests if <em class="parameter"><code>auth</code></em> + is ready to make a request for <em class="parameter"><code>msg</code></em> + with. For most +auths, this is equivalent to <a class="link" href="SoupAuth.html#soup-auth-is-authenticated" title="soup_auth_is_authenticated ()"><code class="function">soup_auth_is_authenticated()</code></a>, but for +some auth types (eg, NTLM), the auth may be sendable (eg, as an +authentication request) even before it is authenticated.</p> +<div class="refsect3"> +<a name="id-1.3.2.9.14.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.2.9.14.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>auth</code></em> +is ready to make a request with.</p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-get-authorization"></a><h3>soup_auth_get_authorization ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_auth_get_authorization (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Generates an appropriate "Authorization" header for <em class="parameter"><code>msg</code></em> +. (The +session will only call this if <a class="link" href="SoupAuth.html#soup-auth-is-authenticated" title="soup_auth_is_authenticated ()"><code class="function">soup_auth_is_authenticated()</code></a> +returned <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>.)</p> +<div class="refsect3"> +<a name="id-1.3.2.9.15.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> to be authorized</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.2.9.15.6"></a><h4>Returns</h4> +<p> the "Authorization" header, which must be freed.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-get-protection-space"></a><h3>soup_auth_get_protection_space ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +soup_auth_get_protection_space (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *source_uri</code></em>);</pre> +<p>Returns a list of paths on the server which <em class="parameter"><code>auth</code></em> + extends over. +(All subdirectories of these paths are also assumed to be part +of <em class="parameter"><code>auth</code></em> +'s protection space, unless otherwise discovered not to +be.)</p> +<div class="refsect3"> +<a name="id-1.3.2.9.16.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>source_uri</p></td> +<td class="parameter_description"><p>the URI of the request that <em class="parameter"><code>auth</code></em> +was generated in +response to.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.2.9.16.6"></a><h4>Returns</h4> +<p> the list of +paths, which can be freed with <a class="link" href="SoupAuth.html#soup-auth-free-protection-space" title="soup_auth_free_protection_space ()"><code class="function">soup_auth_free_protection_space()</code></a>. </p> +<p><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-free-protection-space"></a><h3>soup_auth_free_protection_space ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_auth_free_protection_space (<em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> *space</code></em>);</pre> +<p>Frees <em class="parameter"><code>space</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.2.9.17.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>space</p></td> +<td class="parameter_description"><p>the return value from <a class="link" href="SoupAuth.html#soup-auth-get-protection-space" title="soup_auth_get_protection_space ()"><code class="function">soup_auth_get_protection_space()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuth.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupAuth-struct"></a><h3>SoupAuth</h3> +<pre class="programlisting">typedef struct _SoupAuth SoupAuth;</pre> +<p>The abstract base class for handling authentication. Specific HTTP +Authentication mechanisms are implemented by its subclasses, but +applications never need to be aware of the specific subclasses +being used.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-SCHEME-NAME:CAPS"></a><h3>SOUP_AUTH_SCHEME_NAME</h3> +<pre class="programlisting">#define SOUP_AUTH_SCHEME_NAME "scheme-name" +</pre> +<p>An alias for the <a class="link" href="SoupAuth.html#SoupAuth--scheme-name" title="The “scheme-name” property"><span class="type">“scheme-name”</span></a> property. (The +authentication scheme name.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-REALM:CAPS"></a><h3>SOUP_AUTH_REALM</h3> +<pre class="programlisting">#define SOUP_AUTH_REALM "realm" +</pre> +<p>An alias for the <a class="link" href="SoupAuth.html#SoupAuth--realm" title="The “realm” property"><span class="type">“realm”</span></a> property. (The +authentication realm.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-HOST:CAPS"></a><h3>SOUP_AUTH_HOST</h3> +<pre class="programlisting">#define SOUP_AUTH_HOST "host" +</pre> +<p>An alias for the <a class="link" href="SoupAuth.html#SoupAuth--host" title="The “host” property"><span class="type">“host”</span></a> property. (The +host being authenticated to.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-IS-FOR-PROXY:CAPS"></a><h3>SOUP_AUTH_IS_FOR_PROXY</h3> +<pre class="programlisting">#define SOUP_AUTH_IS_FOR_PROXY "is-for-proxy" +</pre> +<p>An alias for the <a class="link" href="SoupAuth.html#SoupAuth--is-for-proxy" title="The “is-for-proxy” property"><span class="type">“is-for-proxy”</span></a> property. (Whether +or not the auth is for a proxy server.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-IS-AUTHENTICATED:CAPS"></a><h3>SOUP_AUTH_IS_AUTHENTICATED</h3> +<pre class="programlisting">#define SOUP_AUTH_IS_AUTHENTICATED "is-authenticated" +</pre> +<p>An alias for the <a class="link" href="SoupAuth.html#SoupAuth--is-authenticated" title="The “is-authenticated” property"><span class="type">“is-authenticated”</span></a> property. +(Whether or not the auth has been authenticated.)</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuth.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupAuth--host"></a><h3>The <code class="literal">“host”</code> property</h3> +<pre class="programlisting"> “host” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>Authentication host.</p> +<p>Flags: Read / Write</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuth--is-authenticated"></a><h3>The <code class="literal">“is-authenticated”</code> property</h3> +<pre class="programlisting"> “is-authenticated” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Whether or not the auth is authenticated.</p> +<p>Flags: Read</p> +<p>Default value: FALSE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuth--is-for-proxy"></a><h3>The <code class="literal">“is-for-proxy”</code> property</h3> +<pre class="programlisting"> “is-for-proxy” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Whether or not the auth is for a proxy server.</p> +<p>Flags: Read / Write</p> +<p>Default value: FALSE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuth--realm"></a><h3>The <code class="literal">“realm”</code> property</h3> +<pre class="programlisting"> “realm” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>Authentication realm.</p> +<p>Flags: Read / Write</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuth--scheme-name"></a><h3>The <code class="literal">“scheme-name”</code> property</h3> +<pre class="programlisting"> “scheme-name” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>Authentication scheme name.</p> +<p>Flags: Read</p> +<p>Default value: NULL</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuth.see-also"></a><h2>See Also</h2> +<p><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupAuthDomain.html b/docs/reference/html/SoupAuthDomain.html new file mode 100644 index 00000000..db5ac04f --- /dev/null +++ b/docs/reference/html/SoupAuthDomain.html @@ -0,0 +1,936 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupAuthDomain</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupAuth.html" title="SoupAuth"> +<link rel="next" href="SoupAuthDomainBasic.html" title="SoupAuthDomainBasic"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupAuthDomain.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupAuthDomain.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupAuthDomain.properties" class="shortcut">Properties</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupAuth.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupAuthDomainBasic.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupAuthDomain"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupAuthDomain.top_of_page"></a>SoupAuthDomain</span></h2> +<p>SoupAuthDomain — Server-side authentication</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupAuthDomain.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-add-path" title="soup_auth_domain_add_path ()">soup_auth_domain_add_path</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-remove-path" title="soup_auth_domain_remove_path ()">soup_auth_domain_remove_path</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupAuthDomain.html#SoupAuthDomainFilter" title="SoupAuthDomainFilter ()">*SoupAuthDomainFilter</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-set-filter" title="soup_auth_domain_set_filter ()">soup_auth_domain_set_filter</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-get-realm" title="soup_auth_domain_get_realm ()">soup_auth_domain_get_realm</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupAuthDomain.html#SoupAuthDomainGenericAuthCallback" title="SoupAuthDomainGenericAuthCallback ()">*SoupAuthDomainGenericAuthCallback</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-set-generic-auth-callback" title="soup_auth_domain_set_generic_auth_callback ()">soup_auth_domain_set_generic_auth_callback</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-check-password" title="soup_auth_domain_check_password ()">soup_auth_domain_check_password</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-covers" title="soup_auth_domain_covers ()">soup_auth_domain_covers</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-accepts" title="soup_auth_domain_accepts ()">soup_auth_domain_accepts</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-challenge" title="soup_auth_domain_challenge ()">soup_auth_domain_challenge</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomain.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupAuthDomain.html#SoupAuthDomain--add-path" title="The “add-path” property">add-path</a></td> +<td class="property_flags">Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupAuthDomain.html#SoupAuthDomain--filter" title="The “filter” property">filter</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupAuthDomain.html#SoupAuthDomain--filter-data" title="The “filter-data” property">filter-data</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupAuthDomain.html#SoupAuthDomain--generic-auth-callback" title="The “generic-auth-callback” property">generic-auth-callback</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupAuthDomain.html#SoupAuthDomain--generic-auth-data" title="The “generic-auth-data” property">generic-auth-data</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupAuthDomain.html#SoupAuthDomain--proxy" title="The “proxy” property">proxy</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupAuthDomain.html#SoupAuthDomain--realm" title="The “realm” property">realm</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupAuthDomain.html#SoupAuthDomain--remove-path" title="The “remove-path” property">remove-path</a></td> +<td class="property_flags">Write</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomain.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupAuthDomain.html#SoupAuthDomain-struct" title="SoupAuthDomain">SoupAuthDomain</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REALM:CAPS" title="SOUP_AUTH_DOMAIN_REALM">SOUP_AUTH_DOMAIN_REALM</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-PROXY:CAPS" title="SOUP_AUTH_DOMAIN_PROXY">SOUP_AUTH_DOMAIN_PROXY</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-ADD-PATH:CAPS" title="SOUP_AUTH_DOMAIN_ADD_PATH">SOUP_AUTH_DOMAIN_ADD_PATH</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REMOVE-PATH:CAPS" title="SOUP_AUTH_DOMAIN_REMOVE_PATH">SOUP_AUTH_DOMAIN_REMOVE_PATH</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-FILTER:CAPS" title="SOUP_AUTH_DOMAIN_FILTER">SOUP_AUTH_DOMAIN_FILTER</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-FILTER-DATA:CAPS" title="SOUP_AUTH_DOMAIN_FILTER_DATA">SOUP_AUTH_DOMAIN_FILTER_DATA</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-GENERIC-AUTH-CALLBACK:CAPS" title="SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK">SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-GENERIC-AUTH-DATA:CAPS" title="SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA">SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomain.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupAuthDomain + <span class="lineart">├──</span> <a class="link" href="SoupAuthDomainBasic.html" title="SoupAuthDomainBasic">SoupAuthDomainBasic</a> + <span class="lineart">╰──</span> <a class="link" href="SoupAuthDomainDigest.html" title="SoupAuthDomainDigest">SoupAuthDomainDigest</a> +</pre> +</div> +<div class="refsect1"> +<a name="SoupAuthDomain.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupAuthDomain.description"></a><h2>Description</h2> +<p>A <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> manages authentication for all or part of a +<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a>. To make a server require authentication, first create +an appropriate subclass of <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a>, and then add it to the +server with <a class="link" href="SoupServer.html#soup-server-add-auth-domain" title="soup_server_add_auth_domain ()"><code class="function">soup_server_add_auth_domain()</code></a>.</p> +<p>In order for an auth domain to have any effect, you must add one or +more paths to it (via <a class="link" href="SoupAuthDomain.html#soup-auth-domain-add-path" title="soup_auth_domain_add_path ()"><code class="function">soup_auth_domain_add_path()</code></a> or the +<a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-ADD-PATH:CAPS" title="SOUP_AUTH_DOMAIN_ADD_PATH"><code class="literal">SOUP_AUTH_DOMAIN_ADD_PATH</code></a> property). To require authentication for +all ordinary requests, add the path "/". (Note that this does not +include the special "*" URI (eg, "OPTIONS *"), which must be added +as a separate path if you want to cover it.)</p> +<p>If you need greater control over which requests should and +shouldn't be authenticated, add paths covering everything you +<span class="emphasis"><em>might</em></span> want authenticated, and then use a +filter (<a class="link" href="SoupAuthDomain.html#soup-auth-domain-set-filter" title="soup_auth_domain_set_filter ()"><code class="function">soup_auth_domain_set_filter()</code></a>) to bypass authentication for +those requests that don't need it.</p> +</div> +<div class="refsect1"> +<a name="SoupAuthDomain.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-auth-domain-add-path"></a><h3>soup_auth_domain_add_path ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_auth_domain_add_path (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *path</code></em>);</pre> +<p>Adds <em class="parameter"><code>path</code></em> + to <em class="parameter"><code>domain</code></em> +, such that requests under <em class="parameter"><code>path</code></em> + on <em class="parameter"><code>domain</code></em> +'s +server will require authentication (unless overridden by +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-remove-path" title="soup_auth_domain_remove_path ()"><code class="function">soup_auth_domain_remove_path()</code></a> or <a class="link" href="SoupAuthDomain.html#soup-auth-domain-set-filter" title="soup_auth_domain_set_filter ()"><code class="function">soup_auth_domain_set_filter()</code></a>).</p> +<p>You can also add paths by setting the <a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-ADD-PATH:CAPS" title="SOUP_AUTH_DOMAIN_ADD_PATH"><code class="literal">SOUP_AUTH_DOMAIN_ADD_PATH</code></a> +property, which can also be used to add one or more paths at +construct time.</p> +<div class="refsect3"> +<a name="id-1.3.3.9.2.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>path</p></td> +<td class="parameter_description"><p>the path to add to <em class="parameter"><code>domain</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-domain-remove-path"></a><h3>soup_auth_domain_remove_path ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_auth_domain_remove_path (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *path</code></em>);</pre> +<p>Removes <em class="parameter"><code>path</code></em> + from <em class="parameter"><code>domain</code></em> +, such that requests under <em class="parameter"><code>path</code></em> + on +<em class="parameter"><code>domain</code></em> +'s server will NOT require authentication.</p> +<p>This is not simply an undo-er for <a class="link" href="SoupAuthDomain.html#soup-auth-domain-add-path" title="soup_auth_domain_add_path ()"><code class="function">soup_auth_domain_add_path()</code></a>; it +can be used to "carve out" a subtree that does not require +authentication inside a hierarchy that does. Note also that unlike +with <a class="link" href="SoupAuthDomain.html#soup-auth-domain-add-path" title="soup_auth_domain_add_path ()"><code class="function">soup_auth_domain_add_path()</code></a>, this cannot be overridden by +adding a filter, as filters can only bypass authentication that +would otherwise be required, not require it where it would +otherwise be unnecessary.</p> +<p>You can also remove paths by setting the +<a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REMOVE-PATH:CAPS" title="SOUP_AUTH_DOMAIN_REMOVE_PATH"><code class="literal">SOUP_AUTH_DOMAIN_REMOVE_PATH</code></a> property, which can also be used to +remove one or more paths at construct time.</p> +<div class="refsect3"> +<a name="id-1.3.3.9.3.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>path</p></td> +<td class="parameter_description"><p>the path to remove from <em class="parameter"><code>domain</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomainFilter"></a><h3>SoupAuthDomainFilter ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +<span class="c_punctuation">(</span>*SoupAuthDomainFilter<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>The prototype for a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> filter; see +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-set-filter" title="soup_auth_domain_set_filter ()"><code class="function">soup_auth_domain_set_filter()</code></a> for details.</p> +<div class="refsect3"> +<a name="id-1.3.3.9.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the data passed to <a class="link" href="SoupAuthDomain.html#soup-auth-domain-set-filter" title="soup_auth_domain_set_filter ()"><code class="function">soup_auth_domain_set_filter()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.3.9.4.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>msg</code></em> +requires authentication, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if not.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-domain-set-filter"></a><h3>soup_auth_domain_set_filter ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_auth_domain_set_filter (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupAuthDomain.html#SoupAuthDomainFilter" title="SoupAuthDomainFilter ()"><span class="type">SoupAuthDomainFilter</span></a> filter</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> filter_data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> dnotify</code></em>);</pre> +<p>Adds <em class="parameter"><code>filter</code></em> + as an authentication filter to <em class="parameter"><code>domain</code></em> +. The filter +gets a chance to bypass authentication for certain requests that +would otherwise require it. Eg, it might check the message's path +in some way that is too complicated to do via the other methods, or +it might check the message's method, and allow GETs but not PUTs.</p> +<p>The filter function returns <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the request should still +require authentication, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if authentication is unnecessary +for this request.</p> +<p>To help prevent security holes, your filter should return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> by +default, and only return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> under specifically-tested +circumstances, rather than the other way around. Eg, in the example +above, where you want to authenticate PUTs but not GETs, you should +check if the method is GET and return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> in that case, and then +return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> for all other methods (rather than returning <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> for +PUT and <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> for all other methods). This way if it turned out +(now or later) that some paths supported additional methods besides +GET and PUT, those methods would default to being NOT allowed for +unauthenticated users.</p> +<p>You can also set the filter by setting the <a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-FILTER:CAPS" title="SOUP_AUTH_DOMAIN_FILTER"><code class="literal">SOUP_AUTH_DOMAIN_FILTER</code></a> +and <a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-FILTER-DATA:CAPS" title="SOUP_AUTH_DOMAIN_FILTER_DATA"><code class="literal">SOUP_AUTH_DOMAIN_FILTER_DATA</code></a> properties, which can also be +used to set the filter at construct time.</p> +<div class="refsect3"> +<a name="id-1.3.3.9.5.8"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>filter</p></td> +<td class="parameter_description"><p>the auth filter for <em class="parameter"><code>domain</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>filter_data</p></td> +<td class="parameter_description"><p>data to pass to <em class="parameter"><code>filter</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>dnotify</p></td> +<td class="parameter_description"><p>destroy notifier to free <em class="parameter"><code>filter_data</code></em> +when <em class="parameter"><code>domain</code></em> +is destroyed</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-domain-get-realm"></a><h3>soup_auth_domain_get_realm ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_auth_domain_get_realm (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>);</pre> +<p>Gets the realm name associated with <em class="parameter"><code>domain</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.3.9.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.3.9.6.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>domain</code></em> +'s realm</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomainGenericAuthCallback"></a><h3>SoupAuthDomainGenericAuthCallback ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +<span class="c_punctuation">(</span>*SoupAuthDomainGenericAuthCallback<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *username</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>The prototype for a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> generic authentication callback.</p> +<p>The callback should look up the user's password, call +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-check-password" title="soup_auth_domain_check_password ()"><code class="function">soup_auth_domain_check_password()</code></a>, and use the return value from +that method as its own return value.</p> +<p>In general, for security reasons, it is preferable to use the +auth-domain-specific auth callbacks (eg, +<a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasicAuthCallback" title="SoupAuthDomainBasicAuthCallback ()"><span class="type">SoupAuthDomainBasicAuthCallback</span></a> and +<a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigestAuthCallback" title="SoupAuthDomainDigestAuthCallback ()"><span class="type">SoupAuthDomainDigestAuthCallback</span></a>), because they don't require +keeping a cleartext password database. Most users will use the same +password for many different sites, meaning if any site with a +cleartext password database is compromised, accounts on other +servers might be compromised as well. For many of the cases where +<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> is used, this is not really relevant, but it may still +be worth considering.</p> +<div class="refsect3"> +<a name="id-1.3.3.9.7.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> being authenticated</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>username</p></td> +<td class="parameter_description"><p>the username from <em class="parameter"><code>msg</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the data passed to +<a class="link" href="SoupAuthDomain.html#soup-auth-domain-set-generic-auth-callback" title="soup_auth_domain_set_generic_auth_callback ()"><code class="function">soup_auth_domain_set_generic_auth_callback()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.3.9.7.8"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>msg</code></em> +is authenticated, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if not.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-domain-set-generic-auth-callback"></a><h3>soup_auth_domain_set_generic_auth_callback ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_auth_domain_set_generic_auth_callback + (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupAuthDomain.html#SoupAuthDomainGenericAuthCallback" title="SoupAuthDomainGenericAuthCallback ()"><span class="type">SoupAuthDomainGenericAuthCallback</span></a> auth_callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> auth_data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> dnotify</code></em>);</pre> +<p>Sets <em class="parameter"><code>auth_callback</code></em> + as an authentication-handling callback for +<em class="parameter"><code>domain</code></em> +. Whenever a request comes in to <em class="parameter"><code>domain</code></em> + which cannot be +authenticated via a domain-specific auth callback (eg, +<a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigestAuthCallback" title="SoupAuthDomainDigestAuthCallback ()"><span class="type">SoupAuthDomainDigestAuthCallback</span></a>), the generic auth callback +will be invoked. See <a class="link" href="SoupAuthDomain.html#SoupAuthDomainGenericAuthCallback" title="SoupAuthDomainGenericAuthCallback ()"><span class="type">SoupAuthDomainGenericAuthCallback</span></a> for information +on what the callback should do.</p> +<div class="refsect3"> +<a name="id-1.3.3.9.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>auth_callback</p></td> +<td class="parameter_description"><p>the auth callback</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>auth_data</p></td> +<td class="parameter_description"><p>data to pass to <em class="parameter"><code>auth_callback</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>dnotify</p></td> +<td class="parameter_description"><p>destroy notifier to free <em class="parameter"><code>auth_data</code></em> +when <em class="parameter"><code>domain</code></em> +is destroyed</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-domain-check-password"></a><h3>soup_auth_domain_check_password ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_auth_domain_check_password (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *username</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *password</code></em>);</pre> +<p>Checks if <em class="parameter"><code>msg</code></em> + authenticates to <em class="parameter"><code>domain</code></em> + via <em class="parameter"><code>username</code></em> + and +<em class="parameter"><code>password</code></em> +. This would normally be called from a +<a class="link" href="SoupAuthDomain.html#SoupAuthDomainGenericAuthCallback" title="SoupAuthDomainGenericAuthCallback ()"><span class="type">SoupAuthDomainGenericAuthCallback</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.3.9.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>username</p></td> +<td class="parameter_description"><p>a username</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>password</p></td> +<td class="parameter_description"><p>a password</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.3.9.9.6"></a><h4>Returns</h4> +<p> whether or not the message is authenticated</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-domain-covers"></a><h3>soup_auth_domain_covers ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_auth_domain_covers (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Checks if <em class="parameter"><code>domain</code></em> + requires <em class="parameter"><code>msg</code></em> + to be authenticated (according to +its paths and filter function). This does not actually look at +whether <em class="parameter"><code>msg</code></em> + <span class="emphasis"><em>is</em></span> authenticated, merely whether +or not it needs to be.</p> +<p>This is used by <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> internally and is probably of no use to +anyone else.</p> +<div class="refsect3"> +<a name="id-1.3.3.9.10.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.3.9.10.7"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>domain</code></em> +requires <em class="parameter"><code>msg</code></em> +to be authenticated</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-domain-accepts"></a><h3>soup_auth_domain_accepts ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_auth_domain_accepts (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Checks if <em class="parameter"><code>msg</code></em> + contains appropriate authorization for <em class="parameter"><code>domain</code></em> + to +accept it. Mirroring <a class="link" href="SoupAuthDomain.html#soup-auth-domain-covers" title="soup_auth_domain_covers ()"><code class="function">soup_auth_domain_covers()</code></a>, this does not check +whether or not <em class="parameter"><code>domain</code></em> + <span class="emphasis"><em>cares</em></span> if <em class="parameter"><code>msg</code></em> + is +authorized.</p> +<p>This is used by <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> internally and is probably of no use to +anyone else.</p> +<div class="refsect3"> +<a name="id-1.3.3.9.11.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.3.9.11.7"></a><h4>Returns</h4> +<p> the username that <em class="parameter"><code>msg</code></em> +has authenticated as, if in +fact it has authenticated. <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> otherwise.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-domain-challenge"></a><h3>soup_auth_domain_challenge ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_auth_domain_challenge (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to <em class="parameter"><code>msg</code></em> +, +requesting that the client authenticate, and sets <em class="parameter"><code>msg</code></em> +'s status +accordingly.</p> +<p>This is used by <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> internally and is probably of no use to +anyone else.</p> +<div class="refsect3"> +<a name="id-1.3.3.9.12.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomain.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupAuthDomain-struct"></a><h3>SoupAuthDomain</h3> +<pre class="programlisting">typedef struct _SoupAuthDomain SoupAuthDomain;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-REALM:CAPS"></a><h3>SOUP_AUTH_DOMAIN_REALM</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_REALM "realm" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomain.html#SoupAuthDomain--realm" title="The “realm” property"><span class="type">“realm”</span></a> property. (The realm of +this auth domain.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-PROXY:CAPS"></a><h3>SOUP_AUTH_DOMAIN_PROXY</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_PROXY "proxy" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomain.html#SoupAuthDomain--proxy" title="The “proxy” property"><span class="type">“proxy”</span></a> property. (Whether or +not this is a proxy auth domain.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-ADD-PATH:CAPS"></a><h3>SOUP_AUTH_DOMAIN_ADD_PATH</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_ADD_PATH "add-path" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomain.html#SoupAuthDomain--add-path" title="The “add-path” property"><span class="type">“add-path”</span></a> property. (Shortcut +for calling <a class="link" href="SoupAuthDomain.html#soup-auth-domain-add-path" title="soup_auth_domain_add_path ()"><code class="function">soup_auth_domain_add_path()</code></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-REMOVE-PATH:CAPS"></a><h3>SOUP_AUTH_DOMAIN_REMOVE_PATH</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_REMOVE_PATH "remove-path" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomain.html#SoupAuthDomain--remove-path" title="The “remove-path” property"><span class="type">“remove-path”</span></a> property. +(Shortcut for calling <a class="link" href="SoupAuthDomain.html#soup-auth-domain-remove-path" title="soup_auth_domain_remove_path ()"><code class="function">soup_auth_domain_remove_path()</code></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-FILTER:CAPS"></a><h3>SOUP_AUTH_DOMAIN_FILTER</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_FILTER "filter" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomain.html#SoupAuthDomain--filter" title="The “filter” property"><span class="type">“filter”</span></a> property. (The +<a class="link" href="SoupAuthDomain.html#SoupAuthDomainFilter" title="SoupAuthDomainFilter ()"><span class="type">SoupAuthDomainFilter</span></a> for the domain.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-FILTER-DATA:CAPS"></a><h3>SOUP_AUTH_DOMAIN_FILTER_DATA</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_FILTER_DATA "filter-data" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomain.html#SoupAuthDomain--filter-data" title="The “filter-data” property"><span class="type">“filter-data”</span></a> property. (Data +to pass to the <a class="link" href="SoupAuthDomain.html#SoupAuthDomainFilter" title="SoupAuthDomainFilter ()"><span class="type">SoupAuthDomainFilter</span></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-GENERIC-AUTH-CALLBACK:CAPS"></a><h3>SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK "generic-auth-callback" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomain.html#SoupAuthDomain--generic-auth-callback" title="The “generic-auth-callback” property"><span class="type">“generic-auth-callback”</span></a> property. +(The <a class="link" href="SoupAuthDomain.html#SoupAuthDomainGenericAuthCallback" title="SoupAuthDomainGenericAuthCallback ()"><span class="type">SoupAuthDomainGenericAuthCallback</span></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-GENERIC-AUTH-DATA:CAPS"></a><h3>SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA "generic-auth-data" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomain.html#SoupAuthDomain--generic-auth-data" title="The “generic-auth-data” property"><span class="type">“generic-auth-data”</span></a> property. +(The data to pass to the <a class="link" href="SoupAuthDomain.html#SoupAuthDomainGenericAuthCallback" title="SoupAuthDomainGenericAuthCallback ()"><span class="type">SoupAuthDomainGenericAuthCallback</span></a>.)</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomain.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupAuthDomain--add-path"></a><h3>The <code class="literal">“add-path”</code> property</h3> +<pre class="programlisting"> “add-path” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>Add a path covered by this auth domain.</p> +<p>Flags: Write</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomain--filter"></a><h3>The <code class="literal">“filter”</code> property</h3> +<pre class="programlisting"> “filter” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>A filter for deciding whether or not to require authentication.</p> +<p>Flags: Read / Write</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomain--filter-data"></a><h3>The <code class="literal">“filter-data”</code> property</h3> +<pre class="programlisting"> “filter-data” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>Data to pass to filter.</p> +<p>Flags: Read / Write</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomain--generic-auth-callback"></a><h3>The <code class="literal">“generic-auth-callback”</code> property</h3> +<pre class="programlisting"> “generic-auth-callback” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>An authentication callback that can be used with any SoupAuthDomain subclass.</p> +<p>Flags: Read / Write</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomain--generic-auth-data"></a><h3>The <code class="literal">“generic-auth-data”</code> property</h3> +<pre class="programlisting"> “generic-auth-data” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>Data to pass to auth callback.</p> +<p>Flags: Read / Write</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomain--proxy"></a><h3>The <code class="literal">“proxy”</code> property</h3> +<pre class="programlisting"> “proxy” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Whether or not this is a proxy auth domain.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: FALSE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomain--realm"></a><h3>The <code class="literal">“realm”</code> property</h3> +<pre class="programlisting"> “realm” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>The realm of this auth domain.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomain--remove-path"></a><h3>The <code class="literal">“remove-path”</code> property</h3> +<pre class="programlisting"> “remove-path” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>Remove a path covered by this auth domain.</p> +<p>Flags: Write</p> +<p>Default value: NULL</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomain.see-also"></a><h2>See Also</h2> +<p><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupAuthDomainBasic.html b/docs/reference/html/SoupAuthDomainBasic.html new file mode 100644 index 00000000..ba7874fb --- /dev/null +++ b/docs/reference/html/SoupAuthDomainBasic.html @@ -0,0 +1,344 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupAuthDomainBasic</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupAuthDomain.html" title="SoupAuthDomain"> +<link rel="next" href="SoupAuthDomainDigest.html" title="SoupAuthDomainDigest"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupAuthDomainBasic.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupAuthDomainBasic.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupAuthDomainBasic.properties" class="shortcut">Properties</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupAuthDomain.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupAuthDomainDigest.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupAuthDomainBasic"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupAuthDomainBasic.top_of_page"></a>SoupAuthDomainBasic</span></h2> +<p>SoupAuthDomainBasic — Server-side "Basic" authentication</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupAuthDomainBasic.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="returnvalue">SoupAuthDomain</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomainBasic.html#soup-auth-domain-basic-new" title="soup_auth_domain_basic_new ()">soup_auth_domain_basic_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasicAuthCallback" title="SoupAuthDomainBasicAuthCallback ()">*SoupAuthDomainBasicAuthCallback</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomainBasic.html#soup-auth-domain-basic-set-auth-callback" title="soup_auth_domain_basic_set_auth_callback ()">soup_auth_domain_basic_set_auth_callback</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainBasic.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasic--auth-callback" title="The “auth-callback” property">auth-callback</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasic--auth-data" title="The “auth-data” property">auth-data</a></td> +<td class="property_flags">Read / Write</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainBasic.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasic-struct" title="SoupAuthDomainBasic">SoupAuthDomainBasic</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-CALLBACK:CAPS" title="SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK">SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-DATA:CAPS" title="SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA">SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainBasic.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain">SoupAuthDomain</a> + <span class="lineart">╰──</span> SoupAuthDomainBasic +</pre> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainBasic.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainBasic.description"></a><h2>Description</h2> +<p><a class="link" href="SoupAuthDomainBasic.html" title="SoupAuthDomainBasic"><span class="type">SoupAuthDomainBasic</span></a> handles the server side of HTTP "Basic" (ie, +cleartext password) authentication.</p> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainBasic.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-auth-domain-basic-new"></a><h3>soup_auth_domain_basic_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="returnvalue">SoupAuthDomain</span></a> * +soup_auth_domain_basic_new (<em class="parameter"><code>const <span class="type">char</span> *optname1</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Creates a <a class="link" href="SoupAuthDomainBasic.html" title="SoupAuthDomainBasic"><span class="type">SoupAuthDomainBasic</span></a>. You must set the +<a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REALM:CAPS" title="SOUP_AUTH_DOMAIN_REALM"><code class="literal">SOUP_AUTH_DOMAIN_REALM</code></a> parameter, to indicate the realm name to be +returned with the authentication challenge to the client. Other +parameters are optional.</p> +<div class="refsect3"> +<a name="id-1.3.4.9.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>optname1</p></td> +<td class="parameter_description"><p>name of first option, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>option name/value pairs</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.4.9.2.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomainBasicAuthCallback"></a><h3>SoupAuthDomainBasicAuthCallback ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +<span class="c_punctuation">(</span>*SoupAuthDomainBasicAuthCallback<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *username</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *password</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Callback used by <a class="link" href="SoupAuthDomainBasic.html" title="SoupAuthDomainBasic"><span class="type">SoupAuthDomainBasic</span></a> for authentication purposes. +The application should verify that <em class="parameter"><code>username</code></em> + and <em class="parameter"><code>password</code></em> + and valid +and return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>.</p> +<p>If you are maintaining your own password database (rather than +using the password to authenticate against some other system like +PAM or a remote server), you should make sure you know what you are +doing. In particular, don't store cleartext passwords, or +easily-computed hashes of cleartext passwords, even if you don't +care that much about the security of your server, because users +will frequently use the same password for multiple sites, and so +compromising any site with a cleartext (or easily-cracked) password +database may give attackers access to other more-interesting sites +as well.</p> +<div class="refsect3"> +<a name="id-1.3.4.9.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>the domain</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message being authenticated</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>username</p></td> +<td class="parameter_description"><p>the username provided by the client</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>password</p></td> +<td class="parameter_description"><p>the password provided by the client</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the data passed to <a class="link" href="SoupAuthDomainBasic.html#soup-auth-domain-basic-set-auth-callback" title="soup_auth_domain_basic_set_auth_callback ()"><code class="function">soup_auth_domain_basic_set_auth_callback()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.4.9.3.7"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>username</code></em> +and <em class="parameter"><code>password</code></em> +are valid</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-domain-basic-set-auth-callback"></a><h3>soup_auth_domain_basic_set_auth_callback ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_auth_domain_basic_set_auth_callback + (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasicAuthCallback" title="SoupAuthDomainBasicAuthCallback ()"><span class="type">SoupAuthDomainBasicAuthCallback</span></a> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> dnotify</code></em>);</pre> +<p>Sets the callback that <em class="parameter"><code>domain</code></em> + will use to authenticate incoming +requests. For each request containing authorization, <em class="parameter"><code>domain</code></em> + will +invoke the callback, and then either accept or reject the request +based on <em class="parameter"><code>callback</code></em> +'s return value.</p> +<p>You can also set the auth callback by setting the +<a class="link" href="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-CALLBACK:CAPS" title="SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK"><code class="literal">SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK</code></a> and +<a class="link" href="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-DATA:CAPS" title="SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA"><code class="literal">SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA</code></a> properties, which can also be +used to set the callback at construct time.</p> +<div class="refsect3"> +<a name="id-1.3.4.9.4.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>the domain</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p>the callback</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>data to pass to <em class="parameter"><code>auth_callback</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>dnotify</p></td> +<td class="parameter_description"><p>destroy notifier to free <em class="parameter"><code>user_data</code></em> +when <em class="parameter"><code>domain</code></em> +is destroyed</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainBasic.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupAuthDomainBasic-struct"></a><h3>SoupAuthDomainBasic</h3> +<pre class="programlisting">typedef struct _SoupAuthDomainBasic SoupAuthDomainBasic;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-BASIC-AUTH-CALLBACK:CAPS"></a><h3>SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK "auth-callback" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasic--auth-callback" title="The “auth-callback” property"><span class="type">“auth-callback”</span></a> property. +(The <a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasicAuthCallback" title="SoupAuthDomainBasicAuthCallback ()"><span class="type">SoupAuthDomainBasicAuthCallback</span></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-BASIC-AUTH-DATA:CAPS"></a><h3>SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA "auth-data" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasic--auth-data" title="The “auth-data” property"><span class="type">“auth-data”</span></a> property. +(The data to pass to the <a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasicAuthCallback" title="SoupAuthDomainBasicAuthCallback ()"><span class="type">SoupAuthDomainBasicAuthCallback</span></a>.)</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainBasic.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupAuthDomainBasic--auth-callback"></a><h3>The <code class="literal">“auth-callback”</code> property</h3> +<pre class="programlisting"> “auth-callback” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>Password-checking callback.</p> +<p>Flags: Read / Write</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomainBasic--auth-data"></a><h3>The <code class="literal">“auth-data”</code> property</h3> +<pre class="programlisting"> “auth-data” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>Data to pass to authentication callback.</p> +<p>Flags: Read / Write</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupAuthDomainDigest.html b/docs/reference/html/SoupAuthDomainDigest.html new file mode 100644 index 00000000..90f63fc8 --- /dev/null +++ b/docs/reference/html/SoupAuthDomainDigest.html @@ -0,0 +1,395 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupAuthDomainDigest</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupAuthDomainBasic.html" title="SoupAuthDomainBasic"> +<link rel="next" href="SoupCache.html" title="SoupCache"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupAuthDomainDigest.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupAuthDomainDigest.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupAuthDomainDigest.properties" class="shortcut">Properties</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupAuthDomainBasic.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupCache.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupAuthDomainDigest"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupAuthDomainDigest.top_of_page"></a>SoupAuthDomainDigest</span></h2> +<p>SoupAuthDomainDigest — Server-side "Digest" authentication</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupAuthDomainDigest.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="returnvalue">SoupAuthDomain</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomainDigest.html#soup-auth-domain-digest-new" title="soup_auth_domain_digest_new ()">soup_auth_domain_digest_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigestAuthCallback" title="SoupAuthDomainDigestAuthCallback ()">*SoupAuthDomainDigestAuthCallback</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomainDigest.html#soup-auth-domain-digest-set-auth-callback" title="soup_auth_domain_digest_set_auth_callback ()">soup_auth_domain_digest_set_auth_callback</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupAuthDomainDigest.html#soup-auth-domain-digest-encode-password" title="soup_auth_domain_digest_encode_password ()">soup_auth_domain_digest_encode_password</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainDigest.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigest--auth-callback" title="The “auth-callback” property">auth-callback</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigest--auth-data" title="The “auth-data” property">auth-data</a></td> +<td class="property_flags">Read / Write</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainDigest.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigest-struct" title="SoupAuthDomainDigest">SoupAuthDomainDigest</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomainDigest.html#SOUP-AUTH-DOMAIN-DIGEST-AUTH-CALLBACK:CAPS" title="SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK">SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthDomainDigest.html#SOUP-AUTH-DOMAIN-DIGEST-AUTH-DATA:CAPS" title="SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA">SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainDigest.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain">SoupAuthDomain</a> + <span class="lineart">╰──</span> SoupAuthDomainDigest +</pre> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainDigest.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainDigest.description"></a><h2>Description</h2> +<p><a class="link" href="SoupAuthDomainDigest.html" title="SoupAuthDomainDigest"><span class="type">SoupAuthDomainDigest</span></a> handles the server side of HTTP "Digest" +authentication.</p> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainDigest.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-auth-domain-digest-new"></a><h3>soup_auth_domain_digest_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="returnvalue">SoupAuthDomain</span></a> * +soup_auth_domain_digest_new (<em class="parameter"><code>const <span class="type">char</span> *optname1</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Creates a <a class="link" href="SoupAuthDomainDigest.html" title="SoupAuthDomainDigest"><span class="type">SoupAuthDomainDigest</span></a>. You must set the +<a class="link" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REALM:CAPS" title="SOUP_AUTH_DOMAIN_REALM"><code class="literal">SOUP_AUTH_DOMAIN_REALM</code></a> parameter, to indicate the realm name to be +returned with the authentication challenge to the client. Other +parameters are optional.</p> +<div class="refsect3"> +<a name="id-1.3.5.9.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>optname1</p></td> +<td class="parameter_description"><p>name of first option, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>option name/value pairs</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.5.9.2.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomainDigestAuthCallback"></a><h3>SoupAuthDomainDigestAuthCallback ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +<span class="c_punctuation">(</span>*SoupAuthDomainDigestAuthCallback<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *username</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Callback used by <a class="link" href="SoupAuthDomainDigest.html" title="SoupAuthDomainDigest"><span class="type">SoupAuthDomainDigest</span></a> for authentication purposes. +The application should look up <em class="parameter"><code>username</code></em> + in its password database, +and return the corresponding encoded password (see +<a class="link" href="SoupAuthDomainDigest.html#soup-auth-domain-digest-encode-password" title="soup_auth_domain_digest_encode_password ()"><code class="function">soup_auth_domain_digest_encode_password()</code></a>).</p> +<div class="refsect3"> +<a name="id-1.3.5.9.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>the domain</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message being authenticated</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>username</p></td> +<td class="parameter_description"><p>the username provided by the client</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the data passed to <a class="link" href="SoupAuthDomainDigest.html#soup-auth-domain-digest-set-auth-callback" title="soup_auth_domain_digest_set_auth_callback ()"><code class="function">soup_auth_domain_digest_set_auth_callback()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.5.9.3.6"></a><h4>Returns</h4> +<p> the encoded password, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if <em class="parameter"><code>username</code></em> +is not a +valid user. <em class="parameter"><code>domain</code></em> +will free the password when it is done with it.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-domain-digest-set-auth-callback"></a><h3>soup_auth_domain_digest_set_auth_callback ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_auth_domain_digest_set_auth_callback + (<em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *domain</code></em>, + <em class="parameter"><code><a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigestAuthCallback" title="SoupAuthDomainDigestAuthCallback ()"><span class="type">SoupAuthDomainDigestAuthCallback</span></a> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> dnotify</code></em>);</pre> +<p>Sets the callback that <em class="parameter"><code>domain</code></em> + will use to authenticate incoming +requests. For each request containing authorization, <em class="parameter"><code>domain</code></em> + will +invoke the callback, and then either accept or reject the request +based on <em class="parameter"><code>callback</code></em> +'s return value.</p> +<p>You can also set the auth callback by setting the +<a class="link" href="SoupAuthDomainDigest.html#SOUP-AUTH-DOMAIN-DIGEST-AUTH-CALLBACK:CAPS" title="SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK"><code class="literal">SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK</code></a> and +<a class="link" href="SoupAuthDomainDigest.html#SOUP-AUTH-DOMAIN-DIGEST-AUTH-DATA:CAPS" title="SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA"><code class="literal">SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA</code></a> properties, which can also be +used to set the callback at construct time.</p> +<div class="refsect3"> +<a name="id-1.3.5.9.4.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>the domain</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p>the callback</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>data to pass to <em class="parameter"><code>auth_callback</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>dnotify</p></td> +<td class="parameter_description"><p>destroy notifier to free <em class="parameter"><code>user_data</code></em> +when <em class="parameter"><code>domain</code></em> +is destroyed</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-domain-digest-encode-password"></a><h3>soup_auth_domain_digest_encode_password ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_auth_domain_digest_encode_password + (<em class="parameter"><code>const <span class="type">char</span> *username</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *realm</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *password</code></em>);</pre> +<p>Encodes the username/realm/password triplet for Digest +authentication. (That is, it returns a stringified MD5 hash of +<em class="parameter"><code>username</code></em> +, <em class="parameter"><code>realm</code></em> +, and <em class="parameter"><code>password</code></em> + concatenated together). This is +the form that is needed as the return value of +<a class="link" href="SoupAuthDomainDigest.html" title="SoupAuthDomainDigest"><span class="type">SoupAuthDomainDigest</span></a>'s auth handler.</p> +<p>For security reasons, you should store the encoded hash, rather +than storing the cleartext password itself and calling this method +only when you need to verify it. This way, if your server is +compromised, the attackers will not gain access to cleartext +passwords which might also be usable at other sites. (Note also +that the encoded password returned by this method is identical to +the encoded password stored in an Apache .htdigest file.)</p> +<div class="refsect3"> +<a name="id-1.3.5.9.5.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>username</p></td> +<td class="parameter_description"><p>a username</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>realm</p></td> +<td class="parameter_description"><p>an auth realm name</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>password</p></td> +<td class="parameter_description"><p>the password for <em class="parameter"><code>username</code></em> +in <em class="parameter"><code>realm</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.5.9.5.7"></a><h4>Returns</h4> +<p> the encoded password</p> +<p></p> +</div> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainDigest.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupAuthDomainDigest-struct"></a><h3>SoupAuthDomainDigest</h3> +<pre class="programlisting">typedef struct _SoupAuthDomainDigest SoupAuthDomainDigest;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-DIGEST-AUTH-CALLBACK:CAPS"></a><h3>SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK "auth-callback" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigest--auth-callback" title="The “auth-callback” property"><span class="type">“auth-callback”</span></a> property. +(The <a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigestAuthCallback" title="SoupAuthDomainDigestAuthCallback ()"><span class="type">SoupAuthDomainDigestAuthCallback</span></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-AUTH-DOMAIN-DIGEST-AUTH-DATA:CAPS"></a><h3>SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA</h3> +<pre class="programlisting">#define SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA "auth-data" +</pre> +<p>Alias for the <a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigest--auth-callback" title="The “auth-callback” property"><span class="type">“auth-callback”</span></a> property. +(The <a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigestAuthCallback" title="SoupAuthDomainDigestAuthCallback ()"><span class="type">SoupAuthDomainDigestAuthCallback</span></a>.)</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuthDomainDigest.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupAuthDomainDigest--auth-callback"></a><h3>The <code class="literal">“auth-callback”</code> property</h3> +<pre class="programlisting"> “auth-callback” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>Password-finding callback.</p> +<p>Flags: Read / Write</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupAuthDomainDigest--auth-data"></a><h3>The <code class="literal">“auth-data”</code> property</h3> +<pre class="programlisting"> “auth-data” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>Data to pass to authentication callback.</p> +<p>Flags: Read / Write</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupAuthManager.html b/docs/reference/html/SoupAuthManager.html new file mode 100644 index 00000000..537ce8ee --- /dev/null +++ b/docs/reference/html/SoupAuthManager.html @@ -0,0 +1,252 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupAuthManager</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch03.html" title="Additional Features"> +<link rel="prev" href="SoupSessionFeature.html" title="SoupSessionFeature"> +<link rel="next" href="SoupContentDecoder.html" title="SoupContentDecoder"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupAuthManager.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupAuthManager.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupAuthManager.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span><span id="nav_signals"> <span class="dim">|</span> + <a href="#SoupAuthManager.signals" class="shortcut">Signals</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupSessionFeature.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupContentDecoder.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupAuthManager"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupAuthManager.top_of_page"></a>SoupAuthManager</span></h2> +<p>SoupAuthManager — HTTP client-side authentication handler</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupAuthManager.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupAuthManager.html#SOUP-TYPE-AUTH-MANAGER:CAPS" title="SOUP_TYPE_AUTH_MANAGER">SOUP_TYPE_AUTH_MANAGER</a></td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupAuthManager.html#soup-auth-manager-use-auth" title="soup_auth_manager_use_auth ()">soup_auth_manager_use_auth</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthManager.signals"></a><h2>Signals</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="signals_return"> +<col width="300px" class="signals_name"> +<col width="200px" class="signals_flags"> +</colgroup> +<tbody><tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupAuthManager.html#SoupAuthManager-authenticate" title="The “authenticate” signal">authenticate</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthManager.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupAuthManager.html#SoupAuthManager-struct" title="SoupAuthManager">SoupAuthManager</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupAuthManager.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupAuthManager +</pre> +</div> +<div class="refsect1"> +<a name="SoupAuthManager.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupAuthManager implements + <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature">SoupSessionFeature</a>.</p> +</div> +<div class="refsect1"> +<a name="SoupAuthManager.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupAuthManager.description"></a><h2>Description</h2> +<p><a class="link" href="SoupAuthManager.html" title="SoupAuthManager"><span class="type">SoupAuthManager</span></a> is the <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a> that handles HTTP +authentication for a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>.</p> +<p>A <a class="link" href="SoupAuthManager.html" title="SoupAuthManager"><span class="type">SoupAuthManager</span></a> is added to the session by default, and normally +you don't need to worry about it at all. However, if you want to +disable HTTP authentication, you can remove the feature from the +session with <a class="link" href="SoupSession.html#soup-session-remove-feature-by-type" title="soup_session_remove_feature_by_type ()"><code class="function">soup_session_remove_feature_by_type()</code></a>, or disable it on +individual requests with <a class="link" href="SoupMessage.html#soup-message-disable-feature" title="soup_message_disable_feature ()"><code class="function">soup_message_disable_feature()</code></a>.</p> +</div> +<div class="refsect1"> +<a name="SoupAuthManager.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="SOUP-TYPE-AUTH-MANAGER:CAPS"></a><h3>SOUP_TYPE_AUTH_MANAGER</h3> +<pre class="programlisting">#define SOUP_TYPE_AUTH_MANAGER (soup_auth_manager_get_type ()) +</pre> +<p>The <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> of <a class="link" href="SoupAuthManager.html" title="SoupAuthManager"><span class="type">SoupAuthManager</span></a>; you can use this with +<a class="link" href="SoupSession.html#soup-session-remove-feature-by-type" title="soup_session_remove_feature_by_type ()"><code class="function">soup_session_remove_feature_by_type()</code></a> or +<a class="link" href="SoupMessage.html#soup-message-disable-feature" title="soup_message_disable_feature ()"><code class="function">soup_message_disable_feature()</code></a>.</p> +<p>(Although this type has only been publicly visible since libsoup +2.42, it has always existed in the background, and you can use +<code class="literal"><code class="code">g_type_from_name ("SoupAuthManager")</code></code> +to get its <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> in earlier releases.)</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-auth-manager-use-auth"></a><h3>soup_auth_manager_use_auth ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_auth_manager_use_auth (<em class="parameter"><code><a class="link" href="SoupAuthManager.html" title="SoupAuthManager"><span class="type">SoupAuthManager</span></a> *manager</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code><a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth</code></em>);</pre> +<p>Records that <em class="parameter"><code>auth</code></em> + is to be used under <em class="parameter"><code>uri</code></em> +, as though a +WWW-Authenticate header had been received at that URI. This can be +used to "preload" <em class="parameter"><code>manager</code></em> +'s auth cache, to avoid an extra HTTP +round trip in the case where you know ahead of time that a 401 +response will be returned.</p> +<p>This is only useful for authentication types where the initial +Authorization header does not depend on any additional information +from the server. (Eg, Basic or NTLM, but not Digest.)</p> +<div class="refsect3"> +<a name="id-1.4.3.10.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>manager</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthManager.html" title="SoupAuthManager"><span class="type">SoupAuthManager</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> under which <em class="parameter"><code>auth</code></em> +is to be used</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> to use</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.42</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuthManager.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupAuthManager-struct"></a><h3>SoupAuthManager</h3> +<pre class="programlisting">typedef struct _SoupAuthManager SoupAuthManager;</pre> +<p> +</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuthManager.signal-details"></a><h2>Signal Details</h2> +<div class="refsect2"> +<a name="SoupAuthManager-authenticate"></a><h3>The <code class="literal">“authenticate”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupAuthManager.html" title="SoupAuthManager"><span class="type">SoupAuthManager</span></a> *manager, + <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> retrying, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when the manager requires the application to +provide authentication credentials.</p> +<p><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> connects to this signal and emits its own +<a class="link" href="SoupSession.html#SoupSession-authenticate" title="The “authenticate” signal"><span class="type">“authenticate”</span></a> signal when it is emitted, so +you shouldn't need to use this signal directly.</p> +<div class="refsect3"> +<a name="id-1.4.3.12.2.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>manager</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupAuthManager.html" title="SoupAuthManager"><span class="type">SoupAuthManager</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> being sent</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> to authenticate</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>retrying</p></td> +<td class="parameter_description"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if this is the second (or later) attempt</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +</div> +<div class="refsect1"> +<a name="SoupAuthManager.see-also"></a><h2>See Also</h2> +<p><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a></p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupCache.html b/docs/reference/html/SoupCache.html new file mode 100644 index 00000000..31aeacf0 --- /dev/null +++ b/docs/reference/html/SoupCache.html @@ -0,0 +1,433 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupCache</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupAuthDomainDigest.html" title="SoupAuthDomainDigest"> +<link rel="next" href="SoupCookie.html" title="SoupCookie"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupCache.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupCache.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupCache.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupCache.properties" class="shortcut">Properties</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupAuthDomainDigest.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupCookie.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupCache"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupCache.top_of_page"></a>SoupCache</span></h2> +<p>SoupCache — Caching support</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupCache.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupCache.html" title="SoupCache"><span class="returnvalue">SoupCache</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCache.html#soup-cache-new" title="soup_cache_new ()">soup_cache_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCache.html#soup-cache-flush" title="soup_cache_flush ()">soup_cache_flush</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCache.html#soup-cache-clear" title="soup_cache_clear ()">soup_cache_clear</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCache.html#soup-cache-dump" title="soup_cache_dump ()">soup_cache_dump</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCache.html#soup-cache-load" title="soup_cache_load ()">soup_cache_load</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupCache.html#soup-cache-get-max-size" title="soup_cache_get_max_size ()">soup_cache_get_max_size</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCache.html#soup-cache-set-max-size" title="soup_cache_set_max_size ()">soup_cache_set_max_size</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCache.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupCache.html#SoupCache--cache-dir" title="The “cache-dir” property">cache-dir</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a class="link" href="SoupCache.html#SoupCacheType" title="enum SoupCacheType"><span class="type">SoupCacheType</span></a></td> +<td class="property_name"><a class="link" href="SoupCache.html#SoupCache--cache-type" title="The “cache-type” property">cache-type</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCache.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword">struct</td> +<td class="function_name"><a class="link" href="SoupCache.html#SoupCache-struct" title="struct SoupCache">SoupCache</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupCache.html#SoupCacheType" title="enum SoupCacheType">SoupCacheType</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCache.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupCache +</pre> +</div> +<div class="refsect1"> +<a name="SoupCache.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupCache implements + <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature">SoupSessionFeature</a> and SoupContentProcessor.</p> +</div> +<div class="refsect1"> +<a name="SoupCache.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupCache.description"></a><h2>Description</h2> +<p><a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a> implements a file-based cache for HTTP resources.</p> +</div> +<div class="refsect1"> +<a name="SoupCache.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-cache-new"></a><h3>soup_cache_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupCache.html" title="SoupCache"><span class="returnvalue">SoupCache</span></a> * +soup_cache_new (<em class="parameter"><code>const <span class="type">char</span> *cache_dir</code></em>, + <em class="parameter"><code><a class="link" href="SoupCache.html#SoupCacheType" title="enum SoupCacheType"><span class="type">SoupCacheType</span></a> cache_type</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.6.10.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cache_dir</p></td> +<td class="parameter_description"><p>the directory to store the cached data, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to use the default one</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cache_type</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupCache.html#SoupCacheType" title="enum SoupCacheType"><span class="type">SoupCacheType</span></a> of the cache</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.6.10.2.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a></p> +<p></p> +</div> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cache-flush"></a><h3>soup_cache_flush ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cache_flush (<em class="parameter"><code><a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a> *cache</code></em>);</pre> +<p>This function will force all pending writes in the <em class="parameter"><code>cache</code></em> + to be +committed to disk. For doing so it will iterate the <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> +associated with <em class="parameter"><code>cache</code></em> +'s session as long as needed.</p> +<p>Contrast with <a class="link" href="SoupCache.html#soup-cache-dump" title="soup_cache_dump ()"><code class="function">soup_cache_dump()</code></a>, which writes out the cache index +file.</p> +<div class="refsect3"> +<a name="id-1.3.6.10.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cache</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cache-clear"></a><h3>soup_cache_clear ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cache_clear (<em class="parameter"><code><a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a> *cache</code></em>);</pre> +<p>Will remove all entries in the <em class="parameter"><code>cache</code></em> + plus all the cache files.</p> +<div class="refsect3"> +<a name="id-1.3.6.10.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cache</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cache-dump"></a><h3>soup_cache_dump ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cache_dump (<em class="parameter"><code><a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a> *cache</code></em>);</pre> +<p>Synchronously writes the cache index out to disk. Contrast with +<a class="link" href="SoupCache.html#soup-cache-flush" title="soup_cache_flush ()"><code class="function">soup_cache_flush()</code></a>, which writes pending cache +<span class="emphasis"><em>entries</em></span> to disk.</p> +<p>You must call this before exiting if you want your cache data to +persist between sessions.</p> +<div class="refsect3"> +<a name="id-1.3.6.10.5.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cache</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<p class="since">Since 2.34.</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cache-load"></a><h3>soup_cache_load ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cache_load (<em class="parameter"><code><a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a> *cache</code></em>);</pre> +<p>Loads the contents of <em class="parameter"><code>cache</code></em> +'s index into memory.</p> +<div class="refsect3"> +<a name="id-1.3.6.10.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cache</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cache-get-max-size"></a><h3>soup_cache_get_max_size ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_cache_get_max_size (<em class="parameter"><code><a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a> *cache</code></em>);</pre> +<p>Gets the maximum size of the cache.</p> +<div class="refsect3"> +<a name="id-1.3.6.10.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cache</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.6.10.7.6"></a><h4>Returns</h4> +<p> the maximum size of the cache, in bytes.</p> +<p></p> +</div> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cache-set-max-size"></a><h3>soup_cache_set_max_size ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cache_set_max_size (<em class="parameter"><code><a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a> *cache</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> max_size</code></em>);</pre> +<p>Sets the maximum size of the cache.</p> +<div class="refsect3"> +<a name="id-1.3.6.10.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cache</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCache.html" title="SoupCache"><span class="type">SoupCache</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>max_size</p></td> +<td class="parameter_description"><p>the maximum size of the cache, in bytes</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.34</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupCache.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupCache-struct"></a><h3>struct SoupCache</h3> +<pre class="programlisting">struct SoupCache;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupCacheType"></a><h3>enum SoupCacheType</h3> +<p>The type of cache; this affects what kinds of responses will be +saved.</p> +<div class="refsect3"> +<a name="id-1.3.6.11.3.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-CACHE-SINGLE-USER:CAPS"></a>SOUP_CACHE_SINGLE_USER</p></td> +<td class="enum_member_description"> +<p>a single-user cache</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-CACHE-SHARED:CAPS"></a>SOUP_CACHE_SHARED</p></td> +<td class="enum_member_description"> +<p>a shared cache</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.34</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupCache.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupCache--cache-dir"></a><h3>The <code class="literal">“cache-dir”</code> property</h3> +<pre class="programlisting"> “cache-dir” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>The directory to store the cache files.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupCache--cache-type"></a><h3>The <code class="literal">“cache-type”</code> property</h3> +<pre class="programlisting"> “cache-type” <a class="link" href="SoupCache.html#SoupCacheType" title="enum SoupCacheType"><span class="type">SoupCacheType</span></a></pre> +<p>Whether the cache is private or shared.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: SOUP_CACHE_SINGLE_USER</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupContentDecoder.html b/docs/reference/html/SoupContentDecoder.html new file mode 100644 index 00000000..27875a03 --- /dev/null +++ b/docs/reference/html/SoupContentDecoder.html @@ -0,0 +1,110 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupContentDecoder</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch03.html" title="Additional Features"> +<link rel="prev" href="SoupAuthManager.html" title="SoupAuthManager"> +<link rel="next" href="SoupContentSniffer.html" title="SoupContentSniffer"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupContentDecoder.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupContentDecoder.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupContentDecoder.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupAuthManager.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupContentSniffer.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupContentDecoder"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupContentDecoder.top_of_page"></a>SoupContentDecoder</span></h2> +<p>SoupContentDecoder — Content-Encoding handler</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupContentDecoder.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupContentDecoder.html#SoupContentDecoder-struct" title="SoupContentDecoder">SoupContentDecoder</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupContentDecoder.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupContentDecoder +</pre> +</div> +<div class="refsect1"> +<a name="SoupContentDecoder.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupContentDecoder implements + <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature">SoupSessionFeature</a> and SoupContentProcessor.</p> +</div> +<div class="refsect1"> +<a name="SoupContentDecoder.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupContentDecoder.description"></a><h2>Description</h2> +<p><a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder"><span class="type">SoupContentDecoder</span></a> handles adding the "Accept-Encoding" header on +outgoing messages, and processing the "Content-Encoding" header on +incoming ones. Currently it supports the "gzip" and "deflate" +content codings.</p> +<p>If you are using a plain <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> (ie, not <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> or +<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>), then a <a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder"><span class="type">SoupContentDecoder</span></a> will automatically be +added to the session by default. (You can use +<a class="link" href="SoupSession.html#SOUP-SESSION-REMOVE-FEATURE-BY-TYPE:CAPS" title="SOUP_SESSION_REMOVE_FEATURE_BY_TYPE"><code class="literal">SOUP_SESSION_REMOVE_FEATURE_BY_TYPE</code></a> at construct time if you don't +want this.) If you are using one of the deprecated <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> +subclasses, you can add a <a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder"><span class="type">SoupContentDecoder</span></a> to your session with +<a class="link" href="SoupSession.html#soup-session-add-feature" title="soup_session_add_feature ()"><code class="function">soup_session_add_feature()</code></a> or <a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()"><code class="function">soup_session_add_feature_by_type()</code></a>.</p> +<p>If <a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder"><span class="type">SoupContentDecoder</span></a> successfully decodes the Content-Encoding, +it will set the <a class="link" href="SoupMessage.html#SOUP-MESSAGE-CONTENT-DECODED:CAPS"><code class="literal">SOUP_MESSAGE_CONTENT_DECODED</code></a> flag on the message, +and the message body and the chunks in the <a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal"><span class="type">“got_chunk”</span></a> +signals will contain the decoded data; however, the message headers +will be unchanged (and so "Content-Encoding" will still be present, +"Content-Length" will describe the original encoded length, etc).</p> +<p>If "Content-Encoding" contains any encoding types that +<a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder"><span class="type">SoupContentDecoder</span></a> doesn't recognize, then none of the encodings +will be decoded (and the <a class="link" href="SoupMessage.html#SOUP-MESSAGE-CONTENT-DECODED:CAPS"><code class="literal">SOUP_MESSAGE_CONTENT_DECODED</code></a> flag will +not be set).</p> +<p>(Note that currently there is no way to (automatically) use +Content-Encoding when sending a request body, or to pick specific +encoding types to support.)</p> +</div> +<div class="refsect1"> +<a name="SoupContentDecoder.functions_details"></a><h2>Functions</h2> +</div> +<div class="refsect1"> +<a name="SoupContentDecoder.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupContentDecoder-struct"></a><h3>SoupContentDecoder</h3> +<pre class="programlisting">typedef struct _SoupContentDecoder SoupContentDecoder;</pre> +<p> +</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupContentSniffer.html b/docs/reference/html/SoupContentSniffer.html new file mode 100644 index 00000000..2cdde7cf --- /dev/null +++ b/docs/reference/html/SoupContentSniffer.html @@ -0,0 +1,225 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupContentSniffer</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch03.html" title="Additional Features"> +<link rel="prev" href="SoupContentDecoder.html" title="SoupContentDecoder"> +<link rel="next" href="SoupCookieJar.html" title="SoupCookieJar"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupContentSniffer.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupContentSniffer.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupContentSniffer.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupContentDecoder.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupCookieJar.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupContentSniffer"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupContentSniffer.top_of_page"></a>SoupContentSniffer</span></h2> +<p>SoupContentSniffer — Content sniffing for SoupSession</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupContentSniffer.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="returnvalue">SoupContentSniffer</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupContentSniffer.html#soup-content-sniffer-new" title="soup_content_sniffer_new ()">soup_content_sniffer_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupContentSniffer.html#soup-content-sniffer-sniff" title="soup_content_sniffer_sniff ()">soup_content_sniffer_sniff</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="returnvalue">gsize</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupContentSniffer.html#soup-content-sniffer-get-buffer-size" title="soup_content_sniffer_get_buffer_size ()">soup_content_sniffer_get_buffer_size</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupContentSniffer.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupContentSniffer.html#SoupContentSniffer-struct" title="SoupContentSniffer">SoupContentSniffer</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupContentSniffer.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupContentSniffer +</pre> +</div> +<div class="refsect1"> +<a name="SoupContentSniffer.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupContentSniffer implements + <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature">SoupSessionFeature</a> and SoupContentProcessor.</p> +</div> +<div class="refsect1"> +<a name="SoupContentSniffer.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupContentSniffer.description"></a><h2>Description</h2> +<p>A <a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="type">SoupContentSniffer</span></a> tries to detect the actual content type of +the files that are being downloaded by looking at some of the data +before the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> emits its <a class="link" href="SoupMessage.html#SoupMessage-got-headers" title="The “got-headers” signal"><span class="type">“got-headers”</span></a> signal. +<a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="type">SoupContentSniffer</span></a> implements <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a>, so you can add +content sniffing to a session with <a class="link" href="SoupSession.html#soup-session-add-feature" title="soup_session_add_feature ()"><code class="function">soup_session_add_feature()</code></a> or +<a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()"><code class="function">soup_session_add_feature_by_type()</code></a>.</p> +</div> +<div class="refsect1"> +<a name="SoupContentSniffer.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-content-sniffer-new"></a><h3>soup_content_sniffer_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="returnvalue">SoupContentSniffer</span></a> * +soup_content_sniffer_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<p>Creates a new <a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="type">SoupContentSniffer</span></a>.</p> +<div class="refsect3"> +<a name="id-1.4.5.9.2.5"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="type">SoupContentSniffer</span></a></p> +<p></p> +</div> +<p class="since">Since 2.28</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-content-sniffer-sniff"></a><h3>soup_content_sniffer_sniff ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_content_sniffer_sniff (<em class="parameter"><code><a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="type">SoupContentSniffer</span></a> *sniffer</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *buffer</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> **params</code></em>);</pre> +<p>Sniffs <em class="parameter"><code>buffer</code></em> + to determine its Content-Type. The result may also +be influenced by the Content-Type declared in <em class="parameter"><code>msg</code></em> +'s response +headers.</p> +<div class="refsect3"> +<a name="id-1.4.5.9.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sniffer</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="type">SoupContentSniffer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message to sniff</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>buffer</p></td> +<td class="parameter_description"><p>a buffer containing the start of <em class="parameter"><code>msg</code></em> +'s response body</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>params</p></td> +<td class="parameter_description"><p> return +location for Content-Type parameters (eg, "charset"), or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8][<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.4.5.9.3.6"></a><h4>Returns</h4> +<p> the sniffed Content-Type of <em class="parameter"><code>buffer</code></em> +; this will never be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, +but may be "application/octet-stream".</p> +<p></p> +</div> +<p class="since">Since 2.28</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-content-sniffer-get-buffer-size"></a><h3>soup_content_sniffer_get_buffer_size ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="returnvalue">gsize</span></a> +soup_content_sniffer_get_buffer_size (<em class="parameter"><code><a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="type">SoupContentSniffer</span></a> *sniffer</code></em>);</pre> +<p>Gets the number of bytes <em class="parameter"><code>sniffer</code></em> + needs in order to properly sniff +a buffer.</p> +<div class="refsect3"> +<a name="id-1.4.5.9.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>sniffer</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="type">SoupContentSniffer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.4.5.9.4.6"></a><h4>Returns</h4> +<p> the number of bytes to sniff</p> +<p></p> +</div> +<p class="since">Since 2.28</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupContentSniffer.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupContentSniffer-struct"></a><h3>SoupContentSniffer</h3> +<pre class="programlisting">typedef struct _SoupContentSniffer SoupContentSniffer;</pre> +<p> +</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupCookie.html b/docs/reference/html/SoupCookie.html new file mode 100644 index 00000000..f4c2dbdb --- /dev/null +++ b/docs/reference/html/SoupCookie.html @@ -0,0 +1,1478 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupCookie</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupCache.html" title="SoupCache"> +<link rel="next" href="SoupMessage.html" title="SoupMessage"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupCookie.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupCookie.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupCache.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupMessage.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupCookie"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupCookie.top_of_page"></a>SoupCookie</span></h2> +<p>SoupCookie — HTTP Cookies</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupCookie.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupCookie.html" title="SoupCookie"><span class="returnvalue">SoupCookie</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-new" title="soup_cookie_new ()">soup_cookie_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupCookie.html" title="SoupCookie"><span class="returnvalue">SoupCookie</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-parse" title="soup_cookie_parse ()">soup_cookie_parse</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupCookie.html" title="SoupCookie"><span class="returnvalue">SoupCookie</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-copy" title="soup_cookie_copy ()">soup_cookie_copy</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-free" title="soup_cookie_free ()">soup_cookie_free</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-set-name" title="soup_cookie_set_name ()">soup_cookie_set_name</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-get-name" title="soup_cookie_get_name ()">soup_cookie_get_name</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-set-value" title="soup_cookie_set_value ()">soup_cookie_set_value</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-get-value" title="soup_cookie_get_value ()">soup_cookie_get_value</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-set-domain" title="soup_cookie_set_domain ()">soup_cookie_set_domain</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-get-domain" title="soup_cookie_get_domain ()">soup_cookie_get_domain</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-set-path" title="soup_cookie_set_path ()">soup_cookie_set_path</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-get-path" title="soup_cookie_get_path ()">soup_cookie_get_path</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-set-max-age" title="soup_cookie_set_max_age ()">soup_cookie_set_max_age</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-HOUR:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_HOUR">SOUP_COOKIE_MAX_AGE_ONE_HOUR</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-DAY:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_DAY">SOUP_COOKIE_MAX_AGE_ONE_DAY</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-WEEK:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_WEEK">SOUP_COOKIE_MAX_AGE_ONE_WEEK</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-YEAR:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_YEAR">SOUP_COOKIE_MAX_AGE_ONE_YEAR</a></td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-set-expires" title="soup_cookie_set_expires ()">soup_cookie_set_expires</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="returnvalue">SoupDate</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-get-expires" title="soup_cookie_get_expires ()">soup_cookie_get_expires</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-set-secure" title="soup_cookie_set_secure ()">soup_cookie_set_secure</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-get-secure" title="soup_cookie_get_secure ()">soup_cookie_get_secure</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-set-http-only" title="soup_cookie_set_http_only ()">soup_cookie_set_http_only</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-get-http-only" title="soup_cookie_get_http_only ()">soup_cookie_get_http_only</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-applies-to-uri" title="soup_cookie_applies_to_uri ()">soup_cookie_applies_to_uri</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-domain-matches" title="soup_cookie_domain_matches ()">soup_cookie_domain_matches</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-to-cookie-header" title="soup_cookie_to_cookie_header ()">soup_cookie_to_cookie_header</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookie-to-set-cookie-header" title="soup_cookie_to_set_cookie_header ()">soup_cookie_to_set_cookie_header</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookies-from-request" title="soup_cookies_from_request ()">soup_cookies_from_request</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookies-from-response" title="soup_cookies_from_response ()">soup_cookies_from_response</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookies-to-request" title="soup_cookies_to_request ()">soup_cookies_to_request</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookies-to-response" title="soup_cookies_to_response ()">soup_cookies_to_response</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookies-to-cookie-header" title="soup_cookies_to_cookie_header ()">soup_cookies_to_cookie_header</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookie.html#soup-cookies-free" title="soup_cookies_free ()">soup_cookies_free</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookie.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupCookie.html#SoupCookie-struct" title="SoupCookie">SoupCookie</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookie.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> GBoxed + <span class="lineart">╰──</span> SoupCookie +</pre> +</div> +<div class="refsect1"> +<a name="SoupCookie.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupCookie.description"></a><h2>Description</h2> +<p><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> implements HTTP cookies, as described by <a class="ulink" href="http://tools.ietf.org/html/rfc6265.txt" target="_top">RFC 6265</a>.</p> +<p>To have a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> handle cookies for your appliction +automatically, use a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a>.</p> +</div> +<div class="refsect1"> +<a name="SoupCookie.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-cookie-new"></a><h3>soup_cookie_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="returnvalue">SoupCookie</span></a> * +soup_cookie_new (<em class="parameter"><code>const <span class="type">char</span> *name</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *value</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *domain</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *path</code></em>, + <em class="parameter"><code><span class="type">int</span> max_age</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> with the given attributes. (Use +<a class="link" href="SoupCookie.html#soup-cookie-set-secure" title="soup_cookie_set_secure ()"><code class="function">soup_cookie_set_secure()</code></a> and <a class="link" href="SoupCookie.html#soup-cookie-set-http-only" title="soup_cookie_set_http_only ()"><code class="function">soup_cookie_set_http_only()</code></a> if you +need to set those attributes on the returned cookie.)</p> +<p>If <em class="parameter"><code>domain</code></em> + starts with ".", that indicates a domain (which matches +the string after the ".", or any hostname that has <em class="parameter"><code>domain</code></em> + as a +suffix). Otherwise, it is a hostname and must match exactly.</p> +<p><em class="parameter"><code>max_age</code></em> + is used to set the "expires" attribute on the cookie; pass +-1 to not include the attribute (indicating that the cookie expires +with the current session), 0 for an already-expired cookie, or a +lifetime in seconds. You can use the constants +<a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-HOUR:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_HOUR"><code class="literal">SOUP_COOKIE_MAX_AGE_ONE_HOUR</code></a>, <a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-DAY:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_DAY"><code class="literal">SOUP_COOKIE_MAX_AGE_ONE_DAY</code></a>, +<a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-WEEK:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_WEEK"><code class="literal">SOUP_COOKIE_MAX_AGE_ONE_WEEK</code></a> and <a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-YEAR:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_YEAR"><code class="literal">SOUP_COOKIE_MAX_AGE_ONE_YEAR</code></a> (or +multiples thereof) to calculate this value. (If you really care +about setting the exact time that the cookie will expire, use +<a class="link" href="SoupCookie.html#soup-cookie-set-expires" title="soup_cookie_set_expires ()"><code class="function">soup_cookie_set_expires()</code></a>.)</p> +<div class="refsect3"> +<a name="id-1.3.7.8.2.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>cookie name</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>value</p></td> +<td class="parameter_description"><p>cookie value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>cookie domain or hostname</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>path</p></td> +<td class="parameter_description"><p>cookie path, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>max_age</p></td> +<td class="parameter_description"><p>max age of the cookie, or -1 for a session cookie</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.2.8"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>.</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-parse"></a><h3>soup_cookie_parse ()</h3> +<pre class="programlisting"><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="returnvalue">SoupCookie</span></a> * +soup_cookie_parse (<em class="parameter"><code>const <span class="type">char</span> *header</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *origin</code></em>);</pre> +<p>Parses <em class="parameter"><code>header</code></em> + and returns a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>. (If <em class="parameter"><code>header</code></em> + contains +multiple cookies, only the first one will be parsed.)</p> +<p>If <em class="parameter"><code>header</code></em> + does not have "path" or "domain" attributes, they will +be defaulted from <em class="parameter"><code>origin</code></em> +. If <em class="parameter"><code>origin</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, path will default +to "/", but domain will be left as <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. Note that this is not a +valid state for a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>, and you will need to fill in some +appropriate string for the domain if you want to actually make use +of the cookie.</p> +<div class="refsect3"> +<a name="id-1.3.7.8.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>header</p></td> +<td class="parameter_description"><p>a cookie string (eg, the value of a Set-Cookie header)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>origin</p></td> +<td class="parameter_description"><p>origin of the cookie, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.3.7"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if it could not be +parsed, or contained an illegal "domain" attribute for a cookie +originating from <em class="parameter"><code>origin</code></em> +.</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-copy"></a><h3>soup_cookie_copy ()</h3> +<pre class="programlisting"><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="returnvalue">SoupCookie</span></a> * +soup_cookie_copy (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Copies <em class="parameter"><code>cookie</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.7.8.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.4.6"></a><h4>Returns</h4> +<p> a copy of <em class="parameter"><code>cookie</code></em> +</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-free"></a><h3>soup_cookie_free ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_free (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Frees <em class="parameter"><code>cookie</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.7.8.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-set-name"></a><h3>soup_cookie_set_name ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_set_name (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *name</code></em>);</pre> +<p>Sets <em class="parameter"><code>cookie</code></em> +'s name to <em class="parameter"><code>name</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.7.8.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>the new name</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-get-name"></a><h3>soup_cookie_get_name ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_cookie_get_name (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Gets <em class="parameter"><code>cookie</code></em> +'s name</p> +<div class="refsect3"> +<a name="id-1.3.7.8.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.7.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>cookie</code></em> +'s name</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-set-value"></a><h3>soup_cookie_set_value ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_set_value (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *value</code></em>);</pre> +<p>Sets <em class="parameter"><code>cookie</code></em> +'s value to <em class="parameter"><code>value</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.7.8.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>value</p></td> +<td class="parameter_description"><p>the new value</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-get-value"></a><h3>soup_cookie_get_value ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_cookie_get_value (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Gets <em class="parameter"><code>cookie</code></em> +'s value</p> +<div class="refsect3"> +<a name="id-1.3.7.8.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.9.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>cookie</code></em> +'s value</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-set-domain"></a><h3>soup_cookie_set_domain ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_set_domain (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *domain</code></em>);</pre> +<p>Sets <em class="parameter"><code>cookie</code></em> +'s domain to <em class="parameter"><code>domain</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.7.8.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>the new domain</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-get-domain"></a><h3>soup_cookie_get_domain ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_cookie_get_domain (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Gets <em class="parameter"><code>cookie</code></em> +'s domain</p> +<div class="refsect3"> +<a name="id-1.3.7.8.11.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.11.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>cookie</code></em> +'s domain</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-set-path"></a><h3>soup_cookie_set_path ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_set_path (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *path</code></em>);</pre> +<p>Sets <em class="parameter"><code>cookie</code></em> +'s path to <em class="parameter"><code>path</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.7.8.12.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>path</p></td> +<td class="parameter_description"><p>the new path</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-get-path"></a><h3>soup_cookie_get_path ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_cookie_get_path (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Gets <em class="parameter"><code>cookie</code></em> +'s path</p> +<div class="refsect3"> +<a name="id-1.3.7.8.13.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.13.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>cookie</code></em> +'s path</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-set-max-age"></a><h3>soup_cookie_set_max_age ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_set_max_age (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>, + <em class="parameter"><code><span class="type">int</span> max_age</code></em>);</pre> +<p>Sets <em class="parameter"><code>cookie</code></em> +'s max age to <em class="parameter"><code>max_age</code></em> +. If <em class="parameter"><code>max_age</code></em> + is -1, the cookie +is a session cookie, and will expire at the end of the client's +session. Otherwise, it is the number of seconds until the cookie +expires. You can use the constants <a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-HOUR:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_HOUR"><code class="literal">SOUP_COOKIE_MAX_AGE_ONE_HOUR</code></a>, +<a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-DAY:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_DAY"><code class="literal">SOUP_COOKIE_MAX_AGE_ONE_DAY</code></a>, <a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-WEEK:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_WEEK"><code class="literal">SOUP_COOKIE_MAX_AGE_ONE_WEEK</code></a> and +<a class="link" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-YEAR:CAPS" title="SOUP_COOKIE_MAX_AGE_ONE_YEAR"><code class="literal">SOUP_COOKIE_MAX_AGE_ONE_YEAR</code></a> (or multiples thereof) to calculate +this value. (A value of 0 indicates that the cookie should be +considered already-expired.)</p> +<p>(This sets the same property as <a class="link" href="SoupCookie.html#soup-cookie-set-expires" title="soup_cookie_set_expires ()"><code class="function">soup_cookie_set_expires()</code></a>.)</p> +<div class="refsect3"> +<a name="id-1.3.7.8.14.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>max_age</p></td> +<td class="parameter_description"><p>the new max age</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-COOKIE-MAX-AGE-ONE-HOUR:CAPS"></a><h3>SOUP_COOKIE_MAX_AGE_ONE_HOUR</h3> +<pre class="programlisting">#define SOUP_COOKIE_MAX_AGE_ONE_HOUR (60 * 60) +</pre> +<p>A constant corresponding to 1 hour, for use with <a class="link" href="SoupCookie.html#soup-cookie-new" title="soup_cookie_new ()"><code class="function">soup_cookie_new()</code></a> +and <a class="link" href="SoupCookie.html#soup-cookie-set-max-age" title="soup_cookie_set_max_age ()"><code class="function">soup_cookie_set_max_age()</code></a>.</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-COOKIE-MAX-AGE-ONE-DAY:CAPS"></a><h3>SOUP_COOKIE_MAX_AGE_ONE_DAY</h3> +<pre class="programlisting">#define SOUP_COOKIE_MAX_AGE_ONE_DAY (SOUP_COOKIE_MAX_AGE_ONE_HOUR * 24) +</pre> +<p>A constant corresponding to 1 day, for use with <a class="link" href="SoupCookie.html#soup-cookie-new" title="soup_cookie_new ()"><code class="function">soup_cookie_new()</code></a> +and <a class="link" href="SoupCookie.html#soup-cookie-set-max-age" title="soup_cookie_set_max_age ()"><code class="function">soup_cookie_set_max_age()</code></a>.</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-COOKIE-MAX-AGE-ONE-WEEK:CAPS"></a><h3>SOUP_COOKIE_MAX_AGE_ONE_WEEK</h3> +<pre class="programlisting">#define SOUP_COOKIE_MAX_AGE_ONE_WEEK (SOUP_COOKIE_MAX_AGE_ONE_DAY * 7) +</pre> +<p>A constant corresponding to 1 week, for use with <a class="link" href="SoupCookie.html#soup-cookie-new" title="soup_cookie_new ()"><code class="function">soup_cookie_new()</code></a> +and <a class="link" href="SoupCookie.html#soup-cookie-set-max-age" title="soup_cookie_set_max_age ()"><code class="function">soup_cookie_set_max_age()</code></a>.</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-COOKIE-MAX-AGE-ONE-YEAR:CAPS"></a><h3>SOUP_COOKIE_MAX_AGE_ONE_YEAR</h3> +<pre class="programlisting">#define SOUP_COOKIE_MAX_AGE_ONE_YEAR (SOUP_COOKIE_MAX_AGE_ONE_DAY * 365.2422) +</pre> +<p>A constant corresponding to 1 year, for use with <a class="link" href="SoupCookie.html#soup-cookie-new" title="soup_cookie_new ()"><code class="function">soup_cookie_new()</code></a> +and <a class="link" href="SoupCookie.html#soup-cookie-set-max-age" title="soup_cookie_set_max_age ()"><code class="function">soup_cookie_set_max_age()</code></a>.</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-set-expires"></a><h3>soup_cookie_set_expires ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_set_expires (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>, + <em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *expires</code></em>);</pre> +<p>Sets <em class="parameter"><code>cookie</code></em> +'s expiration time to <em class="parameter"><code>expires</code></em> +. If <em class="parameter"><code>expires</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, +<em class="parameter"><code>cookie</code></em> + will be a session cookie and will expire at the end of the +client's session.</p> +<p>(This sets the same property as <a class="link" href="SoupCookie.html#soup-cookie-set-max-age" title="soup_cookie_set_max_age ()"><code class="function">soup_cookie_set_max_age()</code></a>.)</p> +<div class="refsect3"> +<a name="id-1.3.7.8.19.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>expires</p></td> +<td class="parameter_description"><p>the new expiration time, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-get-expires"></a><h3>soup_cookie_get_expires ()</h3> +<pre class="programlisting"><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="returnvalue">SoupDate</span></a> * +soup_cookie_get_expires (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Gets <em class="parameter"><code>cookie</code></em> +'s expiration time</p> +<div class="refsect3"> +<a name="id-1.3.7.8.20.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.20.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>cookie</code></em> +'s expiration time, which is +owned by <em class="parameter"><code>cookie</code></em> +and should not be modified or freed. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-set-secure"></a><h3>soup_cookie_set_secure ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_set_secure (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> secure</code></em>);</pre> +<p>Sets <em class="parameter"><code>cookie</code></em> +'s secure attribute to <em class="parameter"><code>secure</code></em> +. If <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, <em class="parameter"><code>cookie</code></em> + will +only be transmitted from the client to the server over secure +(https) connections.</p> +<div class="refsect3"> +<a name="id-1.3.7.8.21.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>secure</p></td> +<td class="parameter_description"><p>the new value for the secure attribute</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-get-secure"></a><h3>soup_cookie_get_secure ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_cookie_get_secure (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Gets <em class="parameter"><code>cookie</code></em> +'s secure attribute</p> +<div class="refsect3"> +<a name="id-1.3.7.8.22.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.22.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>cookie</code></em> +'s secure attribute</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-set-http-only"></a><h3>soup_cookie_set_http_only ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_set_http_only (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> http_only</code></em>);</pre> +<p>Sets <em class="parameter"><code>cookie</code></em> +'s HttpOnly attribute to <em class="parameter"><code>http_only</code></em> +. If <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, <em class="parameter"><code>cookie</code></em> + +will be marked as "http only", meaning it should not be exposed to +web page scripts or other untrusted code.</p> +<div class="refsect3"> +<a name="id-1.3.7.8.23.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>http_only</p></td> +<td class="parameter_description"><p>the new value for the HttpOnly attribute</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-get-http-only"></a><h3>soup_cookie_get_http_only ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_cookie_get_http_only (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Gets <em class="parameter"><code>cookie</code></em> +'s HttpOnly attribute</p> +<div class="refsect3"> +<a name="id-1.3.7.8.24.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.24.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>cookie</code></em> +'s HttpOnly attribute</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-applies-to-uri"></a><h3>soup_cookie_applies_to_uri ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_cookie_applies_to_uri (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Tests if <em class="parameter"><code>cookie</code></em> + should be sent to <em class="parameter"><code>uri</code></em> +.</p> +<p>(At the moment, this does not check that <em class="parameter"><code>cookie</code></em> +'s domain matches +<em class="parameter"><code>uri</code></em> +, because it assumes that the caller has already done that. +But don't rely on that; it may change in the future.)</p> +<div class="refsect3"> +<a name="id-1.3.7.8.25.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.25.7"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>cookie</code></em> +should be sent to <em class="parameter"><code>uri</code></em> +, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if +not</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-domain-matches"></a><h3>soup_cookie_domain_matches ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_cookie_domain_matches (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *host</code></em>);</pre> +<p>Checks if the <em class="parameter"><code>cookie</code></em> +'s domain and <em class="parameter"><code>host</code></em> + match in the sense that +<em class="parameter"><code>cookie</code></em> + should be sent when making a request to <em class="parameter"><code>host</code></em> +, or that +<em class="parameter"><code>cookie</code></em> + should be accepted when receiving a response from <em class="parameter"><code>host</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.7.8.26.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>host</p></td> +<td class="parameter_description"><p>a URI</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.26.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the domains match, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise</p> +<p></p> +</div> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-to-cookie-header"></a><h3>soup_cookie_to_cookie_header ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_cookie_to_cookie_header (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Serializes <em class="parameter"><code>cookie</code></em> + in the format used by the Cookie header (ie, for +returning a cookie from a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> to a server).</p> +<div class="refsect3"> +<a name="id-1.3.7.8.27.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.27.6"></a><h4>Returns</h4> +<p> the header</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-to-set-cookie-header"></a><h3>soup_cookie_to_set_cookie_header ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_cookie_to_set_cookie_header (<em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Serializes <em class="parameter"><code>cookie</code></em> + in the format used by the Set-Cookie header +(ie, for sending a cookie from a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> to a client).</p> +<div class="refsect3"> +<a name="id-1.3.7.8.28.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.28.6"></a><h4>Returns</h4> +<p> the header</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookies-from-request"></a><h3>soup_cookies_from_request ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +soup_cookies_from_request (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Parses <em class="parameter"><code>msg</code></em> +'s Cookie request header and returns a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> of +<a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>s. As the "Cookie" header, unlike "Set-Cookie", +only contains cookie names and values, none of the other +<a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> fields will be filled in. (Thus, you can't generally +pass a cookie returned from this method directly to +<a class="link" href="SoupCookie.html#soup-cookies-to-response" title="soup_cookies_to_response ()"><code class="function">soup_cookies_to_response()</code></a>.)</p> +<div class="refsect3"> +<a name="id-1.3.7.8.29.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> containing a "Cookie" request header</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.29.6"></a><h4>Returns</h4> +<p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> +of <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>s, which can be freed with +<a class="link" href="SoupCookie.html#soup-cookies-free" title="soup_cookies_free ()"><code class="function">soup_cookies_free()</code></a>. </p> +<p><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> SoupCookie][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookies-from-response"></a><h3>soup_cookies_from_response ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +soup_cookies_from_response (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Parses <em class="parameter"><code>msg</code></em> +'s Set-Cookie response headers and returns a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> of +<a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>s. Cookies that do not specify "path" or +"domain" attributes will have their values defaulted from <em class="parameter"><code>msg</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.7.8.30.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> containing a "Set-Cookie" response header</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.30.6"></a><h4>Returns</h4> +<p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> +of <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>s, which can be freed with +<a class="link" href="SoupCookie.html#soup-cookies-free" title="soup_cookies_free ()"><code class="function">soup_cookies_free()</code></a>. </p> +<p><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> SoupCookie][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookies-to-request"></a><h3>soup_cookies_to_request ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookies_to_request (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> *cookies</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Adds the name and value of each cookie in <em class="parameter"><code>cookies</code></em> + to <em class="parameter"><code>msg</code></em> +'s +"Cookie" request. (If <em class="parameter"><code>msg</code></em> + already has a "Cookie" request header, +these cookies will be appended to the cookies already present. Be +careful that you do not append the same cookies twice, eg, when +requeuing a message.)</p> +<div class="refsect3"> +<a name="id-1.3.7.8.31.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookies</p></td> +<td class="parameter_description"><p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> of <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> SoupCookie]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookies-to-response"></a><h3>soup_cookies_to_response ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookies_to_response (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> *cookies</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Appends a "Set-Cookie" response header to <em class="parameter"><code>msg</code></em> + for each cookie in +<em class="parameter"><code>cookies</code></em> +. (This is in addition to any other "Set-Cookie" headers +<em class="parameter"><code>msg</code></em> + may already have.)</p> +<div class="refsect3"> +<a name="id-1.3.7.8.32.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>cookies</p></td> +<td class="parameter_description"><p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> of <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> SoupCookie]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookies-to-cookie-header"></a><h3>soup_cookies_to_cookie_header ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_cookies_to_cookie_header (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> *cookies</code></em>);</pre> +<p>Serializes a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> of <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> into a string suitable for +setting as the value of the "Cookie" header.</p> +<div class="refsect3"> +<a name="id-1.3.7.8.33.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookies</p></td> +<td class="parameter_description"><p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> of <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> SoupCookie]</span></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.7.8.33.6"></a><h4>Returns</h4> +<p> the serialization of <em class="parameter"><code>cookies</code></em> +</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookies-free"></a><h3>soup_cookies_free ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookies_free (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> *cookies</code></em>);</pre> +<p>Frees <em class="parameter"><code>cookies</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.7.8.34.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>cookies</p></td> +<td class="parameter_description"><p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> of <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> SoupCookie]</span></td> +</tr></tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupCookie.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupCookie-struct"></a><h3>SoupCookie</h3> +<pre class="programlisting">typedef struct { + char *name; + char *value; + char *domain; + char *path; + SoupDate *expires; + gboolean secure; + gboolean http_only; +} SoupCookie; +</pre> +<p>An HTTP cookie.</p> +<p><em class="parameter"><code>name</code></em> + and <em class="parameter"><code>value</code></em> + will be set for all cookies. If the cookie is +generated from a string that appears to have no name, then <em class="parameter"><code>name</code></em> + +will be the empty string.</p> +<p><em class="parameter"><code>domain</code></em> + and <em class="parameter"><code>path</code></em> + give the host or domain, and path within that +host/domain, to restrict this cookie to. If <em class="parameter"><code>domain</code></em> + starts with +".", that indicates a domain (which matches the string after the +".", or any hostname that has <em class="parameter"><code>domain</code></em> + as a suffix). Otherwise, it +is a hostname and must match exactly.</p> +<p><em class="parameter"><code>expires</code></em> + will be non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if the cookie uses either the original +"expires" attribute, or the newer "max-age" attribute. If <em class="parameter"><code>expires</code></em> + +is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, it indicates that neither "expires" nor "max-age" was +specified, and the cookie expires at the end of the session.</p> +<p>If <em class="parameter"><code>http_only</code></em> + is set, the cookie should not be exposed to untrusted +code (eg, javascript), so as to minimize the danger posed by +cross-site scripting attacks.</p> +<div class="refsect3"> +<a name="id-1.3.7.9.2.9"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="struct_members_name"> +<col class="struct_members_description"> +<col width="200px" class="struct_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="struct_member_name"><p><span class="type">char</span> *<em class="structfield"><code><a name="SoupCookie-struct.name"></a>name</code></em>;</p></td> +<td class="struct_member_description"><p>the cookie name</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">char</span> *<em class="structfield"><code><a name="SoupCookie-struct.value"></a>value</code></em>;</p></td> +<td class="struct_member_description"><p>the cookie value</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">char</span> *<em class="structfield"><code><a name="SoupCookie-struct.domain"></a>domain</code></em>;</p></td> +<td class="struct_member_description"><p>the "domain" attribute, or else the hostname that the +cookie came from.</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">char</span> *<em class="structfield"><code><a name="SoupCookie-struct.path"></a>path</code></em>;</p></td> +<td class="struct_member_description"><p>the "path" attribute, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *<em class="structfield"><code><a name="SoupCookie-struct.expires"></a>expires</code></em>;</p></td> +<td class="struct_member_description"><p>the cookie expiration time, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> for a session cookie</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> <em class="structfield"><code><a name="SoupCookie-struct.secure"></a>secure</code></em>;</p></td> +<td class="struct_member_description"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the cookie should only be tranferred over SSL</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> <em class="structfield"><code><a name="SoupCookie-struct.http-only"></a>http_only</code></em>;</p></td> +<td class="struct_member_description"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the cookie should not be exposed to scripts</p></td> +<td class="struct_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupCookie.see-also"></a><h2>See Also</h2> +<p><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupCookieJar.html b/docs/reference/html/SoupCookieJar.html new file mode 100644 index 00000000..45413d39 --- /dev/null +++ b/docs/reference/html/SoupCookieJar.html @@ -0,0 +1,866 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupCookieJar</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch03.html" title="Additional Features"> +<link rel="prev" href="SoupContentSniffer.html" title="SoupContentSniffer"> +<link rel="next" href="SoupCookieJarText.html" title="SoupCookieJarText"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupCookieJar.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupCookieJar.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupCookieJar.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupCookieJar.properties" class="shortcut">Properties</a></span><span id="nav_signals"> <span class="dim">|</span> + <a href="#SoupCookieJar.signals" class="shortcut">Signals</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupContentSniffer.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupCookieJarText.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupCookieJar"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupCookieJar.top_of_page"></a>SoupCookieJar</span></h2> +<p>SoupCookieJar — Automatic cookie handling for SoupSession</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupCookieJar.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="returnvalue">SoupCookieJar</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-new" title="soup_cookie_jar_new ()">soup_cookie_jar_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-get-cookies" title="soup_cookie_jar_get_cookies ()">soup_cookie_jar_get_cookies</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-get-cookie-list" title="soup_cookie_jar_get_cookie_list ()">soup_cookie_jar_get_cookie_list</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-set-cookie" title="soup_cookie_jar_set_cookie ()">soup_cookie_jar_set_cookie</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-set-cookie-with-first-party" title="soup_cookie_jar_set_cookie_with_first_party ()">soup_cookie_jar_set_cookie_with_first_party</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-add-cookie" title="soup_cookie_jar_add_cookie ()">soup_cookie_jar_add_cookie</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-add-cookie-with-first-party" title="soup_cookie_jar_add_cookie_with_first_party ()">soup_cookie_jar_add_cookie_with_first_party</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-delete-cookie" title="soup_cookie_jar_delete_cookie ()">soup_cookie_jar_delete_cookie</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-all-cookies" title="soup_cookie_jar_all_cookies ()">soup_cookie_jar_all_cookies</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy" title="enum SoupCookieJarAcceptPolicy"><span class="returnvalue">SoupCookieJarAcceptPolicy</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-get-accept-policy" title="soup_cookie_jar_get_accept_policy ()">soup_cookie_jar_get_accept_policy</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-set-accept-policy" title="soup_cookie_jar_set_accept_policy ()">soup_cookie_jar_set_accept_policy</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-is-persistent" title="soup_cookie_jar_is_persistent ()">soup_cookie_jar_is_persistent</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookieJar.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"><a class="link" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy" title="enum SoupCookieJarAcceptPolicy"><span class="type">SoupCookieJarAcceptPolicy</span></a></td> +<td class="property_name"><a class="link" href="SoupCookieJar.html#SoupCookieJar--accept-policy" title="The “accept-policy” property">accept-policy</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupCookieJar.html#SoupCookieJar--read-only" title="The “read-only” property">read-only</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookieJar.signals"></a><h2>Signals</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="signals_return"> +<col width="300px" class="signals_name"> +<col width="200px" class="signals_flags"> +</colgroup> +<tbody><tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupCookieJar.html#SoupCookieJar-changed" title="The “changed” signal">changed</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookieJar.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupCookieJar.html#SoupCookieJar-struct" title="SoupCookieJar">SoupCookieJar</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy" title="enum SoupCookieJarAcceptPolicy">SoupCookieJarAcceptPolicy</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupCookieJar.html#SOUP-COOKIE-JAR-READ-ONLY:CAPS" title="SOUP_COOKIE_JAR_READ_ONLY">SOUP_COOKIE_JAR_READ_ONLY</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupCookieJar.html#SOUP-COOKIE-JAR-ACCEPT-POLICY:CAPS" title="SOUP_COOKIE_JAR_ACCEPT_POLICY">SOUP_COOKIE_JAR_ACCEPT_POLICY</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookieJar.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupCookieJar + <span class="lineart">├──</span> <a class="link" href="SoupCookieJarDB.html" title="SoupCookieJarDB">SoupCookieJarDB</a> + <span class="lineart">╰──</span> <a class="link" href="SoupCookieJarText.html" title="SoupCookieJarText">SoupCookieJarText</a> +</pre> +</div> +<div class="refsect1"> +<a name="SoupCookieJar.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupCookieJar implements + <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature">SoupSessionFeature</a>.</p> +</div> +<div class="refsect1"> +<a name="SoupCookieJar.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupCookieJar.description"></a><h2>Description</h2> +<p>A <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> stores <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>s and arrange for them +to be sent with the appropriate <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>s. +<a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> implements <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a>, so you can add a +cookie jar to a session with <a class="link" href="SoupSession.html#soup-session-add-feature" title="soup_session_add_feature ()"><code class="function">soup_session_add_feature()</code></a> or +<a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()"><code class="function">soup_session_add_feature_by_type()</code></a>.</p> +<p>Note that the base <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> class does not support any form +of long-term cookie persistence.</p> +</div> +<div class="refsect1"> +<a name="SoupCookieJar.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-cookie-jar-new"></a><h3>soup_cookie_jar_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="returnvalue">SoupCookieJar</span></a> * +soup_cookie_jar_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<p>Creates a new <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a>. The base <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> class does +not support persistent storage of cookies; use a subclass for that.</p> +<div class="refsect3"> +<a name="id-1.4.6.11.2.5"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-jar-get-cookies"></a><h3>soup_cookie_jar_get_cookies ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_cookie_jar_get_cookies (<em class="parameter"><code><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> for_http</code></em>);</pre> +<p>Retrieves (in Cookie-header form) the list of cookies that would +be sent with a request to <em class="parameter"><code>uri</code></em> +.</p> +<p>If <em class="parameter"><code>for_http</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, the return value will include cookies marked +"HttpOnly" (that is, cookies that the server wishes to keep hidden +from client-side scripting operations such as the JavaScript +document.cookies property). Since <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> sets the Cookie +header itself when making the actual HTTP request, you should +almost certainly be setting <em class="parameter"><code>for_http</code></em> + to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if you are calling +this.</p> +<div class="refsect3"> +<a name="id-1.4.6.11.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>for_http</p></td> +<td class="parameter_description"><p>whether or not the return value is being passed directly +to an HTTP operation</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.4.6.11.3.7"></a><h4>Returns</h4> +<p> the cookies, in string form, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if there are no +cookies for <em class="parameter"><code>uri</code></em> +.</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-jar-get-cookie-list"></a><h3>soup_cookie_jar_get_cookie_list ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +soup_cookie_jar_get_cookie_list (<em class="parameter"><code><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> for_http</code></em>);</pre> +<p>Retrieves the list of cookies that would be sent with a request to <em class="parameter"><code>uri</code></em> + +as a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> of <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> objects.</p> +<p>If <em class="parameter"><code>for_http</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, the return value will include cookies marked +"HttpOnly" (that is, cookies that the server wishes to keep hidden +from client-side scripting operations such as the JavaScript +document.cookies property). Since <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> sets the Cookie +header itself when making the actual HTTP request, you should +almost certainly be setting <em class="parameter"><code>for_http</code></em> + to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if you are calling +this.</p> +<div class="refsect3"> +<a name="id-1.4.6.11.4.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>for_http</p></td> +<td class="parameter_description"><p>whether or not the return value is being passed directly +to an HTTP operation</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.4.6.11.4.7"></a><h4>Returns</h4> +<p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> +with the cookies in the <em class="parameter"><code>jar</code></em> +that would be sent with a request to <em class="parameter"><code>uri</code></em> +. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> Soup.Cookie]</span></p> +</div> +<p class="since">Since 2.40</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-jar-set-cookie"></a><h3>soup_cookie_jar_set_cookie ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_jar_set_cookie (<em class="parameter"><code><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *cookie</code></em>);</pre> +<p>Adds <em class="parameter"><code>cookie</code></em> + to <em class="parameter"><code>jar</code></em> +, exactly as though it had appeared in a +Set-Cookie header returned from a request to <em class="parameter"><code>uri</code></em> +.</p> +<p>Keep in mind that if the <a class="link" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy" title="enum SoupCookieJarAcceptPolicy"><span class="type">SoupCookieJarAcceptPolicy</span></a> +<a class="link" href="SoupCookieJar.html#SOUP-COOKIE-JAR-ACCEPT-NO-THIRD-PARTY:CAPS"><code class="literal">SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY</code></a> is set you'll need to use +<a class="link" href="SoupCookieJar.html#soup-cookie-jar-set-cookie-with-first-party" title="soup_cookie_jar_set_cookie_with_first_party ()"><code class="function">soup_cookie_jar_set_cookie_with_first_party()</code></a>, otherwise the jar +will have no way of knowing if the cookie is being set by a third +party or not.</p> +<div class="refsect3"> +<a name="id-1.4.6.11.5.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>the URI setting the cookie</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>the stringified cookie to set</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-jar-set-cookie-with-first-party"></a><h3>soup_cookie_jar_set_cookie_with_first_party ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_jar_set_cookie_with_first_party + (<em class="parameter"><code><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *first_party</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *cookie</code></em>);</pre> +<p>Adds <em class="parameter"><code>cookie</code></em> + to <em class="parameter"><code>jar</code></em> +, exactly as though it had appeared in a +Set-Cookie header returned from a request to <em class="parameter"><code>uri</code></em> +. <em class="parameter"><code>first_party</code></em> + +will be used to reject cookies coming from third party resources in +case such a security policy is set in the <em class="parameter"><code>jar</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.4.6.11.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>the URI setting the cookie</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>first_party</p></td> +<td class="parameter_description"><p>the URI for the main document</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>the stringified cookie to set</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-jar-add-cookie"></a><h3>soup_cookie_jar_add_cookie ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_jar_add_cookie (<em class="parameter"><code><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar</code></em>, + <em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Adds <em class="parameter"><code>cookie</code></em> + to <em class="parameter"><code>jar</code></em> +, emitting the 'changed' signal if we are modifying +an existing cookie or adding a valid new cookie ('valid' means +that the cookie's expire date is not in the past).</p> +<p><em class="parameter"><code>cookie</code></em> + will be 'stolen' by the jar, so don't free it afterwards.</p> +<div class="refsect3"> +<a name="id-1.4.6.11.7.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p> a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-jar-add-cookie-with-first-party"></a><h3>soup_cookie_jar_add_cookie_with_first_party ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_jar_add_cookie_with_first_party + (<em class="parameter"><code><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *first_party</code></em>, + <em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Adds <em class="parameter"><code>cookie</code></em> + to <em class="parameter"><code>jar</code></em> +, emitting the 'changed' signal if we are modifying +an existing cookie or adding a valid new cookie ('valid' means +that the cookie's expire date is not in the past).</p> +<p><em class="parameter"><code>first_party</code></em> + will be used to reject cookies coming from third party +resources in case such a security policy is set in the <em class="parameter"><code>jar</code></em> +.</p> +<p><em class="parameter"><code>cookie</code></em> + will be 'stolen' by the jar, so don't free it afterwards.</p> +<div class="refsect3"> +<a name="id-1.4.6.11.8.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>first_party</p></td> +<td class="parameter_description"><p>the URI for the main document</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p> a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.40</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-jar-delete-cookie"></a><h3>soup_cookie_jar_delete_cookie ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_jar_delete_cookie (<em class="parameter"><code><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar</code></em>, + <em class="parameter"><code><a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *cookie</code></em>);</pre> +<p>Deletes <em class="parameter"><code>cookie</code></em> + from <em class="parameter"><code>jar</code></em> +, emitting the 'changed' signal.</p> +<div class="refsect3"> +<a name="id-1.4.6.11.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cookie</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-jar-all-cookies"></a><h3>soup_cookie_jar_all_cookies ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +soup_cookie_jar_all_cookies (<em class="parameter"><code><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar</code></em>);</pre> +<p>Constructs a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> with every cookie inside the <em class="parameter"><code>jar</code></em> +. +The cookies in the list are a copy of the original, so +you have to free them when you are done with them.</p> +<div class="refsect3"> +<a name="id-1.4.6.11.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.4.6.11.10.6"></a><h4>Returns</h4> +<p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> +with all the cookies in the <em class="parameter"><code>jar</code></em> +. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> Soup.Cookie]</span></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-jar-get-accept-policy"></a><h3>soup_cookie_jar_get_accept_policy ()</h3> +<pre class="programlisting"><a class="link" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy" title="enum SoupCookieJarAcceptPolicy"><span class="returnvalue">SoupCookieJarAcceptPolicy</span></a> +soup_cookie_jar_get_accept_policy (<em class="parameter"><code><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar</code></em>);</pre> +<p>Gets <em class="parameter"><code>jar</code></em> +'s <a class="link" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy" title="enum SoupCookieJarAcceptPolicy"><span class="type">SoupCookieJarAcceptPolicy</span></a></p> +<div class="refsect3"> +<a name="id-1.4.6.11.11.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.4.6.11.11.6"></a><h4>Returns</h4> +<p> the <a class="link" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy" title="enum SoupCookieJarAcceptPolicy"><span class="type">SoupCookieJarAcceptPolicy</span></a> set in the <em class="parameter"><code>jar</code></em> +</p> +<p></p> +</div> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-jar-set-accept-policy"></a><h3>soup_cookie_jar_set_accept_policy ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_cookie_jar_set_accept_policy (<em class="parameter"><code><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar</code></em>, + <em class="parameter"><code><a class="link" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy" title="enum SoupCookieJarAcceptPolicy"><span class="type">SoupCookieJarAcceptPolicy</span></a> policy</code></em>);</pre> +<p>Sets <em class="parameter"><code>policy</code></em> + as the cookie acceptance policy for <em class="parameter"><code>jar</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.4.6.11.12.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>policy</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy" title="enum SoupCookieJarAcceptPolicy"><span class="type">SoupCookieJarAcceptPolicy</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-cookie-jar-is-persistent"></a><h3>soup_cookie_jar_is_persistent ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_cookie_jar_is_persistent (<em class="parameter"><code><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar</code></em>);</pre> +<p>Gets whether <em class="parameter"><code>jar</code></em> + stores cookies persistenly.</p> +<div class="refsect3"> +<a name="id-1.4.6.11.13.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.4.6.11.13.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>jar</code></em> +storage is persistent or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise.</p> +<p></p> +</div> +<p class="since">Since 2.40</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupCookieJar.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupCookieJar-struct"></a><h3>SoupCookieJar</h3> +<pre class="programlisting">typedef struct _SoupCookieJar SoupCookieJar;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupCookieJarAcceptPolicy"></a><h3>enum SoupCookieJarAcceptPolicy</h3> +<p>The policy for accepting or rejecting cookies returned in +responses.</p> +<div class="refsect3"> +<a name="id-1.4.6.12.3.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-COOKIE-JAR-ACCEPT-ALWAYS:CAPS"></a>SOUP_COOKIE_JAR_ACCEPT_ALWAYS</p></td> +<td class="enum_member_description"> +<p>accept all cookies unconditionally.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-COOKIE-JAR-ACCEPT-NEVER:CAPS"></a>SOUP_COOKIE_JAR_ACCEPT_NEVER</p></td> +<td class="enum_member_description"> +<p>reject all cookies unconditionally.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-COOKIE-JAR-ACCEPT-NO-THIRD-PARTY:CAPS"></a>SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY</p></td> +<td class="enum_member_description"> +<p>accept all cookies set by +the main document loaded in the application using libsoup. An +example of the most common case, web browsers, would be: If +http://www.example.com is the page loaded, accept all cookies set +by example.com, but if a resource from http://www.third-party.com +is loaded from that page reject any cookie that it could try to +set. For libsoup to be able to tell apart first party cookies from +the rest, the application must call <a class="link" href="SoupMessage.html#soup-message-set-first-party" title="soup_message_set_first_party ()"><code class="function">soup_message_set_first_party()</code></a> +on each outgoing <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, setting the <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> of the main +document. If no first party is set in a message when this policy is +in effect, cookies will be assumed to be third party by default.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-COOKIE-JAR-READ-ONLY:CAPS"></a><h3>SOUP_COOKIE_JAR_READ_ONLY</h3> +<pre class="programlisting">#define SOUP_COOKIE_JAR_READ_ONLY "read-only" +</pre> +<p>Alias for the <a class="link" href="SoupCookieJar.html#SoupCookieJar--read-only" title="The “read-only” property"><span class="type">“read-only”</span></a> property. (Whether +or not the cookie jar is read-only.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-COOKIE-JAR-ACCEPT-POLICY:CAPS"></a><h3>SOUP_COOKIE_JAR_ACCEPT_POLICY</h3> +<pre class="programlisting">#define SOUP_COOKIE_JAR_ACCEPT_POLICY "accept-policy" +</pre> +<p>Alias for the <a class="link" href="SoupCookieJar.html#SoupCookieJar--accept-policy" title="The “accept-policy” property"><span class="type">“accept-policy”</span></a> property.</p> +<p class="since">Since 2.30</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupCookieJar.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupCookieJar--accept-policy"></a><h3>The <code class="literal">“accept-policy”</code> property</h3> +<pre class="programlisting"> “accept-policy” <a class="link" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy" title="enum SoupCookieJarAcceptPolicy"><span class="type">SoupCookieJarAcceptPolicy</span></a></pre> +<p>The policy the jar should follow to accept or reject cookies</p> +<p>Flags: Read / Write</p> +<p>Default value: SOUP_COOKIE_JAR_ACCEPT_ALWAYS</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupCookieJar--read-only"></a><h3>The <code class="literal">“read-only”</code> property</h3> +<pre class="programlisting"> “read-only” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Whether or not the cookie jar is read-only.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: FALSE</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupCookieJar.signal-details"></a><h2>Signal Details</h2> +<div class="refsect2"> +<a name="SoupCookieJar-changed"></a><h3>The <code class="literal">“changed”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> *jar, + <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *old_cookie, + <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> *new_cookie, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when <em class="parameter"><code>jar</code></em> + changes. If a cookie has been added, +<em class="parameter"><code>new_cookie</code></em> + will contain the newly-added cookie and +<em class="parameter"><code>old_cookie</code></em> + will be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. If a cookie has been deleted, +<em class="parameter"><code>old_cookie</code></em> + will contain the to-be-deleted cookie and +<em class="parameter"><code>new_cookie</code></em> + will be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. If a cookie has been changed, +<em class="parameter"><code>old_cookie</code></em> + will contain its old value, and <em class="parameter"><code>new_cookie</code></em> + its +new value.</p> +<div class="refsect3"> +<a name="id-1.4.6.14.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>jar</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>old_cookie</p></td> +<td class="parameter_description"><p>the old <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>new_cookie</p></td> +<td class="parameter_description"><p>the new <a class="link" href="SoupCookie.html" title="SoupCookie"><span class="type">SoupCookie</span></a> value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupCookieJarDB.html b/docs/reference/html/SoupCookieJarDB.html new file mode 100644 index 00000000..f0edeed7 --- /dev/null +++ b/docs/reference/html/SoupCookieJarDB.html @@ -0,0 +1,196 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupCookieJarDB</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch03.html" title="Additional Features"> +<link rel="prev" href="SoupCookieJarText.html" title="SoupCookieJarText"> +<link rel="next" href="SoupLogger.html" title="SoupLogger"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupCookieJarDB.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupCookieJarDB.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupCookieJarDB.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupCookieJarDB.properties" class="shortcut">Properties</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupCookieJarText.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupLogger.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupCookieJarDB"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupCookieJarDB.top_of_page"></a>SoupCookieJarDB</span></h2> +<p>SoupCookieJarDB — Database-based Cookie Jar</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupCookieJarDB.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody><tr> +<td class="function_type"> +<a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="returnvalue">SoupCookieJar</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJarDB.html#soup-cookie-jar-db-new" title="soup_cookie_jar_db_new ()">soup_cookie_jar_db_new</a> <span class="c_punctuation">()</span> +</td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookieJarDB.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody><tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupCookieJarDB.html#SoupCookieJarDB--filename" title="The “filename” property">filename</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookieJarDB.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupCookieJarDB.html#SoupCookieJarDB-struct" title="SoupCookieJarDB">SoupCookieJarDB</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupCookieJarDB.html#SOUP-COOKIE-JAR-DB-FILENAME:CAPS" title="SOUP_COOKIE_JAR_DB_FILENAME">SOUP_COOKIE_JAR_DB_FILENAME</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookieJarDB.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> <a class="link" href="SoupCookieJar.html" title="SoupCookieJar">SoupCookieJar</a> + <span class="lineart">╰──</span> SoupCookieJarDB +</pre> +</div> +<div class="refsect1"> +<a name="SoupCookieJarDB.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupCookieJarDB implements + <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature">SoupSessionFeature</a>.</p> +</div> +<div class="refsect1"> +<a name="SoupCookieJarDB.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupCookieJarDB.description"></a><h2>Description</h2> +<p><a class="link" href="SoupCookieJarDB.html" title="SoupCookieJarDB"><span class="type">SoupCookieJarDB</span></a> is a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> that reads cookies from and +writes them to a sqlite database in the new Mozilla format.</p> +<p>(This is identical to <code class="literal">SoupCookieJarSqlite</code> in +libsoup-gnome; it has just been moved into libsoup proper, and +renamed to avoid conflicting.)</p> +</div> +<div class="refsect1"> +<a name="SoupCookieJarDB.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-cookie-jar-db-new"></a><h3>soup_cookie_jar_db_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="returnvalue">SoupCookieJar</span></a> * +soup_cookie_jar_db_new (<em class="parameter"><code>const <span class="type">char</span> *filename</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> read_only</code></em>);</pre> +<p>Creates a <a class="link" href="SoupCookieJarDB.html" title="SoupCookieJarDB"><span class="type">SoupCookieJarDB</span></a>.</p> +<p><em class="parameter"><code>filename</code></em> + will be read in at startup to create an initial set of +cookies. If <em class="parameter"><code>read_only</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, then the non-session cookies will +be written to <em class="parameter"><code>filename</code></em> + when the 'changed' signal is emitted from +the jar. (If <em class="parameter"><code>read_only</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, then the cookie jar will only be +used for this session, and changes made to it will be lost when the +jar is destroyed.)</p> +<div class="refsect3"> +<a name="id-1.4.8.10.2.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>filename</p></td> +<td class="parameter_description"><p>the filename to read to/write from, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>read_only</p></td> +<td class="parameter_description"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>filename</code></em> +is read-only</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.4.8.10.2.7"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupCookieJarDB.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupCookieJarDB-struct"></a><h3>SoupCookieJarDB</h3> +<pre class="programlisting">typedef struct _SoupCookieJarDB SoupCookieJarDB;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-COOKIE-JAR-DB-FILENAME:CAPS"></a><h3>SOUP_COOKIE_JAR_DB_FILENAME</h3> +<pre class="programlisting">#define SOUP_COOKIE_JAR_DB_FILENAME "filename" +</pre> +<p>Alias for the <a class="link" href="SoupCookieJarDB.html#SoupCookieJarDB--filename" title="The “filename” property"><span class="type">“filename”</span></a> property. (The +cookie-storage filename.)</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupCookieJarDB.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupCookieJarDB--filename"></a><h3>The <code class="literal">“filename”</code> property</h3> +<pre class="programlisting"> “filename” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>Cookie-storage filename.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: NULL</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupCookieJarText.html b/docs/reference/html/SoupCookieJarText.html new file mode 100644 index 00000000..cae26465 --- /dev/null +++ b/docs/reference/html/SoupCookieJarText.html @@ -0,0 +1,193 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupCookieJarText</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch03.html" title="Additional Features"> +<link rel="prev" href="SoupCookieJar.html" title="SoupCookieJar"> +<link rel="next" href="SoupCookieJarDB.html" title="SoupCookieJarDB"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupCookieJarText.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupCookieJarText.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupCookieJarText.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupCookieJarText.properties" class="shortcut">Properties</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupCookieJar.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupCookieJarDB.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupCookieJarText"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupCookieJarText.top_of_page"></a>SoupCookieJarText</span></h2> +<p>SoupCookieJarText — Text-file-based ("cookies.txt") Cookie Jar</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupCookieJarText.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody><tr> +<td class="function_type"> +<a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="returnvalue">SoupCookieJar</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupCookieJarText.html#soup-cookie-jar-text-new" title="soup_cookie_jar_text_new ()">soup_cookie_jar_text_new</a> <span class="c_punctuation">()</span> +</td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookieJarText.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody><tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupCookieJarText.html#SoupCookieJarText--filename" title="The “filename” property">filename</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookieJarText.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupCookieJarText.html#SoupCookieJarText-struct" title="SoupCookieJarText">SoupCookieJarText</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupCookieJarText.html#SOUP-COOKIE-JAR-TEXT-FILENAME:CAPS" title="SOUP_COOKIE_JAR_TEXT_FILENAME">SOUP_COOKIE_JAR_TEXT_FILENAME</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupCookieJarText.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> <a class="link" href="SoupCookieJar.html" title="SoupCookieJar">SoupCookieJar</a> + <span class="lineart">╰──</span> SoupCookieJarText +</pre> +</div> +<div class="refsect1"> +<a name="SoupCookieJarText.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupCookieJarText implements + <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature">SoupSessionFeature</a>.</p> +</div> +<div class="refsect1"> +<a name="SoupCookieJarText.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupCookieJarText.description"></a><h2>Description</h2> +<p><a class="link" href="SoupCookieJarText.html" title="SoupCookieJarText"><span class="type">SoupCookieJarText</span></a> is a <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a> that reads cookies from and +writes them to a text file in the Mozilla "cookies.txt" format.</p> +</div> +<div class="refsect1"> +<a name="SoupCookieJarText.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-cookie-jar-text-new"></a><h3>soup_cookie_jar_text_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="returnvalue">SoupCookieJar</span></a> * +soup_cookie_jar_text_new (<em class="parameter"><code>const <span class="type">char</span> *filename</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> read_only</code></em>);</pre> +<p>Creates a <a class="link" href="SoupCookieJarText.html" title="SoupCookieJarText"><span class="type">SoupCookieJarText</span></a>.</p> +<p><em class="parameter"><code>filename</code></em> + will be read in at startup to create an initial set of +cookies. If <em class="parameter"><code>read_only</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, then the non-session cookies will +be written to <em class="parameter"><code>filename</code></em> + when the 'changed' signal is emitted from +the jar. (If <em class="parameter"><code>read_only</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, then the cookie jar will only be +used for this session, and changes made to it will be lost when the +jar is destroyed.)</p> +<div class="refsect3"> +<a name="id-1.4.7.10.2.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>filename</p></td> +<td class="parameter_description"><p>the filename to read to/write from</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>read_only</p></td> +<td class="parameter_description"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>filename</code></em> +is read-only</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.4.7.10.2.7"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a></p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupCookieJarText.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupCookieJarText-struct"></a><h3>SoupCookieJarText</h3> +<pre class="programlisting">typedef struct _SoupCookieJarText SoupCookieJarText;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-COOKIE-JAR-TEXT-FILENAME:CAPS"></a><h3>SOUP_COOKIE_JAR_TEXT_FILENAME</h3> +<pre class="programlisting">#define SOUP_COOKIE_JAR_TEXT_FILENAME "filename" +</pre> +<p>Alias for the <a class="link" href="SoupCookieJarText.html#SoupCookieJarText--filename" title="The “filename” property"><span class="type">“filename”</span></a> property. (The +cookie-storage filename.)</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupCookieJarText.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupCookieJarText--filename"></a><h3>The <code class="literal">“filename”</code> property</h3> +<pre class="programlisting"> “filename” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>Cookie-storage filename.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: NULL</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupLogger.html b/docs/reference/html/SoupLogger.html new file mode 100644 index 00000000..fdfcf5d3 --- /dev/null +++ b/docs/reference/html/SoupLogger.html @@ -0,0 +1,647 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupLogger</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch03.html" title="Additional Features"> +<link rel="prev" href="SoupCookieJarDB.html" title="SoupCookieJarDB"> +<link rel="next" href="SoupProxyResolverDefault.html" title="SoupProxyResolverDefault"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupLogger.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupLogger.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupLogger.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupCookieJarDB.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupProxyResolverDefault.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupLogger"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupLogger.top_of_page"></a>SoupLogger</span></h2> +<p>SoupLogger — Debug logging support</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupLogger.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupLogger.html" title="SoupLogger"><span class="returnvalue">SoupLogger</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupLogger.html#soup-logger-new" title="soup_logger_new ()">soup_logger_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupLogger.html#soup-logger-attach" title="soup_logger_attach ()">soup_logger_attach</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupLogger.html#soup-logger-detach" title="soup_logger_detach ()">soup_logger_detach</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupLogger.html#SoupLoggerLogLevel" title="enum SoupLoggerLogLevel"><span class="returnvalue">SoupLoggerLogLevel</span></a> +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupLogger.html#SoupLoggerFilter" title="SoupLoggerFilter ()">*SoupLoggerFilter</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupLogger.html#soup-logger-set-request-filter" title="soup_logger_set_request_filter ()">soup_logger_set_request_filter</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupLogger.html#soup-logger-set-response-filter" title="soup_logger_set_response_filter ()">soup_logger_set_response_filter</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupLogger.html#SoupLoggerPrinter" title="SoupLoggerPrinter ()">*SoupLoggerPrinter</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupLogger.html#soup-logger-set-printer" title="soup_logger_set_printer ()">soup_logger_set_printer</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupLogger.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupLogger.html#SoupLogger-struct" title="SoupLogger">SoupLogger</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupLogger.html#SoupLoggerLogLevel" title="enum SoupLoggerLogLevel">SoupLoggerLogLevel</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupLogger.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupLogger +</pre> +</div> +<div class="refsect1"> +<a name="SoupLogger.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupLogger implements + <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature">SoupSessionFeature</a>.</p> +</div> +<div class="refsect1"> +<a name="SoupLogger.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupLogger.description"></a><h2>Description</h2> +<p><a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a> watches a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> and logs the HTTP traffic that +it generates, for debugging purposes. Many applications use an +environment variable to determine whether or not to use +<a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a>, and to determine the amount of debugging output.</p> +<p>To use <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a>, first create a logger with <a class="link" href="SoupLogger.html#soup-logger-new" title="soup_logger_new ()"><code class="function">soup_logger_new()</code></a>, +optionally configure it with <a class="link" href="SoupLogger.html#soup-logger-set-request-filter" title="soup_logger_set_request_filter ()"><code class="function">soup_logger_set_request_filter()</code></a>, +<a class="link" href="SoupLogger.html#soup-logger-set-response-filter" title="soup_logger_set_response_filter ()"><code class="function">soup_logger_set_response_filter()</code></a>, and <a class="link" href="SoupLogger.html#soup-logger-set-printer" title="soup_logger_set_printer ()"><code class="function">soup_logger_set_printer()</code></a>, +and then attach it to a session (or multiple sessions) with +<a class="link" href="SoupSession.html#soup-session-add-feature" title="soup_session_add_feature ()"><code class="function">soup_session_add_feature()</code></a>.</p> +<p>By default, the debugging output is sent to +<code class="literal">stdout</code>, and looks something like:</p> +<div class="informalexample"><pre class="screen"> +> POST /unauth HTTP/1.1 +> Soup-Debug-Timestamp: 1200171744 +> Soup-Debug: SoupSessionAsync 1 (0x612190), SoupMessage 1 (0x617000), SoupSocket 1 (0x612220) +> Host: localhost +> Content-Type: text/plain +> Connection: close +> +> This is a test. + +< HTTP/1.1 201 Created +< Soup-Debug-Timestamp: 1200171744 +< Soup-Debug: SoupMessage 1 (0x617000) +< Date: Sun, 12 Jan 2008 21:02:24 GMT +< Content-Length: 0 +</pre></div> +<p>The <code class="literal">Soup-Debug-Timestamp</code> line gives the time (as +a <span class="type">time_t</span>) when the request was sent, or the response fully +received.</p> +<p>The <code class="literal">Soup-Debug</code> line gives further debugging +information about the <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, and <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> +involved; the hex numbers are the addresses of the objects in +question (which may be useful if you are running in a debugger). +The decimal IDs are simply counters that uniquely identify objects +across the lifetime of the <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a>. In particular, this can be +used to identify when multiple messages are sent across the same +connection.</p> +<p>Currently, the request half of the message is logged just before +the first byte of the request gets written to the network (from the +<a class="link" href="SoupSession.html#SoupSession-request-started" title="The “request-started” signal"><span class="type">“request_started”</span></a> signal), which means that if you have +not made the complete request body available at that point, it will +not be logged.</p> +<p>The response is logged just after the last byte of the response +body is read from the network (from the <a class="link" href="SoupMessage.html#SoupMessage-got-body" title="The “got-body” signal"><span class="type">“got_body”</span></a> or +<a class="link" href="SoupMessage.html#SoupMessage-got-informational" title="The “got-informational” signal"><span class="type">“got_informational”</span></a> signal), which means that the +<a class="link" href="SoupMessage.html#SoupMessage-got-headers" title="The “got-headers” signal"><span class="type">“got_headers”</span></a> signal, and anything triggered off it +(such as <a class="link" href="SoupSession.html#SoupSession-authenticate" title="The “authenticate” signal"><span class="type">“authenticate”</span></a>) will be emitted +<span class="emphasis"><em>before</em></span> the response headers are actually +logged.</p> +<p>If the response doesn't happen to trigger the +<a class="link" href="SoupMessage.html#SoupMessage-got-body" title="The “got-body” signal"><span class="type">“got_body”</span></a> nor <a class="link" href="SoupMessage.html#SoupMessage-got-informational" title="The “got-informational” signal"><span class="type">“got_informational”</span></a> signals +due to, for example, a cancellation before receiving the last byte +of the response body, the response will still be logged on the +event of the <a class="link" href="SoupMessage.html#SoupMessage-finished" title="The “finished” signal"><span class="type">“finished”</span></a> signal.</p> +</div> +<div class="refsect1"> +<a name="SoupLogger.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-logger-new"></a><h3>soup_logger_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupLogger.html" title="SoupLogger"><span class="returnvalue">SoupLogger</span></a> * +soup_logger_new (<em class="parameter"><code><a class="link" href="SoupLogger.html#SoupLoggerLogLevel" title="enum SoupLoggerLogLevel"><span class="type">SoupLoggerLogLevel</span></a> level</code></em>, + <em class="parameter"><code><span class="type">int</span> max_body_size</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a> with the given debug level. If <em class="parameter"><code>level</code></em> + is +<a class="link" href="SoupLogger.html#SOUP-LOGGER-LOG-BODY:CAPS"><code class="literal">SOUP_LOGGER_LOG_BODY</code></a>, <em class="parameter"><code>max_body_size</code></em> + gives the maximum number of +bytes of the body that will be logged. (-1 means "no limit".)</p> +<p>If you need finer control over what message parts are and aren't +logged, use <a class="link" href="SoupLogger.html#soup-logger-set-request-filter" title="soup_logger_set_request_filter ()"><code class="function">soup_logger_set_request_filter()</code></a> and +<a class="link" href="SoupLogger.html#soup-logger-set-response-filter" title="soup_logger_set_response_filter ()"><code class="function">soup_logger_set_response_filter()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.4.9.9.2.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>level</p></td> +<td class="parameter_description"><p>the debug level</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>max_body_size</p></td> +<td class="parameter_description"><p>the maximum body size to output, or -1</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.4.9.9.2.7"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-logger-attach"></a><h3>soup_logger_attach ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_logger_attach (<em class="parameter"><code><a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a> *logger</code></em>, + <em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>);</pre> +<div class="warning"> +<p><code class="literal">soup_logger_attach</code> is deprecated and should not be used in newly-written code.</p> +<p>Use <a class="link" href="SoupSession.html#soup-session-add-feature" title="soup_session_add_feature ()"><code class="function">soup_session_add_feature()</code></a> instead.</p> +</div> +<p>Sets <em class="parameter"><code>logger</code></em> + to watch <em class="parameter"><code>session</code></em> + and print debug information for +its messages.</p> +<p>(The session will take a reference on <em class="parameter"><code>logger</code></em> +, which will be +removed when you call <a class="link" href="SoupLogger.html#soup-logger-detach" title="soup_logger_detach ()"><code class="function">soup_logger_detach()</code></a>, or when the session is +destroyed.)</p> +<div class="refsect3"> +<a name="id-1.4.9.9.3.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>logger</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-logger-detach"></a><h3>soup_logger_detach ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_logger_detach (<em class="parameter"><code><a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a> *logger</code></em>, + <em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>);</pre> +<div class="warning"> +<p><code class="literal">soup_logger_detach</code> is deprecated and should not be used in newly-written code.</p> +<p>Use <a class="link" href="SoupSession.html#soup-session-remove-feature" title="soup_session_remove_feature ()"><code class="function">soup_session_remove_feature()</code></a> instead.</p> +</div> +<p>Stops <em class="parameter"><code>logger</code></em> + from watching <em class="parameter"><code>session</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.4.9.9.4.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>logger</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupLoggerFilter"></a><h3>SoupLoggerFilter ()</h3> +<pre class="programlisting"><a class="link" href="SoupLogger.html#SoupLoggerLogLevel" title="enum SoupLoggerLogLevel"><span class="returnvalue">SoupLoggerLogLevel</span></a> +<span class="c_punctuation">(</span>*SoupLoggerFilter<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a> *logger</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>The prototype for a logging filter. The filter callback will be +invoked for each request or response, and should analyze it and +return a <a class="link" href="SoupLogger.html#SoupLoggerLogLevel" title="enum SoupLoggerLogLevel"><span class="type">SoupLoggerLogLevel</span></a> value indicating how much of the +message to log. Eg, it might choose between <a class="link" href="SoupLogger.html#SOUP-LOGGER-LOG-BODY:CAPS"><code class="literal">SOUP_LOGGER_LOG_BODY</code></a> +and <a class="link" href="SoupLogger.html#SOUP-LOGGER-LOG-HEADERS:CAPS"><code class="literal">SOUP_LOGGER_LOG_HEADERS</code></a> depending on the Content-Type.</p> +<div class="refsect3"> +<a name="id-1.4.9.9.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>logger</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message being logged</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the data passed to <a class="link" href="SoupLogger.html#soup-logger-set-request-filter" title="soup_logger_set_request_filter ()"><code class="function">soup_logger_set_request_filter()</code></a> +or <a class="link" href="SoupLogger.html#soup-logger-set-response-filter" title="soup_logger_set_response_filter ()"><code class="function">soup_logger_set_response_filter()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.4.9.9.5.6"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupLogger.html#SoupLoggerLogLevel" title="enum SoupLoggerLogLevel"><span class="type">SoupLoggerLogLevel</span></a> value indicating how much of +the message to log</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-logger-set-request-filter"></a><h3>soup_logger_set_request_filter ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_logger_set_request_filter (<em class="parameter"><code><a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a> *logger</code></em>, + <em class="parameter"><code><a class="link" href="SoupLogger.html#SoupLoggerFilter" title="SoupLoggerFilter ()"><span class="type">SoupLoggerFilter</span></a> request_filter</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> filter_data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> destroy</code></em>);</pre> +<p>Sets up a filter to determine the log level for a given request. +For each HTTP request <em class="parameter"><code>logger</code></em> + will invoke <em class="parameter"><code>request_filter</code></em> + to +determine how much (if any) of that request to log. (If you do not +set a request filter, <em class="parameter"><code>logger</code></em> + will just always log requests at the +level passed to <a class="link" href="SoupLogger.html#soup-logger-new" title="soup_logger_new ()"><code class="function">soup_logger_new()</code></a>.)</p> +<div class="refsect3"> +<a name="id-1.4.9.9.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>logger</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>request_filter</p></td> +<td class="parameter_description"><p>the callback for request debugging</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>filter_data</p></td> +<td class="parameter_description"><p>data to pass to the callback</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>destroy</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> to free <em class="parameter"><code>filter_data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-logger-set-response-filter"></a><h3>soup_logger_set_response_filter ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_logger_set_response_filter (<em class="parameter"><code><a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a> *logger</code></em>, + <em class="parameter"><code><a class="link" href="SoupLogger.html#SoupLoggerFilter" title="SoupLoggerFilter ()"><span class="type">SoupLoggerFilter</span></a> response_filter</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> filter_data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> destroy</code></em>);</pre> +<p>Sets up a filter to determine the log level for a given response. +For each HTTP response <em class="parameter"><code>logger</code></em> + will invoke <em class="parameter"><code>response_filter</code></em> + to +determine how much (if any) of that response to log. (If you do not +set a response filter, <em class="parameter"><code>logger</code></em> + will just always log responses at +the level passed to <a class="link" href="SoupLogger.html#soup-logger-new" title="soup_logger_new ()"><code class="function">soup_logger_new()</code></a>.)</p> +<div class="refsect3"> +<a name="id-1.4.9.9.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>logger</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>response_filter</p></td> +<td class="parameter_description"><p>the callback for response debugging</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>filter_data</p></td> +<td class="parameter_description"><p>data to pass to the callback</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>destroy</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> to free <em class="parameter"><code>filter_data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupLoggerPrinter"></a><h3>SoupLoggerPrinter ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +<span class="c_punctuation">(</span>*SoupLoggerPrinter<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a> *logger</code></em>, + <em class="parameter"><code><a class="link" href="SoupLogger.html#SoupLoggerLogLevel" title="enum SoupLoggerLogLevel"><span class="type">SoupLoggerLogLevel</span></a> level</code></em>, + <em class="parameter"><code><span class="type">char</span> direction</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>The prototype for a custom printing callback.</p> +<p><em class="parameter"><code>level</code></em> + indicates what kind of information is being printed. Eg, it +will be <a class="link" href="SoupLogger.html#SOUP-LOGGER-LOG-HEADERS:CAPS"><code class="literal">SOUP_LOGGER_LOG_HEADERS</code></a> if <em class="parameter"><code>data</code></em> + is header data.</p> +<p><em class="parameter"><code>direction</code></em> + is either '<', '>', or ' ', and <em class="parameter"><code>data</code></em> + is the single line +to print; the printer is expected to add a terminating newline.</p> +<p>To get the effect of the default printer, you would do:</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="function">printf</span><span class="normal"> </span><span class="symbol">(</span><span class="string">"%c %s</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">,</span><span class="normal"> direction</span><span class="symbol">,</span><span class="normal"> data</span><span class="symbol">);</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<div class="refsect3"> +<a name="id-1.4.9.9.8.9"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>logger</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>level</p></td> +<td class="parameter_description"><p>the level of the information being printed.</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>direction</p></td> +<td class="parameter_description"><p>a single-character prefix to <em class="parameter"><code>data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p>data to print</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the data passed to <a class="link" href="SoupLogger.html#soup-logger-set-printer" title="soup_logger_set_printer ()"><code class="function">soup_logger_set_printer()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-logger-set-printer"></a><h3>soup_logger_set_printer ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_logger_set_printer (<em class="parameter"><code><a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a> *logger</code></em>, + <em class="parameter"><code><a class="link" href="SoupLogger.html#SoupLoggerPrinter" title="SoupLoggerPrinter ()"><span class="type">SoupLoggerPrinter</span></a> printer</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> printer_data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> destroy</code></em>);</pre> +<p>Sets up an alternate log printing routine, if you don't want +the log to go to <code class="literal">stdout</code>.</p> +<div class="refsect3"> +<a name="id-1.4.9.9.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>logger</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>printer</p></td> +<td class="parameter_description"><p>the callback for printing logging output</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>printer_data</p></td> +<td class="parameter_description"><p>data to pass to the callback</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>destroy</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> to free <em class="parameter"><code>printer_data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +<div class="refsect1"> +<a name="SoupLogger.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupLogger-struct"></a><h3>SoupLogger</h3> +<pre class="programlisting">typedef struct _SoupLogger SoupLogger;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupLoggerLogLevel"></a><h3>enum SoupLoggerLogLevel</h3> +<p>Describes the level of logging output to provide.</p> +<div class="refsect3"> +<a name="id-1.4.9.10.3.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-LOGGER-LOG-NONE:CAPS"></a>SOUP_LOGGER_LOG_NONE</p></td> +<td class="enum_member_description"> +<p>No logging</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-LOGGER-LOG-MINIMAL:CAPS"></a>SOUP_LOGGER_LOG_MINIMAL</p></td> +<td class="enum_member_description"> +<p>Log the Request-Line or Status-Line and +the Soup-Debug pseudo-headers</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-LOGGER-LOG-HEADERS:CAPS"></a>SOUP_LOGGER_LOG_HEADERS</p></td> +<td class="enum_member_description"> +<p>Log the full request/response headers</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-LOGGER-LOG-BODY:CAPS"></a>SOUP_LOGGER_LOG_BODY</p></td> +<td class="enum_member_description"> +<p>Log the full headers and request/response +bodies.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupMessage.html b/docs/reference/html/SoupMessage.html new file mode 100644 index 00000000..c9dd121e --- /dev/null +++ b/docs/reference/html/SoupMessage.html @@ -0,0 +1,2768 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupMessage</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupCookie.html" title="SoupCookie"> +<link rel="next" href="SoupMessageHeaders.html" title="SoupMessageHeaders"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupMessage.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupMessage.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupMessage.properties" class="shortcut">Properties</a></span><span id="nav_signals"> <span class="dim">|</span> + <a href="#SoupMessage.signals" class="shortcut">Signals</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupCookie.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupMessageHeaders.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupMessage"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupMessage.top_of_page"></a>SoupMessage</span></h2> +<p>SoupMessage — An HTTP request and response.</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupMessage.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-new" title="soup_message_new ()">soup_message_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-new-from-uri" title="soup_message_new_from_uri ()">soup_message_new_from_uri</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-set-request" title="soup_message_set_request ()">soup_message_set_request</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-set-response" title="soup_message_set_response ()">soup_message_set_response</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-set-http-version" title="soup_message_set_http_version ()">soup_message_set_http_version</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessage.html#SoupHTTPVersion" title="enum SoupHTTPVersion"><span class="returnvalue">SoupHTTPVersion</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-get-http-version" title="soup_message_get_http_version ()">soup_message_get_http_version</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-get-uri" title="soup_message_get_uri ()">soup_message_get_uri</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-set-uri" title="soup_message_set_uri ()">soup_message_set_uri</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-get-address" title="soup_message_get_address ()">soup_message_get_address</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-set-status" title="soup_message_set_status ()">soup_message_set_status</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-set-status-full" title="soup_message_set_status_full ()">soup_message_set_status_full</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-set-redirect" title="soup_message_set_redirect ()">soup_message_set_redirect</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-is-keepalive" title="soup_message_is_keepalive ()">soup_message_is_keepalive</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-get-https-status" title="soup_message_get_https_status ()">soup_message_get_https_status</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-set-first-party" title="soup_message_set_first_party ()">soup_message_set_first_party</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-get-first-party" title="soup_message_get_first_party ()">soup_message_get_first_party</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-add-header-handler" title="soup_message_add_header_handler ()">soup_message_add_header_handler</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-add-status-code-handler" title="soup_message_add_status_code_handler ()">soup_message_add_status_code_handler</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-set-flags" title="soup_message_set_flags ()">soup_message_set_flags</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessage.html#SoupMessageFlags" title="enum SoupMessageFlags"><span class="returnvalue">SoupMessageFlags</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-get-flags" title="soup_message_get_flags ()">soup_message_get_flags</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupMessage.html#SoupChunkAllocator" title="SoupChunkAllocator ()">*SoupChunkAllocator</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-set-chunk-allocator" title="soup_message_set_chunk_allocator ()">soup_message_set_chunk_allocator</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-disable-feature" title="soup_message_disable_feature ()">soup_message_disable_feature</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupRequest.html" title="SoupRequest"><span class="returnvalue">SoupRequest</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-get-soup-request" title="soup_message_get_soup_request ()">soup_message_get_soup_request</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessage.html#SoupMessagePriority" title="enum SoupMessagePriority"><span class="returnvalue">SoupMessagePriority</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-get-priority" title="soup_message_get_priority ()">soup_message_get_priority</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessage.html#soup-message-set-priority" title="soup_message_set_priority ()">soup_message_set_priority</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMessage.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"> +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *</td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--first-party" title="The “first-party” property">first-party</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a class="link" href="SoupMessage.html#SoupMessageFlags" title="enum SoupMessageFlags"><span class="type">SoupMessageFlags</span></a></td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--flags" title="The “flags” property">flags</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a class="link" href="SoupMessage.html#SoupHTTPVersion" title="enum SoupHTTPVersion"><span class="type">SoupHTTPVersion</span></a></td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--http-version" title="The “http-version” property">http-version</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--method" title="The “method” property">method</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a class="link" href="SoupMessage.html#SoupMessagePriority" title="enum SoupMessagePriority"><span class="type">SoupMessagePriority</span></a></td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--priority" title="The “priority” property">priority</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--reason-phrase" title="The “reason-phrase” property">reason-phrase</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *</td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--request-body" title="The “request-body” property">request-body</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> *</td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--request-body-data" title="The “request-body-data” property">request-body-data</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *</td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--request-headers" title="The “request-headers” property">request-headers</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *</td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--response-body" title="The “response-body” property">response-body</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> *</td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--response-body-data" title="The “response-body-data” property">response-body-data</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *</td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--response-headers" title="The “response-headers” property">response-headers</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--server-side" title="The “server-side” property">server-side</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a></td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--status-code" title="The “status-code” property">status-code</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<span class="type">GTlsCertificate</span> *</td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--tls-certificate" title="The “tls-certificate” property">tls-certificate</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><span class="type">GTlsCertificateFlags</span></td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--tls-errors" title="The “tls-errors” property">tls-errors</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *</td> +<td class="property_name"><a class="link" href="SoupMessage.html#SoupMessage--uri" title="The “uri” property">uri</a></td> +<td class="property_flags">Read / Write</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMessage.signals"></a><h2>Signals</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="signals_return"> +<col width="300px" class="signals_name"> +<col width="200px" class="signals_flags"> +</colgroup> +<tbody> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-content-sniffed" title="The “content-sniffed” signal">content-sniffed</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-finished" title="The “finished” signal">finished</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-got-body" title="The “got-body” signal">got-body</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal">got-chunk</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-got-headers" title="The “got-headers” signal">got-headers</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-got-informational" title="The “got-informational” signal">got-informational</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-network-event" title="The “network-event” signal">network-event</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-restarted" title="The “restarted” signal">restarted</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-wrote-body" title="The “wrote-body” signal">wrote-body</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-wrote-body-data" title="The “wrote-body-data” signal">wrote-body-data</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-wrote-chunk" title="The “wrote-chunk” signal">wrote-chunk</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-wrote-headers" title="The “wrote-headers” signal">wrote-headers</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupMessage.html#SoupMessage-wrote-informational" title="The “wrote-informational” signal">wrote-informational</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMessage.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupMessage.html#SoupMessage-struct" title="SoupMessage">SoupMessage</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SoupHTTPVersion" title="enum SoupHTTPVersion">SoupHTTPVersion</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SoupMessageFlags" title="enum SoupMessageFlags">SoupMessageFlags</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SoupMessagePriority" title="enum SoupMessagePriority">SoupMessagePriority</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-METHOD:CAPS" title="SOUP_MESSAGE_METHOD">SOUP_MESSAGE_METHOD</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-URI:CAPS" title="SOUP_MESSAGE_URI">SOUP_MESSAGE_URI</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-HTTP-VERSION:CAPS" title="SOUP_MESSAGE_HTTP_VERSION">SOUP_MESSAGE_HTTP_VERSION</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-FLAGS:CAPS" title="SOUP_MESSAGE_FLAGS">SOUP_MESSAGE_FLAGS</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-STATUS-CODE:CAPS" title="SOUP_MESSAGE_STATUS_CODE">SOUP_MESSAGE_STATUS_CODE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-REASON-PHRASE:CAPS" title="SOUP_MESSAGE_REASON_PHRASE">SOUP_MESSAGE_REASON_PHRASE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-SERVER-SIDE:CAPS" title="SOUP_MESSAGE_SERVER_SIDE">SOUP_MESSAGE_SERVER_SIDE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-FIRST-PARTY:CAPS" title="SOUP_MESSAGE_FIRST_PARTY">SOUP_MESSAGE_FIRST_PARTY</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-PRIORITY:CAPS" title="SOUP_MESSAGE_PRIORITY">SOUP_MESSAGE_PRIORITY</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-REQUEST-BODY:CAPS" title="SOUP_MESSAGE_REQUEST_BODY">SOUP_MESSAGE_REQUEST_BODY</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-REQUEST-BODY-DATA:CAPS" title="SOUP_MESSAGE_REQUEST_BODY_DATA">SOUP_MESSAGE_REQUEST_BODY_DATA</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-REQUEST-HEADERS:CAPS" title="SOUP_MESSAGE_REQUEST_HEADERS">SOUP_MESSAGE_REQUEST_HEADERS</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-RESPONSE-BODY:CAPS" title="SOUP_MESSAGE_RESPONSE_BODY">SOUP_MESSAGE_RESPONSE_BODY</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-RESPONSE-BODY-DATA:CAPS" title="SOUP_MESSAGE_RESPONSE_BODY_DATA">SOUP_MESSAGE_RESPONSE_BODY_DATA</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-RESPONSE-HEADERS:CAPS" title="SOUP_MESSAGE_RESPONSE_HEADERS">SOUP_MESSAGE_RESPONSE_HEADERS</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-TLS-CERTIFICATE:CAPS" title="SOUP_MESSAGE_TLS_CERTIFICATE">SOUP_MESSAGE_TLS_CERTIFICATE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupMessage.html#SOUP-MESSAGE-TLS-ERRORS:CAPS" title="SOUP_MESSAGE_TLS_ERRORS">SOUP_MESSAGE_TLS_ERRORS</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMessage.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupMessage +</pre> +</div> +<div class="refsect1"> +<a name="SoupMessage.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupMessage.description"></a><h2>Description</h2> +<p>A <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> represents an HTTP message that is being sent or +received.</p> +<p>For client-side usage, if you are using the traditional +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> APIs (<a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a> and +<a class="link" href="SoupSession.html#soup-session-send-message" title="soup_session_send_message ()"><code class="function">soup_session_send_message()</code></a>), you would create a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> with +<a class="link" href="SoupMessage.html#soup-message-new" title="soup_message_new ()"><code class="function">soup_message_new()</code></a> or <a class="link" href="SoupMessage.html#soup-message-new-from-uri" title="soup_message_new_from_uri ()"><code class="function">soup_message_new_from_uri()</code></a>, set up its +fields appropriately, and send it. If you are using the newer +<a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> API, you would create a request with +<a class="link" href="SoupSession.html#soup-session-request-http" title="soup_session_request_http ()"><code class="function">soup_session_request_http()</code></a> or <a class="link" href="SoupSession.html#soup-session-request-http-uri" title="soup_session_request_http_uri ()"><code class="function">soup_session_request_http_uri()</code></a>, and +the returned <a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a> will already have an associated +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> that you can retrieve via +<a class="link" href="SoupRequestHTTP.html#soup-request-http-get-message" title="soup_request_http_get_message ()"><code class="function">soup_request_http_get_message()</code></a>.</p> +<p>For server-side usage, <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> will create <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>s automatically for incoming requests, which your application +will receive via handlers.</p> +<p>Note that libsoup's terminology here does not quite match the HTTP +specification: in RFC 2616, an "HTTP-message" is +<span class="emphasis"><em>either</em></span> a Request, <span class="emphasis"><em>or</em></span> a +Response. In libsoup, a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> combines both the request and +the response.</p> +</div> +<div class="refsect1"> +<a name="SoupMessage.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-message-new"></a><h3>soup_message_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +soup_message_new (<em class="parameter"><code>const <span class="type">char</span> *method</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *uri_string</code></em>);</pre> +<p>Creates a new empty <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, which will connect to <em class="parameter"><code>uri</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.8.10.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>method</p></td> +<td class="parameter_description"><p>the HTTP method for the created request</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri_string</p></td> +<td class="parameter_description"><p>the destination endpoint (as a string)</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.2.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> (or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if <em class="parameter"><code>uri</code></em> +could not +be parsed).</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-new-from-uri"></a><h3>soup_message_new_from_uri ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +soup_message_new_from_uri (<em class="parameter"><code>const <span class="type">char</span> *method</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Creates a new empty <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, which will connect to <em class="parameter"><code>uri</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.8.10.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>method</p></td> +<td class="parameter_description"><p>the HTTP method for the created request</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>the destination endpoint (as a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>)</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.3.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-set-request"></a><h3>soup_message_set_request ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_set_request (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *content_type</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupMemoryUse" title="enum SoupMemoryUse"><span class="type">SoupMemoryUse</span></a> req_use</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *req_body</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> req_length</code></em>);</pre> +<p>Convenience function to set the request body of a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>. If +<em class="parameter"><code>content_type</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, the request body must be empty as well.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>content_type</p></td> +<td class="parameter_description"><p> MIME Content-Type of the body. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>req_use</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html#SoupMemoryUse" title="enum SoupMemoryUse"><span class="type">SoupMemoryUse</span></a> describing how to handle <em class="parameter"><code>req_body</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>req_body</p></td> +<td class="parameter_description"><p> a data buffer containing the body of the message request. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=req_length][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> guint8]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>req_length</p></td> +<td class="parameter_description"><p>the byte length of <em class="parameter"><code>req_body</code></em> +.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-set-response"></a><h3>soup_message_set_response ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_set_response (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *content_type</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupMemoryUse" title="enum SoupMemoryUse"><span class="type">SoupMemoryUse</span></a> resp_use</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *resp_body</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> resp_length</code></em>);</pre> +<p>Convenience function to set the response body of a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>. If +<em class="parameter"><code>content_type</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, the response body must be empty as well.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>content_type</p></td> +<td class="parameter_description"><p> MIME Content-Type of the body. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>resp_use</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html#SoupMemoryUse" title="enum SoupMemoryUse"><span class="type">SoupMemoryUse</span></a> describing how to handle <em class="parameter"><code>resp_body</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>resp_body</p></td> +<td class="parameter_description"><p> a data buffer containing the body of the message response. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=resp_length][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> guint8]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>resp_length</p></td> +<td class="parameter_description"><p>the byte length of <em class="parameter"><code>resp_body</code></em> +.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-set-http-version"></a><h3>soup_message_set_http_version ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_set_http_version (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html#SoupHTTPVersion" title="enum SoupHTTPVersion"><span class="type">SoupHTTPVersion</span></a> version</code></em>);</pre> +<p>Sets the HTTP version on <em class="parameter"><code>msg</code></em> +. The default version is +<a class="link" href="SoupMessage.html#SOUP-HTTP-1-1:CAPS"><code class="literal">SOUP_HTTP_1_1</code></a>. Setting it to <a class="link" href="SoupMessage.html#SOUP-HTTP-1-0:CAPS"><code class="literal">SOUP_HTTP_1_0</code></a> will prevent certain +functionality from being used.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>version</p></td> +<td class="parameter_description"><p>the HTTP version</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-get-http-version"></a><h3>soup_message_get_http_version ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessage.html#SoupHTTPVersion" title="enum SoupHTTPVersion"><span class="returnvalue">SoupHTTPVersion</span></a> +soup_message_get_http_version (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Gets the HTTP version of <em class="parameter"><code>msg</code></em> +. This is the minimum of the +version from the request and the version from the response.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.7.6"></a><h4>Returns</h4> +<p> the HTTP version</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-get-uri"></a><h3>soup_message_get_uri ()</h3> +<pre class="programlisting"><a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +soup_message_get_uri (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Gets <em class="parameter"><code>msg</code></em> +'s URI</p> +<div class="refsect3"> +<a name="id-1.3.8.10.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.8.6"></a><h4>Returns</h4> +<p> the URI <em class="parameter"><code>msg</code></em> +is targeted for. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-set-uri"></a><h3>soup_message_set_uri ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_set_uri (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Sets <em class="parameter"><code>msg</code></em> +'s URI to <em class="parameter"><code>uri</code></em> +. If <em class="parameter"><code>msg</code></em> + has already been sent and you want +to re-send it with the new URI, you need to call +<a class="link" href="SoupSession.html#soup-session-requeue-message" title="soup_session_requeue_message ()"><code class="function">soup_session_requeue_message()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>the new <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-get-address"></a><h3>soup_message_get_address ()</h3> +<pre class="programlisting"><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +soup_message_get_address (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Gets the address <em class="parameter"><code>msg</code></em> +'s URI points to. After first setting the +URI on a message, this will be unresolved, although the message's +session will resolve it before sending the message.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.10.6"></a><h4>Returns</h4> +<p> the address <em class="parameter"><code>msg</code></em> +'s URI points to. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-set-status"></a><h3>soup_message_set_status ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_set_status (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> status_code</code></em>);</pre> +<p>Sets <em class="parameter"><code>msg</code></em> +'s status code to <em class="parameter"><code>status_code</code></em> +. If <em class="parameter"><code>status_code</code></em> + is a +known value, it will also set <em class="parameter"><code>msg</code></em> +'s reason_phrase.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.11.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>status_code</p></td> +<td class="parameter_description"><p>an HTTP status code</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-set-status-full"></a><h3>soup_message_set_status_full ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_set_status_full (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> status_code</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *reason_phrase</code></em>);</pre> +<p>Sets <em class="parameter"><code>msg</code></em> +'s status code and reason phrase.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.12.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>status_code</p></td> +<td class="parameter_description"><p>an HTTP status code</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>reason_phrase</p></td> +<td class="parameter_description"><p>a description of the status</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-set-redirect"></a><h3>soup_message_set_redirect ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_set_redirect (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> status_code</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *redirect_uri</code></em>);</pre> +<p>Sets <em class="parameter"><code>msg</code></em> +'s status_code to <em class="parameter"><code>status_code</code></em> + and adds a Location header +pointing to <em class="parameter"><code>redirect_uri</code></em> +. Use this from a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> when you +want to redirect the client to another URI.</p> +<p><em class="parameter"><code>redirect_uri</code></em> + can be a relative URI, in which case it is +interpreted relative to <em class="parameter"><code>msg</code></em> +'s current URI. In particular, if +<em class="parameter"><code>redirect_uri</code></em> + is just a path, it will replace the path +<span class="emphasis"><em>and query</em></span> of <em class="parameter"><code>msg</code></em> +'s URI.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.13.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>status_code</p></td> +<td class="parameter_description"><p>a 3xx status code</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>redirect_uri</p></td> +<td class="parameter_description"><p>the URI to redirect <em class="parameter"><code>msg</code></em> +to</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-is-keepalive"></a><h3>soup_message_is_keepalive ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_message_is_keepalive (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Determines whether or not <em class="parameter"><code>msg</code></em> +'s connection can be kept alive for +further requests after processing <em class="parameter"><code>msg</code></em> +, based on the HTTP version, +Connection header, etc.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.14.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.14.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-get-https-status"></a><h3>soup_message_get_https_status ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_message_get_https_status (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><span class="type">GTlsCertificate</span> **certificate</code></em>, + <em class="parameter"><code><span class="type">GTlsCertificateFlags</span> *errors</code></em>);</pre> +<p>If <em class="parameter"><code>msg</code></em> + is using https (or attempted to use https but got +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-SSL-FAILED:CAPS"><code class="literal">SOUP_STATUS_SSL_FAILED</code></a>), this retrieves the <span class="type">GTlsCertificate</span> +associated with its connection, and the <span class="type">GTlsCertificateFlags</span> +showing what problems, if any, have been found with that +certificate.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.15.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>certificate</p></td> +<td class="parameter_description"><p> <em class="parameter"><code>msg</code></em> +'s TLS certificate. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>errors</p></td> +<td class="parameter_description"><p> the verification status of <em class="parameter"><code>certificate</code></em> +. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.15.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>msg</code></em> +used/attempted https, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if not</p> +<p></p> +</div> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-set-first-party"></a><h3>soup_message_set_first_party ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_set_first_party (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *first_party</code></em>);</pre> +<p>Sets <em class="parameter"><code>first_party</code></em> + as the main document <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> for <em class="parameter"><code>msg</code></em> +. For +details of when and how this is used refer to the documentation for +<a class="link" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy" title="enum SoupCookieJarAcceptPolicy"><span class="type">SoupCookieJarAcceptPolicy</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.16.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>first_party</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> for the <em class="parameter"><code>msg</code></em> +'s first party</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-get-first-party"></a><h3>soup_message_get_first_party ()</h3> +<pre class="programlisting"><a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +soup_message_get_first_party (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Gets <em class="parameter"><code>msg</code></em> +'s first-party <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p> +<div class="refsect3"> +<a name="id-1.3.8.10.17.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.17.6"></a><h4>Returns</h4> +<p> the <em class="parameter"><code>msg</code></em> +'s first party <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-add-header-handler"></a><h3>soup_message_add_header_handler ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_message_add_header_handler (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *signal</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *header</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Adds a signal handler to <em class="parameter"><code>msg</code></em> + for <em class="parameter"><code>signal</code></em> +, as with +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect"><code class="function">g_signal_connect()</code></a>, but the <em class="parameter"><code>callback</code></em> + will only be run if <em class="parameter"><code>msg</code></em> +'s +incoming messages headers (that is, the +<code class="literal">request_headers</code> for a client <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, or +the <code class="literal">response_headers</code> for a server <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>) +contain a header named <em class="parameter"><code>header</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.18.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>signal</p></td> +<td class="parameter_description"><p>signal to connect the handler to.</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>header</p></td> +<td class="parameter_description"><p>HTTP response header to match against</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p>the header handler</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>data to pass to <em class="parameter"><code>handler_cb</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.18.6"></a><h4>Returns</h4> +<p> the handler ID from <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect"><code class="function">g_signal_connect()</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-add-status-code-handler"></a><h3>soup_message_add_status_code_handler ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_message_add_status_code_handler (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *signal</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> status_code</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#GCallback"><span class="type">GCallback</span></a> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Adds a signal handler to <em class="parameter"><code>msg</code></em> + for <em class="parameter"><code>signal</code></em> +, as with +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect"><code class="function">g_signal_connect()</code></a>, but the <em class="parameter"><code>callback</code></em> + will only be run if <em class="parameter"><code>msg</code></em> + has +the status <em class="parameter"><code>status_code</code></em> +.</p> +<p><em class="parameter"><code>signal</code></em> + must be a signal that will be emitted after <em class="parameter"><code>msg</code></em> +'s status +is set. For a client <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, this means it can't be a "wrote" +signal. For a server <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, this means it can't be a "got" +signal.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.19.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>signal</p></td> +<td class="parameter_description"><p>signal to connect the handler to.</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>status_code</p></td> +<td class="parameter_description"><p>status code to match against</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p>the header handler</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>data to pass to <em class="parameter"><code>handler_cb</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.19.7"></a><h4>Returns</h4> +<p> the handler ID from <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect"><code class="function">g_signal_connect()</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-set-flags"></a><h3>soup_message_set_flags ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_set_flags (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html#SoupMessageFlags" title="enum SoupMessageFlags"><span class="type">SoupMessageFlags</span></a> flags</code></em>);</pre> +<p>Sets the specified flags on <em class="parameter"><code>msg</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.20.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>flags</p></td> +<td class="parameter_description"><p>a set of <a class="link" href="SoupMessage.html#SoupMessageFlags" title="enum SoupMessageFlags"><span class="type">SoupMessageFlags</span></a> values</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-get-flags"></a><h3>soup_message_get_flags ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessage.html#SoupMessageFlags" title="enum SoupMessageFlags"><span class="returnvalue">SoupMessageFlags</span></a> +soup_message_get_flags (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Gets the flags on <em class="parameter"><code>msg</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.8.10.21.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.21.6"></a><h4>Returns</h4> +<p> the flags</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupChunkAllocator"></a><h3>SoupChunkAllocator ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +<span class="c_punctuation">(</span>*SoupChunkAllocator<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> max_len</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<div class="warning"> +<p><code class="literal">SoupChunkAllocator</code> is deprecated and should not be used in newly-written code.</p> +<p>Use <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> if you want to read into your +own buffers.</p> +</div> +<p>The prototype for a chunk allocation callback. This should allocate +a new <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> and return it for the I/O layer to read message +body data off the network into.</p> +<p>If <em class="parameter"><code>max_len</code></em> + is non-0, it indicates the maximum number of bytes that +could be read, based on what is known about the message size. Note +that this might be a very large number, and you should not simply +try to allocate that many bytes blindly. If <em class="parameter"><code>max_len</code></em> + is 0, that +means that libsoup does not know how many bytes remain to be read, +and the allocator should return a buffer of a size that it finds +convenient.</p> +<p>If the allocator returns <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, the message will be paused. It is +up to the application to make sure that it gets unpaused when it +becomes possible to allocate a new buffer.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.22.8"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> the chunk is being allocated for</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>max_len</p></td> +<td class="parameter_description"><p>the maximum length that will be read, or 0.</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the data passed to <a class="link" href="SoupMessage.html#soup-message-set-chunk-allocator" title="soup_message_set_chunk_allocator ()"><code class="function">soup_message_set_chunk_allocator()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.22.9"></a><h4>Returns</h4> +<p> the new buffer (or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>)</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-set-chunk-allocator"></a><h3>soup_message_set_chunk_allocator ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_set_chunk_allocator (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html#SoupChunkAllocator" title="SoupChunkAllocator ()"><span class="type">SoupChunkAllocator</span></a> allocator</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> destroy_notify</code></em>);</pre> +<div class="warning"> +<p><code class="literal">soup_message_set_chunk_allocator</code> is deprecated and should not be used in newly-written code.</p> +<p><a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> provides a much simpler API that lets you +read the response directly into your own buffers without needing to +mess with callbacks, pausing/unpausing, etc.</p> +</div> +<p>Sets an alternate chunk-allocation function to use when reading +<em class="parameter"><code>msg</code></em> +'s body when using the traditional (ie, +non-<a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>-based) API. Every time data is available +to read, libsoup will call <em class="parameter"><code>allocator</code></em> +, which should return a +<a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>. (See <a class="link" href="SoupMessage.html#SoupChunkAllocator" title="SoupChunkAllocator ()"><span class="type">SoupChunkAllocator</span></a> for additional details.) +Libsoup will then read data from the network into that buffer, and +update the buffer's <code class="literal">length</code> to indicate how much +data it read.</p> +<p>Generally, a custom chunk allocator would be used in conjunction +with <a class="link" href="SoupMessageBody.html#soup-message-body-set-accumulate" title="soup_message_body_set_accumulate ()"><code class="function">soup_message_body_set_accumulate()</code></a> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> and +<a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal"><span class="type">“got_chunk”</span></a>, as part of a strategy to avoid unnecessary +copying of data. However, you cannot assume that every call to the +allocator will be followed by a call to your +<a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal"><span class="type">“got_chunk”</span></a> handler; if an I/O error occurs, then the +buffer will be unreffed without ever having been used. If your +buffer-allocation strategy requires special cleanup, use +<a class="link" href="SoupMessageBody.html#soup-buffer-new-with-owner" title="soup_buffer_new_with_owner ()"><code class="function">soup_buffer_new_with_owner()</code></a> rather than doing the cleanup from the +<a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal"><span class="type">“got_chunk”</span></a> handler.</p> +<p>The other thing to remember when using non-accumulating message +bodies is that the buffer passed to the <a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal"><span class="type">“got_chunk”</span></a> +handler will be unreffed after the handler returns, just as it +would be in the non-custom-allocated case. If you want to hand the +chunk data off to some other part of your program to use later, +you'll need to ref the <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> (or its owner, in the +<a class="link" href="SoupMessageBody.html#soup-buffer-new-with-owner" title="soup_buffer_new_with_owner ()"><code class="function">soup_buffer_new_with_owner()</code></a> case) to ensure that the data remains +valid.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.23.8"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>allocator</p></td> +<td class="parameter_description"><p>the chunk allocator callback</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>data to pass to <em class="parameter"><code>allocator</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>destroy_notify</p></td> +<td class="parameter_description"><p>destroy notifier to free <em class="parameter"><code>user_data</code></em> +when <em class="parameter"><code>msg</code></em> +is +destroyed</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-disable-feature"></a><h3>soup_message_disable_feature ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_disable_feature (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> feature_type</code></em>);</pre> +<p>This disables the actions of <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a>s with the +given <em class="parameter"><code>feature_type</code></em> + (or a subclass of that type) on <em class="parameter"><code>msg</code></em> +, so that +<em class="parameter"><code>msg</code></em> + is processed as though the feature(s) hadn't been added to the +session. Eg, passing <span class="type">SOUP_TYPE_CONTENT_SNIFFER</span> for <em class="parameter"><code>feature_type</code></em> + +will disable Content-Type sniffing on the message.</p> +<p>You must call this before queueing <em class="parameter"><code>msg</code></em> + on a session; calling it on +a message that has already been queued is undefined. In particular, +you cannot call this on a message that is being requeued after a +redirect or authentication.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.24.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>feature_type</p></td> +<td class="parameter_description"><p>the <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> of a <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.28</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-get-soup-request"></a><h3>soup_message_get_soup_request ()</h3> +<pre class="programlisting"><a class="link" href="SoupRequest.html" title="SoupRequest"><span class="returnvalue">SoupRequest</span></a> * +soup_message_get_soup_request (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>If <em class="parameter"><code>msg</code></em> + is associated with a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>, this returns that +request. Otherwise it returns <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.25.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.25.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>msg</code></em> +'s associated <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-get-priority"></a><h3>soup_message_get_priority ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessage.html#SoupMessagePriority" title="enum SoupMessagePriority"><span class="returnvalue">SoupMessagePriority</span></a> +soup_message_get_priority (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Retrieves the <a class="link" href="SoupMessage.html#SoupMessagePriority" title="enum SoupMessagePriority"><span class="type">SoupMessagePriority</span></a>. If not set this value defaults +to <a class="link" href="SoupMessage.html#SOUP-MESSAGE-PRIORITY-NORMAL:CAPS"><span class="type">SOUP_MESSAGE_PRIORITY_NORMAL</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.26.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.8.10.26.6"></a><h4>Returns</h4> +<p> the priority of the message.</p> +<p></p> +</div> +<p class="since">Since 2.44</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-set-priority"></a><h3>soup_message_set_priority ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_set_priority (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html#SoupMessagePriority" title="enum SoupMessagePriority"><span class="type">SoupMessagePriority</span></a> priority</code></em>);</pre> +<p>Sets the priority of a message. Note that this won't have any +effect unless used before the message is added to the session's +message processing queue.</p> +<p>The message will be placed just before any other previously added +message with lower priority (messages with the same priority are +processed on a FIFO basis).</p> +<p>Setting priorities does not currently work with <a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a> +(or with synchronous messages on a plain <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>) because in +the synchronous/blocking case, priority ends up being determined +semi-randomly by thread scheduling.</p> +<div class="refsect3"> +<a name="id-1.3.8.10.27.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>priority</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupMessage.html#SoupMessagePriority" title="enum SoupMessagePriority"><span class="type">SoupMessagePriority</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.44</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupMessage.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupMessage-struct"></a><h3>SoupMessage</h3> +<pre class="programlisting">typedef struct { + const char *method; + + guint status_code; + char *reason_phrase; + + SoupMessageBody *request_body; + SoupMessageHeaders *request_headers; + + SoupMessageBody *response_body; + SoupMessageHeaders *response_headers; +} SoupMessage; +</pre> +<p>Represents an HTTP message being sent or received.</p> +<p><em class="parameter"><code>status_code</code></em> + will normally be a <a class="link" href="libsoup-2.4-soup-status.html#SoupStatus" title="enum SoupStatus"><span class="type">SoupStatus</span></a> value, eg, +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-OK:CAPS"><code class="literal">SOUP_STATUS_OK</code></a>, though of course it might actually be an unknown +status code. <em class="parameter"><code>reason_phrase</code></em> + is the actual text returned from the +server, which may or may not correspond to the "standard" +description of <em class="parameter"><code>status_code</code></em> +. At any rate, it is almost certainly +not localized, and not very descriptive even if it is in the user's +language; you should not use <em class="parameter"><code>reason_phrase</code></em> + in user-visible +messages. Rather, you should look at <em class="parameter"><code>status_code</code></em> +, and determine an +end-user-appropriate message based on that and on what you were +trying to do.</p> +<p>As described in the <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> documentation, the +<em class="parameter"><code>request_body</code></em> + and <em class="parameter"><code>response_body</code></em> + <code class="literal">data</code> fields +will not necessarily be filled in at all times. When the body +fields are filled in, they will be terminated with a '\0' byte +(which is not included in the <code class="literal">length</code>), so you +can use them as ordinary C strings (assuming that you know that the +body doesn't have any other '\0' bytes).</p> +<p>For a client-side <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, <em class="parameter"><code>request_body</code></em> +'s +<code class="literal">data</code> is usually filled in right before libsoup +writes the request to the network, but you should not count on +this; use <a class="link" href="SoupMessageBody.html#soup-message-body-flatten" title="soup_message_body_flatten ()"><code class="function">soup_message_body_flatten()</code></a> if you want to ensure that +<code class="literal">data</code> is filled in. If you are not using +<a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> to read the response, then <em class="parameter"><code>response_body</code></em> +'s +<code class="literal">data</code> will be filled in before +<a class="link" href="SoupMessage.html#SoupMessage-finished" title="The “finished” signal"><span class="type">“finished”</span></a> is emitted. (If you are using <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>, +then the message body is not accumulated by default, so +<em class="parameter"><code>response_body</code></em> +'s <code class="literal">data</code> will always be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.)</p> +<p>For a server-side <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, <em class="parameter"><code>request_body</code></em> +'s <code class="literal">data</code> will be +filled in before <a class="link" href="SoupMessage.html#SoupMessage-got-body" title="The “got-body” signal"><span class="type">“got_body”</span></a> is emitted.</p> +<p>To prevent the <code class="literal">data</code> field from being filled in at all (eg, if you +are handling the data from a <a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal"><span class="type">“got_chunk”</span></a>, and so don't +need to see it all at the end), call +<a class="link" href="SoupMessageBody.html#soup-message-body-set-accumulate" title="soup_message_body_set_accumulate ()"><code class="function">soup_message_body_set_accumulate()</code></a> on <em class="parameter"><code>response_body</code></em> + or +<em class="parameter"><code>request_body</code></em> + as appropriate, passing <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.8.11.2.10"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="struct_members_name"> +<col class="struct_members_description"> +<col width="200px" class="struct_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="struct_member_name"><p>const <span class="type">char</span> *<em class="structfield"><code><a name="SoupMessage-struct.method"></a>method</code></em>;</p></td> +<td class="struct_member_description"><p>the HTTP method</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> <em class="structfield"><code><a name="SoupMessage-struct.status-code"></a>status_code</code></em>;</p></td> +<td class="struct_member_description"><p>the HTTP status code</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">char</span> *<em class="structfield"><code><a name="SoupMessage-struct.reason-phrase"></a>reason_phrase</code></em>;</p></td> +<td class="struct_member_description"><p>the status phrase associated with <em class="parameter"><code>status_code</code></em> +</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *<em class="structfield"><code><a name="SoupMessage-struct.request-body"></a>request_body</code></em>;</p></td> +<td class="struct_member_description"><p>the request body</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *<em class="structfield"><code><a name="SoupMessage-struct.request-headers"></a>request_headers</code></em>;</p></td> +<td class="struct_member_description"><p>the request headers</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *<em class="structfield"><code><a name="SoupMessage-struct.response-body"></a>response_body</code></em>;</p></td> +<td class="struct_member_description"><p>the response body</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *<em class="structfield"><code><a name="SoupMessage-struct.response-headers"></a>response_headers</code></em>;</p></td> +<td class="struct_member_description"><p>the response headers</p></td> +<td class="struct_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupHTTPVersion"></a><h3>enum SoupHTTPVersion</h3> +<p>Indicates the HTTP protocol version being used.</p> +<div class="refsect3"> +<a name="id-1.3.8.11.3.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-HTTP-1-0:CAPS"></a>SOUP_HTTP_1_0</p></td> +<td class="enum_member_description"> +<p>HTTP 1.0 (RFC 1945)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-HTTP-1-1:CAPS"></a>SOUP_HTTP_1_1</p></td> +<td class="enum_member_description"> +<p>HTTP 1.1 (RFC 2616)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessageFlags"></a><h3>enum SoupMessageFlags</h3> +<p>Various flags that can be set on a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> to alter its +behavior.</p> +<div class="refsect3"> +<a name="id-1.3.8.11.4.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-NO-REDIRECT:CAPS"></a>SOUP_MESSAGE_NO_REDIRECT</p></td> +<td class="enum_member_description"> +<p>The session should not follow redirect + (3xx) responses received by this message.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-CAN-REBUILD:CAPS"></a>SOUP_MESSAGE_CAN_REBUILD</p></td> +<td class="enum_member_description"> +<p>The caller will rebuild the request + body if the message is restarted; see + <a class="link" href="SoupMessageBody.html#soup-message-body-set-accumulate" title="soup_message_body_set_accumulate ()"><code class="function">soup_message_body_set_accumulate()</code></a> for more details.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-OVERWRITE-CHUNKS:CAPS"></a>SOUP_MESSAGE_OVERWRITE_CHUNKS</p></td> +<td class="enum_member_description"> +<p>Deprecated: equivalent to calling + <a class="link" href="SoupMessageBody.html#soup-message-body-set-accumulate" title="soup_message_body_set_accumulate ()"><code class="function">soup_message_body_set_accumulate()</code></a> on the incoming message body + (ie, <a class="link" href="SoupMessage.html#SoupMessage--response-body" title="The “response-body” property"><span class="type">“response_body”</span></a> for a client-side request), + passing <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-CONTENT-DECODED:CAPS"></a>SOUP_MESSAGE_CONTENT_DECODED</p></td> +<td class="enum_member_description"> +<p>Set by <a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder"><span class="type">SoupContentDecoder</span></a> to + indicate that it has removed the Content-Encoding on a message (and + so headers such as Content-Length may no longer accurately describe + the body).</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-CERTIFICATE-TRUSTED:CAPS"></a>SOUP_MESSAGE_CERTIFICATE_TRUSTED</p></td> +<td class="enum_member_description"> +<p>if set after an https response + has been received, indicates that the server's SSL certificate is + trusted according to the session's CA.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-NEW-CONNECTION:CAPS"></a>SOUP_MESSAGE_NEW_CONNECTION</p></td> +<td class="enum_member_description"> +<p>Requests that the message should be + sent on a newly-created connection, not reusing an existing + persistent connection. Note that messages with non-idempotent + <a class="link" href="SoupMessage.html#SoupMessage--method" title="The “method” property"><span class="type">“method”</span></a>s behave this way by default, unless + <a class="link" href="SoupMessage.html#SOUP-MESSAGE-IDEMPOTENT:CAPS"><span class="type">SOUP_MESSAGE_IDEMPOTENT</span></a> is set.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-IDEMPOTENT:CAPS"></a>SOUP_MESSAGE_IDEMPOTENT</p></td> +<td class="enum_member_description"> +<p>The message is considered idempotent, + regardless its <a class="link" href="SoupMessage.html#SoupMessage--method" title="The “method” property"><span class="type">“method”</span></a>, and allows reuse of existing + idle connections, instead of always requiring a new one, unless + <a class="link" href="SoupMessage.html#SOUP-MESSAGE-NEW-CONNECTION:CAPS"><span class="type">SOUP_MESSAGE_NEW_CONNECTION</span></a> is set.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessagePriority"></a><h3>enum SoupMessagePriority</h3> +<p>Priorities that can be set on a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> to instruct the +message queue to process it before any other message with lower +priority.</p> +<div class="refsect3"> +<a name="id-1.3.8.11.5.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-PRIORITY-VERY-LOW:CAPS"></a>SOUP_MESSAGE_PRIORITY_VERY_LOW</p></td> +<td class="enum_member_description"> +<p>The lowest priority, the messages + with this priority will be the last ones to be attended.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-PRIORITY-LOW:CAPS"></a>SOUP_MESSAGE_PRIORITY_LOW</p></td> +<td class="enum_member_description"> +<p>Use this for low priority messages, a + <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> with the default priority will be processed first.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-PRIORITY-NORMAL:CAPS"></a>SOUP_MESSAGE_PRIORITY_NORMAL</p></td> +<td class="enum_member_description"> +<p>The default priotity, this is the + priority assigned to the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> by default.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-PRIORITY-HIGH:CAPS"></a>SOUP_MESSAGE_PRIORITY_HIGH</p></td> +<td class="enum_member_description"> +<p>High priority, a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> with + this priority will be processed before the ones with the default + priority.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-PRIORITY-VERY-HIGH:CAPS"></a>SOUP_MESSAGE_PRIORITY_VERY_HIGH</p></td> +<td class="enum_member_description"> +<p>The highest priority, use this + for very urgent <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> as they will be the first ones to be + attended.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-METHOD:CAPS"></a><h3>SOUP_MESSAGE_METHOD</h3> +<pre class="programlisting">#define SOUP_MESSAGE_METHOD "method" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--method" title="The “method” property"><span class="type">“method”</span></a> property. (The message's +HTTP method.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-URI:CAPS"></a><h3>SOUP_MESSAGE_URI</h3> +<pre class="programlisting">#define SOUP_MESSAGE_URI "uri" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--uri" title="The “uri” property"><span class="type">“uri”</span></a> property. (The message's +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-HTTP-VERSION:CAPS"></a><h3>SOUP_MESSAGE_HTTP_VERSION</h3> +<pre class="programlisting">#define SOUP_MESSAGE_HTTP_VERSION "http-version" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--http-version" title="The “http-version” property"><span class="type">“http-version”</span></a> property. (The +message's <a class="link" href="SoupMessage.html#SoupHTTPVersion" title="enum SoupHTTPVersion"><span class="type">SoupHTTPVersion</span></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-FLAGS:CAPS"></a><h3>SOUP_MESSAGE_FLAGS</h3> +<pre class="programlisting">#define SOUP_MESSAGE_FLAGS "flags" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--flags" title="The “flags” property"><span class="type">“flags”</span></a> property. (The message's +<a class="link" href="SoupMessage.html#SoupMessageFlags" title="enum SoupMessageFlags"><span class="type">SoupMessageFlags</span></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-STATUS-CODE:CAPS"></a><h3>SOUP_MESSAGE_STATUS_CODE</h3> +<pre class="programlisting">#define SOUP_MESSAGE_STATUS_CODE "status-code" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--status-code" title="The “status-code” property"><span class="type">“status-code”</span></a> property. (The +message's HTTP response status code.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-REASON-PHRASE:CAPS"></a><h3>SOUP_MESSAGE_REASON_PHRASE</h3> +<pre class="programlisting">#define SOUP_MESSAGE_REASON_PHRASE "reason-phrase" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--reason-phrase" title="The “reason-phrase” property"><span class="type">“reason-phrase”</span></a> property. (The +message's HTTP response reason phrase.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-SERVER-SIDE:CAPS"></a><h3>SOUP_MESSAGE_SERVER_SIDE</h3> +<pre class="programlisting">#define SOUP_MESSAGE_SERVER_SIDE "server-side" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--server-side" title="The “server-side” property"><span class="type">“server-side”</span></a> property. (<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if +the message was created by <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-FIRST-PARTY:CAPS"></a><h3>SOUP_MESSAGE_FIRST_PARTY</h3> +<pre class="programlisting">#define SOUP_MESSAGE_FIRST_PARTY "first-party" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--first-party" title="The “first-party” property"><span class="type">“first-party”</span></a> property. (The +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> loaded in the application when the message was +queued.)</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-PRIORITY:CAPS"></a><h3>SOUP_MESSAGE_PRIORITY</h3> +<pre class="programlisting">#define SOUP_MESSAGE_PRIORITY "priority" +</pre> +<p>Sets the priority of the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>. See +<a class="link" href="SoupMessage.html#soup-message-set-priority" title="soup_message_set_priority ()"><code class="function">soup_message_set_priority()</code></a> for further details.</p> +<p class="since">Since 2.44</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-REQUEST-BODY:CAPS"></a><h3>SOUP_MESSAGE_REQUEST_BODY</h3> +<pre class="programlisting">#define SOUP_MESSAGE_REQUEST_BODY "request-body" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--request-body" title="The “request-body” property"><span class="type">“request-body”</span></a> property. (The +message's HTTP request body.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-REQUEST-BODY-DATA:CAPS"></a><h3>SOUP_MESSAGE_REQUEST_BODY_DATA</h3> +<pre class="programlisting">#define SOUP_MESSAGE_REQUEST_BODY_DATA "request-body-data" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--request-body-data" title="The “request-body-data” property"><span class="type">“request-body-data”</span></a> property. (The +message's HTTP request body, as a <a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a>.)</p> +<p class="since">Since 2.46</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-REQUEST-HEADERS:CAPS"></a><h3>SOUP_MESSAGE_REQUEST_HEADERS</h3> +<pre class="programlisting">#define SOUP_MESSAGE_REQUEST_HEADERS "request-headers" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--request-headers" title="The “request-headers” property"><span class="type">“request-headers”</span></a> property. (The +message's HTTP request headers.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-RESPONSE-BODY:CAPS"></a><h3>SOUP_MESSAGE_RESPONSE_BODY</h3> +<pre class="programlisting">#define SOUP_MESSAGE_RESPONSE_BODY "response-body" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--response-body" title="The “response-body” property"><span class="type">“response-body”</span></a> property. (The +message's HTTP response body.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-RESPONSE-BODY-DATA:CAPS"></a><h3>SOUP_MESSAGE_RESPONSE_BODY_DATA</h3> +<pre class="programlisting">#define SOUP_MESSAGE_RESPONSE_BODY_DATA "response-body-data" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--response-body-data" title="The “response-body-data” property"><span class="type">“response-body-data”</span></a> property. (The +message's HTTP response body, as a <a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a>.)</p> +<p class="since">Since 2.46</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-RESPONSE-HEADERS:CAPS"></a><h3>SOUP_MESSAGE_RESPONSE_HEADERS</h3> +<pre class="programlisting">#define SOUP_MESSAGE_RESPONSE_HEADERS "response-headers" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--response-headers" title="The “response-headers” property"><span class="type">“response-headers”</span></a> property. (The +message's HTTP response headers.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-TLS-CERTIFICATE:CAPS"></a><h3>SOUP_MESSAGE_TLS_CERTIFICATE</h3> +<pre class="programlisting">#define SOUP_MESSAGE_TLS_CERTIFICATE "tls-certificate" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--tls-certificate" title="The “tls-certificate” property"><span class="type">“tls-certificate”</span></a> property. (The +TLS certificate associated with the message, if any.)</p> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MESSAGE-TLS-ERRORS:CAPS"></a><h3>SOUP_MESSAGE_TLS_ERRORS</h3> +<pre class="programlisting">#define SOUP_MESSAGE_TLS_ERRORS "tls-errors" +</pre> +<p>Alias for the <a class="link" href="SoupMessage.html#SoupMessage--tls-errors" title="The “tls-errors” property"><span class="type">“tls-errors”</span></a> property. (The +verification errors on <a class="link" href="SoupMessage.html#SoupMessage--tls-certificate" title="The “tls-certificate” property"><span class="type">“tls-certificate”</span></a>.)</p> +<p class="since">Since 2.34</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupMessage.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupMessage--first-party"></a><h3>The <code class="literal">“first-party”</code> property</h3> +<pre class="programlisting"> “first-party” <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *</pre> +<p>The <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> loaded in the application when the message was +queued.</p> +<p>Flags: Read / Write</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--flags"></a><h3>The <code class="literal">“flags”</code> property</h3> +<pre class="programlisting"> “flags” <a class="link" href="SoupMessage.html#SoupMessageFlags" title="enum SoupMessageFlags"><span class="type">SoupMessageFlags</span></a></pre> +<p>Various message options.</p> +<p>Flags: Read / Write</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--http-version"></a><h3>The <code class="literal">“http-version”</code> property</h3> +<pre class="programlisting"> “http-version” <a class="link" href="SoupMessage.html#SoupHTTPVersion" title="enum SoupHTTPVersion"><span class="type">SoupHTTPVersion</span></a></pre> +<p>The HTTP protocol version to use.</p> +<p>Flags: Read / Write</p> +<p>Default value: SOUP_HTTP_1_1</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--method"></a><h3>The <code class="literal">“method”</code> property</h3> +<pre class="programlisting"> “method” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>The message's HTTP method.</p> +<p>Flags: Read / Write</p> +<p>Default value: "GET"</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--priority"></a><h3>The <code class="literal">“priority”</code> property</h3> +<pre class="programlisting"> “priority” <a class="link" href="SoupMessage.html#SoupMessagePriority" title="enum SoupMessagePriority"><span class="type">SoupMessagePriority</span></a></pre> +<p>The priority of the message.</p> +<p>Flags: Read / Write</p> +<p>Default value: SOUP_MESSAGE_PRIORITY_NORMAL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--reason-phrase"></a><h3>The <code class="literal">“reason-phrase”</code> property</h3> +<pre class="programlisting"> “reason-phrase” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>The HTTP response reason phrase.</p> +<p>Flags: Read / Write</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--request-body"></a><h3>The <code class="literal">“request-body”</code> property</h3> +<pre class="programlisting"> “request-body” <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *</pre> +<p>The HTTP request content.</p> +<p>Flags: Read</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--request-body-data"></a><h3>The <code class="literal">“request-body-data”</code> property</h3> +<pre class="programlisting"> “request-body-data” <a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> *</pre> +<p>The message's HTTP request body, as a <a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a>.</p> +<p>Flags: Read</p> +<p class="since">Since 2.46</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--request-headers"></a><h3>The <code class="literal">“request-headers”</code> property</h3> +<pre class="programlisting"> “request-headers” <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *</pre> +<p>The HTTP request headers.</p> +<p>Flags: Read</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--response-body"></a><h3>The <code class="literal">“response-body”</code> property</h3> +<pre class="programlisting"> “response-body” <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *</pre> +<p>The HTTP response content.</p> +<p>Flags: Read</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--response-body-data"></a><h3>The <code class="literal">“response-body-data”</code> property</h3> +<pre class="programlisting"> “response-body-data” <a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> *</pre> +<p>The message's HTTP response body, as a <a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a>.</p> +<p>Flags: Read</p> +<p class="since">Since 2.46</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--response-headers"></a><h3>The <code class="literal">“response-headers”</code> property</h3> +<pre class="programlisting"> “response-headers” <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *</pre> +<p>The HTTP response headers.</p> +<p>Flags: Read</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--server-side"></a><h3>The <code class="literal">“server-side”</code> property</h3> +<pre class="programlisting"> “server-side” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Whether or not the message is server-side rather than client-side.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: FALSE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--status-code"></a><h3>The <code class="literal">“status-code”</code> property</h3> +<pre class="programlisting"> “status-code” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a></pre> +<p>The HTTP response status code.</p> +<p>Flags: Read / Write</p> +<p>Allowed values: <= 599</p> +<p>Default value: 0</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--tls-certificate"></a><h3>The <code class="literal">“tls-certificate”</code> property</h3> +<pre class="programlisting"> “tls-certificate” <span class="type">GTlsCertificate</span> *</pre> +<p>The <span class="type">GTlsCertificate</span> associated with the message</p> +<p>Flags: Read / Write</p> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--tls-errors"></a><h3>The <code class="literal">“tls-errors”</code> property</h3> +<pre class="programlisting"> “tls-errors” <span class="type">GTlsCertificateFlags</span></pre> +<p>The verification errors on <a class="link" href="SoupMessage.html#SoupMessage--tls-certificate" title="The “tls-certificate” property"><span class="type">“tls-certificate”</span></a></p> +<p>Flags: Read / Write</p> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage--uri"></a><h3>The <code class="literal">“uri”</code> property</h3> +<pre class="programlisting"> “uri” <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *</pre> +<p>The message's Request-URI.</p> +<p>Flags: Read / Write</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupMessage.signal-details"></a><h2>Signal Details</h2> +<div class="refsect2"> +<a name="SoupMessage-content-sniffed"></a><h3>The <code class="literal">“content-sniffed”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *type, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *params, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>This signal is emitted after <a class="link" href="SoupMessage.html#SoupMessage-got-headers" title="The “got-headers” signal"><span class="type">“got-headers”</span></a>, and +before the first <a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal"><span class="type">“got-chunk”</span></a>. If content +sniffing is disabled, or no content sniffing will be +performed, due to the sniffer deciding to trust the +Content-Type sent by the server, this signal is emitted +immediately after <a class="link" href="SoupMessage.html#SoupMessage-got-headers" title="The “got-headers” signal"><span class="type">“got-headers”</span></a>, and <em class="parameter"><code>type</code></em> + is +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</p> +<p>If the <a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="type">SoupContentSniffer</span></a> feature is enabled, and the +sniffer decided to perform sniffing, the first +<a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal"><span class="type">“got-chunk”</span></a> emission may be delayed, so that the +sniffer has enough data to correctly sniff the content. It +notified the library user that the content has been +sniffed, and allows it to change the header contents in the +message, if desired.</p> +<p>After this signal is emitted, the data that was spooled so +that sniffing could be done is delivered on the first +emission of <a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal"><span class="type">“got-chunk”</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.8.13.2.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>the content type that we got from sniffing</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>params</p></td> +<td class="parameter_description"><p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> with the parameters. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +<p class="since">Since 2.28</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-finished"></a><h3>The <code class="literal">“finished”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when all HTTP processing is finished for a message. +(After <a class="link" href="SoupMessage.html#SoupMessage-got-body" title="The “got-body” signal"><span class="type">“got_body”</span></a> for client-side messages, or +after <a class="link" href="SoupMessage.html#SoupMessage-wrote-body" title="The “wrote-body” signal"><span class="type">“wrote_body”</span></a> for server-side messages.)</p> +<div class="refsect3"> +<a name="id-1.3.8.13.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-got-body"></a><h3>The <code class="literal">“got-body”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted after receiving the complete message body. (For a +server-side message, this means it has received the request +body. For a client-side message, this means it has received +the response body and is nearly done with the message.)</p> +<p>See also <a class="link" href="SoupMessage.html#soup-message-add-header-handler" title="soup_message_add_header_handler ()"><code class="function">soup_message_add_header_handler()</code></a> and +<a class="link" href="SoupMessage.html#soup-message-add-status-code-handler" title="soup_message_add_status_code_handler ()"><code class="function">soup_message_add_status_code_handler()</code></a>, which can be used +to connect to a subset of emissions of this signal.</p> +<div class="refsect3"> +<a name="id-1.3.8.13.4.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-got-chunk"></a><h3>The <code class="literal">“got-chunk”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *chunk, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted after receiving a chunk of a message body. Note +that "chunk" in this context means any subpiece of the +body, not necessarily the specific HTTP 1.1 chunks sent by +the other side.</p> +<p>If you cancel or requeue <em class="parameter"><code>msg</code></em> + while processing this signal, +then the current HTTP I/O will be stopped after this signal +emission finished, and <em class="parameter"><code>msg</code></em> +'s connection will be closed.</p> +<div class="refsect3"> +<a name="id-1.3.8.13.5.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>chunk</p></td> +<td class="parameter_description"><p>the just-read chunk</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-got-headers"></a><h3>The <code class="literal">“got-headers”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted after receiving all message headers for a message. +(For a client-side message, this is after receiving the +Status-Line and response headers; for a server-side +message, it is after receiving the Request-Line and request +headers.)</p> +<p>See also <a class="link" href="SoupMessage.html#soup-message-add-header-handler" title="soup_message_add_header_handler ()"><code class="function">soup_message_add_header_handler()</code></a> and +<a class="link" href="SoupMessage.html#soup-message-add-status-code-handler" title="soup_message_add_status_code_handler ()"><code class="function">soup_message_add_status_code_handler()</code></a>, which can be used +to connect to a subset of emissions of this signal.</p> +<p>If you cancel or requeue <em class="parameter"><code>msg</code></em> + while processing this signal, +then the current HTTP I/O will be stopped after this signal +emission finished, and <em class="parameter"><code>msg</code></em> +'s connection will be closed. +(If you need to requeue a message--eg, after handling +authentication or redirection--it is usually better to +requeue it from a <a class="link" href="SoupMessage.html#SoupMessage-got-body" title="The “got-body” signal"><span class="type">“got_body”</span></a> handler rather +than a <a class="link" href="SoupMessage.html#SoupMessage-got-headers" title="The “got-headers” signal"><span class="type">“got_headers”</span></a> handler, so that the +existing HTTP connection can be reused.)</p> +<div class="refsect3"> +<a name="id-1.3.8.13.6.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-got-informational"></a><h3>The <code class="literal">“got-informational”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted after receiving a 1xx (Informational) response for +a (client-side) message. The response_headers will be +filled in with the headers associated with the +informational response; however, those header values will +be erased after this signal is done.</p> +<p>If you cancel or requeue <em class="parameter"><code>msg</code></em> + while processing this signal, +then the current HTTP I/O will be stopped after this signal +emission finished, and <em class="parameter"><code>msg</code></em> +'s connection will be closed.</p> +<div class="refsect3"> +<a name="id-1.3.8.13.7.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-network-event"></a><h3>The <code class="literal">“network-event”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <span class="type">GSocketClientEvent</span> event, + <span class="type">GIOStream</span> *connection, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted to indicate that some network-related event +related to <em class="parameter"><code>msg</code></em> + has occurred. This essentially proxies the +<span class="type">“event”</span> signal, but only for events that +occur while <em class="parameter"><code>msg</code></em> + "owns" the connection; if <em class="parameter"><code>msg</code></em> + is sent on +an existing persistent connection, then this signal will +not be emitted. (If you want to force the message to be +sent on a new connection, set the +<a class="link" href="SoupMessage.html#SOUP-MESSAGE-NEW-CONNECTION:CAPS"><code class="literal">SOUP_MESSAGE_NEW_CONNECTION</code></a> flag on it.)</p> +<p>See <span class="type">“event”</span> for more information on what +the different values of <em class="parameter"><code>event</code></em> + correspond to, and what +<em class="parameter"><code>connection</code></em> + will be in each case.</p> +<div class="refsect3"> +<a name="id-1.3.8.13.8.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>event</p></td> +<td class="parameter_description"><p>the network event</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>connection</p></td> +<td class="parameter_description"><p>the current state of the network connection</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-restarted"></a><h3>The <code class="literal">“restarted”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when a request that was already sent once is now +being sent again (eg, because the first attempt received a +redirection response, or because we needed to use +authentication).</p> +<div class="refsect3"> +<a name="id-1.3.8.13.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-wrote-body"></a><h3>The <code class="literal">“wrote-body”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted immediately after writing the complete body for a +message. (For a client-side message, this means that +libsoup is done writing and is now waiting for the response +from the server. For a server-side message, this means that +libsoup has finished writing the response and is nearly +done with the message.)</p> +<div class="refsect3"> +<a name="id-1.3.8.13.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-wrote-body-data"></a><h3>The <code class="literal">“wrote-body-data”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *chunk, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted immediately after writing a portion of the message +body to the network.</p> +<p>Unlike <a class="link" href="SoupMessage.html#SoupMessage-wrote-chunk" title="The “wrote-chunk” signal"><span class="type">“wrote_chunk”</span></a>, this is emitted after +every successful <code class="function">write()</code> call, not only after finishing a +complete "chunk".</p> +<div class="refsect3"> +<a name="id-1.3.8.13.11.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>chunk</p></td> +<td class="parameter_description"><p>the data written</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-wrote-chunk"></a><h3>The <code class="literal">“wrote-chunk”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted immediately after writing a body chunk for a message.</p> +<p>Note that this signal is not parallel to +<a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal"><span class="type">“got_chunk”</span></a>; it is emitted only when a complete +chunk (added with <a class="link" href="SoupMessageBody.html#soup-message-body-append" title="soup_message_body_append ()"><code class="function">soup_message_body_append()</code></a> or +<a class="link" href="SoupMessageBody.html#soup-message-body-append-buffer" title="soup_message_body_append_buffer ()"><code class="function">soup_message_body_append_buffer()</code></a>) has been written. To get +more useful continuous progress information, use +<a class="link" href="SoupMessage.html#SoupMessage-wrote-body-data" title="The “wrote-body-data” signal"><span class="type">“wrote_body_data”</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.8.13.12.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-wrote-headers"></a><h3>The <code class="literal">“wrote-headers”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted immediately after writing the headers for a +message. (For a client-side message, this is after writing +the request headers; for a server-side message, it is after +writing the response headers.)</p> +<div class="refsect3"> +<a name="id-1.3.8.13.13.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessage-wrote-informational"></a><h3>The <code class="literal">“wrote-informational”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted immediately after writing a 1xx (Informational) +response for a (server-side) message.</p> +<div class="refsect3"> +<a name="id-1.3.8.13.14.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +</div> +<div class="refsect1"> +<a name="SoupMessage.see-also"></a><h2>See Also</h2> +<p><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a>, <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupMessageBody.html b/docs/reference/html/SoupMessageBody.html new file mode 100644 index 00000000..a82bcd9d --- /dev/null +++ b/docs/reference/html/SoupMessageBody.html @@ -0,0 +1,1278 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupMessageBody</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupMessageHeaders.html" title="SoupMessageHeaders"> +<link rel="next" href="libsoup-2.4-soup-method.html" title="soup-method"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupMessageBody.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupMessageBody.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupMessageHeaders.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-2.4-soup-method.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupMessageBody"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupMessageBody.top_of_page"></a>SoupMessageBody</span></h2> +<p>SoupMessageBody — HTTP message body</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupMessageBody.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-buffer-new" title="soup_buffer_new ()">soup_buffer_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-buffer-new-subbuffer" title="soup_buffer_new_subbuffer ()">soup_buffer_new_subbuffer</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-buffer-new-with-owner" title="soup_buffer_new_with_owner ()">soup_buffer_new_with_owner</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-buffer-new-take" title="soup_buffer_new_take ()">soup_buffer_new_take</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-buffer-get-owner" title="soup_buffer_get_owner ()">soup_buffer_get_owner</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-buffer-get-data" title="soup_buffer_get_data ()">soup_buffer_get_data</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-buffer-copy" title="soup_buffer_copy ()">soup_buffer_copy</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-buffer-free" title="soup_buffer_free ()">soup_buffer_free</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="returnvalue">GBytes</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-buffer-get-as-bytes" title="soup_buffer_get_as_bytes ()">soup_buffer_get_as_bytes</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="returnvalue">SoupMessageBody</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-new" title="soup_message_body_new ()">soup_message_body_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-free" title="soup_message_body_free ()">soup_message_body_free</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-set-accumulate" title="soup_message_body_set_accumulate ()">soup_message_body_set_accumulate</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-get-accumulate" title="soup_message_body_get_accumulate ()">soup_message_body_get_accumulate</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-append" title="soup_message_body_append ()">soup_message_body_append</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-append-buffer" title="soup_message_body_append_buffer ()">soup_message_body_append_buffer</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-append-take" title="soup_message_body_append_take ()">soup_message_body_append_take</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-truncate" title="soup_message_body_truncate ()">soup_message_body_truncate</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-complete" title="soup_message_body_complete ()">soup_message_body_complete</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-flatten" title="soup_message_body_flatten ()">soup_message_body_flatten</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-get-chunk" title="soup_message_body_get_chunk ()">soup_message_body_get_chunk</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-got-chunk" title="soup_message_body_got_chunk ()">soup_message_body_got_chunk</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageBody.html#soup-message-body-wrote-chunk" title="soup_message_body_wrote_chunk ()">soup_message_body_wrote_chunk</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<a name="SoupBuffer"></a><div class="refsect1"> +<a name="SoupMessageBody.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupMessageBody.html#SoupBuffer-struct" title="SoupBuffer">SoupBuffer</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupMessageBody.html#SoupMemoryUse" title="enum SoupMemoryUse">SoupMemoryUse</a></td> +</tr> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupMessageBody.html#SoupMessageBody-struct" title="SoupMessageBody">SoupMessageBody</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMessageBody.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> GBoxed + <span class="lineart">├──</span> SoupBuffer + <span class="lineart">╰──</span> SoupMessageBody +</pre> +</div> +<div class="refsect1"> +<a name="SoupMessageBody.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupMessageBody.description"></a><h2>Description</h2> +<p><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> represents the request or response body of a +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>.</p> +<p>In addition to <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>, libsoup also defines a "smaller" +data buffer type, <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>, which is primarily used as a +component of <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>. In particular, when using chunked +encoding to transmit or receive a message, each chunk is +represented as a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>.</p> +</div> +<div class="refsect1"> +<a name="SoupMessageBody.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-buffer-new"></a><h3>soup_buffer_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +soup_buffer_new (<em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupMemoryUse" title="enum SoupMemoryUse"><span class="type">SoupMemoryUse</span></a> use</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> length</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> containing <em class="parameter"><code>length</code></em> + bytes from <em class="parameter"><code>data</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>use</p></td> +<td class="parameter_description"><p>how <em class="parameter"><code>data</code></em> +is to be used by the buffer</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p>data</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>length of <em class="parameter"><code>data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.10.9.2.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-buffer-new-subbuffer"></a><h3>soup_buffer_new_subbuffer ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +soup_buffer_new_subbuffer (<em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *parent</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> offset</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> length</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> containing <em class="parameter"><code>length</code></em> + bytes "copied" from +<em class="parameter"><code>parent</code></em> + starting at <em class="parameter"><code>offset</code></em> +. (Normally this will not actually copy +any data, but will instead simply reference the same data as +<em class="parameter"><code>parent</code></em> + does.)</p> +<div class="refsect3"> +<a name="id-1.3.10.9.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>parent</p></td> +<td class="parameter_description"><p>the parent <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>offset</p></td> +<td class="parameter_description"><p>offset within <em class="parameter"><code>parent</code></em> +to start at</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>number of bytes to copy from <em class="parameter"><code>parent</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.10.9.3.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-buffer-new-with-owner"></a><h3>soup_buffer_new_with_owner ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +soup_buffer_new_with_owner (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> length</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> owner</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> owner_dnotify</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> containing <em class="parameter"><code>length</code></em> + bytes from <em class="parameter"><code>data</code></em> +. When +the <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> is freed, it will call <em class="parameter"><code>owner_dnotify</code></em> +, passing +<em class="parameter"><code>owner</code></em> + to it. You must ensure that <em class="parameter"><code>data</code></em> + will remain valid until +<em class="parameter"><code>owner_dnotify</code></em> + is called.</p> +<p>For example, you could use this to create a buffer containing data +returned from libxml without needing to do an extra copy:</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="function">xmlDocDumpMemory</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">doc</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">xmlbody</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">len</span><span class="symbol">);</span> +<span class="keyword">return</span><span class="normal"> </span><span class="function"><a href="SoupMessageBody.html#soup-buffer-new-with-owner">soup_buffer_new_with_owner</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">xmlbody</span><span class="symbol">,</span><span class="normal"> len</span><span class="symbol">,</span><span class="normal"> xmlbody</span><span class="symbol">,</span> +<span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify">GDestroyNotify</a></span><span class="symbol">)</span><span class="normal">xmlFree</span><span class="symbol">);</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p>In this example, <em class="parameter"><code>data</code></em> + and <em class="parameter"><code>owner</code></em> + are the same, but in other cases +they would be different (eg, <em class="parameter"><code>owner</code></em> + would be a object, and <em class="parameter"><code>data</code></em> + +would be a pointer to one of the object's fields).</p> +<div class="refsect3"> +<a name="id-1.3.10.9.4.8"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p>data</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>length of <em class="parameter"><code>data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>owner</p></td> +<td class="parameter_description"><p>pointer to an object that owns <em class="parameter"><code>data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>owner_dnotify</p></td> +<td class="parameter_description"><p> a function to free/unref <em class="parameter"><code>owner</code></em> +when +the buffer is freed. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.10.9.4.9"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-buffer-new-take"></a><h3>soup_buffer_new_take ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +soup_buffer_new_take (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guchar"><span class="type">guchar</span></a> *data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> length</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> containing <em class="parameter"><code>length</code></em> + bytes from <em class="parameter"><code>data</code></em> +.</p> +<p>This function is exactly equivalent to <a class="link" href="SoupMessageBody.html#soup-buffer-new" title="soup_buffer_new ()"><code class="function">soup_buffer_new()</code></a> with +<a class="link" href="SoupMessageBody.html#SOUP-MEMORY-TAKE:CAPS"><code class="literal">SOUP_MEMORY_TAKE</code></a> as first argument; it exists mainly for +convenience and simplifying language bindings.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.5.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p> data. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=length][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>length of <em class="parameter"><code>data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.10.9.5.7"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>.</p> +<p>Rename to: soup_buffer_new</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-buffer-get-owner"></a><h3>soup_buffer_get_owner ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a> +soup_buffer_get_owner (<em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *buffer</code></em>);</pre> +<p>Gets the "owner" object for a buffer created with +<a class="link" href="SoupMessageBody.html#soup-buffer-new-with-owner" title="soup_buffer_new_with_owner ()"><code class="function">soup_buffer_new_with_owner()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>buffer</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> created with <a class="link" href="SoupMessageBody.html#soup-buffer-new-with-owner" title="soup_buffer_new_with_owner ()"><code class="function">soup_buffer_new_with_owner()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.10.9.6.6"></a><h4>Returns</h4> +<p> the owner pointer. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-buffer-get-data"></a><h3>soup_buffer_get_data ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_buffer_get_data (<em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *buffer</code></em>, + <em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint8"><span class="type">guint8</span></a> **data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> *length</code></em>);</pre> +<p>This function exists for use by language bindings, because it's not +currently possible to get the right effect by annotating the fields +of <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>buffer</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p> the pointer +to the buffer data is stored here. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=length][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p> the length of the buffer data is stored here. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-buffer-copy"></a><h3>soup_buffer_copy ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +soup_buffer_copy (<em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *buffer</code></em>);</pre> +<p>Makes a copy of <em class="parameter"><code>buffer</code></em> +. In reality, <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> is a refcounted +type, and calling <a class="link" href="SoupMessageBody.html#soup-buffer-copy" title="soup_buffer_copy ()"><code class="function">soup_buffer_copy()</code></a> will normally just increment +the refcount on <em class="parameter"><code>buffer</code></em> + and return it. However, if <em class="parameter"><code>buffer</code></em> + was +created with <a class="link" href="SoupMessageBody.html#SOUP-MEMORY-TEMPORARY:CAPS"><span class="type">SOUP_MEMORY_TEMPORARY</span></a> memory, then <a class="link" href="SoupMessageBody.html#soup-buffer-copy" title="soup_buffer_copy ()"><code class="function">soup_buffer_copy()</code></a> +will actually return a copy of it, so that the data in the copy +will remain valid after the temporary buffer is freed.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>buffer</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.10.9.8.6"></a><h4>Returns</h4> +<p> the new (or newly-reffed) buffer</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-buffer-free"></a><h3>soup_buffer_free ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_buffer_free (<em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *buffer</code></em>);</pre> +<p>Frees <em class="parameter"><code>buffer</code></em> +. (In reality, as described in the documentation for +<a class="link" href="SoupMessageBody.html#soup-buffer-copy" title="soup_buffer_copy ()"><code class="function">soup_buffer_copy()</code></a>, this is actually an "unref" operation, and may +or may not actually free <em class="parameter"><code>buffer</code></em> +.)</p> +<div class="refsect3"> +<a name="id-1.3.10.9.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>buffer</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-buffer-get-as-bytes"></a><h3>soup_buffer_get_as_bytes ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="returnvalue">GBytes</span></a> * +soup_buffer_get_as_bytes (<em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *buffer</code></em>);</pre> +<p>Creates a <a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> pointing to the same memory as <em class="parameter"><code>buffer</code></em> +. The +<a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> will hold a reference on <em class="parameter"><code>buffer</code></em> + to ensure that it is not +freed while the <a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> is still valid.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>buffer</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.10.9.10.6"></a><h4>Returns</h4> +<p> a new <a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GBytes"><span class="type">GBytes</span></a> which has the same content +as the <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.40</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-new"></a><h3>soup_message_body_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="returnvalue">SoupMessageBody</span></a> * +soup_message_body_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<p>Creates a new <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>. <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> uses this internally; you +will not normally need to call it yourself.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.11.5"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-free"></a><h3>soup_message_body_free ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_body_free (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>);</pre> +<p>Frees <em class="parameter"><code>body</code></em> +. You will not normally need to use this, as +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> frees its associated message bodies automatically.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.12.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-set-accumulate"></a><h3>soup_message_body_set_accumulate ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_body_set_accumulate (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> accumulate</code></em>);</pre> +<p>Sets or clears the accumulate flag on <em class="parameter"><code>body</code></em> +. (The default value is +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>.) If set to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, <em class="parameter"><code>body</code></em> +'s <code class="literal">data</code> field will not be filled in +after the body is fully sent/received, and the chunks that make up +<em class="parameter"><code>body</code></em> + may be discarded when they are no longer needed.</p> +<p>In particular, if you set this flag to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> on an "incoming" +message body (that is, the <a class="link" href="SoupMessage.html#SoupMessage--response-body" title="The “response-body” property"><span class="type">“response_body”</span></a> of a +client-side message, or <a class="link" href="SoupMessage.html#SoupMessage--request-body" title="The “request-body” property"><span class="type">“request_body”</span></a> of a server-side +message), this will cause each chunk of the body to be discarded +after its corresponding <a class="link" href="SoupMessage.html#SoupMessage-got-chunk" title="The “got-chunk” signal"><span class="type">“got_chunk”</span></a> signal is emitted. +(This is equivalent to setting the deprecated +<a class="link" href="SoupMessage.html#SOUP-MESSAGE-OVERWRITE-CHUNKS:CAPS"><code class="literal">SOUP_MESSAGE_OVERWRITE_CHUNKS</code></a> flag on the message.)</p> +<p>If you set this flag to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> on the <a class="link" href="SoupMessage.html#SoupMessage--response-body" title="The “response-body” property"><span class="type">“response_body”</span></a> of +a server-side message, it will cause each chunk of the body to be +discarded after its corresponding <a class="link" href="SoupMessage.html#SoupMessage-wrote-chunk" title="The “wrote-chunk” signal"><span class="type">“wrote_chunk”</span></a> signal +is emitted.</p> +<p>If you set the flag to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> on the <a class="link" href="SoupMessage.html#SoupMessage--request-body" title="The “request-body” property"><span class="type">“request_body”</span></a> of a +client-side message, it will block the accumulation of chunks into +<em class="parameter"><code>body</code></em> +'s <code class="literal">data</code> field, but it will not normally cause the chunks to +be discarded after being written like in the server-side +<a class="link" href="SoupMessage.html#SoupMessage--response-body" title="The “response-body” property"><span class="type">“response_body”</span></a> case, because the request body needs to +be kept around in case the request needs to be sent a second time +due to redirection or authentication. However, if you set the +<a class="link" href="SoupMessage.html#SOUP-MESSAGE-CAN-REBUILD:CAPS"><code class="literal">SOUP_MESSAGE_CAN_REBUILD</code></a> flag on the message, then the chunks will +be discarded, and you will be responsible for recreating the +request body after the <a class="link" href="SoupMessage.html#SoupMessage-restarted" title="The “restarted” signal"><span class="type">“restarted”</span></a> signal is emitted.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.13.8"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>accumulate</p></td> +<td class="parameter_description"><p>whether or not to accumulate body chunks in <em class="parameter"><code>body</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-get-accumulate"></a><h3>soup_message_body_get_accumulate ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_message_body_get_accumulate (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>);</pre> +<p>Gets the accumulate flag on <em class="parameter"><code>body</code></em> +; see +<a class="link" href="SoupMessageBody.html#soup-message-body-set-accumulate" title="soup_message_body_set_accumulate ()"><code class="function">soup_message_body_set_accumulate()</code></a> for details.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.14.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.10.9.14.6"></a><h4>Returns</h4> +<p> the accumulate flag for <em class="parameter"><code>body</code></em> +.</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-append"></a><h3>soup_message_body_append ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_body_append (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupMemoryUse" title="enum SoupMemoryUse"><span class="type">SoupMemoryUse</span></a> use</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> length</code></em>);</pre> +<p>Appends <em class="parameter"><code>length</code></em> + bytes from <em class="parameter"><code>data</code></em> + to <em class="parameter"><code>body</code></em> + according to <em class="parameter"><code>use</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.15.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>use</p></td> +<td class="parameter_description"><p>how to use <em class="parameter"><code>data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p> data to append. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=length][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> guint8]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>length of <em class="parameter"><code>data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-append-buffer"></a><h3>soup_message_body_append_buffer ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_body_append_buffer (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *buffer</code></em>);</pre> +<p>Appends the data from <em class="parameter"><code>buffer</code></em> + to <em class="parameter"><code>body</code></em> +. (<a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> uses +<a href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffers</span></a> internally, so this is normally a constant-time +operation that doesn't actually require copying the data in +<em class="parameter"><code>buffer</code></em> +.)</p> +<div class="refsect3"> +<a name="id-1.3.10.9.16.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>buffer</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-append-take"></a><h3>soup_message_body_append_take ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_body_append_take (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guchar"><span class="type">guchar</span></a> *data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> length</code></em>);</pre> +<p>Appends <em class="parameter"><code>length</code></em> + bytes from <em class="parameter"><code>data</code></em> + to <em class="parameter"><code>body</code></em> +.</p> +<p>This function is exactly equivalent to <a class="link" href="SoupMessageBody.html#soup-message-body-append" title="soup_message_body_append ()"><code class="function">soup_message_body_append()</code></a> +with <a class="link" href="SoupMessageBody.html#SOUP-MEMORY-TAKE:CAPS"><code class="literal">SOUP_MEMORY_TAKE</code></a> as second argument; it exists mainly for +convenience and simplifying language bindings.</p> +<p>Rename to: soup_message_body_append</p> +<div class="refsect3"> +<a name="id-1.3.10.9.17.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p> data to append. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=length][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>length of <em class="parameter"><code>data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-truncate"></a><h3>soup_message_body_truncate ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_body_truncate (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>);</pre> +<p>Deletes all of the data in <em class="parameter"><code>body</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.18.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-complete"></a><h3>soup_message_body_complete ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_body_complete (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>);</pre> +<p>Tags <em class="parameter"><code>body</code></em> + as being complete; Call this when using chunked encoding +after you have appended the last chunk.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.19.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-flatten"></a><h3>soup_message_body_flatten ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +soup_message_body_flatten (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>);</pre> +<p>Fills in <em class="parameter"><code>body</code></em> +'s data field with a buffer containing all of the +data in <em class="parameter"><code>body</code></em> + (plus an additional '\0' byte not counted by <em class="parameter"><code>body</code></em> +'s +length field).</p> +<div class="refsect3"> +<a name="id-1.3.10.9.20.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.10.9.20.6"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> containing the same data as <em class="parameter"><code>body</code></em> +. +(You must free this buffer if you do not want it.)</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-get-chunk"></a><h3>soup_message_body_get_chunk ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="returnvalue">SoupBuffer</span></a> * +soup_message_body_get_chunk (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> offset</code></em>);</pre> +<p>Gets a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> containing data from <em class="parameter"><code>body</code></em> + starting at <em class="parameter"><code>offset</code></em> +. +The size of the returned chunk is unspecified. You can iterate +through the entire body by first calling +<a class="link" href="SoupMessageBody.html#soup-message-body-get-chunk" title="soup_message_body_get_chunk ()"><code class="function">soup_message_body_get_chunk()</code></a> with an offset of 0, and then on each +successive call, increment the offset by the length of the +previously-returned chunk.</p> +<p>If <em class="parameter"><code>offset</code></em> + is greater than or equal to the total length of <em class="parameter"><code>body</code></em> +, +then the return value depends on whether or not +<a class="link" href="SoupMessageBody.html#soup-message-body-complete" title="soup_message_body_complete ()"><code class="function">soup_message_body_complete()</code></a> has been called or not; if it has, +then <a class="link" href="SoupMessageBody.html#soup-message-body-get-chunk" title="soup_message_body_get_chunk ()"><code class="function">soup_message_body_get_chunk()</code></a> will return a 0-length chunk +(indicating the end of <em class="parameter"><code>body</code></em> +). If it has not, then +<a class="link" href="SoupMessageBody.html#soup-message-body-get-chunk" title="soup_message_body_get_chunk ()"><code class="function">soup_message_body_get_chunk()</code></a> will return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> (indicating that +<em class="parameter"><code>body</code></em> + may still potentially have more data, but that data is not +currently available).</p> +<div class="refsect3"> +<a name="id-1.3.10.9.21.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>offset</p></td> +<td class="parameter_description"><p>an offset</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.10.9.21.7"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-got-chunk"></a><h3>soup_message_body_got_chunk ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_body_got_chunk (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *chunk</code></em>);</pre> +<p>Handles the <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> part of receiving a chunk of data from +the network. Normally this means appending <em class="parameter"><code>chunk</code></em> + to <em class="parameter"><code>body</code></em> +, exactly +as with <a class="link" href="SoupMessageBody.html#soup-message-body-append-buffer" title="soup_message_body_append_buffer ()"><code class="function">soup_message_body_append_buffer()</code></a>, but if you have set +<em class="parameter"><code>body</code></em> +'s accumulate flag to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, then that will not happen.</p> +<p>This is a low-level method which you should not normally need to +use.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.22.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>chunk</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> received from the network</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-body-wrote-chunk"></a><h3>soup_message_body_wrote_chunk ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_body_wrote_chunk (<em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *chunk</code></em>);</pre> +<p>Handles the <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> part of writing a chunk of data to the +network. Normally this is a no-op, but if you have set <em class="parameter"><code>body</code></em> +'s +accumulate flag to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, then this will cause <em class="parameter"><code>chunk</code></em> + to be +discarded to free up memory.</p> +<p>This is a low-level method which you should not need to use, and +there are further restrictions on its proper use which are not +documented here.</p> +<div class="refsect3"> +<a name="id-1.3.10.9.23.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>chunk</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> returned from <a class="link" href="SoupMessageBody.html#soup-message-body-get-chunk" title="soup_message_body_get_chunk ()"><code class="function">soup_message_body_get_chunk()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupMessageBody.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupBuffer-struct"></a><h3>SoupBuffer</h3> +<pre class="programlisting">typedef struct { + const char *data; + gsize length; +} SoupBuffer; +</pre> +<p>A data buffer, generally used to represent a chunk of a +<a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>.</p> +<p><em class="parameter"><code>data</code></em> + is a <span class="type">char</span> because that's generally convenient; in some +situations you may need to cast it to <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guchar"><span class="type">guchar</span></a> or another type.</p> +<div class="refsect3"> +<a name="id-1.3.10.10.2.6"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="struct_members_name"> +<col class="struct_members_description"> +<col width="200px" class="struct_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="struct_member_name"><p>const <span class="type">char</span> *<em class="structfield"><code><a name="SoupBuffer-struct.data"></a>data</code></em>;</p></td> +<td class="struct_member_description"><p> the data. </p></td> +<td class="struct_member_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> gpointer]</span></td> +</tr> +<tr> +<td class="struct_member_name"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> <em class="structfield"><code><a name="SoupBuffer-struct.length"></a>length</code></em>;</p></td> +<td class="struct_member_description"><p>length of <em class="parameter"><code>data</code></em> +</p></td> +<td class="struct_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMemoryUse"></a><h3>enum SoupMemoryUse</h3> +<p>Describes how <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> should use the data passed in by the +caller.</p> +<p>See also <a class="link" href="SoupMessageBody.html#soup-buffer-new-with-owner" title="soup_buffer_new_with_owner ()"><code class="function">soup_buffer_new_with_owner()</code></a>, which allows to you create a +buffer containing data which is owned by another object.</p> +<div class="refsect3"> +<a name="id-1.3.10.10.3.5"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MEMORY-STATIC:CAPS"></a>SOUP_MEMORY_STATIC</p></td> +<td class="enum_member_description"> +<p>The memory is statically allocated and +constant; libsoup can use the passed-in buffer directly and not +need to worry about it being modified or freed.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MEMORY-TAKE:CAPS"></a>SOUP_MEMORY_TAKE</p></td> +<td class="enum_member_description"> +<p>The caller has allocated the memory for the +<a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>'s use; libsoup will assume ownership of it and free it +(with <a href="http://library.gnome.org/devel/glib/unstable/glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a>) when it is done with it.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MEMORY-COPY:CAPS"></a>SOUP_MEMORY_COPY</p></td> +<td class="enum_member_description"> +<p>The passed-in data belongs to the caller; the +<a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> will copy it into new memory, leaving the caller free +to reuse the original memory.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MEMORY-TEMPORARY:CAPS"></a>SOUP_MEMORY_TEMPORARY</p></td> +<td class="enum_member_description"> +<p>The passed-in data belongs to the caller, +but will remain valid for the lifetime of the <a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a>. The +difference between this and <em class="parameter"><code>SOUP_MEMORY_STATIC</code></em> + is that if you copy +a <em class="parameter"><code>SOUP_MEMORY_TEMPORARY</code></em> + buffer, it will make a copy of the memory +as well, rather than reusing the original memory.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessageBody-struct"></a><h3>SoupMessageBody</h3> +<pre class="programlisting">typedef struct { + const char *data; + goffset length; +} SoupMessageBody; +</pre> +<p>A <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> request or response body.</p> +<p>Note that while <em class="parameter"><code>length</code></em> + always reflects the full length of the +message body, <em class="parameter"><code>data</code></em> + is normally <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, and will only be filled in +after <a class="link" href="SoupMessageBody.html#soup-message-body-flatten" title="soup_message_body_flatten ()"><code class="function">soup_message_body_flatten()</code></a> is called. For client-side +messages, this automatically happens for the response body after it +has been fully read, unless you set the +<a class="link" href="SoupMessage.html#SOUP-MESSAGE-OVERWRITE-CHUNKS:CAPS"><code class="literal">SOUP_MESSAGE_OVERWRITE_CHUNKS</code></a> flags. Likewise, for server-side +messages, the request body is automatically filled in after being +read.</p> +<p>As an added bonus, when <em class="parameter"><code>data</code></em> + is filled in, it is always terminated +with a '\0' byte (which is not reflected in <em class="parameter"><code>length</code></em> +).</p> +<div class="refsect3"> +<a name="id-1.3.10.10.4.7"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="struct_members_name"> +<col class="struct_members_description"> +<col width="200px" class="struct_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="struct_member_name"><p>const <span class="type">char</span> *<em class="structfield"><code><a name="SoupMessageBody-struct.data"></a>data</code></em>;</p></td> +<td class="struct_member_description"><p>the data</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> <em class="structfield"><code><a name="SoupMessageBody-struct.length"></a>length</code></em>;</p></td> +<td class="struct_member_description"><p>length of <em class="parameter"><code>data</code></em> +</p></td> +<td class="struct_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +<div class="refsect1"> +<a name="SoupMessageBody.see-also"></a><h2>See Also</h2> +<p><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupMessageHeaders.html b/docs/reference/html/SoupMessageHeaders.html new file mode 100644 index 00000000..36f3ef79 --- /dev/null +++ b/docs/reference/html/SoupMessageHeaders.html @@ -0,0 +1,1818 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupMessageHeaders</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupMessage.html" title="SoupMessage"> +<link rel="next" href="SoupMessageBody.html" title="SoupMessageBody"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupMessageHeaders.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupMessageHeaders.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupMessage.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupMessageBody.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupMessageHeaders"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupMessageHeaders.top_of_page"></a>SoupMessageHeaders</span></h2> +<p>SoupMessageHeaders — HTTP message headers</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupMessageHeaders.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="returnvalue">SoupMessageHeaders</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-new" title="soup_message_headers_new ()">soup_message_headers_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-free" title="soup_message_headers_free ()">soup_message_headers_free</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-append" title="soup_message_headers_append ()">soup_message_headers_append</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-replace" title="soup_message_headers_replace ()">soup_message_headers_replace</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-remove" title="soup_message_headers_remove ()">soup_message_headers_remove</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-clear" title="soup_message_headers_clear ()">soup_message_headers_clear</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-clean-connection-headers" title="soup_message_headers_clean_connection_headers ()">soup_message_headers_clean_connection_headers</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-one" title="soup_message_headers_get_one ()">soup_message_headers_get_one</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-list" title="soup_message_headers_get_list ()">soup_message_headers_get_list</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get" title="soup_message_headers_get ()">soup_message_headers_get</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupMessageHeaders.html#SoupMessageHeadersForeachFunc" title="SoupMessageHeadersForeachFunc ()">*SoupMessageHeadersForeachFunc</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-foreach" title="soup_message_headers_foreach ()">soup_message_headers_foreach</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-iter-init" title="soup_message_headers_iter_init ()">soup_message_headers_iter_init</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-iter-next" title="soup_message_headers_iter_next ()">soup_message_headers_iter_next</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageHeaders.html#SoupEncoding" title="enum SoupEncoding"><span class="returnvalue">SoupEncoding</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-encoding" title="soup_message_headers_get_encoding ()">soup_message_headers_get_encoding</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-encoding" title="soup_message_headers_set_encoding ()">soup_message_headers_set_encoding</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="returnvalue">goffset</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-content-length" title="soup_message_headers_get_content_length ()">soup_message_headers_get_content_length</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-content-length" title="soup_message_headers_set_content_length ()">soup_message_headers_set_content_length</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageHeaders.html#SoupExpectation" title="enum SoupExpectation"><span class="returnvalue">SoupExpectation</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-expectations" title="soup_message_headers_get_expectations ()">soup_message_headers_get_expectations</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-expectations" title="soup_message_headers_set_expectations ()">soup_message_headers_set_expectations</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-content-type" title="soup_message_headers_get_content_type ()">soup_message_headers_get_content_type</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-content-type" title="soup_message_headers_set_content_type ()">soup_message_headers_set_content_type</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-content-disposition" title="soup_message_headers_get_content_disposition ()">soup_message_headers_get_content_disposition</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-content-disposition" title="soup_message_headers_set_content_disposition ()">soup_message_headers_set_content_disposition</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-ranges" title="soup_message_headers_get_ranges ()">soup_message_headers_get_ranges</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-ranges" title="soup_message_headers_set_ranges ()">soup_message_headers_set_ranges</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-range" title="soup_message_headers_set_range ()">soup_message_headers_set_range</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-free-ranges" title="soup_message_headers_free_ranges ()">soup_message_headers_free_ranges</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-content-range" title="soup_message_headers_get_content_range ()">soup_message_headers_get_content_range</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-content-range" title="soup_message_headers_set_content_range ()">soup_message_headers_set_content_range</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMessageHeaders.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="typedef_keyword">typedef</td> +<td class="function_name"><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders">SoupMessageHeaders</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupMessageHeaders.html#SoupMessageHeadersType" title="enum SoupMessageHeadersType">SoupMessageHeadersType</a></td> +</tr> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupMessageHeaders.html#SoupMessageHeadersIter" title="SoupMessageHeadersIter">SoupMessageHeadersIter</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupMessageHeaders.html#SoupEncoding" title="enum SoupEncoding">SoupEncoding</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupMessageHeaders.html#SoupExpectation" title="enum SoupExpectation">SoupExpectation</a></td> +</tr> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupMessageHeaders.html#SoupRange" title="SoupRange">SoupRange</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMessageHeaders.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> GBoxed + <span class="lineart">╰──</span> SoupMessageHeaders +</pre> +</div> +<div class="refsect1"> +<a name="SoupMessageHeaders.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupMessageHeaders.description"></a><h2>Description</h2> +<p><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> represents the HTTP message headers associated +with a request or response.</p> +</div> +<div class="refsect1"> +<a name="SoupMessageHeaders.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-message-headers-new"></a><h3>soup_message_headers_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="returnvalue">SoupMessageHeaders</span></a> * +soup_message_headers_new (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html#SoupMessageHeadersType" title="enum SoupMessageHeadersType"><span class="type">SoupMessageHeadersType</span></a> type</code></em>);</pre> +<p>Creates a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a>. (<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> does this +automatically for its own headers. You would only need to use this +method if you are manually parsing or generating message headers.)</p> +<div class="refsect3"> +<a name="id-1.3.9.8.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>the type of headers</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.2.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-free"></a><h3>soup_message_headers_free ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_free (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>);</pre> +<p>Frees <em class="parameter"><code>hdrs</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-append"></a><h3>soup_message_headers_append ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_append (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *name</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *value</code></em>);</pre> +<p>Appends a new header with name <em class="parameter"><code>name</code></em> + and value <em class="parameter"><code>value</code></em> + to <em class="parameter"><code>hdrs</code></em> +. (If +there is an existing header with name <em class="parameter"><code>name</code></em> +, then this creates a +second one, which is only allowed for list-valued headers; see also +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-replace" title="soup_message_headers_replace ()"><code class="function">soup_message_headers_replace()</code></a>.)</p> +<p>The caller is expected to make sure that <em class="parameter"><code>name</code></em> + and <em class="parameter"><code>value</code></em> + are +syntactically correct.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.4.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>the header name to add</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>value</p></td> +<td class="parameter_description"><p>the new value of <em class="parameter"><code>name</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-replace"></a><h3>soup_message_headers_replace ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_replace (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *name</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *value</code></em>);</pre> +<p>Replaces the value of the header <em class="parameter"><code>name</code></em> + in <em class="parameter"><code>hdrs</code></em> + with <em class="parameter"><code>value</code></em> +. (See +also <a class="link" href="SoupMessageHeaders.html#soup-message-headers-append" title="soup_message_headers_append ()"><code class="function">soup_message_headers_append()</code></a>.)</p> +<p>The caller is expected to make sure that <em class="parameter"><code>name</code></em> + and <em class="parameter"><code>value</code></em> + are +syntactically correct.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.5.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>the header name to replace</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>value</p></td> +<td class="parameter_description"><p>the new value of <em class="parameter"><code>name</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-remove"></a><h3>soup_message_headers_remove ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_remove (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *name</code></em>);</pre> +<p>Removes <em class="parameter"><code>name</code></em> + from <em class="parameter"><code>hdrs</code></em> +. If there are multiple values for <em class="parameter"><code>name</code></em> +, +they are all removed.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>the header name to remove</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-clear"></a><h3>soup_message_headers_clear ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_clear (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>);</pre> +<p>Clears <em class="parameter"><code>hdrs</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-clean-connection-headers"></a><h3>soup_message_headers_clean_connection_headers ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_clean_connection_headers + (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>);</pre> +<p>Removes all the headers listed in the Connection header.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<p class="since">Since 2.36</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-get-one"></a><h3>soup_message_headers_get_one ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_message_headers_get_one (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *name</code></em>);</pre> +<p>Gets the value of header <em class="parameter"><code>name</code></em> + in <em class="parameter"><code>hdrs</code></em> +. Use this for headers whose +values are <span class="emphasis"><em>not</em></span> comma-delimited lists, and +which therefore can only appear at most once in the headers. For +list-valued headers, use <a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-list" title="soup_message_headers_get_list ()"><code class="function">soup_message_headers_get_list()</code></a>.</p> +<p>If <em class="parameter"><code>hdrs</code></em> + does erroneously contain multiple copies of the header, it +is not defined which one will be returned. (Ideally, it will return +whichever one makes libsoup most compatible with other HTTP +implementations.)</p> +<div class="refsect3"> +<a name="id-1.3.9.8.9.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>header name</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.9.7"></a><h4>Returns</h4> +<p> the header's value or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if not found.</p> +<p></p> +</div> +<p class="since">Since 2.28</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-get-list"></a><h3>soup_message_headers_get_list ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_message_headers_get_list (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *name</code></em>);</pre> +<p>Gets the value of header <em class="parameter"><code>name</code></em> + in <em class="parameter"><code>hdrs</code></em> +. Use this for headers whose +values are comma-delimited lists, and which are therefore allowed +to appear multiple times in the headers. For non-list-valued +headers, use <a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-one" title="soup_message_headers_get_one ()"><code class="function">soup_message_headers_get_one()</code></a>.</p> +<p>If <em class="parameter"><code>name</code></em> + appears multiple times in <em class="parameter"><code>hdrs</code></em> +, +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-list" title="soup_message_headers_get_list ()"><code class="function">soup_message_headers_get_list()</code></a> will concatenate all of the values +together, separated by commas. This is sometimes awkward to parse +(eg, WWW-Authenticate, Set-Cookie), but you have to be able to deal +with it anyway, because the HTTP spec explicitly states that this +transformation is allowed, and so an upstream proxy could do the +same thing.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.10.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>header name</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.10.7"></a><h4>Returns</h4> +<p> the header's value or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if not found.</p> +<p></p> +</div> +<p class="since">Since 2.28</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-get"></a><h3>soup_message_headers_get ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_message_headers_get (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *name</code></em>);</pre> +<div class="warning"> +<p><code class="literal">soup_message_headers_get</code> is deprecated and should not be used in newly-written code.</p> +<p>Use <a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-one" title="soup_message_headers_get_one ()"><code class="function">soup_message_headers_get_one()</code></a> or +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-list" title="soup_message_headers_get_list ()"><code class="function">soup_message_headers_get_list()</code></a> instead.</p> +</div> +<p>Gets the value of header <em class="parameter"><code>name</code></em> + in <em class="parameter"><code>hdrs</code></em> +.</p> +<p>This method was supposed to work correctly for both single-valued +and list-valued headers, but because some HTTP clients/servers +mistakenly send multiple copies of headers that are supposed to be +single-valued, it sometimes returns incorrect results. To fix this, +the methods <a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-one" title="soup_message_headers_get_one ()"><code class="function">soup_message_headers_get_one()</code></a> and +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-list" title="soup_message_headers_get_list ()"><code class="function">soup_message_headers_get_list()</code></a> were introduced, so callers can +explicitly state which behavior they are expecting.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.11.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>header name</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.11.8"></a><h4>Returns</h4> +<p> as with <a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-list" title="soup_message_headers_get_list ()"><code class="function">soup_message_headers_get_list()</code></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessageHeadersForeachFunc"></a><h3>SoupMessageHeadersForeachFunc ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +<span class="c_punctuation">(</span>*SoupMessageHeadersForeachFunc<span class="c_punctuation">)</span> (<em class="parameter"><code>const <span class="type">char</span> *name</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *value</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>The callback passed to <a class="link" href="SoupMessageHeaders.html#soup-message-headers-foreach" title="soup_message_headers_foreach ()"><code class="function">soup_message_headers_foreach()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.12.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>the header name</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>value</p></td> +<td class="parameter_description"><p>the header value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the data passed to <a class="link" href="SoupMessageHeaders.html#soup-message-headers-foreach" title="soup_message_headers_foreach ()"><code class="function">soup_message_headers_foreach()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-foreach"></a><h3>soup_message_headers_foreach ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_foreach (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html#SoupMessageHeadersForeachFunc" title="SoupMessageHeadersForeachFunc ()"><span class="type">SoupMessageHeadersForeachFunc</span></a> func</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Calls <em class="parameter"><code>func</code></em> + once for each header value in <em class="parameter"><code>hdrs</code></em> +.</p> +<p>Beware that unlike <a class="link" href="SoupMessageHeaders.html#soup-message-headers-get" title="soup_message_headers_get ()"><code class="function">soup_message_headers_get()</code></a>, this processes the +headers in exactly the way they were added, rather than +concatenating multiple same-named headers into a single value. +(This is intentional; it ensures that if you call +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-append" title="soup_message_headers_append ()"><code class="function">soup_message_headers_append()</code></a> multiple times with the same name, +then the I/O code will output multiple copies of the header when +sending the message to the remote implementation, which may be +required for interoperability in some cases.)</p> +<p>You may not modify the headers from <em class="parameter"><code>func</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.13.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>func</p></td> +<td class="parameter_description"><p> callback function to run for each header. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid only during the call to the method."><span class="acronym">scope call</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>data to pass to <em class="parameter"><code>func</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-iter-init"></a><h3>soup_message_headers_iter_init ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_iter_init (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html#SoupMessageHeadersIter" title="SoupMessageHeadersIter"><span class="type">SoupMessageHeadersIter</span></a> *iter</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>);</pre> +<p>Initializes <em class="parameter"><code>iter</code></em> + for iterating <em class="parameter"><code>hdrs</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.14.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>iter</p></td> +<td class="parameter_description"><p> a pointer to a <a class="link" href="SoupMessageHeaders.html#SoupMessageHeadersIter" title="SoupMessageHeadersIter"><code class="literal">SoupMessageHeadersIter</code></a> +structure. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><code class="literal">SoupMessageHeaders</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-iter-next"></a><h3>soup_message_headers_iter_next ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_message_headers_iter_next (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html#SoupMessageHeadersIter" title="SoupMessageHeadersIter"><span class="type">SoupMessageHeadersIter</span></a> *iter</code></em>, + <em class="parameter"><code>const <span class="type">char</span> **name</code></em>, + <em class="parameter"><code>const <span class="type">char</span> **value</code></em>);</pre> +<p>Yields the next name/value pair in the <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><code class="literal">SoupMessageHeaders</code></a> being +iterated by <em class="parameter"><code>iter</code></em> +. If <em class="parameter"><code>iter</code></em> + has already yielded the last header, +then <a class="link" href="SoupMessageHeaders.html#soup-message-headers-iter-next" title="soup_message_headers_iter_next ()"><code class="function">soup_message_headers_iter_next()</code></a> will return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> and <em class="parameter"><code>name</code></em> + +and <em class="parameter"><code>value</code></em> + will be unchanged.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.15.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>iter</p></td> +<td class="parameter_description"><p> a <a class="link" href="SoupMessageHeaders.html#SoupMessageHeadersIter" title="SoupMessageHeadersIter"><code class="literal">SoupMessageHeadersIter</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p> pointer to a variable to return +the header name in. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>value</p></td> +<td class="parameter_description"><p> pointer to a variable to return +the header value in. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.15.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if another name and value were returned, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> +if the end of the headers has been reached.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-get-encoding"></a><h3>soup_message_headers_get_encoding ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageHeaders.html#SoupEncoding" title="enum SoupEncoding"><span class="returnvalue">SoupEncoding</span></a> +soup_message_headers_get_encoding (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>);</pre> +<p>Gets the message body encoding that <em class="parameter"><code>hdrs</code></em> + declare. This may not +always correspond to the encoding used on the wire; eg, a HEAD +response may declare a Content-Length or Transfer-Encoding, but +it will never actually include a body.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.16.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.16.6"></a><h4>Returns</h4> +<p> the encoding declared by <em class="parameter"><code>hdrs</code></em> +.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-set-encoding"></a><h3>soup_message_headers_set_encoding ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_set_encoding (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html#SoupEncoding" title="enum SoupEncoding"><span class="type">SoupEncoding</span></a> encoding</code></em>);</pre> +<p>Sets the message body encoding that <em class="parameter"><code>hdrs</code></em> + will declare. In particular, +you should use this if you are going to send a request or response in +chunked encoding.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.17.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>encoding</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html#SoupEncoding" title="enum SoupEncoding"><span class="type">SoupEncoding</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-get-content-length"></a><h3>soup_message_headers_get_content_length ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="returnvalue">goffset</span></a> +soup_message_headers_get_content_length + (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>);</pre> +<p>Gets the message body length that <em class="parameter"><code>hdrs</code></em> + declare. This will only +be non-0 if <a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-encoding" title="soup_message_headers_get_encoding ()"><code class="function">soup_message_headers_get_encoding()</code></a> returns +<a class="link" href="SoupMessageHeaders.html#SOUP-ENCODING-CONTENT-LENGTH:CAPS"><code class="literal">SOUP_ENCODING_CONTENT_LENGTH</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.18.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.18.6"></a><h4>Returns</h4> +<p> the message body length declared by <em class="parameter"><code>hdrs</code></em> +.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-set-content-length"></a><h3>soup_message_headers_set_content_length ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_set_content_length + (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> content_length</code></em>);</pre> +<p>Sets the message body length that <em class="parameter"><code>hdrs</code></em> + will declare, and sets +<em class="parameter"><code>hdrs</code></em> +'s encoding to <a class="link" href="SoupMessageHeaders.html#SOUP-ENCODING-CONTENT-LENGTH:CAPS"><code class="literal">SOUP_ENCODING_CONTENT_LENGTH</code></a>.</p> +<p>You do not normally need to call this; if <em class="parameter"><code>hdrs</code></em> + is set to use +Content-Length encoding, libsoup will automatically set its +Content-Length header for you immediately before sending the +headers. One situation in which this method is useful is when +generating the response to a HEAD request; Calling +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-content-length" title="soup_message_headers_set_content_length ()"><code class="function">soup_message_headers_set_content_length()</code></a> allows you to put the +correct content length into the response without needing to waste +memory by filling in a response body which won't actually be sent.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.19.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>content_length</p></td> +<td class="parameter_description"><p>the message body length</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-get-expectations"></a><h3>soup_message_headers_get_expectations ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageHeaders.html#SoupExpectation" title="enum SoupExpectation"><span class="returnvalue">SoupExpectation</span></a> +soup_message_headers_get_expectations (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>);</pre> +<p>Gets the expectations declared by <em class="parameter"><code>hdrs</code></em> +'s "Expect" header. +Currently this will either be <a class="link" href="SoupMessageHeaders.html#SOUP-EXPECTATION-CONTINUE:CAPS"><code class="literal">SOUP_EXPECTATION_CONTINUE</code></a> or +<a class="link" href="SoupMessageHeaders.html#SOUP-EXPECTATION-UNRECOGNIZED:CAPS"><code class="literal">SOUP_EXPECTATION_UNRECOGNIZED</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.20.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.20.6"></a><h4>Returns</h4> +<p> the contents of <em class="parameter"><code>hdrs</code></em> +'s "Expect" header</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-set-expectations"></a><h3>soup_message_headers_set_expectations ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_set_expectations (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html#SoupExpectation" title="enum SoupExpectation"><span class="type">SoupExpectation</span></a> expectations</code></em>);</pre> +<p>Sets <em class="parameter"><code>hdrs</code></em> +'s "Expect" header according to <em class="parameter"><code>expectations</code></em> +.</p> +<p>Currently <a class="link" href="SoupMessageHeaders.html#SOUP-EXPECTATION-CONTINUE:CAPS"><code class="literal">SOUP_EXPECTATION_CONTINUE</code></a> is the only known expectation +value. You should set this value on a request if you are sending a +large message body (eg, via POST or PUT), and want to give the +server a chance to reject the request after seeing just the headers +(eg, because it will require authentication before allowing you to +post, or because you're POSTing to a URL that doesn't exist). This +saves you from having to transmit the large request body when the +server is just going to ignore it anyway.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.21.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>expectations</p></td> +<td class="parameter_description"><p>the expectations to set</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-get-content-type"></a><h3>soup_message_headers_get_content_type ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_message_headers_get_content_type (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> **params</code></em>);</pre> +<p>Looks up the "Content-Type" header in <em class="parameter"><code>hdrs</code></em> +, parses it, and returns +its value in *<em class="parameter"><code>content_type</code></em> + and *<em class="parameter"><code>params</code></em> +. <em class="parameter"><code>params</code></em> + can be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if you +are only interested in the content type itself.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.22.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>params</p></td> +<td class="parameter_description"><p> return location for the Content-Type parameters (eg, "charset"), or +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.22.6"></a><h4>Returns</h4> +<p> a string with the value of the "Content-Type" header +or NULL if <em class="parameter"><code>hdrs</code></em> +does not contain that header or it cannot be +parsed (in which case *<em class="parameter"><code>params</code></em> +will be unchanged).</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-set-content-type"></a><h3>soup_message_headers_set_content_type ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_set_content_type (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *content_type</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *params</code></em>);</pre> +<p>Sets the "Content-Type" header in <em class="parameter"><code>hdrs</code></em> + to <em class="parameter"><code>content_type</code></em> +, +optionally with additional parameters specified in <em class="parameter"><code>params</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.23.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>content_type</p></td> +<td class="parameter_description"><p>the MIME type</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>params</p></td> +<td class="parameter_description"><p> additional +parameters, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8]</span></td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-get-content-disposition"></a><h3>soup_message_headers_get_content_disposition ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_message_headers_get_content_disposition + (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><span class="type">char</span> **disposition</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> **params</code></em>);</pre> +<p>Looks up the "Content-Disposition" header in <em class="parameter"><code>hdrs</code></em> +, parses it, and +returns its value in *<em class="parameter"><code>disposition</code></em> + and *<em class="parameter"><code>params</code></em> +. <em class="parameter"><code>params</code></em> + can be +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if you are only interested in the disposition-type.</p> +<p>In HTTP, the most common use of this header is to set a +disposition-type of "attachment", to suggest to the browser that a +response should be saved to disk rather than displayed in the +browser. If <em class="parameter"><code>params</code></em> + contains a "filename" parameter, this is a +suggestion of a filename to use. (If the parameter value in the +header contains an absolute or relative path, libsoup will truncate +it down to just the final path component, so you do not need to +test this yourself.)</p> +<p>Content-Disposition is also used in "multipart/form-data", however +this is handled automatically by <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> and the associated +form methods.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.24.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>disposition</p></td> +<td class="parameter_description"><p> return location for the +disposition-type, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>params</p></td> +<td class="parameter_description"><p> return +location for the Content-Disposition parameters, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.24.8"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>hdrs</code></em> +contains a "Content-Disposition" +header, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if not (in which case *<em class="parameter"><code>disposition</code></em> +and *<em class="parameter"><code>params</code></em> +will be unchanged).</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-set-content-disposition"></a><h3>soup_message_headers_set_content_disposition ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_set_content_disposition + (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *disposition</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *params</code></em>);</pre> +<p>Sets the "Content-Disposition" header in <em class="parameter"><code>hdrs</code></em> + to <em class="parameter"><code>disposition</code></em> +, +optionally with additional parameters specified in <em class="parameter"><code>params</code></em> +.</p> +<p>See <a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-content-disposition" title="soup_message_headers_get_content_disposition ()"><code class="function">soup_message_headers_get_content_disposition()</code></a> for a discussion +of how Content-Disposition is used in HTTP.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.25.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>disposition</p></td> +<td class="parameter_description"><p>the disposition-type</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>params</p></td> +<td class="parameter_description"><p> additional +parameters, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8]</span></td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-get-ranges"></a><h3>soup_message_headers_get_ranges ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_message_headers_get_ranges (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> total_length</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html#SoupRange" title="SoupRange"><span class="type">SoupRange</span></a> **ranges</code></em>, + <em class="parameter"><code><span class="type">int</span> *length</code></em>);</pre> +<p>Parses <em class="parameter"><code>hdrs</code></em> +'s Range header and returns an array of the requested +byte ranges. The returned array must be freed with +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-free-ranges" title="soup_message_headers_free_ranges ()"><code class="function">soup_message_headers_free_ranges()</code></a>.</p> +<p>If <em class="parameter"><code>total_length</code></em> + is non-0, its value will be used to adjust the +returned ranges to have explicit start and end values, and the +returned ranges will be sorted and non-overlapping. If +<em class="parameter"><code>total_length</code></em> + is 0, then some ranges may have an end value of -1, +as described under <a class="link" href="SoupMessageHeaders.html#SoupRange" title="SoupRange"><span class="type">SoupRange</span></a>, and some of the ranges may be +redundant.</p> +<p>Beware that even if given a <em class="parameter"><code>total_length</code></em> +, this function does not +check that the ranges are satisfiable.</p> +<div class="note"><p> +<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> has built-in handling for range requests. If your +server handler returns a <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-OK:CAPS"><code class="literal">SOUP_STATUS_OK</code></a> response containing the +complete response body (rather than pausing the message and +returning some of the response body later), and there is a Range +header in the request, then libsoup will automatically convert the +response to a <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-PARTIAL-CONTENT:CAPS"><code class="literal">SOUP_STATUS_PARTIAL_CONTENT</code></a> response containing only +the range(s) requested by the client. + +The only time you need to process the Range header yourself is if +either you need to stream the response body rather than returning +it all at once, or you do not already have the complete response +body available, and only want to generate the parts that were +actually requested by the client. +</p></div> +<div class="refsect3"> +<a name="id-1.3.9.8.26.8"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>total_length</p></td> +<td class="parameter_description"><p>the total_length of the response body</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>ranges</p></td> +<td class="parameter_description"><p> return location for an array of <a class="link" href="SoupMessageHeaders.html#SoupRange" title="SoupRange"><span class="type">SoupRange</span></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>the length of the returned array</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.26.9"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>hdrs</code></em> +contained a syntactically-valid +"Range" header, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise (in which case <em class="parameter"><code>range</code></em> +and <em class="parameter"><code>length</code></em> +will not be set).</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-set-ranges"></a><h3>soup_message_headers_set_ranges ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_set_ranges (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html#SoupRange" title="SoupRange"><span class="type">SoupRange</span></a> *ranges</code></em>, + <em class="parameter"><code><span class="type">int</span> length</code></em>);</pre> +<p>Sets <em class="parameter"><code>hdrs</code></em> +'s Range header to request the indicated ranges. (If you +only want to request a single range, you can use +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-range" title="soup_message_headers_set_range ()"><code class="function">soup_message_headers_set_range()</code></a>.)</p> +<div class="refsect3"> +<a name="id-1.3.9.8.27.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>ranges</p></td> +<td class="parameter_description"><p>an array of <a class="link" href="SoupMessageHeaders.html#SoupRange" title="SoupRange"><span class="type">SoupRange</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>the length of <em class="parameter"><code>range</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-set-range"></a><h3>soup_message_headers_set_range ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_set_range (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> start</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> end</code></em>);</pre> +<p>Sets <em class="parameter"><code>hdrs</code></em> +'s Range header to request the indicated range. +<em class="parameter"><code>start</code></em> + and <em class="parameter"><code>end</code></em> + are interpreted as in a <a class="link" href="SoupMessageHeaders.html#SoupRange" title="SoupRange"><span class="type">SoupRange</span></a>.</p> +<p>If you need to request multiple ranges, use +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-ranges" title="soup_message_headers_set_ranges ()"><code class="function">soup_message_headers_set_ranges()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.28.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>start</p></td> +<td class="parameter_description"><p>the start of the range to request</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>end</p></td> +<td class="parameter_description"><p>the end of the range to request</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-free-ranges"></a><h3>soup_message_headers_free_ranges ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_free_ranges (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html#SoupRange" title="SoupRange"><span class="type">SoupRange</span></a> *ranges</code></em>);</pre> +<p>Frees the array of ranges returned from <a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-ranges" title="soup_message_headers_get_ranges ()"><code class="function">soup_message_headers_get_ranges()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.29.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>ranges</p></td> +<td class="parameter_description"><p>an array of <a class="link" href="SoupMessageHeaders.html#SoupRange" title="SoupRange"><span class="type">SoupRange</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-get-content-range"></a><h3>soup_message_headers_get_content_range ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_message_headers_get_content_range + (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> *start</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> *end</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> *total_length</code></em>);</pre> +<p>Parses <em class="parameter"><code>hdrs</code></em> +'s Content-Range header and returns it in <em class="parameter"><code>start</code></em> +, +<em class="parameter"><code>end</code></em> +, and <em class="parameter"><code>total_length</code></em> +. If the total length field in the header +was specified as "*", then <em class="parameter"><code>total_length</code></em> + will be set to -1.</p> +<div class="refsect3"> +<a name="id-1.3.9.8.30.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>start</p></td> +<td class="parameter_description"><p>return value for the start of the range</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>end</p></td> +<td class="parameter_description"><p>return value for the end of the range</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>total_length</p></td> +<td class="parameter_description"><p>return value for the total length of the resource, +or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if you don't care.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.9.8.30.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>hdrs</code></em> +contained a "Content-Range" header +containing a byte range which could be parsed, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise.</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-message-headers-set-content-range"></a><h3>soup_message_headers_set_content_range ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_message_headers_set_content_range + (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *hdrs</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> start</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> end</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> total_length</code></em>);</pre> +<p>Sets <em class="parameter"><code>hdrs</code></em> +'s Content-Range header according to the given values. +(Note that <em class="parameter"><code>total_length</code></em> + is the total length of the entire resource +that this is a range of, not simply <em class="parameter"><code>end</code></em> + - <em class="parameter"><code>start</code></em> + + 1.)</p> +<div class="note"><p> +<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> has built-in handling for range requests, and you do +not normally need to call this function youself. See +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-ranges" title="soup_message_headers_get_ranges ()"><code class="function">soup_message_headers_get_ranges()</code></a> for more details. +</p></div> +<div class="refsect3"> +<a name="id-1.3.9.8.31.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hdrs</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>start</p></td> +<td class="parameter_description"><p>the start of the range</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>end</p></td> +<td class="parameter_description"><p>the end of the range</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>total_length</p></td> +<td class="parameter_description"><p>the total length of the resource, or -1 if unknown</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupMessageHeaders.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupMessageHeaders"></a><h3>SoupMessageHeaders</h3> +<pre class="programlisting">typedef struct SoupMessageHeaders SoupMessageHeaders; +</pre> +<p>The HTTP message headers associated with a request or response.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessageHeadersType"></a><h3>enum SoupMessageHeadersType</h3> +<p>Value passed to <a class="link" href="SoupMessageHeaders.html#soup-message-headers-new" title="soup_message_headers_new ()"><code class="function">soup_message_headers_new()</code></a> to set certain default +behaviors.</p> +<div class="refsect3"> +<a name="id-1.3.9.9.3.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-HEADERS-REQUEST:CAPS"></a>SOUP_MESSAGE_HEADERS_REQUEST</p></td> +<td class="enum_member_description"> +<p>request headers</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-HEADERS-RESPONSE:CAPS"></a>SOUP_MESSAGE_HEADERS_RESPONSE</p></td> +<td class="enum_member_description"> +<p>response headers</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-MESSAGE-HEADERS-MULTIPART:CAPS"></a>SOUP_MESSAGE_HEADERS_MULTIPART</p></td> +<td class="enum_member_description"> +<p>multipart body part headers</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupMessageHeadersIter"></a><h3>SoupMessageHeadersIter</h3> +<pre class="programlisting">typedef struct { +} SoupMessageHeadersIter; +</pre> +<p>An opaque type used to iterate over a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><code class="literal">SoupMessageHeaders</code></a> +structure.</p> +<p>After intializing the iterator with +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-iter-init" title="soup_message_headers_iter_init ()"><code class="function">soup_message_headers_iter_init()</code></a>, call +<a class="link" href="SoupMessageHeaders.html#soup-message-headers-iter-next" title="soup_message_headers_iter_next ()"><code class="function">soup_message_headers_iter_next()</code></a> to fetch data from it.</p> +<p>You may not modify the headers while iterating over them.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupEncoding"></a><h3>enum SoupEncoding</h3> +<p>How a message body is encoded for transport</p> +<div class="refsect3"> +<a name="id-1.3.9.9.5.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-ENCODING-UNRECOGNIZED:CAPS"></a>SOUP_ENCODING_UNRECOGNIZED</p></td> +<td class="enum_member_description"> +<p>unknown / error</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-ENCODING-NONE:CAPS"></a>SOUP_ENCODING_NONE</p></td> +<td class="enum_member_description"> +<p>no body is present (which is not the same as a +0-length body, and only occurs in certain places)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-ENCODING-CONTENT-LENGTH:CAPS"></a>SOUP_ENCODING_CONTENT_LENGTH</p></td> +<td class="enum_member_description"> +<p>Content-Length encoding</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-ENCODING-EOF:CAPS"></a>SOUP_ENCODING_EOF</p></td> +<td class="enum_member_description"> +<p>Response body ends when the connection is closed</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-ENCODING-CHUNKED:CAPS"></a>SOUP_ENCODING_CHUNKED</p></td> +<td class="enum_member_description"> +<p>chunked encoding (currently only supported +for response)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-ENCODING-BYTERANGES:CAPS"></a>SOUP_ENCODING_BYTERANGES</p></td> +<td class="enum_member_description"> +<p>multipart/byteranges (Reserved for future +use: NOT CURRENTLY IMPLEMENTED)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupExpectation"></a><h3>enum SoupExpectation</h3> +<p>Represents the parsed value of the "Expect" header.</p> +<div class="refsect3"> +<a name="id-1.3.9.9.6.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-EXPECTATION-UNRECOGNIZED:CAPS"></a>SOUP_EXPECTATION_UNRECOGNIZED</p></td> +<td class="enum_member_description"> +<p>any unrecognized expectation</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-EXPECTATION-CONTINUE:CAPS"></a>SOUP_EXPECTATION_CONTINUE</p></td> +<td class="enum_member_description"> +<p>"100-continue"</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupRange"></a><h3>SoupRange</h3> +<pre class="programlisting">typedef struct { + goffset start; + goffset end; +} SoupRange; +</pre> +<p>Represents a byte range as used in the Range header.</p> +<p>If <em class="parameter"><code>end</code></em> + is non-negative, then <em class="parameter"><code>start</code></em> + and <em class="parameter"><code>end</code></em> + represent the bounds +of of the range, counting from 0. (Eg, the first 500 bytes would be +represented as <em class="parameter"><code>start</code></em> + = 0 and <em class="parameter"><code>end</code></em> + = 499.)</p> +<p>If <em class="parameter"><code>end</code></em> + is -1 and <em class="parameter"><code>start</code></em> + is non-negative, then this represents a +range starting at <em class="parameter"><code>start</code></em> + and ending with the last byte of the +requested resource body. (Eg, all but the first 500 bytes would be +<em class="parameter"><code>start</code></em> + = 500, and <em class="parameter"><code>end</code></em> + = -1.)</p> +<p>If <em class="parameter"><code>end</code></em> + is -1 and <em class="parameter"><code>start</code></em> + is negative, then it represents a "suffix +range", referring to the last -<em class="parameter"><code>start</code></em> + bytes of the resource body. +(Eg, the last 500 bytes would be <em class="parameter"><code>start</code></em> + = -500 and <em class="parameter"><code>end</code></em> + = -1.)</p> +<div class="refsect3"> +<a name="id-1.3.9.9.7.8"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="struct_members_name"> +<col class="struct_members_description"> +<col width="200px" class="struct_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="struct_member_name"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> <em class="structfield"><code><a name="SoupRange.start"></a>start</code></em>;</p></td> +<td class="struct_member_description"><p>the start of the range</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="type">goffset</span></a> <em class="structfield"><code><a name="SoupRange.end"></a>end</code></em>;</p></td> +<td class="struct_member_description"><p>the end of the range</p></td> +<td class="struct_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupMessageHeaders.see-also"></a><h2>See Also</h2> +<p><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupMultipart.html b/docs/reference/html/SoupMultipart.html new file mode 100644 index 00000000..25580672 --- /dev/null +++ b/docs/reference/html/SoupMultipart.html @@ -0,0 +1,537 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupMultipart</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html" title="Soup Miscellaneous Utilities"> +<link rel="next" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupMultipart.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupMultipart.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupMultipartInputStream.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupMultipart"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupMultipart.top_of_page"></a>SoupMultipart</span></h2> +<p>SoupMultipart — multipart HTTP message bodies</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupMultipart.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="returnvalue">SoupMultipart</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMultipart.html#soup-multipart-new" title="soup_multipart_new ()">soup_multipart_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="returnvalue">SoupMultipart</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMultipart.html#soup-multipart-new-from-message" title="soup_multipart_new_from_message ()">soup_multipart_new_from_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMultipart.html#soup-multipart-free" title="soup_multipart_free ()">soup_multipart_free</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">int</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMultipart.html#soup-multipart-get-length" title="soup_multipart_get_length ()">soup_multipart_get_length</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupMultipart.html#soup-multipart-get-part" title="soup_multipart_get_part ()">soup_multipart_get_part</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMultipart.html#soup-multipart-append-part" title="soup_multipart_append_part ()">soup_multipart_append_part</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMultipart.html#soup-multipart-append-form-string" title="soup_multipart_append_form_string ()">soup_multipart_append_form_string</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMultipart.html#soup-multipart-append-form-file" title="soup_multipart_append_form_file ()">soup_multipart_append_form_file</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMultipart.html#soup-multipart-to-message" title="soup_multipart_to_message ()">soup_multipart_to_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMultipart.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="typedef_keyword">typedef</td> +<td class="function_name"><a class="link" href="SoupMultipart.html" title="SoupMultipart">SoupMultipart</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMultipart.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> GBoxed + <span class="lineart">╰──</span> SoupMultipart +</pre> +</div> +<div class="refsect1"> +<a name="SoupMultipart.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupMultipart.description"></a><h2>Description</h2> +</div> +<div class="refsect1"> +<a name="SoupMultipart.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-multipart-new"></a><h3>soup_multipart_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="returnvalue">SoupMultipart</span></a> * +soup_multipart_new (<em class="parameter"><code>const <span class="type">char</span> *mime_type</code></em>);</pre> +<p>Creates a new empty <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> with a randomly-generated +boundary string. Note that <em class="parameter"><code>mime_type</code></em> + must be the full MIME type, +including "multipart/".</p> +<div class="refsect3"> +<a name="id-1.3.13.8.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>mime_type</p></td> +<td class="parameter_description"><p>the MIME type of the multipart to create.</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.13.8.2.6"></a><h4>Returns</h4> +<p> a new empty <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> of the given <em class="parameter"><code>mime_type</code></em> +</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-new-from-message"></a><h3>soup_multipart_new_from_message ()</h3> +<pre class="programlisting"><a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="returnvalue">SoupMultipart</span></a> * +soup_multipart_new_from_message (<em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *headers</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *body</code></em>);</pre> +<p>Parses <em class="parameter"><code>headers</code></em> + and <em class="parameter"><code>body</code></em> + to form a new <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a></p> +<div class="refsect3"> +<a name="id-1.3.13.8.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>headers</p></td> +<td class="parameter_description"><p>the headers of the HTTP message to parse</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>the body of the HTTP message to parse</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.13.8.3.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> (or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if the message couldn't +be parsed or wasn't multipart).</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-free"></a><h3>soup_multipart_free ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_multipart_free (<em class="parameter"><code><a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> *multipart</code></em>);</pre> +<p>Frees <em class="parameter"><code>multipart</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.13.8.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-get-length"></a><h3>soup_multipart_get_length ()</h3> +<pre class="programlisting"><span class="returnvalue">int</span> +soup_multipart_get_length (<em class="parameter"><code><a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> *multipart</code></em>);</pre> +<p>Gets the number of body parts in <em class="parameter"><code>multipart</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.13.8.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.13.8.5.6"></a><h4>Returns</h4> +<p> the number of body parts in <em class="parameter"><code>multipart</code></em> +</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-get-part"></a><h3>soup_multipart_get_part ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_multipart_get_part (<em class="parameter"><code><a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> *multipart</code></em>, + <em class="parameter"><code><span class="type">int</span> part</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> **headers</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> **body</code></em>);</pre> +<p>Gets the indicated body part from <em class="parameter"><code>multipart</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.13.8.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>part</p></td> +<td class="parameter_description"><p>the part number to get (counting from 0)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>headers</p></td> +<td class="parameter_description"><p> return location for the MIME part +headers. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p> return location for the MIME part +body. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.13.8.6.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> on success, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if <em class="parameter"><code>part</code></em> +is out of range (in +which case <em class="parameter"><code>headers</code></em> +and <em class="parameter"><code>body</code></em> +won't be set)</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-append-part"></a><h3>soup_multipart_append_part ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_multipart_append_part (<em class="parameter"><code><a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> *multipart</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *headers</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *body</code></em>);</pre> +<p>Adds a new MIME part to <em class="parameter"><code>multipart</code></em> + with the given headers and body. +(The multipart will make its own copies of <em class="parameter"><code>headers</code></em> + and <em class="parameter"><code>body</code></em> +, so +you should free your copies if you are not using them for anything +else.)</p> +<div class="refsect3"> +<a name="id-1.3.13.8.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>headers</p></td> +<td class="parameter_description"><p>the MIME part headers</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>the MIME part body</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-append-form-string"></a><h3>soup_multipart_append_form_string ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_multipart_append_form_string (<em class="parameter"><code><a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> *multipart</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *control_name</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *data</code></em>);</pre> +<p>Adds a new MIME part containing <em class="parameter"><code>data</code></em> + to <em class="parameter"><code>multipart</code></em> +, using +"Content-Disposition: form-data", as per the HTML forms +specification. See <a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-multipart" title="soup_form_request_new_from_multipart ()"><code class="function">soup_form_request_new_from_multipart()</code></a> for more +details.</p> +<div class="refsect3"> +<a name="id-1.3.13.8.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>a multipart (presumably of type "multipart/form-data")</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>control_name</p></td> +<td class="parameter_description"><p>the name of the control associated with <em class="parameter"><code>data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p>the body data</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-append-form-file"></a><h3>soup_multipart_append_form_file ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_multipart_append_form_file (<em class="parameter"><code><a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> *multipart</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *control_name</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *filename</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *content_type</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> *body</code></em>);</pre> +<p>Adds a new MIME part containing <em class="parameter"><code>body</code></em> + to <em class="parameter"><code>multipart</code></em> +, using +"Content-Disposition: form-data", as per the HTML forms +specification. See <a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-multipart" title="soup_form_request_new_from_multipart ()"><code class="function">soup_form_request_new_from_multipart()</code></a> for more +details.</p> +<div class="refsect3"> +<a name="id-1.3.13.8.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>a multipart (presumably of type "multipart/form-data")</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>control_name</p></td> +<td class="parameter_description"><p>the name of the control associated with this file</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>filename</p></td> +<td class="parameter_description"><p>the name of the file, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if not known</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>content_type</p></td> +<td class="parameter_description"><p>the MIME type of the file, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if not known</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>body</p></td> +<td class="parameter_description"><p>the file data</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-to-message"></a><h3>soup_multipart_to_message ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_multipart_to_message (<em class="parameter"><code><a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> *multipart</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *dest_headers</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a> *dest_body</code></em>);</pre> +<p>Serializes <em class="parameter"><code>multipart</code></em> + to <em class="parameter"><code>dest_headers</code></em> + and <em class="parameter"><code>dest_body</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.13.8.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>dest_headers</p></td> +<td class="parameter_description"><p>the headers of the HTTP message to serialize <em class="parameter"><code>multipart</code></em> +to</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>dest_body</p></td> +<td class="parameter_description"><p>the body of the HTTP message to serialize <em class="parameter"><code>multipart</code></em> +to</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupMultipart.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupMultipart"></a><h3>SoupMultipart</h3> +<pre class="programlisting">typedef struct SoupMultipart SoupMultipart; +</pre> +<p>Represents a multipart HTTP message body, parsed according to the +syntax of RFC 2046. Of particular interest to HTTP are +<code class="literal">multipart/byte-ranges</code> and +<code class="literal">multipart/form-data</code>.</p> +<p>Although the headers of a <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> body part will contain the +full headers from that body part, libsoup does not interpret them +according to MIME rules. For example, each body part is assumed to +have "binary" Content-Transfer-Encoding, even if its headers +explicitly state otherwise. In other words, don't try to use +<a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> for handling real MIME multiparts.</p> +<p class="since">Since 2.26</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupMultipart.see-also"></a><h2>See Also</h2> +<p><a class="link" href="SoupMessageBody.html" title="SoupMessageBody"><span class="type">SoupMessageBody</span></a>, <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a></p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupMultipartInputStream.html b/docs/reference/html/SoupMultipartInputStream.html new file mode 100644 index 00000000..725d93ed --- /dev/null +++ b/docs/reference/html/SoupMultipartInputStream.html @@ -0,0 +1,399 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupMultipartInputStream</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupMultipart.html" title="SoupMultipart"> +<link rel="next" href="SoupRequest.html" title="SoupRequest"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupMultipartInputStream.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupMultipartInputStream.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupMultipartInputStream.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupMultipartInputStream.properties" class="shortcut">Properties</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupMultipart.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupRequest.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupMultipartInputStream"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupMultipartInputStream.top_of_page"></a>SoupMultipartInputStream</span></h2> +<p>SoupMultipartInputStream — Multipart input handling stream</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupMultipartInputStream.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="returnvalue">SoupMultipartInputStream</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMultipartInputStream.html#soup-multipart-input-stream-new" title="soup_multipart_input_stream_new ()">soup_multipart_input_stream_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="returnvalue">SoupMessageHeaders</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupMultipartInputStream.html#soup-multipart-input-stream-get-headers" title="soup_multipart_input_stream_get_headers ()">soup_multipart_input_stream_get_headers</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">GInputStream</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part" title="soup_multipart_input_stream_next_part ()">soup_multipart_input_stream_next_part</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part-async" title="soup_multipart_input_stream_next_part_async ()">soup_multipart_input_stream_next_part_async</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">GInputStream</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part-finish" title="soup_multipart_input_stream_next_part_finish ()">soup_multipart_input_stream_next_part_finish</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMultipartInputStream.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody><tr> +<td class="property_type"> +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *</td> +<td class="property_name"><a class="link" href="SoupMultipartInputStream.html#SoupMultipartInputStream--message" title="The “message” property">message</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMultipartInputStream.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="datatype_keyword">struct</td> +<td class="function_name"><a class="link" href="SoupMultipartInputStream.html#SoupMultipartInputStream-struct" title="struct SoupMultipartInputStream">SoupMultipartInputStream</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupMultipartInputStream.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> GInputStream + <span class="lineart">╰──</span> GFilterInputStream + <span class="lineart">╰──</span> SoupMultipartInputStream +</pre> +</div> +<div class="refsect1"> +<a name="SoupMultipartInputStream.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupMultipartInputStream implements + GPollableInputStream.</p> +</div> +<div class="refsect1"> +<a name="SoupMultipartInputStream.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupMultipartInputStream.description"></a><h2>Description</h2> +<p>This adds support for the multipart responses. For handling the +multiple parts the user needs to wrap the <span class="type">GInputStream</span> obtained by +sending the request with a <a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a> and use +<a class="link" href="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part" title="soup_multipart_input_stream_next_part ()"><code class="function">soup_multipart_input_stream_next_part()</code></a> before reading. Responses +which are not wrapped will be treated like non-multipart responses.</p> +<p>Note that although <a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a> is a <span class="type">GInputStream</span>, +you should not read directly from it, and the results are undefined +if you do.</p> +</div> +<div class="refsect1"> +<a name="SoupMultipartInputStream.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-multipart-input-stream-new"></a><h3>soup_multipart_input_stream_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="returnvalue">SoupMultipartInputStream</span></a> * +soup_multipart_input_stream_new (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><span class="type">GInputStream</span> *base_stream</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a> that wraps the +<span class="type">GInputStream</span> obtained by sending the <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>. Reads should +not be done directly through this object, use the input streams +returned by <a class="link" href="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part" title="soup_multipart_input_stream_next_part ()"><code class="function">soup_multipart_input_stream_next_part()</code></a> or its async +counterpart instead.</p> +<div class="refsect3"> +<a name="id-1.3.14.10.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> the response is related to.</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>base_stream</p></td> +<td class="parameter_description"><p>the <span class="type">GInputStream</span> returned by sending the request.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.14.10.2.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a></p> +<p></p> +</div> +<p class="since">Since 2.40</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-input-stream-get-headers"></a><h3>soup_multipart_input_stream_get_headers ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="returnvalue">SoupMessageHeaders</span></a> * +soup_multipart_input_stream_get_headers + (<em class="parameter"><code><a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a> *multipart</code></em>);</pre> +<p>Obtains the headers for the part currently being processed. Note +that the <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> that are returned are owned by the +<a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a> and will be replaced when a call is made +to <a class="link" href="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part" title="soup_multipart_input_stream_next_part ()"><code class="function">soup_multipart_input_stream_next_part()</code></a> or its async +counterpart, so if keeping the headers is required, a copy must be +made.</p> +<p>Note that if a part had no headers at all an empty <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> +will be returned.</p> +<div class="refsect3"> +<a name="id-1.3.14.10.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a>.</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.14.10.3.7"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> containing the headers +for the part currently being processed or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if the headers failed to +parse. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +<p class="since">Since 2.40</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-input-stream-next-part"></a><h3>soup_multipart_input_stream_next_part ()</h3> +<pre class="programlisting"><span class="returnvalue">GInputStream</span> * +soup_multipart_input_stream_next_part (<em class="parameter"><code><a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a> *multipart</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Obtains an input stream for the next part. When dealing with a +multipart response the input stream needs to be wrapped in a +<a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a> and this function or its async +counterpart need to be called to obtain the first part for +reading.</p> +<p>After calling this function, +<a class="link" href="SoupMultipartInputStream.html#soup-multipart-input-stream-get-headers" title="soup_multipart_input_stream_get_headers ()"><code class="function">soup_multipart_input_stream_get_headers()</code></a> can be used to obtain the +headers for the first part. A read of 0 bytes indicates the end of +the part; a new call to this function should be done at that point, +to obtain the next part.</p> +<div class="refsect3"> +<a name="id-1.3.14.10.4.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.14.10.4.7"></a><h4>Returns</h4> +<p> a new <span class="type">GInputStream</span>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if +there are no more parts. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.40</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-input-stream-next-part-async"></a><h3>soup_multipart_input_stream_next_part_async ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_multipart_input_stream_next_part_async + (<em class="parameter"><code><a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a> *multipart</code></em>, + <em class="parameter"><code><span class="type">int</span> io_priority</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><span class="type">GAsyncReadyCallback</span> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre> +<p>Obtains a <span class="type">GInputStream</span> for the next request. See +<a class="link" href="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part" title="soup_multipart_input_stream_next_part ()"><code class="function">soup_multipart_input_stream_next_part()</code></a> for details on the +workflow.</p> +<div class="refsect3"> +<a name="id-1.3.14.10.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a>.</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>io_priority</p></td> +<td class="parameter_description"><p>the I/O priority for the request.</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span>.</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p>callback to call when request is satisfied.</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p>data for <em class="parameter"><code>callback</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.40</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-multipart-input-stream-next-part-finish"></a><h3>soup_multipart_input_stream_next_part_finish ()</h3> +<pre class="programlisting"><span class="returnvalue">GInputStream</span> * +soup_multipart_input_stream_next_part_finish + (<em class="parameter"><code><a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a> *multipart</code></em>, + <em class="parameter"><code><span class="type">GAsyncResult</span> *result</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Finishes an asynchronous request for the next part.</p> +<div class="refsect3"> +<a name="id-1.3.14.10.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"><span class="type">SoupMultipartInputStream</span></a>.</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>result</p></td> +<td class="parameter_description"><p>a <span class="type">GAsyncResult</span>.</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> location to store any error, or NULL to ignore.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.14.10.6.6"></a><h4>Returns</h4> +<p> a newly created <span class="type">GInputStream</span> for +reading the next part or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if there are no more parts. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.40</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupMultipartInputStream.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupMultipartInputStream-struct"></a><h3>struct SoupMultipartInputStream</h3> +<pre class="programlisting">struct SoupMultipartInputStream;</pre> +<p> +</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupMultipartInputStream.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupMultipartInputStream--message"></a><h3>The <code class="literal">“message”</code> property</h3> +<pre class="programlisting"> “message” <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *</pre> +<p>The SoupMessage.</p> +<p>Flags: Read / Write / Construct Only</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupProxyResolverDefault.html b/docs/reference/html/SoupProxyResolverDefault.html new file mode 100644 index 00000000..6f4b1c72 --- /dev/null +++ b/docs/reference/html/SoupProxyResolverDefault.html @@ -0,0 +1,120 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupProxyResolverDefault</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch03.html" title="Additional Features"> +<link rel="prev" href="SoupLogger.html" title="SoupLogger"> +<link rel="next" href="ch04.html" title="Web Services APIs"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupProxyResolverDefault.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupProxyResolverDefault.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupProxyResolverDefault.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupProxyResolverDefault.properties" class="shortcut">Properties</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupLogger.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="ch04.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupProxyResolverDefault"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupProxyResolverDefault.top_of_page"></a>SoupProxyResolverDefault</span></h2> +<p>SoupProxyResolverDefault — System proxy configuration integration</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupProxyResolverDefault.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody><tr> +<td class="property_type"> +<span class="type">GProxyResolver</span> *</td> +<td class="property_name"><a class="link" href="SoupProxyResolverDefault.html#SoupProxyResolverDefault--gproxy-resolver" title="The “gproxy-resolver” property">gproxy-resolver</a></td> +<td class="property_flags">Write</td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupProxyResolverDefault.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupProxyResolverDefault.html#SoupProxyResolverDefault-struct" title="SoupProxyResolverDefault">SoupProxyResolverDefault</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupProxyResolverDefault.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupProxyResolverDefault +</pre> +</div> +<div class="refsect1"> +<a name="SoupProxyResolverDefault.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupProxyResolverDefault implements + <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature">SoupSessionFeature</a> and SoupProxyURIResolver.</p> +</div> +<div class="refsect1"> +<a name="SoupProxyResolverDefault.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupProxyResolverDefault.description"></a><h2>Description</h2> +<p><a class="link" href="SoupProxyResolverDefault.html" title="SoupProxyResolverDefault"><span class="type">SoupProxyResolverDefault</span></a> is a <span class="type">SoupProxyURIResolver</span> +implementation that uses the default gio <span class="type">GProxyResolver</span> to resolve +proxies.</p> +<p>In libsoup 2.44 and later, you can set the session's +<a class="link" href="SoupSession.html#SoupSession--proxy-resolver" title="The “proxy-resolver” property"><span class="type">“proxy-resolver”</span></a> property to the resolver returned by +<code class="function">g_proxy_resolver_get_default()</code> to get the same effect. Note that +for "plain" <a href="SoupSession.html"><span class="type">SoupSessions</span></a> (ie, not <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> or +<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>), this is done for you automatically.</p> +</div> +<div class="refsect1"> +<a name="SoupProxyResolverDefault.functions_details"></a><h2>Functions</h2> +</div> +<div class="refsect1"> +<a name="SoupProxyResolverDefault.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupProxyResolverDefault-struct"></a><h3>SoupProxyResolverDefault</h3> +<pre class="programlisting">typedef struct _SoupProxyResolverDefault SoupProxyResolverDefault;</pre> +<p> +</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupProxyResolverDefault.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupProxyResolverDefault--gproxy-resolver"></a><h3>The <code class="literal">“gproxy-resolver”</code> property</h3> +<pre class="programlisting"> “gproxy-resolver” <span class="type">GProxyResolver</span> *</pre> +<p>The underlying GProxyResolver.</p> +<p>Flags: Write</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupRequest.html b/docs/reference/html/SoupRequest.html new file mode 100644 index 00000000..7c69f464 --- /dev/null +++ b/docs/reference/html/SoupRequest.html @@ -0,0 +1,493 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupRequest</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupMultipartInputStream.html" title="SoupMultipartInputStream"> +<link rel="next" href="SoupRequestHTTP.html" title="SoupRequestHTTP"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupRequest.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupRequest.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupRequest.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupRequest.properties" class="shortcut">Properties</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupMultipartInputStream.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupRequestHTTP.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupRequest"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupRequest.top_of_page"></a>SoupRequest</span></h2> +<p>SoupRequest — Protocol-independent streaming request interface</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupRequest.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<span class="returnvalue">GInputStream</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupRequest.html#soup-request-send" title="soup_request_send ()">soup_request_send</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupRequest.html#soup-request-send-async" title="soup_request_send_async ()">soup_request_send_async</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">GInputStream</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupRequest.html#soup-request-send-finish" title="soup_request_send_finish ()">soup_request_send_finish</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="returnvalue">goffset</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupRequest.html#soup-request-get-content-length" title="soup_request_get_content_length ()">soup_request_get_content_length</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupRequest.html#soup-request-get-content-type" title="soup_request_get_content_type ()">soup_request_get_content_type</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupRequest.html#soup-request-get-session" title="soup_request_get_session ()">soup_request_get_session</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupRequest.html#soup-request-get-uri" title="soup_request_get_uri ()">soup_request_get_uri</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupRequest.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"> +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *</td> +<td class="property_name"><a class="link" href="SoupRequest.html#SoupRequest--session" title="The “session” property">session</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *</td> +<td class="property_name"><a class="link" href="SoupRequest.html#SoupRequest--uri" title="The “uri” property">uri</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupRequest.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupRequest.html#SoupRequest-struct" title="SoupRequest">SoupRequest</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupRequest.html#SOUP-REQUEST-SESSION:CAPS" title="SOUP_REQUEST_SESSION">SOUP_REQUEST_SESSION</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupRequest.html#SOUP-REQUEST-URI:CAPS" title="SOUP_REQUEST_URI">SOUP_REQUEST_URI</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupRequest.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupRequest + <span class="lineart">├──</span> <a class="link" href="SoupRequestData.html" title="SoupRequestData">SoupRequestData</a> + <span class="lineart">├──</span> <a class="link" href="SoupRequestFile.html" title="SoupRequestFile">SoupRequestFile</a> + <span class="lineart">╰──</span> <a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP">SoupRequestHTTP</a> +</pre> +</div> +<div class="refsect1"> +<a name="SoupRequest.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupRequest implements + GInitable.</p> +</div> +<div class="refsect1"> +<a name="SoupRequest.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupRequest.description"></a><h2>Description</h2> +<p>A <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> is created by <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, and represents a request +to retrieve a particular URI.</p> +</div> +<div class="refsect1"> +<a name="SoupRequest.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-request-send"></a><h3>soup_request_send ()</h3> +<pre class="programlisting"><span class="returnvalue">GInputStream</span> * +soup_request_send (<em class="parameter"><code><a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> *request</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Synchronously requests the URI pointed to by <em class="parameter"><code>request</code></em> +, and returns +a <span class="type">GInputStream</span> that can be used to read its contents.</p> +<p>Note that you cannot use this method with <a href="SoupRequest.html"><span class="type">SoupRequests</span></a> attached to +a <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.15.10.2.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>request</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>return location for a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.15.10.2.7"></a><h4>Returns</h4> +<p> a <span class="type">GInputStream</span> that can be used to +read from the URI pointed to by <em class="parameter"><code>request</code></em> +. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-request-send-async"></a><h3>soup_request_send_async ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_request_send_async (<em class="parameter"><code><a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> *request</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><span class="type">GAsyncReadyCallback</span> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Begins an asynchronously request for the URI pointed to by +<em class="parameter"><code>request</code></em> +.</p> +<p>Note that you cannot use this method with <a href="SoupRequest.html"><span class="type">SoupRequests</span></a> attached to +a <a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.15.10.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>request</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p>a <span class="type">GAsyncReadyCallback</span></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data passed to <em class="parameter"><code>callback</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-request-send-finish"></a><h3>soup_request_send_finish ()</h3> +<pre class="programlisting"><span class="returnvalue">GInputStream</span> * +soup_request_send_finish (<em class="parameter"><code><a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> *request</code></em>, + <em class="parameter"><code><span class="type">GAsyncResult</span> *result</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Gets the result of a <a class="link" href="SoupRequest.html#soup-request-send-async" title="soup_request_send_async ()"><code class="function">soup_request_send_async()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.15.10.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>request</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>result</p></td> +<td class="parameter_description"><p>the <span class="type">GAsyncResult</span></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>return location for a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.15.10.4.6"></a><h4>Returns</h4> +<p> a <span class="type">GInputStream</span> that can be used to +read from the URI pointed to by <em class="parameter"><code>request</code></em> +. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-request-get-content-length"></a><h3>soup_request_get_content_length ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#goffset"><span class="returnvalue">goffset</span></a> +soup_request_get_content_length (<em class="parameter"><code><a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> *request</code></em>);</pre> +<p>Gets the length of the data represented by <em class="parameter"><code>request</code></em> +. For most +request types, this will not be known until after you call +<a class="link" href="SoupRequest.html#soup-request-send" title="soup_request_send ()"><code class="function">soup_request_send()</code></a> or <a class="link" href="SoupRequest.html#soup-request-send-finish" title="soup_request_send_finish ()"><code class="function">soup_request_send_finish()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.15.10.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>request</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.15.10.5.6"></a><h4>Returns</h4> +<p> the length of the data represented by <em class="parameter"><code>request</code></em> +, +or -1 if not known.</p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-request-get-content-type"></a><h3>soup_request_get_content_type ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_request_get_content_type (<em class="parameter"><code><a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> *request</code></em>);</pre> +<p>Gets the type of the data represented by <em class="parameter"><code>request</code></em> +. For most request +types, this will not be known until after you call +<a class="link" href="SoupRequest.html#soup-request-send" title="soup_request_send ()"><code class="function">soup_request_send()</code></a> or <a class="link" href="SoupRequest.html#soup-request-send-finish" title="soup_request_send_finish ()"><code class="function">soup_request_send_finish()</code></a>.</p> +<p>As in the HTTP Content-Type header, this may include parameters +after the MIME type.</p> +<div class="refsect3"> +<a name="id-1.3.15.10.6.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>request</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.15.10.6.7"></a><h4>Returns</h4> +<p> the type of the data represented by <em class="parameter"><code>request</code></em> +, +or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if not known.</p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-request-get-session"></a><h3>soup_request_get_session ()</h3> +<pre class="programlisting"><a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +soup_request_get_session (<em class="parameter"><code><a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> *request</code></em>);</pre> +<p>Gets <em class="parameter"><code>request</code></em> +'s <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p> +<div class="refsect3"> +<a name="id-1.3.15.10.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>request</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.15.10.7.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>request</code></em> +'s <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-request-get-uri"></a><h3>soup_request_get_uri ()</h3> +<pre class="programlisting"><a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +soup_request_get_uri (<em class="parameter"><code><a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> *request</code></em>);</pre> +<p>Gets <em class="parameter"><code>request</code></em> +'s URI</p> +<div class="refsect3"> +<a name="id-1.3.15.10.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>request</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.15.10.8.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>request</code></em> +'s URI. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +<p class="since">Since 2.42</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupRequest.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupRequest-struct"></a><h3>SoupRequest</h3> +<pre class="programlisting">typedef struct _SoupRequest SoupRequest;</pre> +<p>A request to retrieve a particular URI.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-REQUEST-SESSION:CAPS"></a><h3>SOUP_REQUEST_SESSION</h3> +<pre class="programlisting">#define SOUP_REQUEST_SESSION "session" +</pre> +<p>Alias for the <a class="link" href="SoupRequest.html#SoupRequest--session" title="The “session” property"><span class="type">“session”</span></a> property, qv.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-REQUEST-URI:CAPS"></a><h3>SOUP_REQUEST_URI</h3> +<pre class="programlisting">#define SOUP_REQUEST_URI "uri" +</pre> +<p>Alias for the <a class="link" href="SoupRequest.html#SoupRequest--uri" title="The “uri” property"><span class="type">“uri”</span></a> property, qv.</p> +<p class="since">Since 2.42</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupRequest.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupRequest--session"></a><h3>The <code class="literal">“session”</code> property</h3> +<pre class="programlisting"> “session” <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *</pre> +<p>The request's <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>.</p> +<p>Flags: Read / Write / Construct Only</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupRequest--uri"></a><h3>The <code class="literal">“uri”</code> property</h3> +<pre class="programlisting"> “uri” <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *</pre> +<p>The request URI.</p> +<p>Flags: Read / Write / Construct Only</p> +<p class="since">Since 2.42</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupRequestData.html b/docs/reference/html/SoupRequestData.html new file mode 100644 index 00000000..ae07adf1 --- /dev/null +++ b/docs/reference/html/SoupRequestData.html @@ -0,0 +1,88 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupRequestData</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupRequestFile.html" title="SoupRequestFile"> +<link rel="next" href="SoupServer.html" title="SoupServer"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupRequestData.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupRequestData.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupRequestData.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupRequestFile.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupServer.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupRequestData"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupRequestData.top_of_page"></a>SoupRequestData</span></h2> +<p>SoupRequestData — SoupRequest support for "data" URIs</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupRequestData.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupRequestData.html#SoupRequestData-struct" title="SoupRequestData">SoupRequestData</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupRequestData.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> <a class="link" href="SoupRequest.html" title="SoupRequest">SoupRequest</a> + <span class="lineart">╰──</span> SoupRequestData +</pre> +</div> +<div class="refsect1"> +<a name="SoupRequestData.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupRequestData implements + GInitable.</p> +</div> +<div class="refsect1"> +<a name="SoupRequestData.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupRequestData.description"></a><h2>Description</h2> +<p><a class="link" href="SoupRequestData.html" title="SoupRequestData"><span class="type">SoupRequestData</span></a> implements <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> for "data" URIs.</p> +</div> +<div class="refsect1"> +<a name="SoupRequestData.functions_details"></a><h2>Functions</h2> +</div> +<div class="refsect1"> +<a name="SoupRequestData.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupRequestData-struct"></a><h3>SoupRequestData</h3> +<pre class="programlisting">typedef struct _SoupRequestData SoupRequestData;</pre> +<p> +</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupRequestFile.html b/docs/reference/html/SoupRequestFile.html new file mode 100644 index 00000000..a8e66d3f --- /dev/null +++ b/docs/reference/html/SoupRequestFile.html @@ -0,0 +1,135 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupRequestFile</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupRequestHTTP.html" title="SoupRequestHTTP"> +<link rel="next" href="SoupRequestData.html" title="SoupRequestData"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupRequestFile.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupRequestFile.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupRequestFile.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupRequestHTTP.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupRequestData.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupRequestFile"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupRequestFile.top_of_page"></a>SoupRequestFile</span></h2> +<p>SoupRequestFile — SoupRequest support for "file" and "resource" URIs</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupRequestFile.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody><tr> +<td class="function_type"> +<span class="returnvalue">GFile</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupRequestFile.html#soup-request-file-get-file" title="soup_request_file_get_file ()">soup_request_file_get_file</a> <span class="c_punctuation">()</span> +</td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupRequestFile.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupRequestFile.html#SoupRequestFile-struct" title="SoupRequestFile">SoupRequestFile</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupRequestFile.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> <a class="link" href="SoupRequest.html" title="SoupRequest">SoupRequest</a> + <span class="lineart">╰──</span> SoupRequestFile +</pre> +</div> +<div class="refsect1"> +<a name="SoupRequestFile.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupRequestFile implements + GInitable.</p> +</div> +<div class="refsect1"> +<a name="SoupRequestFile.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupRequestFile.description"></a><h2>Description</h2> +<p><a class="link" href="SoupRequestFile.html" title="SoupRequestFile"><span class="type">SoupRequestFile</span></a> implements <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> for "file" and "resource" +URIs.</p> +</div> +<div class="refsect1"> +<a name="SoupRequestFile.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-request-file-get-file"></a><h3>soup_request_file_get_file ()</h3> +<pre class="programlisting"><span class="returnvalue">GFile</span> * +soup_request_file_get_file (<em class="parameter"><code><a class="link" href="SoupRequestFile.html" title="SoupRequestFile"><span class="type">SoupRequestFile</span></a> *file</code></em>);</pre> +<p>Gets a <span class="type">GFile</span> corresponding to <em class="parameter"><code>file</code></em> +'s URI</p> +<div class="refsect3"> +<a name="id-1.3.17.9.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>file</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupRequestFile.html" title="SoupRequestFile"><span class="type">SoupRequestFile</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.17.9.2.6"></a><h4>Returns</h4> +<p> a <span class="type">GFile</span> corresponding to <em class="parameter"><code>file</code></em> +. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.40</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupRequestFile.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupRequestFile-struct"></a><h3>SoupRequestFile</h3> +<pre class="programlisting">typedef struct _SoupRequestFile SoupRequestFile;</pre> +<p> +</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupRequestHTTP.html b/docs/reference/html/SoupRequestHTTP.html new file mode 100644 index 00000000..4aeb9d84 --- /dev/null +++ b/docs/reference/html/SoupRequestHTTP.html @@ -0,0 +1,136 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupRequestHTTP</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupRequest.html" title="SoupRequest"> +<link rel="next" href="SoupRequestFile.html" title="SoupRequestFile"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupRequestHTTP.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupRequestHTTP.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_interfaces"> <span class="dim">|</span> + <a href="#SoupRequestHTTP.implemented-interfaces" class="shortcut">Implemented Interfaces</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupRequest.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupRequestFile.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupRequestHTTP"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupRequestHTTP.top_of_page"></a>SoupRequestHTTP</span></h2> +<p>SoupRequestHTTP — SoupRequest support for "http" and "https" URIs</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupRequestHTTP.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody><tr> +<td class="function_type"> +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupRequestHTTP.html#soup-request-http-get-message" title="soup_request_http_get_message ()">soup_request_http_get_message</a> <span class="c_punctuation">()</span> +</td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupRequestHTTP.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupRequestHTTP.html#SoupRequestHTTP-struct" title="SoupRequestHTTP">SoupRequestHTTP</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupRequestHTTP.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> <a class="link" href="SoupRequest.html" title="SoupRequest">SoupRequest</a> + <span class="lineart">╰──</span> SoupRequestHTTP +</pre> +</div> +<div class="refsect1"> +<a name="SoupRequestHTTP.implemented-interfaces"></a><h2>Implemented Interfaces</h2> +<p> +SoupRequestHTTP implements + GInitable.</p> +</div> +<div class="refsect1"> +<a name="SoupRequestHTTP.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupRequestHTTP.description"></a><h2>Description</h2> +<p><a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a> implements <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> for "http" and "https" +URIs.</p> +<p>To do more complicated HTTP operations using the <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> APIs, +call <a class="link" href="SoupRequestHTTP.html#soup-request-http-get-message" title="soup_request_http_get_message ()"><code class="function">soup_request_http_get_message()</code></a> to get the request's +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>.</p> +</div> +<div class="refsect1"> +<a name="SoupRequestHTTP.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-request-http-get-message"></a><h3>soup_request_http_get_message ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +soup_request_http_get_message (<em class="parameter"><code><a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a> *http</code></em>);</pre> +<p>Gets a new reference to the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> associated to this SoupRequest</p> +<div class="refsect3"> +<a name="id-1.3.16.9.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>http</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a> object</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.16.9.2.6"></a><h4>Returns</h4> +<p> a new reference to the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.40</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupRequestHTTP.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupRequestHTTP-struct"></a><h3>SoupRequestHTTP</h3> +<pre class="programlisting">typedef struct _SoupRequestHTTP SoupRequestHTTP;</pre> +<p> +</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupServer.html b/docs/reference/html/SoupServer.html new file mode 100644 index 00000000..34345f14 --- /dev/null +++ b/docs/reference/html/SoupServer.html @@ -0,0 +1,1645 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupServer</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupRequestData.html" title="SoupRequestData"> +<link rel="next" href="SoupSession.html" title="SoupSession"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupServer.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupServer.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupServer.properties" class="shortcut">Properties</a></span><span id="nav_signals"> <span class="dim">|</span> + <a href="#SoupServer.signals" class="shortcut">Signals</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupRequestData.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupSession.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupServer"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupServer.top_of_page"></a>SoupServer</span></h2> +<p>SoupServer — HTTP server</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupServer.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupServer.html" title="SoupServer"><span class="returnvalue">SoupServer</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-new" title="soup_server_new ()">soup_server_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-is-https" title="soup_server_is_https ()">soup_server_is_https</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-get-port" title="soup_server_get_port ()">soup_server_get_port</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupSocket.html" title="SoupSocket"><span class="returnvalue">SoupSocket</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-get-listener" title="soup_server_get_listener ()">soup_server_get_listener</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-run" title="soup_server_run ()">soup_server_run</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-run-async" title="soup_server_run_async ()">soup_server_run_async</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-quit" title="soup_server_quit ()">soup_server_quit</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-disconnect" title="soup_server_disconnect ()">soup_server_disconnect</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="returnvalue">GMainContext</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-get-async-context" title="soup_server_get_async_context ()">soup_server_get_async_context</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupServer.html#SoupServerCallback" title="SoupServerCallback ()">*SoupServerCallback</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-add-handler" title="soup_server_add_handler ()">soup_server_add_handler</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-remove-handler" title="soup_server_remove_handler ()">soup_server_remove_handler</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupSocket.html" title="SoupSocket"><span class="returnvalue">SoupSocket</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-client-context-get-socket" title="soup_client_context_get_socket ()">soup_client_context_get_socket</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-client-context-get-address" title="soup_client_context_get_address ()">soup_client_context_get_address</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-client-context-get-host" title="soup_client_context_get_host ()">soup_client_context_get_host</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="returnvalue">SoupAuthDomain</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-client-context-get-auth-domain" title="soup_client_context_get_auth_domain ()">soup_client_context_get_auth_domain</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-client-context-get-auth-user" title="soup_client_context_get_auth_user ()">soup_client_context_get_auth_user</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-add-auth-domain" title="soup_server_add_auth_domain ()">soup_server_add_auth_domain</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-remove-auth-domain" title="soup_server_remove_auth_domain ()">soup_server_remove_auth_domain</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-pause-message" title="soup_server_pause_message ()">soup_server_pause_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupServer.html#soup-server-unpause-message" title="soup_server_unpause_message ()">soup_server_unpause_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupServer.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupServer.html#SoupServer--async-context" title="The “async-context” property">async-context</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Boxed-Types.html#GStrv"><span class="type">GStrv</span></a></td> +<td class="property_name"><a class="link" href="SoupServer.html#SoupServer--http-aliases" title="The “http-aliases” property">http-aliases</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Boxed-Types.html#GStrv"><span class="type">GStrv</span></a></td> +<td class="property_name"><a class="link" href="SoupServer.html#SoupServer--https-aliases" title="The “https-aliases” property">https-aliases</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *</td> +<td class="property_name"><a class="link" href="SoupServer.html#SoupServer--interface" title="The “interface” property">interface</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a></td> +<td class="property_name"><a class="link" href="SoupServer.html#SoupServer--port" title="The “port” property">port</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupServer.html#SoupServer--raw-paths" title="The “raw-paths” property">raw-paths</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupServer.html#SoupServer--server-header" title="The “server-header” property">server-header</a></td> +<td class="property_flags">Read / Write / Construct</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupServer.html#SoupServer--ssl-cert-file" title="The “ssl-cert-file” property">ssl-cert-file</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupServer.html#SoupServer--ssl-key-file" title="The “ssl-key-file” property">ssl-key-file</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"> +<span class="type">GTlsCertificate</span> *</td> +<td class="property_name"><a class="link" href="SoupServer.html#SoupServer--tls-certificate" title="The “tls-certificate” property">tls-certificate</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupServer.signals"></a><h2>Signals</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="signals_return"> +<col width="300px" class="signals_name"> +<col width="200px" class="signals_flags"> +</colgroup> +<tbody> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupServer.html#SoupServer-request-aborted" title="The “request-aborted” signal">request-aborted</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupServer.html#SoupServer-request-finished" title="The “request-finished” signal">request-finished</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupServer.html#SoupServer-request-read" title="The “request-read” signal">request-read</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupServer.html#SoupServer-request-started" title="The “request-started” signal">request-started</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +</tbody> +</table></div> +</div> +<a name="SoupClientContext"></a><div class="refsect1"> +<a name="SoupServer.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupServer.html#SoupServer-struct" title="SoupServer">SoupServer</a></td> +</tr> +<tr> +<td class="typedef_keyword">typedef</td> +<td class="function_name"><a class="link" href="SoupServer.html#SoupClientContext">SoupClientContext</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupServer.html#SOUP-SERVER-PORT:CAPS" title="SOUP_SERVER_PORT">SOUP_SERVER_PORT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupServer.html#SOUP-SERVER-INTERFACE:CAPS" title="SOUP_SERVER_INTERFACE">SOUP_SERVER_INTERFACE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupServer.html#SOUP-SERVER-SSL-CERT-FILE:CAPS" title="SOUP_SERVER_SSL_CERT_FILE">SOUP_SERVER_SSL_CERT_FILE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupServer.html#SOUP-SERVER-SSL-KEY-FILE:CAPS" title="SOUP_SERVER_SSL_KEY_FILE">SOUP_SERVER_SSL_KEY_FILE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupServer.html#SOUP-SERVER-TLS-CERTIFICATE:CAPS" title="SOUP_SERVER_TLS_CERTIFICATE">SOUP_SERVER_TLS_CERTIFICATE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupServer.html#SOUP-SERVER-ASYNC-CONTEXT:CAPS" title="SOUP_SERVER_ASYNC_CONTEXT">SOUP_SERVER_ASYNC_CONTEXT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupServer.html#SOUP-SERVER-RAW-PATHS:CAPS" title="SOUP_SERVER_RAW_PATHS">SOUP_SERVER_RAW_PATHS</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupServer.html#SOUP-SERVER-SERVER-HEADER:CAPS" title="SOUP_SERVER_SERVER_HEADER">SOUP_SERVER_SERVER_HEADER</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupServer.html#SOUP-SERVER-HTTP-ALIASES:CAPS" title="SOUP_SERVER_HTTP_ALIASES">SOUP_SERVER_HTTP_ALIASES</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupServer.html#SOUP-SERVER-HTTPS-ALIASES:CAPS" title="SOUP_SERVER_HTTPS_ALIASES">SOUP_SERVER_HTTPS_ALIASES</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupServer.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> GBoxed + <span class="lineart">╰──</span> SoupClientContext + <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupServer +</pre> +</div> +<div class="refsect1"> +<a name="SoupServer.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupServer.description"></a><h2>Description</h2> +<p><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> implements a simple HTTP server.</p> +<p>To begin, create a server using <a class="link" href="SoupServer.html#soup-server-new" title="soup_server_new ()"><code class="function">soup_server_new()</code></a>. Add at least one +handler by calling <a class="link" href="SoupServer.html#soup-server-add-handler" title="soup_server_add_handler ()"><code class="function">soup_server_add_handler()</code></a>; the handler will be +called to process any requests underneath the path passed to +<a class="link" href="SoupServer.html#soup-server-add-handler" title="soup_server_add_handler ()"><code class="function">soup_server_add_handler()</code></a>. (If you want all requests to go to the +same handler, just pass "/" (or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>) for the path.) Any request +that does not match any handler will automatically be returned to +the client with a 404 (Not Found) status.</p> +<p>If you want to handle the special "*" URI (eg, "OPTIONS *"), you +must explicitly register a handler for "*"; the default handler +will not be used for that case.</p> +<p>To add authentication to some or all paths, create an appropriate +<a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> (qv), and add it to the server via +<a class="link" href="SoupServer.html#soup-server-add-auth-domain" title="soup_server_add_auth_domain ()"><code class="function">soup_server_add_auth_domain()</code></a>. (As with handlers, you must +explicitly add "*" to an auth domain if you want it to be covered.)</p> +<p>Additional processing options are available via <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a>'s +signals; Connect to <a class="link" href="SoupServer.html#SoupServer-request-started" title="The “request-started” signal"><span class="type">“request-started”</span></a> to be notified +every time a new request is being processed. (This gives you a +chance to connect to the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> "got-" signals in case you +want to do processing before the body has been fully read.)</p> +<p>Once the server is set up, start it processing connections by +calling <a class="link" href="SoupServer.html#soup-server-run-async" title="soup_server_run_async ()"><code class="function">soup_server_run_async()</code></a> or <a class="link" href="SoupServer.html#soup-server-run" title="soup_server_run ()"><code class="function">soup_server_run()</code></a>. <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> +runs via the glib main loop; if you need to have a server that runs +in another thread (or merely isn't bound to the default main loop), +create a <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> for it to use, and set that via the +<a class="link" href="SoupServer.html#SOUP-SERVER-ASYNC-CONTEXT:CAPS" title="SOUP_SERVER_ASYNC_CONTEXT"><span class="type">SOUP_SERVER_ASYNC_CONTEXT</span></a> property.</p> +</div> +<div class="refsect1"> +<a name="SoupServer.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-server-new"></a><h3>soup_server_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupServer.html" title="SoupServer"><span class="returnvalue">SoupServer</span></a> * +soup_server_new (<em class="parameter"><code>const <span class="type">char</span> *optname1</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>optname1</p></td> +<td class="parameter_description"><p>name of first property to set</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>value of <em class="parameter"><code>optname1</code></em> +, followed by additional property/value pairs</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.19.11.2.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-is-https"></a><h3>soup_server_is_https ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_server_is_https (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>);</pre> +<p>Checks whether <em class="parameter"><code>server</code></em> + is running plain http or https.</p> +<p>In order for a server to run https, you must set the +<a class="link" href="SoupServer.html#SOUP-SERVER-SSL-CERT-FILE:CAPS" title="SOUP_SERVER_SSL_CERT_FILE"><code class="literal">SOUP_SERVER_SSL_CERT_FILE</code></a> and <a class="link" href="SoupServer.html#SOUP-SERVER-SSL-KEY-FILE:CAPS" title="SOUP_SERVER_SSL_KEY_FILE"><code class="literal">SOUP_SERVER_SSL_KEY_FILE</code></a> properties +or <a class="link" href="SoupServer.html#SOUP-SERVER-TLS-CERTIFICATE:CAPS" title="SOUP_SERVER_TLS_CERTIFICATE"><code class="literal">SOUP_SERVER_TLS_CERTIFICATE</code></a> property to provide it with an SSL +certificate to use.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.19.11.3.7"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>server</code></em> +is serving https.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-get-port"></a><h3>soup_server_get_port ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_server_get_port (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>);</pre> +<p>Gets the TCP port that <em class="parameter"><code>server</code></em> + is listening on. This is most useful +when you did not request a specific port (or explicitly requested +<a class="link" href="SoupAddress.html#SOUP-ADDRESS-ANY-PORT:CAPS" title="SOUP_ADDRESS_ANY_PORT"><code class="literal">SOUP_ADDRESS_ANY_PORT</code></a>).</p> +<div class="refsect3"> +<a name="id-1.3.19.11.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.19.11.4.6"></a><h4>Returns</h4> +<p> the port <em class="parameter"><code>server</code></em> +is listening on.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-get-listener"></a><h3>soup_server_get_listener ()</h3> +<pre class="programlisting"><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="returnvalue">SoupSocket</span></a> * +soup_server_get_listener (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>);</pre> +<p>Gets <em class="parameter"><code>server</code></em> +'s listening socket. You should treat this as +read-only; writing to it or modifiying it may cause <em class="parameter"><code>server</code></em> + to +malfunction.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.19.11.5.6"></a><h4>Returns</h4> +<p> the listening socket. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-run"></a><h3>soup_server_run ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_server_run (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>);</pre> +<p>Starts <em class="parameter"><code>server</code></em> +, causing it to listen for and process incoming +connections. Unlike <a class="link" href="SoupServer.html#soup-server-run-async" title="soup_server_run_async ()"><code class="function">soup_server_run_async()</code></a>, this creates a +<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainLoop"><span class="type">GMainLoop</span></a> and runs it, and it will not return until someone calls +<a class="link" href="SoupServer.html#soup-server-quit" title="soup_server_quit ()"><code class="function">soup_server_quit()</code></a> to stop the server.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-run-async"></a><h3>soup_server_run_async ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_server_run_async (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>);</pre> +<p>Starts <em class="parameter"><code>server</code></em> +, causing it to listen for and process incoming +connections.</p> +<p>The server actually runs in <em class="parameter"><code>server</code></em> +'s <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>. It will not +actually perform any processing unless the appropriate main loop is +running. In the simple case where you did not set the server's +<a class="link" href="SoupServer.html#SOUP-SERVER-ASYNC-CONTEXT:CAPS" title="SOUP_SERVER_ASYNC_CONTEXT"><code class="literal">SOUP_SERVER_ASYNC_CONTEXT</code></a> property, this means the server will run +whenever the glib main loop is running.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.7.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-quit"></a><h3>soup_server_quit ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_server_quit (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>);</pre> +<p>Stops processing for <em class="parameter"><code>server</code></em> +. Call this to clean up after +<a class="link" href="SoupServer.html#soup-server-run-async" title="soup_server_run_async ()"><code class="function">soup_server_run_async()</code></a>, or to terminate a call to <a class="link" href="SoupServer.html#soup-server-run" title="soup_server_run ()"><code class="function">soup_server_run()</code></a>.</p> +<p><em class="parameter"><code>server</code></em> + is still in a working state after this call; you can start +and stop a server as many times as you want.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.8.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-disconnect"></a><h3>soup_server_disconnect ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_server_disconnect (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>);</pre> +<p>Stops processing for <em class="parameter"><code>server</code></em> + and closes its socket. This implies +the effects of <a class="link" href="SoupServer.html#soup-server-quit" title="soup_server_quit ()"><code class="function">soup_server_quit()</code></a>, but additionally closes the +listening socket. Note that messages currently in progress will +continue to be handled, if the main loop associated with the +server is resumed or kept running.</p> +<p>After calling this function, <em class="parameter"><code>server</code></em> + is no longer functional, so it +has nearly the same effect as destroying <em class="parameter"><code>server</code></em> + entirely. The +function is thus useful mainly for language bindings without +explicit control over object lifetime.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.9.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-get-async-context"></a><h3>soup_server_get_async_context ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="returnvalue">GMainContext</span></a> * +soup_server_get_async_context (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>);</pre> +<p>Gets <em class="parameter"><code>server</code></em> +'s async_context. This does not add a ref to the +context, so you will need to ref it yourself if you want it to +outlive its server.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.19.11.10.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>server</code></em> +'s <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>, which may be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServerCallback"></a><h3>SoupServerCallback ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +<span class="c_punctuation">(</span>*SoupServerCallback<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *path</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *query</code></em>, + <em class="parameter"><code><a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a> *client</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>A callback used to handle requests to a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a>. The callback +will be invoked after receiving the request body; <em class="parameter"><code>msg</code></em> +'s +<a class="link" href="SoupMessage.html#SoupMessage--method" title="The “method” property"><span class="type">“method”</span></a>, <a class="link" href="SoupMessage.html#SoupMessage--request-headers" title="The “request-headers” property"><span class="type">“request_headers”</span></a>, and +<a class="link" href="SoupMessage.html#SoupMessage--request-body" title="The “request-body” property"><span class="type">“request_body”</span></a> fields will be filled in.</p> +<p><em class="parameter"><code>path</code></em> + and <em class="parameter"><code>query</code></em> + contain the likewise-named components of the +Request-URI, subject to certain assumptions. By default, +<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> decodes all percent-encoding in the URI path, such that +"/foo%2Fbar" is treated the same as "/foo/bar". If your +server is serving resources in some non-POSIX-filesystem namespace, +you may want to distinguish those as two distinct paths. In that +case, you can set the <a class="link" href="SoupServer.html#SOUP-SERVER-RAW-PATHS:CAPS" title="SOUP_SERVER_RAW_PATHS"><code class="literal">SOUP_SERVER_RAW_PATHS</code></a> property when creating +the <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a>, and it will leave those characters undecoded. (You +may want to call <a class="link" href="SoupURI.html#soup-uri-normalize" title="soup_uri_normalize ()"><code class="function">soup_uri_normalize()</code></a> to decode any percent-encoded +characters that you aren't handling specially.)</p> +<p><em class="parameter"><code>query</code></em> + contains the query component of the Request-URI parsed +according to the rules for HTML form handling. Although this is the +only commonly-used query string format in HTTP, there is nothing +that actually requires that HTTP URIs use that format; if your +server needs to use some other format, you can just ignore <em class="parameter"><code>query</code></em> +, +and call <a class="link" href="SoupMessage.html#soup-message-get-uri" title="soup_message_get_uri ()"><code class="function">soup_message_get_uri()</code></a> and parse the URI's query field +yourself.</p> +<p>After determining what to do with the request, the callback must at +a minimum call <a class="link" href="SoupMessage.html#soup-message-set-status" title="soup_message_set_status ()"><code class="function">soup_message_set_status()</code></a> (or +<a class="link" href="SoupMessage.html#soup-message-set-status-full" title="soup_message_set_status_full ()"><code class="function">soup_message_set_status_full()</code></a>) on <em class="parameter"><code>msg</code></em> + to set the response status +code. Additionally, it may set response headers and/or fill in the +response body.</p> +<p>If the callback cannot fully fill in the response before returning +(eg, if it needs to wait for information from a database, or +another network server), it should call <a class="link" href="SoupServer.html#soup-server-pause-message" title="soup_server_pause_message ()"><code class="function">soup_server_pause_message()</code></a> +to tell <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> to not send the response right away. When the +response is ready, call <a class="link" href="SoupServer.html#soup-server-unpause-message" title="soup_server_unpause_message ()"><code class="function">soup_server_unpause_message()</code></a> to cause it +to be sent.</p> +<p>To send the response body a bit at a time using "chunked" encoding, +first call <a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-encoding" title="soup_message_headers_set_encoding ()"><code class="function">soup_message_headers_set_encoding()</code></a> to set +<a class="link" href="SoupMessageHeaders.html#SOUP-ENCODING-CHUNKED:CAPS"><code class="literal">SOUP_ENCODING_CHUNKED</code></a> on the <a class="link" href="SoupMessage.html#SoupMessage--response-headers" title="The “response-headers” property"><span class="type">“response_headers”</span></a>. Then call +<a class="link" href="SoupMessageBody.html#soup-message-body-append" title="soup_message_body_append ()"><code class="function">soup_message_body_append()</code></a> (or <a class="link" href="SoupMessageBody.html#soup-message-body-append-buffer" title="soup_message_body_append_buffer ()"><code class="function">soup_message_body_append_buffer()</code></a>) +to append each chunk as it becomes ready, and +<a class="link" href="SoupServer.html#soup-server-unpause-message" title="soup_server_unpause_message ()"><code class="function">soup_server_unpause_message()</code></a> to make sure it's running. (The +server will automatically pause the message if it is using chunked +encoding but no more chunks are available.) When you are done, call +<a class="link" href="SoupMessageBody.html#soup-message-body-complete" title="soup_message_body_complete ()"><code class="function">soup_message_body_complete()</code></a> to indicate that no more chunks are +coming.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.11.10"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message being processed</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>path</p></td> +<td class="parameter_description"><p>the path component of <em class="parameter"><code>msg</code></em> +'s Request-URI</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>query</p></td> +<td class="parameter_description"><p> the parsed query +component of <em class="parameter"><code>msg</code></em> +'s Request-URI. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>client</p></td> +<td class="parameter_description"><p>additional contextual information about the client</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the data passed to <em class="parameter"><code>soup_server_add_handler</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-add-handler"></a><h3>soup_server_add_handler ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_server_add_handler (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *path</code></em>, + <em class="parameter"><code><a class="link" href="SoupServer.html#SoupServerCallback" title="SoupServerCallback ()"><span class="type">SoupServerCallback</span></a> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Datasets.html#GDestroyNotify"><span class="type">GDestroyNotify</span></a> destroy</code></em>);</pre> +<p>Adds a handler to <em class="parameter"><code>server</code></em> + for requests under <em class="parameter"><code>path</code></em> +. See the +documentation for <a class="link" href="SoupServer.html#SoupServerCallback" title="SoupServerCallback ()"><span class="type">SoupServerCallback</span></a> for information about +how callbacks should behave.</p> +<p>If <em class="parameter"><code>path</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> or "/", then this will be the default handler for +all requests that don't have a more specific handler. Note though +that if you want to handle requests to the special "*" URI, you +must explicitly register a handler for "*"; the default handler +will not be used for that case.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.12.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>path</p></td> +<td class="parameter_description"><p> the toplevel path for the handler. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p>callback to invoke for requests under <em class="parameter"><code>path</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>data for <em class="parameter"><code>callback</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>destroy</p></td> +<td class="parameter_description"><p>destroy notifier to free <em class="parameter"><code>user_data</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-remove-handler"></a><h3>soup_server_remove_handler ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_server_remove_handler (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *path</code></em>);</pre> +<p>Removes the handler registered at <em class="parameter"><code>path</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.13.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>path</p></td> +<td class="parameter_description"><p>the toplevel path for the handler</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-client-context-get-socket"></a><h3>soup_client_context_get_socket ()</h3> +<pre class="programlisting"><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="returnvalue">SoupSocket</span></a> * +soup_client_context_get_socket (<em class="parameter"><code><a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a> *client</code></em>);</pre> +<p>Retrieves the <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> that <em class="parameter"><code>client</code></em> + is associated with.</p> +<p>If you are using this method to observe when multiple requests are +made on the same persistent HTTP connection (eg, as the ntlm-test +test program does), you will need to pay attention to socket +destruction as well (either by using weak references, or by +connecting to the <a class="link" href="SoupSocket.html#SoupSocket-disconnected" title="The “disconnected” signal"><span class="type">“disconnected”</span></a> signal), so that you do +not get fooled when the allocator reuses the memory address of a +previously-destroyed socket to represent a new socket.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.14.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>client</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.19.11.14.7"></a><h4>Returns</h4> +<p> the <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> that <em class="parameter"><code>client</code></em> +is +associated with. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-client-context-get-address"></a><h3>soup_client_context_get_address ()</h3> +<pre class="programlisting"><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +soup_client_context_get_address (<em class="parameter"><code><a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a> *client</code></em>);</pre> +<p>Retrieves the <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> associated with the remote end +of a connection.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.15.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>client</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.19.11.15.6"></a><h4>Returns</h4> +<p> the <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> associated with the +remote end of a connection. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-client-context-get-host"></a><h3>soup_client_context_get_host ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_client_context_get_host (<em class="parameter"><code><a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a> *client</code></em>);</pre> +<p>Retrieves the IP address associated with the remote end of a +connection. (If you want the actual hostname, you'll have to call +<a class="link" href="SoupServer.html#soup-client-context-get-address" title="soup_client_context_get_address ()"><code class="function">soup_client_context_get_address()</code></a> and then call the appropriate +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> method to resolve it.)</p> +<div class="refsect3"> +<a name="id-1.3.19.11.16.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>client</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.19.11.16.6"></a><h4>Returns</h4> +<p> the IP address associated with the remote end of a +connection.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-client-context-get-auth-domain"></a><h3>soup_client_context_get_auth_domain ()</h3> +<pre class="programlisting"><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="returnvalue">SoupAuthDomain</span></a> * +soup_client_context_get_auth_domain (<em class="parameter"><code><a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a> *client</code></em>);</pre> +<p>Checks whether the request associated with <em class="parameter"><code>client</code></em> + has been +authenticated, and if so returns the <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> that +authenticated it.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.17.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>client</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.19.11.17.6"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a>, or +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if the request was not authenticated. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-client-context-get-auth-user"></a><h3>soup_client_context_get_auth_user ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_client_context_get_auth_user (<em class="parameter"><code><a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a> *client</code></em>);</pre> +<p>Checks whether the request associated with <em class="parameter"><code>client</code></em> + has been +authenticated, and if so returns the username that the client +authenticated as.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.18.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>client</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.19.11.18.6"></a><h4>Returns</h4> +<p> the authenticated-as user, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if the request +was not authenticated.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-add-auth-domain"></a><h3>soup_server_add_auth_domain ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_server_add_auth_domain (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>, + <em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *auth_domain</code></em>);</pre> +<p>Adds an authentication domain to <em class="parameter"><code>server</code></em> +. Each auth domain will +have the chance to require authentication for each request that +comes in; normally auth domains will require authentication for +requests on certain paths that they have been set up to watch, or +that meet other criteria set by the caller. If an auth domain +determines that a request requires authentication (and the request +doesn't contain authentication), <em class="parameter"><code>server</code></em> + will automatically reject +the request with an appropriate status (401 Unauthorized or 407 +Proxy Authentication Required). If the request used the +"100-continue" Expectation, <em class="parameter"><code>server</code></em> + will reject it before the +request body is sent.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.19.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>auth_domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-remove-auth-domain"></a><h3>soup_server_remove_auth_domain ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_server_remove_auth_domain (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>, + <em class="parameter"><code><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a> *auth_domain</code></em>);</pre> +<p>Removes <em class="parameter"><code>auth_domain</code></em> + from <em class="parameter"><code>server</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.20.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>auth_domain</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-pause-message"></a><h3>soup_server_pause_message ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_server_pause_message (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Pauses I/O on <em class="parameter"><code>msg</code></em> +. This can be used when you need to return from +the server handler without having the full response ready yet. Use +<a class="link" href="SoupServer.html#soup-server-unpause-message" title="soup_server_unpause_message ()"><code class="function">soup_server_unpause_message()</code></a> to resume I/O.</p> +<p>This must only be called on <a href="SoupMessage.html"><span class="type">SoupMessages</span></a> which were created by the +<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> and are currently doing I/O, such as those passed into a +<a class="link" href="SoupServer.html#SoupServerCallback" title="SoupServerCallback ()"><span class="type">SoupServerCallback</span></a> or emitted in a <a class="link" href="SoupServer.html#SoupServer-request-read" title="The “request-read” signal"><span class="type">“request-read”</span></a> signal.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.21.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> associated with <em class="parameter"><code>server</code></em> +.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-server-unpause-message"></a><h3>soup_server_unpause_message ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_server_unpause_message (<em class="parameter"><code><a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Resumes I/O on <em class="parameter"><code>msg</code></em> +. Use this to resume after calling +<a class="link" href="SoupServer.html#soup-server-pause-message" title="soup_server_pause_message ()"><code class="function">soup_server_pause_message()</code></a>, or after adding a new chunk to a +chunked response.</p> +<p>I/O won't actually resume until you return to the main loop.</p> +<p>This must only be called on <a href="SoupMessage.html"><span class="type">SoupMessages</span></a> which were created by the +<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> and are currently doing I/O, such as those passed into a +<a class="link" href="SoupServer.html#SoupServerCallback" title="SoupServerCallback ()"><span class="type">SoupServerCallback</span></a> or emitted in a <a class="link" href="SoupServer.html#SoupServer-request-read" title="The “request-read” signal"><span class="type">“request-read”</span></a> signal.</p> +<div class="refsect3"> +<a name="id-1.3.19.11.22.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> associated with <em class="parameter"><code>server</code></em> +.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +<div class="refsect1"> +<a name="SoupServer.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupServer-struct"></a><h3>SoupServer</h3> +<pre class="programlisting">typedef struct _SoupServer SoupServer;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupClientContext"></a><h3>SoupClientContext</h3> +<pre class="programlisting">typedef struct SoupClientContext SoupClientContext; +</pre> +<p>A <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a> provides additional information about the +client making a particular request. In particular, you can use +<a class="link" href="SoupServer.html#soup-client-context-get-auth-domain" title="soup_client_context_get_auth_domain ()"><code class="function">soup_client_context_get_auth_domain()</code></a> and +<a class="link" href="SoupServer.html#soup-client-context-get-auth-user" title="soup_client_context_get_auth_user ()"><code class="function">soup_client_context_get_auth_user()</code></a> to determine if HTTP +authentication was used successfully.</p> +<p>soup_client_context_get_address() and/or +<a class="link" href="SoupServer.html#soup-client-context-get-host" title="soup_client_context_get_host ()"><code class="function">soup_client_context_get_host()</code></a> can be used to get information for +logging or debugging purposes. <a class="link" href="SoupServer.html#soup-client-context-get-socket" title="soup_client_context_get_socket ()"><code class="function">soup_client_context_get_socket()</code></a> may +also be of use in some situations (eg, tracking when multiple +requests are made on the same connection).</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SERVER-PORT:CAPS"></a><h3>SOUP_SERVER_PORT</h3> +<pre class="programlisting">#define SOUP_SERVER_PORT "port" +</pre> +<p>Alias for the <a class="link" href="SoupServer.html#SoupServer--port" title="The “port” property"><span class="type">“port”</span></a> property. (The port the +server listens on.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SERVER-INTERFACE:CAPS"></a><h3>SOUP_SERVER_INTERFACE</h3> +<pre class="programlisting">#define SOUP_SERVER_INTERFACE "interface" +</pre> +<p>Alias for the <a class="link" href="SoupServer.html#SoupServer--interface" title="The “interface” property"><span class="type">“interface”</span></a> property. (The address +of the network interface the server listens on.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SERVER-SSL-CERT-FILE:CAPS"></a><h3>SOUP_SERVER_SSL_CERT_FILE</h3> +<pre class="programlisting">#define SOUP_SERVER_SSL_CERT_FILE "ssl-cert-file" +</pre> +<p>Alias for the <a class="link" href="SoupServer.html#SoupServer--ssl-cert-file" title="The “ssl-cert-file” property"><span class="type">“ssl-cert-file”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SERVER-SSL-KEY-FILE:CAPS"></a><h3>SOUP_SERVER_SSL_KEY_FILE</h3> +<pre class="programlisting">#define SOUP_SERVER_SSL_KEY_FILE "ssl-key-file" +</pre> +<p>Alias for the <a class="link" href="SoupServer.html#SoupServer--ssl-key-file" title="The “ssl-key-file” property"><span class="type">“ssl-key-file”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SERVER-TLS-CERTIFICATE:CAPS"></a><h3>SOUP_SERVER_TLS_CERTIFICATE</h3> +<pre class="programlisting">#define SOUP_SERVER_TLS_CERTIFICATE "tls-certificate" +</pre> +<p>Alias for the <a class="link" href="SoupServer.html#SoupServer--tls-certificate" title="The “tls-certificate” property"><span class="type">“tls-certificate”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SERVER-ASYNC-CONTEXT:CAPS"></a><h3>SOUP_SERVER_ASYNC_CONTEXT</h3> +<pre class="programlisting">#define SOUP_SERVER_ASYNC_CONTEXT "async-context" +</pre> +<p>Alias for the <a class="link" href="SoupServer.html#SoupServer--async-context" title="The “async-context” property"><span class="type">“async-context”</span></a> property. (The +server's <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SERVER-RAW-PATHS:CAPS"></a><h3>SOUP_SERVER_RAW_PATHS</h3> +<pre class="programlisting">#define SOUP_SERVER_RAW_PATHS "raw-paths" +</pre> +<p>Alias for the <a class="link" href="SoupServer.html#SoupServer--raw-paths" title="The “raw-paths” property"><span class="type">“raw-paths”</span></a> property. (If <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, +percent-encoding in the Request-URI path will not be +automatically decoded.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SERVER-SERVER-HEADER:CAPS"></a><h3>SOUP_SERVER_SERVER_HEADER</h3> +<pre class="programlisting">#define SOUP_SERVER_SERVER_HEADER "server-header" +</pre> +<p>Alias for the <a class="link" href="SoupServer.html#SoupServer--server-header" title="The “server-header” property"><span class="type">“server-header”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SERVER-HTTP-ALIASES:CAPS"></a><h3>SOUP_SERVER_HTTP_ALIASES</h3> +<pre class="programlisting">#define SOUP_SERVER_HTTP_ALIASES "http-aliases" +</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SERVER-HTTPS-ALIASES:CAPS"></a><h3>SOUP_SERVER_HTTPS_ALIASES</h3> +<pre class="programlisting">#define SOUP_SERVER_HTTPS_ALIASES "https-aliases" +</pre> +<p>Alias for the <a class="link" href="SoupServer.html#SoupServer--https-aliases" title="The “https-aliases” property"><span class="type">“https-aliases”</span></a> property, qv.</p> +<p class="since">Since 2.44</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupServer.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupServer--async-context"></a><h3>The <code class="literal">“async-context”</code> property</h3> +<pre class="programlisting"> “async-context” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>The GMainContext to dispatch async I/O in.</p> +<p>Flags: Read / Write / Construct Only</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer--http-aliases"></a><h3>The <code class="literal">“http-aliases”</code> property</h3> +<pre class="programlisting"> “http-aliases” <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Boxed-Types.html#GStrv"><span class="type">GStrv</span></a></pre> +<p>A <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>-terminated array of URI schemes that should be +considered to be aliases for "http". Eg, if this included +<code class="literal">"dav"</code>, than a URI of +<code class="literal">dav://example.com/path</code> would be treated +identically to <code class="literal">http://example.com/path</code>. +In particular, this is needed in cases where a client +sends requests with absolute URIs, where those URIs do +not use "http:".</p> +<p>The default value is an array containing the single element +<code class="literal">"*"</code>, a special value which means that +any scheme except "https" is considered to be an alias for +"http".</p> +<p>See also <a class="link" href="SoupServer.html#SoupServer--https-aliases" title="The “https-aliases” property"><span class="type">“https-aliases”</span></a>.</p> +<p>Flags: Read / Write</p> +<p class="since">Since 2.44</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer--https-aliases"></a><h3>The <code class="literal">“https-aliases”</code> property</h3> +<pre class="programlisting"> “https-aliases” <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Boxed-Types.html#GStrv"><span class="type">GStrv</span></a></pre> +<p>A comma-delimited list of URI schemes that should be +considered to be aliases for "https". See +<a class="link" href="SoupServer.html#SoupServer--http-aliases" title="The “http-aliases” property"><span class="type">“http-aliases”</span></a> for more information.</p> +<p>The default value is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, meaning that no URI schemes +are considered aliases for "https".</p> +<p>Flags: Read / Write</p> +<p class="since">Since 2.44</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer--interface"></a><h3>The <code class="literal">“interface”</code> property</h3> +<pre class="programlisting"> “interface” <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *</pre> +<p>Address of interface to listen on.</p> +<p>Flags: Read / Write / Construct Only</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer--port"></a><h3>The <code class="literal">“port”</code> property</h3> +<pre class="programlisting"> “port” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a></pre> +<p>Port to listen on.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Allowed values: <= 65536</p> +<p>Default value: 0</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer--raw-paths"></a><h3>The <code class="literal">“raw-paths”</code> property</h3> +<pre class="programlisting"> “raw-paths” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>If %TRUE, percent-encoding in the Request-URI path will not be automatically decoded.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: FALSE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer--server-header"></a><h3>The <code class="literal">“server-header”</code> property</h3> +<pre class="programlisting"> “server-header” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>If non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, the value to use for the "Server" header on +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>s processed by this server.</p> +<p>The Server header is the server equivalent of the +User-Agent header, and provides information about the +server and its components. It contains a list of one or +more product tokens, separated by whitespace, with the most +significant product token coming first. The tokens must be +brief, ASCII, and mostly alphanumeric (although "-", "_", +and "." are also allowed), and may optionally include a "/" +followed by a version string. You may also put comments, +enclosed in parentheses, between or after the tokens.</p> +<p>Some HTTP server implementations intentionally do not use +version numbers in their Server header, so that +installations running older versions of the server don't +end up advertising their vulnerability to specific security +holes.</p> +<p>As with <a class="link" href="SoupSession.html#SoupSession--user-agent" title="The “user-agent” property"><span class="type">“user_agent”</span></a>, if you set a +<a class="link" href="SoupServer.html#SoupServer--server-header" title="The “server-header” property"><span class="type">“server_header”</span></a> property that has trailing whitespace, +<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> will append its own product token (eg, +"<code class="literal">libsoup/2.3.2</code>") to the end of the +header for you.</p> +<p>Flags: Read / Write / Construct</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer--ssl-cert-file"></a><h3>The <code class="literal">“ssl-cert-file”</code> property</h3> +<pre class="programlisting"> “ssl-cert-file” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>Path to a file containing a PEM-encoded certificate. If +this and <a class="link" href="SoupServer.html#SoupServer--ssl-key-file" title="The “ssl-key-file” property"><span class="type">“ssl-key-file”</span></a> are both set, then the +server will speak https rather than plain http.</p> +<p>Alternatively, you can use <a class="link" href="SoupServer.html#SoupServer--tls-certificate" title="The “tls-certificate” property"><span class="type">“tls-certificate”</span></a> +to provide an arbitrary <span class="type">GTlsCertificate</span>.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer--ssl-key-file"></a><h3>The <code class="literal">“ssl-key-file”</code> property</h3> +<pre class="programlisting"> “ssl-key-file” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>Path to a file containing a PEM-encoded private key. If +this and <a class="link" href="SoupServer.html#SoupServer--ssl-key-file" title="The “ssl-key-file” property"><span class="type">“ssl-key-file”</span></a> are both set, then the +server will speak https rather than plain http. Note that +you are allowed to set them to the same value, if you have +a single file containing both the certificate and the key.</p> +<p>Alternatively, you can use <a class="link" href="SoupServer.html#SoupServer--tls-certificate" title="The “tls-certificate” property"><span class="type">“tls-certificate”</span></a> +to provide an arbitrary <span class="type">GTlsCertificate</span>.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer--tls-certificate"></a><h3>The <code class="literal">“tls-certificate”</code> property</h3> +<pre class="programlisting"> “tls-certificate” <span class="type">GTlsCertificate</span> *</pre> +<p>A <span class="type">GTlsCertificate</span> that has a <span class="type">“private-key”</span> +set. If this is set, then the server will speak https +rather than plain http.</p> +<p>Alternatively, you can use <a class="link" href="SoupServer.html#SoupServer--ssl-cert-file" title="The “ssl-cert-file” property"><span class="type">“ssl-cert-file”</span></a> and +<a class="link" href="SoupServer.html#SoupServer--ssl-key-file" title="The “ssl-key-file” property"><span class="type">“ssl-key-file”</span></a> properties, to have <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> +read in a a certificate from a file.</p> +<p>Flags: Read / Write / Construct Only</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupServer.signal-details"></a><h2>Signal Details</h2> +<div class="refsect2"> +<a name="SoupServer-request-aborted"></a><h3>The <code class="literal">“request-aborted”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server, + <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *message, + <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a> *client, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when processing has failed for a message; this +could mean either that it could not be read (if +<a class="link" href="SoupServer.html#SoupServer-request-read" title="The “request-read” signal"><span class="type">“request_read”</span></a> has not been emitted for it yet), +or that the response could not be written back (if +<a class="link" href="SoupServer.html#SoupServer-request-read" title="The “request-read” signal"><span class="type">“request_read”</span></a> has been emitted but +<a class="link" href="SoupServer.html#SoupServer-request-finished" title="The “request-finished” signal"><span class="type">“request_finished”</span></a> has not been).</p> +<p><em class="parameter"><code>message</code></em> + is in an undefined state when this signal is +emitted; the signal exists primarily to allow the server to +free any state that it may have allocated in +<a class="link" href="SoupServer.html#SoupServer-request-started" title="The “request-started” signal"><span class="type">“request_started”</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.19.14.2.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>the server</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>message</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>client</p></td> +<td class="parameter_description"><p>the client context</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer-request-finished"></a><h3>The <code class="literal">“request-finished”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server, + <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *message, + <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a> *client, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when the server has finished writing a response to +a request.</p> +<div class="refsect3"> +<a name="id-1.3.19.14.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>the server</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>message</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>client</p></td> +<td class="parameter_description"><p>the client context</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer-request-read"></a><h3>The <code class="literal">“request-read”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server, + <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *message, + <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a> *client, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when the server has successfully read a request. +<em class="parameter"><code>message</code></em> + will have all of its request-side information +filled in, and if the message was authenticated, <em class="parameter"><code>client</code></em> + +will have information about that. This signal is emitted +before any handlers are called for the message, and if it +sets the message's <span class="type">status_code</span>, then normal handler +processing will be skipped.</p> +<div class="refsect3"> +<a name="id-1.3.19.14.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>the server</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>message</p></td> +<td class="parameter_description"><p>the message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>client</p></td> +<td class="parameter_description"><p>the client context</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupServer-request-started"></a><h3>The <code class="literal">“request-started”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> *server, + <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *message, + <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a> *client, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when the server has started reading a new request. +<em class="parameter"><code>message</code></em> + will be completely blank; not even the +Request-Line will have been read yet. About the only thing +you can usefully do with it is connect to its signals.</p> +<p>If the request is read successfully, this will eventually +be followed by a <a class="link" href="SoupServer.html#SoupServer-request-read" title="The “request-read” signal"><span class="type">“request_read”</span></a> signal. If a +response is then sent, the request processing will end with +a <a class="link" href="SoupServer.html#SoupServer-request-finished" title="The “request-finished” signal"><span class="type">“request_finished”</span></a> signal. If a network error +occurs, the processing will instead end with +<a class="link" href="SoupServer.html#SoupServer-request-aborted" title="The “request-aborted” signal"><span class="type">“request_aborted”</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.19.14.5.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>server</p></td> +<td class="parameter_description"><p>the server</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>message</p></td> +<td class="parameter_description"><p>the new message</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>client</p></td> +<td class="parameter_description"><p>the client context</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +</div> +<div class="refsect1"> +<a name="SoupServer.see-also"></a><h2>See Also</h2> +<p><a class="link" href="SoupAuthDomain.html" title="SoupAuthDomain"><span class="type">SoupAuthDomain</span></a></p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupSession.html b/docs/reference/html/SoupSession.html new file mode 100644 index 00000000..edab9e41 --- /dev/null +++ b/docs/reference/html/SoupSession.html @@ -0,0 +1,2841 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupSession</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupServer.html" title="SoupServer"> +<link rel="next" href="SoupSessionAsync.html" title="SoupSessionAsync"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupSession.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupSession.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupSession.properties" class="shortcut">Properties</a></span><span id="nav_signals"> <span class="dim">|</span> + <a href="#SoupSession.signals" class="shortcut">Signals</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupServer.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupSessionAsync.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupSession"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupSession.top_of_page"></a>SoupSession</span></h2> +<p>SoupSession — Soup session state object</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupSession.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-new" title="soup_session_new ()">soup_session_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-new-with-options" title="soup_session_new_with_options ()">soup_session_new_with_options</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupRequest.html" title="SoupRequest"><span class="returnvalue">SoupRequest</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-request" title="soup_session_request ()">soup_session_request</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupRequest.html" title="SoupRequest"><span class="returnvalue">SoupRequest</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-request-uri" title="soup_session_request_uri ()">soup_session_request_uri</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="returnvalue">SoupRequestHTTP</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-request-http" title="soup_session_request_http ()">soup_session_request_http</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="returnvalue">SoupRequestHTTP</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-request-http-uri" title="soup_session_request_http_uri ()">soup_session_request_http_uri</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupSession.html#SoupSessionCallback" title="SoupSessionCallback ()">*SoupSessionCallback</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()">soup_session_queue_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-requeue-message" title="soup_session_requeue_message ()">soup_session_requeue_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-send-message" title="soup_session_send_message ()">soup_session_send_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-cancel-message" title="soup_session_cancel_message ()">soup_session_cancel_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">GInputStream</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-send" title="soup_session_send ()">soup_session_send</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-send-async" title="soup_session_send_async ()">soup_session_send_async</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">GInputStream</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-send-finish" title="soup_session_send_finish ()">soup_session_send_finish</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-prefetch-dns" title="soup_session_prefetch_dns ()">soup_session_prefetch_dns</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-prepare-for-uri" title="soup_session_prepare_for_uri ()">soup_session_prepare_for_uri</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-abort" title="soup_session_abort ()">soup_session_abort</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-would-redirect" title="soup_session_would_redirect ()">soup_session_would_redirect</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-redirect-message" title="soup_session_redirect_message ()">soup_session_redirect_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-pause-message" title="soup_session_pause_message ()">soup_session_pause_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-unpause-message" title="soup_session_unpause_message ()">soup_session_unpause_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="returnvalue">GMainContext</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-get-async-context" title="soup_session_get_async_context ()">soup_session_get_async_context</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-add-feature" title="soup_session_add_feature ()">soup_session_add_feature</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()">soup_session_add_feature_by_type</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-remove-feature" title="soup_session_remove_feature ()">soup_session_remove_feature</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-remove-feature-by-type" title="soup_session_remove_feature_by_type ()">soup_session_remove_feature_by_type</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-get-features" title="soup_session_get_features ()">soup_session_get_features</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="returnvalue">SoupSessionFeature</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-get-feature" title="soup_session_get_feature ()">soup_session_get_feature</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="returnvalue">SoupSessionFeature</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-get-feature-for-message" title="soup_session_get_feature_for_message ()">soup_session_get_feature_for_message</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSession.html#soup-session-has-feature" title="soup_session_has_feature ()">soup_session_has_feature</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSession.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--accept-language" title="The “accept-language” property">accept-language</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--accept-language-auto" title="The “accept-language-auto” property">accept-language-auto</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a> *</td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--add-feature" title="The “add-feature” property">add-feature</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> *</td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--add-feature-by-type" title="The “add-feature-by-type” property">add-feature-by-type</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--async-context" title="The “async-context” property">async-context</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Boxed-Types.html#GStrv"><span class="type">GStrv</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--http-aliases" title="The “http-aliases” property">http-aliases</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Boxed-Types.html#GStrv"><span class="type">GStrv</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--https-aliases" title="The “https-aliases” property">https-aliases</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--idle-timeout" title="The “idle-timeout” property">idle-timeout</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *</td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--local-address" title="The “local-address” property">local-address</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--max-conns" title="The “max-conns” property">max-conns</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--max-conns-per-host" title="The “max-conns-per-host” property">max-conns-per-host</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<span class="type">GProxyResolver</span> *</td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--proxy-resolver" title="The “proxy-resolver” property">proxy-resolver</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *</td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--proxy-uri" title="The “proxy-uri” property">proxy-uri</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> *</td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--remove-feature-by-type" title="The “remove-feature-by-type” property">remove-feature-by-type</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--ssl-ca-file" title="The “ssl-ca-file” property">ssl-ca-file</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--ssl-strict" title="The “ssl-strict” property">ssl-strict</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--ssl-use-system-ca-file" title="The “ssl-use-system-ca-file” property">ssl-use-system-ca-file</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--timeout" title="The “timeout” property">timeout</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<span class="type">GTlsDatabase</span> *</td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--tls-database" title="The “tls-database” property">tls-database</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--use-ntlm" title="The “use-ntlm” property">use-ntlm</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--use-thread-context" title="The “use-thread-context” property">use-thread-context</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</td> +<td class="property_name"><a class="link" href="SoupSession.html#SoupSession--user-agent" title="The “user-agent” property">user-agent</a></td> +<td class="property_flags">Read / Write</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSession.signals"></a><h2>Signals</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="signals_return"> +<col width="300px" class="signals_name"> +<col width="200px" class="signals_flags"> +</colgroup> +<tbody> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupSession.html#SoupSession-authenticate" title="The “authenticate” signal">authenticate</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupSession.html#SoupSession-connection-created" title="The “connection-created” signal">connection-created</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupSession.html#SoupSession-request-queued" title="The “request-queued” signal">request-queued</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupSession.html#SoupSession-request-started" title="The “request-started” signal">request-started</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupSession.html#SoupSession-request-unqueued" title="The “request-unqueued” signal">request-unqueued</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupSession.html#SoupSession-tunneling" title="The “tunneling” signal">tunneling</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSession.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupSession.html#SoupSession-struct" title="SoupSession">SoupSession</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupSession.html#SoupRequestError" title="enum SoupRequestError">SoupRequestError</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-REQUEST-ERROR:CAPS" title="SOUP_REQUEST_ERROR">SOUP_REQUEST_ERROR</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-PROXY-URI:CAPS" title="SOUP_SESSION_PROXY_URI">SOUP_SESSION_PROXY_URI</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-PROXY-RESOLVER:CAPS" title="SOUP_SESSION_PROXY_RESOLVER">SOUP_SESSION_PROXY_RESOLVER</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-MAX-CONNS:CAPS" title="SOUP_SESSION_MAX_CONNS">SOUP_SESSION_MAX_CONNS</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-MAX-CONNS-PER-HOST:CAPS" title="SOUP_SESSION_MAX_CONNS_PER_HOST">SOUP_SESSION_MAX_CONNS_PER_HOST</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-TLS-DATABASE:CAPS" title="SOUP_SESSION_TLS_DATABASE">SOUP_SESSION_TLS_DATABASE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-SSL-USE-SYSTEM-CA-FILE:CAPS" title="SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE">SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-SSL-CA-FILE:CAPS" title="SOUP_SESSION_SSL_CA_FILE">SOUP_SESSION_SSL_CA_FILE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-SSL-STRICT:CAPS" title="SOUP_SESSION_SSL_STRICT">SOUP_SESSION_SSL_STRICT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-ASYNC-CONTEXT:CAPS" title="SOUP_SESSION_ASYNC_CONTEXT">SOUP_SESSION_ASYNC_CONTEXT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-USE-THREAD-CONTEXT:CAPS" title="SOUP_SESSION_USE_THREAD_CONTEXT">SOUP_SESSION_USE_THREAD_CONTEXT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-TIMEOUT:CAPS" title="SOUP_SESSION_TIMEOUT">SOUP_SESSION_TIMEOUT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-IDLE-TIMEOUT:CAPS" title="SOUP_SESSION_IDLE_TIMEOUT">SOUP_SESSION_IDLE_TIMEOUT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-USER-AGENT:CAPS" title="SOUP_SESSION_USER_AGENT">SOUP_SESSION_USER_AGENT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-ADD-FEATURE:CAPS" title="SOUP_SESSION_ADD_FEATURE">SOUP_SESSION_ADD_FEATURE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS" title="SOUP_SESSION_ADD_FEATURE_BY_TYPE">SOUP_SESSION_ADD_FEATURE_BY_TYPE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-REMOVE-FEATURE-BY-TYPE:CAPS" title="SOUP_SESSION_REMOVE_FEATURE_BY_TYPE">SOUP_SESSION_REMOVE_FEATURE_BY_TYPE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-ACCEPT-LANGUAGE:CAPS" title="SOUP_SESSION_ACCEPT_LANGUAGE">SOUP_SESSION_ACCEPT_LANGUAGE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-ACCEPT-LANGUAGE-AUTO:CAPS" title="SOUP_SESSION_ACCEPT_LANGUAGE_AUTO">SOUP_SESSION_ACCEPT_LANGUAGE_AUTO</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-HTTP-ALIASES:CAPS" title="SOUP_SESSION_HTTP_ALIASES">SOUP_SESSION_HTTP_ALIASES</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-HTTPS-ALIASES:CAPS" title="SOUP_SESSION_HTTPS_ALIASES">SOUP_SESSION_HTTPS_ALIASES</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSession.html#SOUP-SESSION-LOCAL-ADDRESS:CAPS" title="SOUP_SESSION_LOCAL_ADDRESS">SOUP_SESSION_LOCAL_ADDRESS</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSession.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupSession + <span class="lineart">├──</span> <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync">SoupSessionAsync</a> + <span class="lineart">╰──</span> <a class="link" href="SoupSessionSync.html" title="SoupSessionSync">SoupSessionSync</a> +</pre> +</div> +<div class="refsect1"> +<a name="SoupSession.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupSession.description"></a><h2>Description</h2> +<p><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> is the object that controls client-side HTTP. A +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> encapsulates all of the state that libsoup is keeping +on behalf of your program; cached HTTP connections, authentication +information, etc. It also keeps track of various global options +and features that you are using.</p> +<p>Most applications will only need a single <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>; the primary +reason you might need multiple sessions is if you need to have +multiple independent authentication contexts. (Eg, you are +connecting to a server and authenticating as two different users at +different times; the easiest way to ensure that each <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> +is sent with the authentication information you intended is to use +one session for the first user, and a second session for the other +user.)</p> +<p>In the past, <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> was an abstract class, and users needed +to choose between <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> (which always uses +<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainLoop"><span class="type">GMainLoop</span></a>-based I/O), or <a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a> (which always uses +blocking I/O and can be used from multiple threads simultaneously). +This is no longer necessary; you can (and should) use a plain +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, which supports both synchronous and asynchronous use. +(When using a plain <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a> +behaves like it traditionally did on a <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a>, and +<a class="link" href="SoupSession.html#soup-session-send-message" title="soup_session_send_message ()"><code class="function">soup_session_send_message()</code></a> behaves like it traditionally did on a +<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>.)</p> +</div> +<div class="refsect1"> +<a name="SoupSession.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-session-new"></a><h3>soup_session_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +soup_session_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<p>Creates a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> with the default options.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.2.5"></a><h4>Returns</h4> +<p> the new session.</p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-new-with-options"></a><h3>soup_session_new_with_options ()</h3> +<pre class="programlisting"><a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +soup_session_new_with_options (<em class="parameter"><code>const <span class="type">char</span> *optname1</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Creates a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> with the specified options.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>optname1</p></td> +<td class="parameter_description"><p>name of first property to set</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>value of <em class="parameter"><code>optname1</code></em> +, followed by additional property/value pairs</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.3.6"></a><h4>Returns</h4> +<p> the new session.</p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-request"></a><h3>soup_session_request ()</h3> +<pre class="programlisting"><a class="link" href="SoupRequest.html" title="SoupRequest"><span class="returnvalue">SoupRequest</span></a> * +soup_session_request (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *uri_string</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Creates a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> for retrieving <em class="parameter"><code>uri_string</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri_string</p></td> +<td class="parameter_description"><p>a URI, in string form</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>return location for a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.4.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>, or +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-request-uri"></a><h3>soup_session_request_uri ()</h3> +<pre class="programlisting"><a class="link" href="SoupRequest.html" title="SoupRequest"><span class="returnvalue">SoupRequest</span></a> * +soup_session_request_uri (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Creates a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> for retrieving <em class="parameter"><code>uri</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> representing the URI to retrieve</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>return location for a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.5.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>, or +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-request-http"></a><h3>soup_session_request_http ()</h3> +<pre class="programlisting"><a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="returnvalue">SoupRequestHTTP</span></a> * +soup_session_request_http (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *method</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *uri_string</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Creates a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> for retrieving <em class="parameter"><code>uri_string</code></em> +, which must be an +"http" or "https" URI (or another protocol listed in <em class="parameter"><code>session</code></em> +'s +<a class="link" href="SoupSession.html#SoupSession--http-aliases" title="The “http-aliases” property"><span class="type">“http-aliases”</span></a> or <a class="link" href="SoupSession.html#SoupSession--https-aliases" title="The “https-aliases” property"><span class="type">“https-aliases”</span></a>).</p> +<div class="refsect3"> +<a name="id-1.3.20.10.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>method</p></td> +<td class="parameter_description"><p>an HTTP method</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri_string</p></td> +<td class="parameter_description"><p>a URI, in string form</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>return location for a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.6.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a>, or +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-request-http-uri"></a><h3>soup_session_request_http_uri ()</h3> +<pre class="programlisting"><a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="returnvalue">SoupRequestHTTP</span></a> * +soup_session_request_http_uri (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *method</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Creates a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> for retrieving <em class="parameter"><code>uri</code></em> +, which must be an +"http" or "https" URI (or another protocol listed in <em class="parameter"><code>session</code></em> +'s +<a class="link" href="SoupSession.html#SoupSession--http-aliases" title="The “http-aliases” property"><span class="type">“http-aliases”</span></a> or <a class="link" href="SoupSession.html#SoupSession--https-aliases" title="The “https-aliases” property"><span class="type">“https-aliases”</span></a>).</p> +<div class="refsect3"> +<a name="id-1.3.20.10.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>method</p></td> +<td class="parameter_description"><p>an HTTP method</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> representing the URI to retrieve</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>return location for a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.7.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a>, or +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSessionCallback"></a><h3>SoupSessionCallback ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +<span class="c_punctuation">(</span>*SoupSessionCallback<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Prototype for the callback passed to <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a>, +qv.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>the session</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message that has finished</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the data passed to soup_session_queue_message</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-queue-message"></a><h3>soup_session_queue_message ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_queue_message (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a class="link" href="SoupSession.html#SoupSessionCallback" title="SoupSessionCallback ()"><span class="type">SoupSessionCallback</span></a> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Queues the message <em class="parameter"><code>msg</code></em> + for asynchronously sending the request and +receiving a response in the current thread-default <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>. +If <em class="parameter"><code>msg</code></em> + has been processed before, any resources related to the +time it was last sent are freed.</p> +<p>Upon message completion, the callback specified in <em class="parameter"><code>callback</code></em> + will +be invoked. If after returning from this callback the message has not +been requeued, <em class="parameter"><code>msg</code></em> + will be unreffed.</p> +<p>(The behavior above applies to a plain <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>; if you are +using <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> or <a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>, then the <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> +that is used depends on the settings of <a class="link" href="SoupSession.html#SoupSession--async-context" title="The “async-context” property"><span class="type">“async-context”</span></a> +and <a class="link" href="SoupSession.html#SoupSession--use-thread-context" title="The “use-thread-context” property"><span class="type">“use-thread-context”</span></a>, and for <a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>, the +message will actually be sent and processed in another thread, with +only the final callback occurring in the indicated <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>.)</p> +<p>Contrast this method with <a class="link" href="SoupSession.html#soup-session-send-async" title="soup_session_send_async ()"><code class="function">soup_session_send_async()</code></a>, which also +asynchronously sends a message, but returns before reading the +response body, and allows you to read the response via a +<span class="type">GInputStream</span>.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.9.8"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p> the message to queue. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p> a <a class="link" href="SoupSession.html#SoupSessionCallback" title="SoupSessionCallback ()"><span class="type">SoupSessionCallback</span></a> which will +be called after the message completes or when an unrecoverable error occurs. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p> a pointer passed to <em class="parameter"><code>callback</code></em> +. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-requeue-message"></a><h3>soup_session_requeue_message ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_requeue_message (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>This causes <em class="parameter"><code>msg</code></em> + to be placed back on the queue to be attempted +again.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message to requeue</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-send-message"></a><h3>soup_session_send_message ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_session_send_message (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Synchronously send <em class="parameter"><code>msg</code></em> +. This call will not return until the +transfer is finished successfully or there is an unrecoverable +error.</p> +<p>Unlike with <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a>, <em class="parameter"><code>msg</code></em> + is not freed upon +return.</p> +<p>(Note that if you call this method on a <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a>, it will +still use asynchronous I/O internally, running the glib main loop +to process the message, which may also cause other events to be +processed.)</p> +<p>Contrast this method with <a class="link" href="SoupSession.html#soup-session-send" title="soup_session_send ()"><code class="function">soup_session_send()</code></a>, which also +synchronously sends a message, but returns before reading the +response body, and allows you to read the response via a +<span class="type">GInputStream</span>.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.11.8"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message to send</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.11.9"></a><h4>Returns</h4> +<p> the HTTP status code of the response</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-cancel-message"></a><h3>soup_session_cancel_message ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_cancel_message (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> status_code</code></em>);</pre> +<p>Causes <em class="parameter"><code>session</code></em> + to immediately finish processing <em class="parameter"><code>msg</code></em> + (regardless +of its current state) with a final status_code of <em class="parameter"><code>status_code</code></em> +. You +may call this at any time after handing <em class="parameter"><code>msg</code></em> + off to <em class="parameter"><code>session</code></em> +; if +<em class="parameter"><code>session</code></em> + has started sending the request but has not yet received +the complete response, then it will close the request's connection. +Note that with requests that have side effects (eg, +<code class="literal">POST</code>, <code class="literal">PUT</code>, +<code class="literal">DELETE</code>) it is possible that you might cancel the +request after the server acts on it, but before it returns a +response, leaving the remote resource in an unknown state.</p> +<p>If the message is cancelled while its response body is being read, +then the response body in <em class="parameter"><code>msg</code></em> + will be left partially-filled-in. +The response headers, on the other hand, will always be either +empty or complete.</p> +<p>Beware that with the deprecated <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a>, messages queued +with <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a> will have their callbacks invoked +before <a class="link" href="SoupSession.html#soup-session-cancel-message" title="soup_session_cancel_message ()"><code class="function">soup_session_cancel_message()</code></a> returns. The plain +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> does not have this behavior; cancelling an +asynchronous message will merely queue its callback to be run after +returning to the main loop.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.12.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the message to cancel</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>status_code</p></td> +<td class="parameter_description"><p>status code to set on <em class="parameter"><code>msg</code></em> +(generally +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANCELLED:CAPS"><code class="literal">SOUP_STATUS_CANCELLED</code></a>)</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-send"></a><h3>soup_session_send ()</h3> +<pre class="programlisting"><span class="returnvalue">GInputStream</span> * +soup_session_send (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Synchronously sends <em class="parameter"><code>msg</code></em> + and waits for the beginning of a response. +On success, a <span class="type">GInputStream</span> will be returned which you can use to +read the response body. ("Success" here means only that an HTTP +response was received and understood; it does not necessarily mean +that a 2xx class status code was received.)</p> +<p>If non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, <em class="parameter"><code>cancellable</code></em> + can be used to cancel the request; +<a class="link" href="SoupSession.html#soup-session-send" title="soup_session_send ()"><code class="function">soup_session_send()</code></a> will return a <code class="literal">G_IO_ERROR_CANCELLED</code> error. Note +that with requests that have side effects (eg, +<code class="literal">POST</code>, <code class="literal">PUT</code>, +<code class="literal">DELETE</code>) it is possible that you might cancel the +request after the server acts on it, but before it returns a +response, leaving the remote resource in an unknown state.</p> +<p>If <em class="parameter"><code>msg</code></em> + is requeued due to a redirect or authentication, the +initial (3xx/401/407) response body will be suppressed, and +<a class="link" href="SoupSession.html#soup-session-send" title="soup_session_send ()"><code class="function">soup_session_send()</code></a> will only return once a final response has been +received.</p> +<p>Contrast this method with <a class="link" href="SoupSession.html#soup-session-send-message" title="soup_session_send_message ()"><code class="function">soup_session_send_message()</code></a>, which also +synchronously sends a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, but doesn't return until the +response has been completely read.</p> +<p>(Note that this method cannot be called on the deprecated +<a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> subclass.)</p> +<div class="refsect3"> +<a name="id-1.3.20.10.13.9"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>return location for a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.13.10"></a><h4>Returns</h4> +<p> a <span class="type">GInputStream</span> for reading the +response body, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-send-async"></a><h3>soup_session_send_async ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_send_async (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><span class="type">GAsyncReadyCallback</span> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Asynchronously sends <em class="parameter"><code>msg</code></em> + and waits for the beginning of a +response. When <em class="parameter"><code>callback</code></em> + is called, then either <em class="parameter"><code>msg</code></em> + has been sent, +and its response headers received, or else an error has occurred. +Call <a class="link" href="SoupSession.html#soup-session-send-finish" title="soup_session_send_finish ()"><code class="function">soup_session_send_finish()</code></a> to get a <span class="type">GInputStream</span> for reading +the response body.</p> +<p>See <a class="link" href="SoupSession.html#soup-session-send" title="soup_session_send ()"><code class="function">soup_session_send()</code></a> for more details on the general semantics.</p> +<p>Contrast this method with <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a>, which also +asynchronously sends a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, but doesn't invoke its +callback until the response has been completely read.</p> +<p>(Note that this method cannot be called on the deprecated +<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a> subclass, and can only be called on +<a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> if you have set the +<a class="link" href="SoupSession.html#SoupSession--use-thread-context" title="The “use-thread-context” property"><span class="type">“use-thread-context”</span></a> property.)</p> +<div class="refsect3"> +<a name="id-1.3.20.10.14.8"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p>the callback to invoke</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>data for <em class="parameter"><code>callback</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-send-finish"></a><h3>soup_session_send_finish ()</h3> +<pre class="programlisting"><span class="returnvalue">GInputStream</span> * +soup_session_send_finish (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><span class="type">GAsyncResult</span> *result</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Gets the response to a <a class="link" href="SoupSession.html#soup-session-send-async" title="soup_session_send_async ()"><code class="function">soup_session_send_async()</code></a> call and (if +successful), returns a <span class="type">GInputStream</span> that can be used to read the +response body.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.15.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>result</p></td> +<td class="parameter_description"><p>the <span class="type">GAsyncResult</span> passed to your callback</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>return location for a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.15.6"></a><h4>Returns</h4> +<p> a <span class="type">GInputStream</span> for reading the +response body, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-prefetch-dns"></a><h3>soup_session_prefetch_dns ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_prefetch_dns (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *hostname</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><a class="link" href="SoupAddress.html#SoupAddressCallback" title="SoupAddressCallback ()"><span class="type">SoupAddressCallback</span></a> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Tells <em class="parameter"><code>session</code></em> + that an URI from the given <em class="parameter"><code>hostname</code></em> + may be requested +shortly, and so the session can try to prepare by resolving the +domain name in advance, in order to work more quickly once the URI +is actually requested.</p> +<p>If <em class="parameter"><code>cancellable</code></em> + is non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, it can be used to cancel the +resolution. <em class="parameter"><code>callback</code></em> + will still be invoked in this case, with a +status of <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANCELLED:CAPS"><code class="literal">SOUP_STATUS_CANCELLED</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.16.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>hostname</p></td> +<td class="parameter_description"><p>a hostname to be resolved</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p> a <span class="type">GCancellable</span> object, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p> callback to call with the +result, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>data for <em class="parameter"><code>callback</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-prepare-for-uri"></a><h3>soup_session_prepare_for_uri ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_prepare_for_uri (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<div class="warning"> +<p><code class="literal">soup_session_prepare_for_uri</code> has been deprecated since version 2.38 and should not be used in newly-written code.</p> +<p>use <a class="link" href="SoupSession.html#soup-session-prefetch-dns" title="soup_session_prefetch_dns ()"><code class="function">soup_session_prefetch_dns()</code></a> instead</p> +</div> +<p>Tells <em class="parameter"><code>session</code></em> + that <em class="parameter"><code>uri</code></em> + may be requested shortly, and so the +session can try to prepare (resolving the domain name, obtaining +proxy address, etc.) in order to work more quickly once the URI is +actually requested.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.17.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> which may be required</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-abort"></a><h3>soup_session_abort ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_abort (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>);</pre> +<p>Cancels all pending requests in <em class="parameter"><code>session</code></em> + and closes all idle +persistent connections.</p> +<p>The message cancellation has the same semantics as with +<a class="link" href="SoupSession.html#soup-session-cancel-message" title="soup_session_cancel_message ()"><code class="function">soup_session_cancel_message()</code></a>; asynchronous requests on a +<a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> will have their callback called before +<a class="link" href="SoupSession.html#soup-session-abort" title="soup_session_abort ()"><code class="function">soup_session_abort()</code></a> returns. Requests on a plain <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> will +not.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.18.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>the session</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-would-redirect"></a><h3>soup_session_would_redirect ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_session_would_redirect (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Checks if <em class="parameter"><code>msg</code></em> + contains a response that would cause <em class="parameter"><code>session</code></em> + to +redirect it to a new URL (ignoring <em class="parameter"><code>msg</code></em> +'s <a class="link" href="SoupMessage.html#SOUP-MESSAGE-NO-REDIRECT:CAPS"><code class="literal">SOUP_MESSAGE_NO_REDIRECT</code></a> +flag, and the number of times it has already been redirected).</p> +<div class="refsect3"> +<a name="id-1.3.20.10.19.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> that has response headers</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.19.6"></a><h4>Returns</h4> +<p> whether <em class="parameter"><code>msg</code></em> +would be redirected</p> +<p></p> +</div> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-redirect-message"></a><h3>soup_session_redirect_message ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_session_redirect_message (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Updates <em class="parameter"><code>msg</code></em> +'s URI according to its status code and "Location" +header, and requeues it on <em class="parameter"><code>session</code></em> +. Use this when you have set +<a class="link" href="SoupMessage.html#SOUP-MESSAGE-NO-REDIRECT:CAPS"><code class="literal">SOUP_MESSAGE_NO_REDIRECT</code></a> on a message, but have decided to allow a +particular redirection to occur, or if you want to allow a +redirection that <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> will not perform automatically (eg, +redirecting a non-safe method such as DELETE).</p> +<p>If <em class="parameter"><code>msg</code></em> +'s status code indicates that it should be retried as a GET +request, then <em class="parameter"><code>msg</code></em> + will be modified accordingly.</p> +<p>If <em class="parameter"><code>msg</code></em> + has already been redirected too many times, this will +cause it to fail with <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-TOO-MANY-REDIRECTS:CAPS"><code class="literal">SOUP_STATUS_TOO_MANY_REDIRECTS</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.20.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>the session</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> that has received a 3xx response</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.20.8"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if a redirection was applied, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if not +(eg, because there was no Location header, or it could not be +parsed).</p> +<p></p> +</div> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-pause-message"></a><h3>soup_session_pause_message ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_pause_message (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Pauses HTTP I/O on <em class="parameter"><code>msg</code></em> +. Call <a class="link" href="SoupSession.html#soup-session-unpause-message" title="soup_session_unpause_message ()"><code class="function">soup_session_unpause_message()</code></a> to +resume I/O.</p> +<p>This may only be called for asynchronous messages (those sent on a +<a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> or using <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a>).</p> +<div class="refsect3"> +<a name="id-1.3.20.10.21.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> currently running on <em class="parameter"><code>session</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-unpause-message"></a><h3>soup_session_unpause_message ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_unpause_message (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Resumes HTTP I/O on <em class="parameter"><code>msg</code></em> +. Use this to resume after calling +<a class="link" href="SoupSession.html#soup-session-pause-message" title="soup_session_pause_message ()"><code class="function">soup_session_pause_message()</code></a>.</p> +<p>If <em class="parameter"><code>msg</code></em> + is being sent via blocking I/O, this will resume reading or +writing immediately. If <em class="parameter"><code>msg</code></em> + is using non-blocking I/O, then +reading or writing won't resume until you return to the main loop.</p> +<p>This may only be called for asynchronous messages (those sent on a +<a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> or using <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a>).</p> +<div class="refsect3"> +<a name="id-1.3.20.10.22.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> currently running on <em class="parameter"><code>session</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-get-async-context"></a><h3>soup_session_get_async_context ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="returnvalue">GMainContext</span></a> * +soup_session_get_async_context (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>);</pre> +<p>Gets <em class="parameter"><code>session</code></em> +'s <a class="link" href="SoupSession.html#SoupSession--async-context" title="The “async-context” property"><span class="type">“async-context”</span></a>. This does not add a ref +to the context, so you will need to ref it yourself if you want it +to outlive its session.</p> +<p>For a modern <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, this will always just return the +thread-default <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>, and so is not especially useful.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.23.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.23.7"></a><h4>Returns</h4> +<p> <em class="parameter"><code>session</code></em> +'s <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>, which may +be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-add-feature"></a><h3>soup_session_add_feature ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_add_feature (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a> *feature</code></em>);</pre> +<p>Adds <em class="parameter"><code>feature</code></em> +'s functionality to <em class="parameter"><code>session</code></em> +. You can also add a +feature to the session at construct time by using the +<a class="link" href="SoupSession.html#SOUP-SESSION-ADD-FEATURE:CAPS" title="SOUP_SESSION_ADD_FEATURE"><code class="literal">SOUP_SESSION_ADD_FEATURE</code></a> property.</p> +<p>Note that a <a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder"><span class="type">SoupContentDecoder</span></a> is added to the session by default +(unless you are using one of the deprecated session subclasses).</p> +<div class="refsect3"> +<a name="id-1.3.20.10.24.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>feature</p></td> +<td class="parameter_description"><p>an object that implements <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-add-feature-by-type"></a><h3>soup_session_add_feature_by_type ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_add_feature_by_type (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> feature_type</code></em>);</pre> +<p>If <em class="parameter"><code>feature_type</code></em> + is the type of a class that implements +<a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a>, this creates a new feature of that type and +adds it to <em class="parameter"><code>session</code></em> + as with <a class="link" href="SoupSession.html#soup-session-add-feature" title="soup_session_add_feature ()"><code class="function">soup_session_add_feature()</code></a>. You can use +this when you don't need to customize the new feature in any way.</p> +<p>If <em class="parameter"><code>feature_type</code></em> + is not a <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a> type, this gives each +existing feature on <em class="parameter"><code>session</code></em> + the chance to accept <em class="parameter"><code>feature_type</code></em> + as +a "subfeature". This can be used to add new <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> or +<a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> types, for instance.</p> +<p>You can also add a feature to the session at construct time by +using the <a class="link" href="SoupSession.html#SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS" title="SOUP_SESSION_ADD_FEATURE_BY_TYPE"><code class="literal">SOUP_SESSION_ADD_FEATURE_BY_TYPE</code></a> property.</p> +<p>Note that a <a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder"><span class="type">SoupContentDecoder</span></a> is added to the session by default +(unless you are using one of the deprecated session subclasses).</p> +<div class="refsect3"> +<a name="id-1.3.20.10.25.8"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>feature_type</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-remove-feature"></a><h3>soup_session_remove_feature ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_remove_feature (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a> *feature</code></em>);</pre> +<p>Removes <em class="parameter"><code>feature</code></em> +'s functionality from <em class="parameter"><code>session</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.26.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>feature</p></td> +<td class="parameter_description"><p>a feature that has previously been added to <em class="parameter"><code>session</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-remove-feature-by-type"></a><h3>soup_session_remove_feature_by_type ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_session_remove_feature_by_type (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> feature_type</code></em>);</pre> +<p>Removes all features of type <em class="parameter"><code>feature_type</code></em> + (or any subclass of +<em class="parameter"><code>feature_type</code></em> +) from <em class="parameter"><code>session</code></em> +. You can also remove standard features +from the session at construct time by using the +<a class="link" href="SoupSession.html#SOUP-SESSION-REMOVE-FEATURE-BY-TYPE:CAPS" title="SOUP_SESSION_REMOVE_FEATURE_BY_TYPE"><code class="literal">SOUP_SESSION_REMOVE_FEATURE_BY_TYPE</code></a> property.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.27.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>feature_type</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-get-features"></a><h3>soup_session_get_features ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +soup_session_get_features (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> feature_type</code></em>);</pre> +<p>Generates a list of <em class="parameter"><code>session</code></em> +'s features of type <em class="parameter"><code>feature_type</code></em> +. (If +you want to see all features, you can pass <code class="literal">SOUP_TYPE_SESSION_FEATURE</code> +for <em class="parameter"><code>feature_type</code></em> +.)</p> +<div class="refsect3"> +<a name="id-1.3.20.10.28.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>feature_type</p></td> +<td class="parameter_description"><p>the <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> of the class of features to get</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.28.6"></a><h4>Returns</h4> +<p>a list of features. You must free the list, but not its contents. </p> +<p><span class="annotation">[<acronym title="Free data container after the code is done."><span class="acronym">transfer container</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> Soup.SessionFeature]</span></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-get-feature"></a><h3>soup_session_get_feature ()</h3> +<pre class="programlisting"><a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="returnvalue">SoupSessionFeature</span></a> * +soup_session_get_feature (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> feature_type</code></em>);</pre> +<p>Gets the first feature in <em class="parameter"><code>session</code></em> + of type <em class="parameter"><code>feature_type</code></em> +. For +features where there may be more than one feature of a given type, +use <a class="link" href="SoupSession.html#soup-session-get-features" title="soup_session_get_features ()"><code class="function">soup_session_get_features()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.29.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>feature_type</p></td> +<td class="parameter_description"><p>the <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> of the feature to get</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.29.6"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. The +feature is owned by <em class="parameter"><code>session</code></em> +. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-get-feature-for-message"></a><h3>soup_session_get_feature_for_message ()</h3> +<pre class="programlisting"><a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="returnvalue">SoupSessionFeature</span></a> * +soup_session_get_feature_for_message (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> feature_type</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>);</pre> +<p>Gets the first feature in <em class="parameter"><code>session</code></em> + of type <em class="parameter"><code>feature_type</code></em> +, provided +that it is not disabled for <em class="parameter"><code>msg</code></em> +. As with +<a class="link" href="SoupSession.html#soup-session-get-feature" title="soup_session_get_feature ()"><code class="function">soup_session_get_feature()</code></a>, this should only be used for features +where <em class="parameter"><code>feature_type</code></em> + is only expected to match a single feature. In +particular, if there are two matching features, and the first is +disabled on <em class="parameter"><code>msg</code></em> +, and the second is not, then this will return +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, not the second feature.</p> +<div class="refsect3"> +<a name="id-1.3.20.10.30.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>feature_type</p></td> +<td class="parameter_description"><p>the <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> of the feature to get</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.30.6"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. The +feature is owned by <em class="parameter"><code>session</code></em> +. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +<p class="since">Since 2.28</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-has-feature"></a><h3>soup_session_has_feature ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_session_has_feature (<em class="parameter"><code><a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> feature_type</code></em>);</pre> +<p>Tests if <em class="parameter"><code>session</code></em> + has at a feature of type <em class="parameter"><code>feature_type</code></em> + (which can +be the type of either a <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a>, or else a subtype of +some class managed by another feature, such as <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> or +<a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>).</p> +<div class="refsect3"> +<a name="id-1.3.20.10.31.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>feature_type</p></td> +<td class="parameter_description"><p>the <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> of the class of features to check for</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.20.10.31.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a></p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupSession.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupSession-struct"></a><h3>SoupSession</h3> +<pre class="programlisting">typedef struct _SoupSession SoupSession;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupRequestError"></a><h3>enum SoupRequestError</h3> +<p>A <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> error.</p> +<div class="refsect3"> +<a name="id-1.3.20.11.3.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-REQUEST-ERROR-BAD-URI:CAPS"></a>SOUP_REQUEST_ERROR_BAD_URI</p></td> +<td class="enum_member_description"> +<p>the URI could not be parsed</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-REQUEST-ERROR-UNSUPPORTED-URI-SCHEME:CAPS"></a>SOUP_REQUEST_ERROR_UNSUPPORTED_URI_SCHEME</p></td> +<td class="enum_member_description"> +<p>the URI scheme is not + supported by this <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-REQUEST-ERROR-PARSING:CAPS"></a>SOUP_REQUEST_ERROR_PARSING</p></td> +<td class="enum_member_description"> +<p>the server's response could not + be parsed</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-REQUEST-ERROR-ENCODING:CAPS"></a>SOUP_REQUEST_ERROR_ENCODING</p></td> +<td class="enum_member_description"> +<p>the server's response was in an + unsupported format</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-REQUEST-ERROR:CAPS"></a><h3>SOUP_REQUEST_ERROR</h3> +<pre class="programlisting">#define SOUP_REQUEST_ERROR soup_request_error_quark () +</pre> +<p>A <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> domain for <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>-related errors. Used with +<a class="link" href="SoupSession.html#SoupRequestError" title="enum SoupRequestError"><span class="type">SoupRequestError</span></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-PROXY-URI:CAPS"></a><h3>SOUP_SESSION_PROXY_URI</h3> +<pre class="programlisting">#define SOUP_SESSION_PROXY_URI "proxy-uri" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--proxy-uri" title="The “proxy-uri” property"><span class="type">“proxy-uri”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-PROXY-RESOLVER:CAPS"></a><h3>SOUP_SESSION_PROXY_RESOLVER</h3> +<pre class="programlisting">#define SOUP_SESSION_PROXY_RESOLVER "proxy-resolver" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--proxy-resolver" title="The “proxy-resolver” property"><span class="type">“proxy-resolver”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-MAX-CONNS:CAPS"></a><h3>SOUP_SESSION_MAX_CONNS</h3> +<pre class="programlisting">#define SOUP_SESSION_MAX_CONNS "max-conns" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--max-conns" title="The “max-conns” property"><span class="type">“max-conns”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-MAX-CONNS-PER-HOST:CAPS"></a><h3>SOUP_SESSION_MAX_CONNS_PER_HOST</h3> +<pre class="programlisting">#define SOUP_SESSION_MAX_CONNS_PER_HOST "max-conns-per-host" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--max-conns-per-host" title="The “max-conns-per-host” property"><span class="type">“max-conns-per-host”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-TLS-DATABASE:CAPS"></a><h3>SOUP_SESSION_TLS_DATABASE</h3> +<pre class="programlisting">#define SOUP_SESSION_TLS_DATABASE "tls-database" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--tls-database" title="The “tls-database” property"><span class="type">“tls-database”</span></a> property, qv.</p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-SSL-USE-SYSTEM-CA-FILE:CAPS"></a><h3>SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE</h3> +<pre class="programlisting">#define SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE "ssl-use-system-ca-file" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--ssl-use-system-ca-file" title="The “ssl-use-system-ca-file” property"><span class="type">“ssl-use-system-ca-file”</span></a> property, +qv.</p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-SSL-CA-FILE:CAPS"></a><h3>SOUP_SESSION_SSL_CA_FILE</h3> +<pre class="programlisting">#define SOUP_SESSION_SSL_CA_FILE "ssl-ca-file" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--ssl-ca-file" title="The “ssl-ca-file” property"><span class="type">“ssl-ca-file”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-SSL-STRICT:CAPS"></a><h3>SOUP_SESSION_SSL_STRICT</h3> +<pre class="programlisting">#define SOUP_SESSION_SSL_STRICT "ssl-strict" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--ssl-strict" title="The “ssl-strict” property"><span class="type">“ssl-strict”</span></a> property, qv.</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-ASYNC-CONTEXT:CAPS"></a><h3>SOUP_SESSION_ASYNC_CONTEXT</h3> +<pre class="programlisting">#define SOUP_SESSION_ASYNC_CONTEXT "async-context" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--async-context" title="The “async-context” property"><span class="type">“async-context”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-USE-THREAD-CONTEXT:CAPS"></a><h3>SOUP_SESSION_USE_THREAD_CONTEXT</h3> +<pre class="programlisting">#define SOUP_SESSION_USE_THREAD_CONTEXT "use-thread-context" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--use-thread-context" title="The “use-thread-context” property"><span class="type">“use-thread-context”</span></a> property, qv.</p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-TIMEOUT:CAPS"></a><h3>SOUP_SESSION_TIMEOUT</h3> +<pre class="programlisting">#define SOUP_SESSION_TIMEOUT "timeout" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--timeout" title="The “timeout” property"><span class="type">“timeout”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-IDLE-TIMEOUT:CAPS"></a><h3>SOUP_SESSION_IDLE_TIMEOUT</h3> +<pre class="programlisting">#define SOUP_SESSION_IDLE_TIMEOUT "idle-timeout" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--idle-timeout" title="The “idle-timeout” property"><span class="type">“idle-timeout”</span></a> property, qv.</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-USER-AGENT:CAPS"></a><h3>SOUP_SESSION_USER_AGENT</h3> +<pre class="programlisting">#define SOUP_SESSION_USER_AGENT "user-agent" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--user-agent" title="The “user-agent” property"><span class="type">“user-agent”</span></a> property, qv.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-ADD-FEATURE:CAPS"></a><h3>SOUP_SESSION_ADD_FEATURE</h3> +<pre class="programlisting">#define SOUP_SESSION_ADD_FEATURE "add-feature" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--add-feature" title="The “add-feature” property"><span class="type">“add-feature”</span></a> property, qv.</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS"></a><h3>SOUP_SESSION_ADD_FEATURE_BY_TYPE</h3> +<pre class="programlisting">#define SOUP_SESSION_ADD_FEATURE_BY_TYPE "add-feature-by-type" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--add-feature-by-type" title="The “add-feature-by-type” property"><span class="type">“add-feature-by-type”</span></a> property, qv.</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-REMOVE-FEATURE-BY-TYPE:CAPS"></a><h3>SOUP_SESSION_REMOVE_FEATURE_BY_TYPE</h3> +<pre class="programlisting">#define SOUP_SESSION_REMOVE_FEATURE_BY_TYPE "remove-feature-by-type" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--remove-feature-by-type" title="The “remove-feature-by-type” property"><span class="type">“remove-feature-by-type”</span></a> property, +qv.</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-ACCEPT-LANGUAGE:CAPS"></a><h3>SOUP_SESSION_ACCEPT_LANGUAGE</h3> +<pre class="programlisting">#define SOUP_SESSION_ACCEPT_LANGUAGE "accept-language" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--accept-language" title="The “accept-language” property"><span class="type">“accept-language”</span></a> property, qv.</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-ACCEPT-LANGUAGE-AUTO:CAPS"></a><h3>SOUP_SESSION_ACCEPT_LANGUAGE_AUTO</h3> +<pre class="programlisting">#define SOUP_SESSION_ACCEPT_LANGUAGE_AUTO "accept-language-auto" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--accept-language-auto" title="The “accept-language-auto” property"><span class="type">“accept-language-auto”</span></a> property, qv.</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-HTTP-ALIASES:CAPS"></a><h3>SOUP_SESSION_HTTP_ALIASES</h3> +<pre class="programlisting">#define SOUP_SESSION_HTTP_ALIASES "http-aliases" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--http-aliases" title="The “http-aliases” property"><span class="type">“http-aliases”</span></a> property, qv.</p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-HTTPS-ALIASES:CAPS"></a><h3>SOUP_SESSION_HTTPS_ALIASES</h3> +<pre class="programlisting">#define SOUP_SESSION_HTTPS_ALIASES "https-aliases" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--https-aliases" title="The “https-aliases” property"><span class="type">“https-aliases”</span></a> property, qv.</p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SESSION-LOCAL-ADDRESS:CAPS"></a><h3>SOUP_SESSION_LOCAL_ADDRESS</h3> +<pre class="programlisting">#define SOUP_SESSION_LOCAL_ADDRESS "local-address" +</pre> +<p>Alias for the <a class="link" href="SoupSession.html#SoupSession--local-address" title="The “local-address” property"><span class="type">“local-address”</span></a> property, qv.</p> +<p class="since">Since 2.42</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupSession.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupSession--accept-language"></a><h3>The <code class="literal">“accept-language”</code> property</h3> +<pre class="programlisting"> “accept-language” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>If non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, the value to use for the "Accept-Language" header +on <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>s sent from this session.</p> +<p>Setting this will disable +<a class="link" href="SoupSession.html#SoupSession--accept-language-auto" title="The “accept-language-auto” property"><span class="type">“accept-language-auto”</span></a>.</p> +<p>Flags: Read / Write</p> +<p>Default value: NULL</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--accept-language-auto"></a><h3>The <code class="literal">“accept-language-auto”</code> property</h3> +<pre class="programlisting"> “accept-language-auto” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>If <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> will automatically set the string +for the "Accept-Language" header on every <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> +sent, based on the return value of <a href="http://library.gnome.org/devel/glib/unstable/glib-I18N.html#g-get-language-names"><code class="function">g_get_language_names()</code></a>.</p> +<p>Setting this will override any previous value of +<a class="link" href="SoupSession.html#SoupSession--accept-language" title="The “accept-language” property"><span class="type">“accept-language”</span></a>.</p> +<p>Flags: Read / Write</p> +<p>Default value: FALSE</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--add-feature"></a><h3>The <code class="literal">“add-feature”</code> property</h3> +<pre class="programlisting"> “add-feature” <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a> *</pre> +<p>Add a feature object to the session. (Shortcut for calling +<a class="link" href="SoupSession.html#soup-session-add-feature" title="soup_session_add_feature ()"><code class="function">soup_session_add_feature()</code></a>.)</p> +<p>Flags: Read / Write</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--add-feature-by-type"></a><h3>The <code class="literal">“add-feature-by-type”</code> property</h3> +<pre class="programlisting"> “add-feature-by-type” <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> *</pre> +<p>Add a feature object of the given type to the session. +(Shortcut for calling <a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()"><code class="function">soup_session_add_feature_by_type()</code></a>.)</p> +<p>Flags: Read / Write</p> +<p>Allowed values: GObject</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--async-context"></a><h3>The <code class="literal">“async-context”</code> property</h3> +<pre class="programlisting"> “async-context” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>The <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> that miscellaneous session-related +asynchronous callbacks are invoked on. (Eg, setting +<a class="link" href="SoupSession.html#SoupSession--idle-timeout" title="The “idle-timeout” property"><span class="type">“idle-timeout”</span></a> will add a timeout source on this +context.)</p> +<p>For a plain <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, this property is always set to +the <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> that is the thread-default at the time +the session was created, and cannot be overridden. For the +deprecated <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> subclasses, the default value is +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, meaning to use the global default <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>.</p> +<p>If <a class="link" href="SoupSession.html#SoupSession--use-thread-context" title="The “use-thread-context” property"><span class="type">“use-thread-context”</span></a> is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, this context +will also be used for asynchronous HTTP I/O.</p> +<p>Flags: Read / Write / Construct Only</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--http-aliases"></a><h3>The <code class="literal">“http-aliases”</code> property</h3> +<pre class="programlisting"> “http-aliases” <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Boxed-Types.html#GStrv"><span class="type">GStrv</span></a></pre> +<p>A <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>-terminated array of URI schemes that should be +considered to be aliases for "http". Eg, if this included +<code class="literal">"dav"</code>, than a URI of +<code class="literal">dav://example.com/path</code> would be treated +identically to <code class="literal">http://example.com/path</code>.</p> +<p>In a plain <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, the default value is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, +meaning that only "http" is recognized as meaning "http". +In <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> and <a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>, for backward +compatibility, the default value is an array containing the +single element <code class="literal">"*"</code>, a special value +which means that any scheme except "https" is considered to +be an alias for "http".</p> +<p>See also <a class="link" href="SoupSession.html#SoupSession--https-aliases" title="The “https-aliases” property"><span class="type">“https-aliases”</span></a>.</p> +<p>Flags: Read / Write</p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--https-aliases"></a><h3>The <code class="literal">“https-aliases”</code> property</h3> +<pre class="programlisting"> “https-aliases” <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Boxed-Types.html#GStrv"><span class="type">GStrv</span></a></pre> +<p>A comma-delimited list of URI schemes that should be +considered to be aliases for "https". See +<a class="link" href="SoupSession.html#SoupSession--http-aliases" title="The “http-aliases” property"><span class="type">“http-aliases”</span></a> for more information.</p> +<p>The default value is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, meaning that no URI schemes +are considered aliases for "https".</p> +<p>Flags: Read / Write</p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--idle-timeout"></a><h3>The <code class="literal">“idle-timeout”</code> property</h3> +<pre class="programlisting"> “idle-timeout” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a></pre> +<p>Connection lifetime (in seconds) when idle. Any connection +left idle longer than this will be closed.</p> +<p>Although you can change this property at any time, it will +only affect newly-created connections, not currently-open +ones. You can call <a class="link" href="SoupSession.html#soup-session-abort" title="soup_session_abort ()"><code class="function">soup_session_abort()</code></a> after setting this +if you want to ensure that all future connections will have +this timeout value.</p> +<p>Note that the default value of 60 seconds only applies to +plain <a href="SoupSession.html"><span class="type">SoupSessions</span></a>. If you are using <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> or +<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>, the default value is 0 (meaning idle +connections will never time out).</p> +<p>Flags: Read / Write</p> +<p>Default value: 60</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--local-address"></a><h3>The <code class="literal">“local-address”</code> property</h3> +<pre class="programlisting"> “local-address” <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *</pre> +<p>Sets the <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> to use for the client side of +the connection.</p> +<p>Use this property if you want for instance to bind the +local socket to a specific IP address.</p> +<p>Flags: Read / Write / Construct Only</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--max-conns"></a><h3>The <code class="literal">“max-conns”</code> property</h3> +<pre class="programlisting"> “max-conns” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a></pre> +<p>The maximum number of connections that the session can open at once.</p> +<p>Flags: Read / Write</p> +<p>Allowed values: >= 1</p> +<p>Default value: 10</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--max-conns-per-host"></a><h3>The <code class="literal">“max-conns-per-host”</code> property</h3> +<pre class="programlisting"> “max-conns-per-host” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a></pre> +<p>The maximum number of connections that the session can open at once to a given host.</p> +<p>Flags: Read / Write</p> +<p>Allowed values: >= 1</p> +<p>Default value: 2</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--proxy-resolver"></a><h3>The <code class="literal">“proxy-resolver”</code> property</h3> +<pre class="programlisting"> “proxy-resolver” <span class="type">GProxyResolver</span> *</pre> +<p>A <span class="type">GProxyResolver</span> to use with this session. Setting this +will clear the <a class="link" href="SoupSession.html#SoupSession--proxy-uri" title="The “proxy-uri” property"><span class="type">“proxy-uri”</span></a> property, and remove +any <span class="type">SoupProxyURIResolver</span> features that have +been added to the session.</p> +<p>By default, in a plain <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, this is set to the +default <span class="type">GProxyResolver</span>, but you can set it to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if you +don't want to use proxies, or set it to your own +<span class="type">GProxyResolver</span> if you want to control what proxies get +used.</p> +<p>Flags: Read / Write</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--proxy-uri"></a><h3>The <code class="literal">“proxy-uri”</code> property</h3> +<pre class="programlisting"> “proxy-uri” <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *</pre> +<p>A proxy to use for all http and https requests in this +session. Setting this will clear the +<a class="link" href="SoupSession.html#SoupSession--proxy-resolver" title="The “proxy-resolver” property"><span class="type">“proxy-resolver”</span></a> property, and remove any</p> +<span class="type">SoupProxyURIResolver</span> features that have been +<p>added to the session. Setting this property will also +cancel all currently pending messages.</p> +<p>Note that <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> will normally handle looking up the +user's proxy settings for you; you should only use +<a class="link" href="SoupSession.html#SoupSession--proxy-uri" title="The “proxy-uri” property"><span class="type">“proxy-uri”</span></a> if you need to override the user's +normal proxy settings.</p> +<p>Also note that this proxy will be used for +<span class="emphasis"><em>all</em></span> requests; even requests to +<code class="literal">localhost</code>. If you need more control over +proxies, you can create a <span class="type">GSimpleProxyResolver</span> and set the +<a class="link" href="SoupSession.html#SoupSession--proxy-resolver" title="The “proxy-resolver” property"><span class="type">“proxy-resolver”</span></a> property.</p> +<p>Flags: Read / Write</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--remove-feature-by-type"></a><h3>The <code class="literal">“remove-feature-by-type”</code> property</h3> +<pre class="programlisting"> “remove-feature-by-type” <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> *</pre> +<p>Remove feature objects from the session. (Shortcut for +calling <a class="link" href="SoupSession.html#soup-session-remove-feature-by-type" title="soup_session_remove_feature_by_type ()"><code class="function">soup_session_remove_feature_by_type()</code></a>.)</p> +<p>Flags: Read / Write</p> +<p>Allowed values: GObject</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--ssl-ca-file"></a><h3>The <code class="literal">“ssl-ca-file”</code> property</h3> +<pre class="programlisting"> “ssl-ca-file” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>File containing SSL CA certificates.</p> +<p>If the specified file does not exist or cannot be read, +then libsoup will print a warning, and then behave as +though it had read in a empty CA file, meaning that all SSL +certificates will be considered invalid.</p> +<div class="warning"> +<p><code class="literal">SoupSession:ssl-ca-file</code> is deprecated and should not be used in newly-written code.</p> +<p>use <a class="link" href="SoupSession.html#SoupSession--ssl-use-system-ca-file" title="The “ssl-use-system-ca-file” property"><span class="type">“ssl-use-system-ca-file”</span></a>, or +else <a class="link" href="SoupSession.html#SoupSession--tls-database" title="The “tls-database” property"><span class="type">“tls-database”</span></a> with a <span class="type">GTlsFileDatabase</span> +(which allows you to do explicit error handling).</p> +</div> +<p>Flags: Read / Write</p> +<p>Default value: NULL</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--ssl-strict"></a><h3>The <code class="literal">“ssl-strict”</code> property</h3> +<pre class="programlisting"> “ssl-strict” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Normally, if <a class="link" href="SoupSession.html#SoupSession--tls-database" title="The “tls-database” property"><span class="type">“tls-database”</span></a> is set (including if +it was set via <a class="link" href="SoupSession.html#SoupSession--ssl-use-system-ca-file" title="The “ssl-use-system-ca-file” property"><span class="type">“ssl-use-system-ca-file”</span></a> or +<a class="link" href="SoupSession.html#SoupSession--ssl-ca-file" title="The “ssl-ca-file” property"><span class="type">“ssl-ca-file”</span></a>), then libsoup will reject any +certificate that is invalid (ie, expired) or that is not +signed by one of the given CA certificates, and the +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> will fail with the status +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-SSL-FAILED:CAPS"><code class="literal">SOUP_STATUS_SSL_FAILED</code></a>.</p> +<p>If you set <a class="link" href="SoupSession.html#SoupSession--ssl-strict" title="The “ssl-strict” property"><span class="type">“ssl-strict”</span></a> to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, then all +certificates will be accepted, and you will need to call +<a class="link" href="SoupMessage.html#soup-message-get-https-status" title="soup_message_get_https_status ()"><code class="function">soup_message_get_https_status()</code></a> to distinguish valid from +invalid certificates. (This can be used, eg, if you want to +accept invalid certificates after giving some sort of +warning.)</p> +<p>For a plain <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, if the session has no CA file or +TLS database, and this property is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, then all +certificates will be rejected. However, beware that the +deprecated <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> subclasses (<a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> and +<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>) have the opposite behavior: if there is +no CA file or TLS database, then all certificates are always +accepted, and this property has no effect.</p> +<p>Flags: Read / Write</p> +<p>Default value: TRUE</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--ssl-use-system-ca-file"></a><h3>The <code class="literal">“ssl-use-system-ca-file”</code> property</h3> +<pre class="programlisting"> “ssl-use-system-ca-file” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Setting this to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> is equivalent to setting +<a class="link" href="SoupSession.html#SoupSession--tls-database" title="The “tls-database” property"><span class="type">“tls-database”</span></a> to the default system CA database. +(and likewise, setting <a class="link" href="SoupSession.html#SoupSession--tls-database" title="The “tls-database” property"><span class="type">“tls-database”</span></a> to the +default database by hand will cause this property to +become <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>).</p> +<p>Setting this to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> (when it was previously <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>) will +clear the <a class="link" href="SoupSession.html#SoupSession--tls-database" title="The “tls-database” property"><span class="type">“tls-database”</span></a> field.</p> +<p>See <a class="link" href="SoupSession.html#SoupSession--ssl-strict" title="The “ssl-strict” property"><span class="type">“ssl-strict”</span></a> for more information on how +https certificate validation is handled.</p> +<p>Note that the default value of <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> only applies to plain +<a href="SoupSession.html"><span class="type">SoupSessions</span></a>. If you are using <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> or +<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>, the default value is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, for backward +compatibility.</p> +<p>Flags: Read / Write</p> +<p>Default value: TRUE</p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--timeout"></a><h3>The <code class="literal">“timeout”</code> property</h3> +<pre class="programlisting"> “timeout” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a></pre> +<p>The timeout (in seconds) for socket I/O operations +(including connecting to a server, and waiting for a reply +to an HTTP request).</p> +<p>Although you can change this property at any time, it will +only affect newly-created connections, not currently-open +ones. You can call <a class="link" href="SoupSession.html#soup-session-abort" title="soup_session_abort ()"><code class="function">soup_session_abort()</code></a> after setting this +if you want to ensure that all future connections will have +this timeout value.</p> +<p>Note that the default value of 60 seconds only applies to +plain <a href="SoupSession.html"><span class="type">SoupSessions</span></a>. If you are using <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> or +<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>, the default value is 0 (meaning socket I/O +will not time out).</p> +<p>Not to be confused with <a class="link" href="SoupSession.html#SoupSession--idle-timeout" title="The “idle-timeout” property"><span class="type">“idle-timeout”</span></a> (which is +the length of time that idle persistent connections will be +kept open).</p> +<p>Flags: Read / Write</p> +<p>Default value: 0</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--tls-database"></a><h3>The <code class="literal">“tls-database”</code> property</h3> +<pre class="programlisting"> “tls-database” <span class="type">GTlsDatabase</span> *</pre> +<p>Sets the <span class="type">GTlsDatabase</span> to use for validating SSL/TLS +certificates.</p> +<p>Note that setting the <a class="link" href="SoupSession.html#SoupSession--ssl-ca-file" title="The “ssl-ca-file” property"><span class="type">“ssl-ca-file”</span></a> or +<a class="link" href="SoupSession.html#SoupSession--ssl-use-system-ca-file" title="The “ssl-use-system-ca-file” property"><span class="type">“ssl-use-system-ca-file”</span></a> property will cause +this property to be set to a <span class="type">GTlsDatabase</span> corresponding to +the indicated file or system default.</p> +<p>See <a class="link" href="SoupSession.html#SoupSession--ssl-strict" title="The “ssl-strict” property"><span class="type">“ssl-strict”</span></a> for more information on how +https certificate validation is handled.</p> +<p>If you are using a plain <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> then +<a class="link" href="SoupSession.html#SoupSession--ssl-use-system-ca-file" title="The “ssl-use-system-ca-file” property"><span class="type">“ssl-use-system-ca-file”</span></a> will be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> by +default, and so this property will be a copy of the system +CA database. If you are using <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> or +<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>, this property will be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> by default.</p> +<p>Flags: Read / Write</p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--use-ntlm"></a><h3>The <code class="literal">“use-ntlm”</code> property</h3> +<pre class="programlisting"> “use-ntlm” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Whether or not to use NTLM authentication.</p> +<div class="warning"> +<p><code class="literal">SoupSession:use-ntlm</code> is deprecated and should not be used in newly-written code.</p> +<p>use <a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()"><code class="function">soup_session_add_feature_by_type()</code></a> with +<a class="link" href="SoupAuth.html#SOUP-TYPE-AUTH-NTLM:CAPS" title="SOUP_TYPE_AUTH_NTLM"><span class="type">SOUP_TYPE_AUTH_NTLM</span></a>.</p> +</div> +<p>Flags: Read / Write</p> +<p>Default value: FALSE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--use-thread-context"></a><h3>The <code class="literal">“use-thread-context”</code> property</h3> +<pre class="programlisting"> “use-thread-context” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>If <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> (which it always is on a plain <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>), +asynchronous HTTP requests in this session will run in +whatever the thread-default <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> is at the time +they are started, rather than always occurring in +<a class="link" href="SoupSession.html#SoupSession--async-context" title="The “async-context” property"><span class="type">“async-context”</span></a>.</p> +<p>Flags: Read / Write</p> +<p>Default value: FALSE</p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession--user-agent"></a><h3>The <code class="literal">“user-agent”</code> property</h3> +<pre class="programlisting"> “user-agent” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *</pre> +<p>If non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, the value to use for the "User-Agent" header +on <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>s sent from this session.</p> +<p>RFC 2616 says: "The User-Agent request-header field +contains information about the user agent originating the +request. This is for statistical purposes, the tracing of +protocol violations, and automated recognition of user +agents for the sake of tailoring responses to avoid +particular user agent limitations. User agents SHOULD +include this field with requests."</p> +<p>The User-Agent header contains a list of one or more +product tokens, separated by whitespace, with the most +significant product token coming first. The tokens must be +brief, ASCII, and mostly alphanumeric (although "-", "_", +and "." are also allowed), and may optionally include a "/" +followed by a version string. You may also put comments, +enclosed in parentheses, between or after the tokens.</p> +<p>If you set a <a class="link" href="SoupSession.html#SoupSession--user-agent" title="The “user-agent” property"><span class="type">“user_agent”</span></a> property that has trailing +whitespace, <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> will append its own product token +(eg, "<code class="literal">libsoup/2.3.2</code>") to the end of the +header for you.</p> +<p>Flags: Read / Write</p> +<p>Default value: NULL</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupSession.signal-details"></a><h2>Signal Details</h2> +<div class="refsect2"> +<a name="SoupSession-authenticate"></a><h3>The <code class="literal">“authenticate”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session, + <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> *auth, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> retrying, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when the session requires authentication. If +credentials are available call <a class="link" href="SoupAuth.html#soup-auth-authenticate" title="soup_auth_authenticate ()"><code class="function">soup_auth_authenticate()</code></a> on +<em class="parameter"><code>auth</code></em> +. If these credentials fail, the signal will be +emitted again, with <em class="parameter"><code>retrying</code></em> + set to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, which will +continue until you return without calling +<a class="link" href="SoupAuth.html#soup-auth-authenticate" title="soup_auth_authenticate ()"><code class="function">soup_auth_authenticate()</code></a> on <em class="parameter"><code>auth</code></em> +.</p> +<p>Note that this may be emitted before <em class="parameter"><code>msg</code></em> +'s body has been +fully read.</p> +<p>If you call <a class="link" href="SoupSession.html#soup-session-pause-message" title="soup_session_pause_message ()"><code class="function">soup_session_pause_message()</code></a> on <em class="parameter"><code>msg</code></em> + before +returning, then you can authenticate <em class="parameter"><code>auth</code></em> + asynchronously +(as long as you <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-ref"><code class="function">g_object_ref()</code></a> it to make sure it doesn't +get destroyed), and then unpause <em class="parameter"><code>msg</code></em> + when you are ready +for it to continue.</p> +<div class="refsect3"> +<a name="id-1.3.20.13.2.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>the session</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> being sent</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>auth</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> to authenticate</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>retrying</p></td> +<td class="parameter_description"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if this is the second (or later) attempt</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession-connection-created"></a><h3>The <code class="literal">“connection-created”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session, + <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> *connection, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when a new connection is created. This is an +internal signal intended only to be used for debugging +purposes, and may go away in the future.</p> +<div class="refsect3"> +<a name="id-1.3.20.13.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>connection</p></td> +<td class="parameter_description"><p>the connection</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession-request-queued"></a><h3>The <code class="literal">“request-queued”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session, + <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when a request is queued on <em class="parameter"><code>session</code></em> +. (Note that +"queued" doesn't just mean <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a>; +<a class="link" href="SoupSession.html#soup-session-send-message" title="soup_session_send_message ()"><code class="function">soup_session_send_message()</code></a> implicitly queues the message +as well.)</p> +<p>When sending a request, first <a class="link" href="SoupSession.html#SoupSession-request-queued" title="The “request-queued” signal"><span class="type">“request_queued”</span></a> +is emitted, indicating that the session has become aware of +the request.</p> +<p>Once a connection is available to send the request on, the +session emits <a class="link" href="SoupSession.html#SoupSession-request-started" title="The “request-started” signal"><span class="type">“request_started”</span></a>. Then, various +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> signals are emitted as the message is +processed. If the message is requeued, it will emit +<a class="link" href="SoupMessage.html#SoupMessage-restarted" title="The “restarted” signal"><span class="type">“restarted”</span></a>, which will then be followed by +another <a class="link" href="SoupSession.html#SoupSession-request-started" title="The “request-started” signal"><span class="type">“request_started”</span></a> and another set of +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> signals when the message is re-sent.</p> +<p>Eventually, the message will emit <a class="link" href="SoupMessage.html#SoupMessage-finished" title="The “finished” signal"><span class="type">“finished”</span></a>. +Normally, this signals the completion of message +processing. However, it is possible that the application +will requeue the message from the "finished" handler (or +equivalently, from the <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a> +callback). In that case, the process will loop back to +<a class="link" href="SoupSession.html#SoupSession-request-started" title="The “request-started” signal"><span class="type">“request_started”</span></a>.</p> +<p>Eventually, a message will reach "finished" and not be +requeued. At that point, the session will emit +<a class="link" href="SoupSession.html#SoupSession-request-unqueued" title="The “request-unqueued” signal"><span class="type">“request_unqueued”</span></a> to indicate that it is done +with the message.</p> +<p>To sum up: <a class="link" href="SoupSession.html#SoupSession-request-queued" title="The “request-queued” signal"><span class="type">“request_queued”</span></a> and +<a class="link" href="SoupSession.html#SoupSession-request-unqueued" title="The “request-unqueued” signal"><span class="type">“request_unqueued”</span></a> are guaranteed to be emitted +exactly once, but <a class="link" href="SoupSession.html#SoupSession-request-started" title="The “request-started” signal"><span class="type">“request_started”</span></a> and +<a class="link" href="SoupMessage.html#SoupMessage-finished" title="The “finished” signal"><span class="type">“finished”</span></a> (and all of the other <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> +signals) may be invoked multiple times for a given message.</p> +<div class="refsect3"> +<a name="id-1.3.20.13.4.10"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>the session</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the request that was queued</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession-request-started"></a><h3>The <code class="literal">“request-started”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session, + <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *socket, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted just before a request is sent. See +<a class="link" href="SoupSession.html#SoupSession-request-queued" title="The “request-queued” signal"><span class="type">“request_queued”</span></a> for a detailed description of +the message lifecycle within a session.</p> +<div class="refsect3"> +<a name="id-1.3.20.13.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>the session</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the request being sent</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>socket</p></td> +<td class="parameter_description"><p>the socket the request is being sent on</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession-request-unqueued"></a><h3>The <code class="literal">“request-unqueued”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session, + <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when a request is removed from <em class="parameter"><code>session</code></em> +'s queue, +indicating that <em class="parameter"><code>session</code></em> + is done with it. See +<a class="link" href="SoupSession.html#SoupSession-request-queued" title="The “request-queued” signal"><span class="type">“request_queued”</span></a> for a detailed description of the +message lifecycle within a session.</p> +<div class="refsect3"> +<a name="id-1.3.20.13.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>the session</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>the request that was unqueued</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSession-tunneling"></a><h3>The <code class="literal">“tunneling”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> *session, + <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> *connection, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when an SSL tunnel is being created on a proxy +connection. This is an internal signal intended only to be +used for debugging purposes, and may go away in the future.</p> +<div class="refsect3"> +<a name="id-1.3.20.13.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>session</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>connection</p></td> +<td class="parameter_description"><p>the connection</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +<p class="since">Since 2.30</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupSessionAsync.html b/docs/reference/html/SoupSessionAsync.html new file mode 100644 index 00000000..99897028 --- /dev/null +++ b/docs/reference/html/SoupSessionAsync.html @@ -0,0 +1,171 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupSessionAsync</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupSession.html" title="SoupSession"> +<link rel="next" href="SoupSessionSync.html" title="SoupSessionSync"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupSessionAsync.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupSessionAsync.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupSession.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupSessionSync.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupSessionAsync"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupSessionAsync.top_of_page"></a>SoupSessionAsync</span></h2> +<p>SoupSessionAsync — (Deprecated) SoupSession for asynchronous + (main-loop-based) I/O.</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupSessionAsync.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSessionAsync.html#soup-session-async-new" title="soup_session_async_new ()">soup_session_async_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSessionAsync.html#soup-session-async-new-with-options" title="soup_session_async_new_with_options ()">soup_session_async_new_with_options</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSessionAsync.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupSessionAsync.html#SoupSessionAsync-struct" title="SoupSessionAsync">SoupSessionAsync</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSessionAsync.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> <a class="link" href="SoupSession.html" title="SoupSession">SoupSession</a> + <span class="lineart">╰──</span> SoupSessionAsync +</pre> +</div> +<div class="refsect1"> +<a name="SoupSessionAsync.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupSessionAsync.description"></a><h2>Description</h2> +<p><a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> is an implementation of <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> that uses +non-blocking I/O via the glib main loop for all I/O.</p> +<p>As of libsoup 2.42, this is deprecated in favor of the plain +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> class (which uses both asynchronous and synchronous +I/O, depending on the API used). See the <a class="link" href="libsoup-session-porting.html" title="Porting to the new SoupSession">porting guide</a>.</p> +</div> +<div class="refsect1"> +<a name="SoupSessionAsync.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-session-async-new"></a><h3>soup_session_async_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +soup_session_async_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<div class="warning"> +<p><code class="literal">soup_session_async_new</code> is deprecated and should not be used in newly-written code.</p> +<p><a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> is deprecated; use a plain +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, created with <a class="link" href="SoupSession.html#soup-session-new" title="soup_session_new ()"><code class="function">soup_session_new()</code></a>. See the <a class="link" href="libsoup-session-porting.html" title="Porting to the new SoupSession">porting guide</a>.</p> +</div> +<p>Creates an asynchronous <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> with the default options.</p> +<div class="refsect3"> +<a name="id-1.3.21.8.2.6"></a><h4>Returns</h4> +<p> the new session.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-async-new-with-options"></a><h3>soup_session_async_new_with_options ()</h3> +<pre class="programlisting"><a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +soup_session_async_new_with_options (<em class="parameter"><code>const <span class="type">char</span> *optname1</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<div class="warning"> +<p><code class="literal">soup_session_async_new_with_options</code> is deprecated and should not be used in newly-written code.</p> +<p><a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> is deprecated; use a plain +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, created with <a class="link" href="SoupSession.html#soup-session-new-with-options" title="soup_session_new_with_options ()"><code class="function">soup_session_new_with_options()</code></a>. See the</p> +<a class="link" href="libsoup-session-porting.html" title="Porting to the new SoupSession">porting guide</a>. +</div> +<p>Creates an asynchronous <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> with the specified options.</p> +<div class="refsect3"> +<a name="id-1.3.21.8.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>optname1</p></td> +<td class="parameter_description"><p>name of first property to set</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>value of <em class="parameter"><code>optname1</code></em> +, followed by additional property/value pairs</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.21.8.3.7"></a><h4>Returns</h4> +<p> the new session.</p> +<p></p> +</div> +</div> +</div> +<div class="refsect1"> +<a name="SoupSessionAsync.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupSessionAsync-struct"></a><h3>SoupSessionAsync</h3> +<pre class="programlisting">typedef struct _SoupSessionAsync SoupSessionAsync;</pre> +<p> +</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupSessionFeature.html b/docs/reference/html/SoupSessionFeature.html new file mode 100644 index 00000000..69154513 --- /dev/null +++ b/docs/reference/html/SoupSessionFeature.html @@ -0,0 +1,197 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupSessionFeature</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch03.html" title="Additional Features"> +<link rel="prev" href="ch03.html" title="Additional Features"> +<link rel="next" href="SoupAuthManager.html" title="SoupAuthManager"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupSessionFeature.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupSessionFeature.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_prerequisites"> <span class="dim">|</span> + <a href="#SoupSessionFeature.prerequisites" class="shortcut">Prerequisites</a></span><span id="nav_implementations"> <span class="dim">|</span> + <a href="#SoupSessionFeature.implementations" class="shortcut">Known Implementations</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="ch03.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupAuthManager.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupSessionFeature"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupSessionFeature.top_of_page"></a>SoupSessionFeature</span></h2> +<p>SoupSessionFeature — Interface for miscellaneous session features</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupSessionFeature.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupSessionFeature.html#SoupSessionFeature-struct" title="SoupSessionFeature">SoupSessionFeature</a></td> +</tr> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupSessionFeature.html#SoupSessionFeatureInterface" title="SoupSessionFeatureInterface">SoupSessionFeatureInterface</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSessionFeature.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> GInterface + <span class="lineart">╰──</span> SoupSessionFeature +</pre> +</div> +<div class="refsect1"> +<a name="SoupSessionFeature.prerequisites"></a><h2>Prerequisites</h2> +<p> +SoupSessionFeature requires + <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>.</p> +</div> +<div class="refsect1"> +<a name="SoupSessionFeature.implementations"></a><h2>Known Implementations</h2> +<p> +SoupSessionFeature is implemented by + <a class="link" href="SoupAuthManager.html" title="SoupAuthManager">SoupAuthManager</a>, <a class="link" href="SoupCache.html" title="SoupCache">SoupCache</a>, <a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder">SoupContentDecoder</a>, <a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer">SoupContentSniffer</a>, <a class="link" href="SoupCookieJar.html" title="SoupCookieJar">SoupCookieJar</a>, <a class="link" href="SoupCookieJarDB.html" title="SoupCookieJarDB">SoupCookieJarDB</a>, <a class="link" href="SoupCookieJarText.html" title="SoupCookieJarText">SoupCookieJarText</a>, <a class="link" href="SoupLogger.html" title="SoupLogger">SoupLogger</a> and <a class="link" href="SoupProxyResolverDefault.html" title="SoupProxyResolverDefault">SoupProxyResolverDefault</a>.</p> +</div> +<div class="refsect1"> +<a name="SoupSessionFeature.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupSessionFeature.description"></a><h2>Description</h2> +<p><a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a> is the interface used by classes that extend +the functionality of a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>. Some features like HTTP +authentication handling are implemented internally via +<a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a>s. Other features can be added to the session +by the application. (Eg, <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a>, <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a>.)</p> +<p>See <a class="link" href="SoupSession.html#soup-session-add-feature" title="soup_session_add_feature ()"><code class="function">soup_session_add_feature()</code></a>, etc, to add a feature to a session.</p> +</div> +<div class="refsect1"> +<a name="SoupSessionFeature.functions_details"></a><h2>Functions</h2> +</div> +<div class="refsect1"> +<a name="SoupSessionFeature.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupSessionFeature-struct"></a><h3>SoupSessionFeature</h3> +<pre class="programlisting">typedef struct _SoupSessionFeature SoupSessionFeature;</pre> +<p>An object that implement some sort of optional feature for +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>.</p> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSessionFeatureInterface"></a><h3>SoupSessionFeatureInterface</h3> +<pre class="programlisting">typedef struct { + GTypeInterface parent; + + /* methods */ + void (*attach) (SoupSessionFeature *feature, + SoupSession *session); + void (*detach) (SoupSessionFeature *feature, + SoupSession *session); + + void (*request_queued) (SoupSessionFeature *feature, + SoupSession *session, + SoupMessage *msg); + void (*request_started) (SoupSessionFeature *feature, + SoupSession *session, + SoupMessage *msg, + SoupSocket *socket); + void (*request_unqueued) (SoupSessionFeature *feature, + SoupSession *session, + SoupMessage *msg); + + gboolean (*add_feature) (SoupSessionFeature *feature, + GType type); + gboolean (*remove_feature) (SoupSessionFeature *feature, + GType type); + gboolean (*has_feature) (SoupSessionFeature *feature, + GType type); +} SoupSessionFeatureInterface; +</pre> +<p>The interface implemented by <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a>s.</p> +<div class="refsect3"> +<a name="id-1.4.2.10.3.5"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="struct_members_name"> +<col class="struct_members_description"> +<col width="200px" class="struct_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="struct_member_name"><p><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GTypeInterface"><span class="type">GTypeInterface</span></a> <em class="structfield"><code><a name="SoupSessionFeatureInterface.parent"></a>parent</code></em>;</p></td> +<td class="struct_member_description"><p>The parent interface.</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><em class="structfield"><code><a name="SoupSessionFeatureInterface.attach"></a>attach</code></em> ()</p></td> +<td class="struct_member_description"><p>Perform setup when a feature is added to a session</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><em class="structfield"><code><a name="SoupSessionFeatureInterface.detach"></a>detach</code></em> ()</p></td> +<td class="struct_member_description"><p>Perform cleanup when a feature is removed from a session</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><em class="structfield"><code><a name="SoupSessionFeatureInterface.request-queued"></a>request_queued</code></em> ()</p></td> +<td class="struct_member_description"><p>Proxies the session's <a class="link" href="SoupSession.html#SoupSession-request-queued" title="The “request-queued” signal"><span class="type">“request_queued”</span></a> signal</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><em class="structfield"><code><a name="SoupSessionFeatureInterface.request-started"></a>request_started</code></em> ()</p></td> +<td class="struct_member_description"><p>Proxies the session's <a class="link" href="SoupSession.html#SoupSession-request-started" title="The “request-started” signal"><span class="type">“request_started”</span></a> signal</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><em class="structfield"><code><a name="SoupSessionFeatureInterface.request-unqueued"></a>request_unqueued</code></em> ()</p></td> +<td class="struct_member_description"><p>Proxies the session's <a class="link" href="SoupSession.html#SoupSession-request-unqueued" title="The “request-unqueued” signal"><span class="type">“request_unqueued”</span></a> signal</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><em class="structfield"><code><a name="SoupSessionFeatureInterface.add-feature"></a>add_feature</code></em> ()</p></td> +<td class="struct_member_description"><p>adds a sub-feature to the main feature</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><em class="structfield"><code><a name="SoupSessionFeatureInterface.remove-feature"></a>remove_feature</code></em> ()</p></td> +<td class="struct_member_description"><p>removes a sub-feature from the main feature</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><em class="structfield"><code><a name="SoupSessionFeatureInterface.has-feature"></a>has_feature</code></em> ()</p></td> +<td class="struct_member_description"><p>tests if the feature includes a sub-feature</p></td> +<td class="struct_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupSessionSync.html b/docs/reference/html/SoupSessionSync.html new file mode 100644 index 00000000..aa035bb4 --- /dev/null +++ b/docs/reference/html/SoupSessionSync.html @@ -0,0 +1,171 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupSessionSync</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupSessionAsync.html" title="SoupSessionAsync"> +<link rel="next" href="libsoup-2.4-soup-status.html" title="soup-status"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupSessionSync.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupSessionSync.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupSessionAsync.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-2.4-soup-status.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupSessionSync"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupSessionSync.top_of_page"></a>SoupSessionSync</span></h2> +<p>SoupSessionSync — (Deprecated) SoupSession for blocking I/O in + multithreaded programs.</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupSessionSync.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSessionSync.html#soup-session-sync-new" title="soup_session_sync_new ()">soup_session_sync_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSessionSync.html#soup-session-sync-new-with-options" title="soup_session_sync_new_with_options ()">soup_session_sync_new_with_options</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSessionSync.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody><tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupSessionSync.html#SoupSessionSync-struct" title="SoupSessionSync">SoupSessionSync</a></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSessionSync.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> <a class="link" href="SoupSession.html" title="SoupSession">SoupSession</a> + <span class="lineart">╰──</span> SoupSessionSync +</pre> +</div> +<div class="refsect1"> +<a name="SoupSessionSync.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupSessionSync.description"></a><h2>Description</h2> +<p><a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a> is an implementation of <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> that uses +synchronous I/O, intended for use in multi-threaded programs.</p> +<p>As of libsoup 2.42, this is deprecated in favor of the plain +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> class (which uses both asynchronous and synchronous +I/O, depending on the API used). See the <a class="link" href="libsoup-session-porting.html" title="Porting to the new SoupSession">porting guide</a>.</p> +</div> +<div class="refsect1"> +<a name="SoupSessionSync.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-session-sync-new"></a><h3>soup_session_sync_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +soup_session_sync_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<div class="warning"> +<p><code class="literal">soup_session_sync_new</code> is deprecated and should not be used in newly-written code.</p> +<p><a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a> is deprecated; use a plain +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, created with <a class="link" href="SoupSession.html#soup-session-new" title="soup_session_new ()"><code class="function">soup_session_new()</code></a>. See the <a class="link" href="libsoup-session-porting.html" title="Porting to the new SoupSession">porting guide</a>.</p> +</div> +<p>Creates an synchronous <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> with the default options.</p> +<div class="refsect3"> +<a name="id-1.3.22.8.2.6"></a><h4>Returns</h4> +<p> the new session.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-session-sync-new-with-options"></a><h3>soup_session_sync_new_with_options ()</h3> +<pre class="programlisting"><a class="link" href="SoupSession.html" title="SoupSession"><span class="returnvalue">SoupSession</span></a> * +soup_session_sync_new_with_options (<em class="parameter"><code>const <span class="type">char</span> *optname1</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<div class="warning"> +<p><code class="literal">soup_session_sync_new_with_options</code> is deprecated and should not be used in newly-written code.</p> +<p><a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a> is deprecated; use a plain +<a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>, created with <a class="link" href="SoupSession.html#soup-session-new-with-options" title="soup_session_new_with_options ()"><code class="function">soup_session_new_with_options()</code></a>. See the</p> +<a class="link" href="libsoup-session-porting.html" title="Porting to the new SoupSession">porting guide</a>. +</div> +<p>Creates an synchronous <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> with the specified options.</p> +<div class="refsect3"> +<a name="id-1.3.22.8.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>optname1</p></td> +<td class="parameter_description"><p>name of first property to set</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>value of <em class="parameter"><code>optname1</code></em> +, followed by additional property/value pairs</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.22.8.3.7"></a><h4>Returns</h4> +<p> the new session.</p> +<p></p> +</div> +</div> +</div> +<div class="refsect1"> +<a name="SoupSessionSync.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupSessionSync-struct"></a><h3>SoupSessionSync</h3> +<pre class="programlisting">typedef struct _SoupSessionSync SoupSessionSync;</pre> +<p> +</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupSocket.html b/docs/reference/html/SoupSocket.html new file mode 100644 index 00000000..6037e3cd --- /dev/null +++ b/docs/reference/html/SoupSocket.html @@ -0,0 +1,1585 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupSocket</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch05.html" title="Low-level Networking API"> +<link rel="prev" href="SoupAddress.html" title="SoupAddress"> +<link rel="next" href="ix01.html" title="Index"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupSocket.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupSocket.object-hierarchy" class="shortcut">Object Hierarchy</a></span><span id="nav_properties"> <span class="dim">|</span> + <a href="#SoupSocket.properties" class="shortcut">Properties</a></span><span id="nav_signals"> <span class="dim">|</span> + <a href="#SoupSocket.signals" class="shortcut">Signals</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch05.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupAddress.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="ix01.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupSocket"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupSocket.top_of_page"></a>SoupSocket</span></h2> +<p>SoupSocket — A network socket</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupSocket.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupSocket.html" title="SoupSocket"><span class="returnvalue">SoupSocket</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-new" title="soup_socket_new ()">soup_socket_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<span class="c_punctuation">(</span><a class="link" href="SoupSocket.html#SoupSocketCallback" title="SoupSocketCallback ()">*SoupSocketCallback</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-connect-async" title="soup_socket_connect_async ()">soup_socket_connect_async</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-connect-sync" title="soup_socket_connect_sync ()">soup_socket_connect_sync</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-listen" title="soup_socket_listen ()">soup_socket_listen</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-start-ssl" title="soup_socket_start_ssl ()">soup_socket_start_ssl</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-start-proxy-ssl" title="soup_socket_start_proxy_ssl ()">soup_socket_start_proxy_ssl</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-is-ssl" title="soup_socket_is_ssl ()">soup_socket_is_ssl</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-disconnect" title="soup_socket_disconnect ()">soup_socket_disconnect</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-is-connected" title="soup_socket_is_connected ()">soup_socket_is_connected</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-get-local-address" title="soup_socket_get_local_address ()">soup_socket_get_local_address</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-get-remote-address" title="soup_socket_get_remote_address ()">soup_socket_get_remote_address</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">int</span> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-get-fd" title="soup_socket_get_fd ()">soup_socket_get_fd</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupSocket.html#SoupSocketIOStatus" title="enum SoupSocketIOStatus"><span class="returnvalue">SoupSocketIOStatus</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-read" title="soup_socket_read ()">soup_socket_read</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupSocket.html#SoupSocketIOStatus" title="enum SoupSocketIOStatus"><span class="returnvalue">SoupSocketIOStatus</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-read-until" title="soup_socket_read_until ()">soup_socket_read_until</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupSocket.html#SoupSocketIOStatus" title="enum SoupSocketIOStatus"><span class="returnvalue">SoupSocketIOStatus</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupSocket.html#soup-socket-write" title="soup_socket_write ()">soup_socket_write</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSocket.properties"></a><h2>Properties</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="properties_type"> +<col width="300px" class="properties_name"> +<col width="200px" class="properties_flags"> +</colgroup> +<tbody> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--async-context" title="The “async-context” property">async-context</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--clean-dispose" title="The “clean-dispose” property">clean-dispose</a></td> +<td class="property_flags">Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--is-server" title="The “is-server” property">is-server</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *</td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--local-address" title="The “local-address” property">local-address</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--non-blocking" title="The “non-blocking” property">non-blocking</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<span class="type">GProxyResolver</span> *</td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--proxy-resolver" title="The “proxy-resolver” property">proxy-resolver</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"> +<a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *</td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--remote-address" title="The “remote-address” property">remote-address</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--ssl-creds" title="The “ssl-creds” property">ssl-creds</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--ssl-fallback" title="The “ssl-fallback” property">ssl-fallback</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--ssl-strict" title="The “ssl-strict” property">ssl-strict</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a></td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--timeout" title="The “timeout” property">timeout</a></td> +<td class="property_flags">Read / Write</td> +</tr> +<tr> +<td class="property_type"> +<span class="type">GTlsCertificate</span> *</td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--tls-certificate" title="The “tls-certificate” property">tls-certificate</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"><span class="type">GTlsCertificateFlags</span></td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--tls-errors" title="The “tls-errors” property">tls-errors</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--trusted-certificate" title="The “trusted-certificate” property">trusted-certificate</a></td> +<td class="property_flags">Read</td> +</tr> +<tr> +<td class="property_type"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></td> +<td class="property_name"><a class="link" href="SoupSocket.html#SoupSocket--use-thread-context" title="The “use-thread-context” property">use-thread-context</a></td> +<td class="property_flags">Read / Write / Construct Only</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSocket.signals"></a><h2>Signals</h2> +<div class="informaltable"><table border="0"> +<colgroup> +<col width="150px" class="signals_return"> +<col width="300px" class="signals_name"> +<col width="200px" class="signals_flags"> +</colgroup> +<tbody> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupSocket.html#SoupSocket-disconnected" title="The “disconnected” signal">disconnected</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS">Run Last</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupSocket.html#SoupSocket-event" title="The “event” signal">event</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS">Run Last</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupSocket.html#SoupSocket-new-connection" title="The “new-connection” signal">new-connection</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupSocket.html#SoupSocket-readable" title="The “readable” signal">readable</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS">Run Last</a></td> +</tr> +<tr> +<td class="signal_type"><span class="returnvalue">void</span></td> +<td class="signal_name"><a class="link" href="SoupSocket.html#SoupSocket-writable" title="The “writable” signal">writable</a></td> +<td class="signal_flags"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS">Run Last</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSocket.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupSocket.html#SoupSocket-struct" title="SoupSocket">SoupSocket</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SoupSocketIOStatus" title="enum SoupSocketIOStatus">SoupSocketIOStatus</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-LOCAL-ADDRESS:CAPS" title="SOUP_SOCKET_LOCAL_ADDRESS">SOUP_SOCKET_LOCAL_ADDRESS</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-REMOTE-ADDRESS:CAPS" title="SOUP_SOCKET_REMOTE_ADDRESS">SOUP_SOCKET_REMOTE_ADDRESS</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-FLAG-NONBLOCKING:CAPS" title="SOUP_SOCKET_FLAG_NONBLOCKING">SOUP_SOCKET_FLAG_NONBLOCKING</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-IS-SERVER:CAPS" title="SOUP_SOCKET_IS_SERVER">SOUP_SOCKET_IS_SERVER</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-SSL-CREDENTIALS:CAPS" title="SOUP_SOCKET_SSL_CREDENTIALS">SOUP_SOCKET_SSL_CREDENTIALS</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-ASYNC-CONTEXT:CAPS" title="SOUP_SOCKET_ASYNC_CONTEXT">SOUP_SOCKET_ASYNC_CONTEXT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-TIMEOUT:CAPS" title="SOUP_SOCKET_TIMEOUT">SOUP_SOCKET_TIMEOUT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-SSL-FALLBACK:CAPS" title="SOUP_SOCKET_SSL_FALLBACK">SOUP_SOCKET_SSL_FALLBACK</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-SSL-STRICT:CAPS" title="SOUP_SOCKET_SSL_STRICT">SOUP_SOCKET_SSL_STRICT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-TLS-CERTIFICATE:CAPS" title="SOUP_SOCKET_TLS_CERTIFICATE">SOUP_SOCKET_TLS_CERTIFICATE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-TLS-ERRORS:CAPS" title="SOUP_SOCKET_TLS_ERRORS">SOUP_SOCKET_TLS_ERRORS</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-TRUSTED-CERTIFICATE:CAPS" title="SOUP_SOCKET_TRUSTED_CERTIFICATE">SOUP_SOCKET_TRUSTED_CERTIFICATE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupSocket.html#SOUP-SOCKET-USE-THREAD-CONTEXT:CAPS" title="SOUP_SOCKET_USE_THREAD_CONTEXT">SOUP_SOCKET_USE_THREAD_CONTEXT</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupSocket.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> + <span class="lineart">╰──</span> SoupSocket +</pre> +</div> +<div class="refsect1"> +<a name="SoupSocket.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupSocket.description"></a><h2>Description</h2> +<p><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> is libsoup's TCP socket type. While it is primarily +intended for internal use, <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a>s are exposed in the +API in various places, and some of their methods (eg, +<a class="link" href="SoupSocket.html#soup-socket-get-remote-address" title="soup_socket_get_remote_address ()"><code class="function">soup_socket_get_remote_address()</code></a>) may be useful to applications.</p> +</div> +<div class="refsect1"> +<a name="SoupSocket.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-socket-new"></a><h3>soup_socket_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="returnvalue">SoupSocket</span></a> * +soup_socket_new (<em class="parameter"><code>const <span class="type">char</span> *optname1</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Creates a new (disconnected) socket</p> +<div class="refsect3"> +<a name="id-1.6.3.10.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>optname1</p></td> +<td class="parameter_description"><p>name of first property to set (or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>value of <em class="parameter"><code>optname1</code></em> +, followed by additional property/value pairs</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.2.6"></a><h4>Returns</h4> +<p> the new socket</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocketCallback"></a><h3>SoupSocketCallback ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +<span class="c_punctuation">(</span>*SoupSocketCallback<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> status</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>The callback function passed to <a class="link" href="SoupSocket.html#soup-socket-connect-async" title="soup_socket_connect_async ()"><code class="function">soup_socket_connect_async()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>the <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>status</p></td> +<td class="parameter_description"><p>an HTTP status code indicating success or failure</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>the data passed to <a class="link" href="SoupSocket.html#soup-socket-connect-async" title="soup_socket_connect_async ()"><code class="function">soup_socket_connect_async()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-connect-async"></a><h3>soup_socket_connect_async ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_socket_connect_async (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><a class="link" href="SoupSocket.html#SoupSocketCallback" title="SoupSocketCallback ()"><span class="type">SoupSocketCallback</span></a> callback</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre> +<p>Begins asynchronously connecting to <em class="parameter"><code>sock</code></em> +'s remote address. The +socket will call <em class="parameter"><code>callback</code></em> + when it succeeds or fails (but not +before returning from this function).</p> +<p>If <em class="parameter"><code>cancellable</code></em> + is non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, it can be used to cancel the +connection. <em class="parameter"><code>callback</code></em> + will still be invoked in this case, with a +status of <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANCELLED:CAPS"><code class="literal">SOUP_STATUS_CANCELLED</code></a>.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.4.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>a client <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> (which must not already be connected)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>callback</p></td> +<td class="parameter_description"><p> callback to call after connecting. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="The callback is valid until first called."><span class="acronym">scope async</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>data to pass to <em class="parameter"><code>callback</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-connect-sync"></a><h3>soup_socket_connect_sync ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_socket_connect_sync (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>);</pre> +<p>Attempt to synchronously connect <em class="parameter"><code>sock</code></em> + to its remote address.</p> +<p>If <em class="parameter"><code>cancellable</code></em> + is non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, it can be used to cancel the +connection, in which case <a class="link" href="SoupSocket.html#soup-socket-connect-sync" title="soup_socket_connect_sync ()"><code class="function">soup_socket_connect_sync()</code></a> will return +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANCELLED:CAPS"><code class="literal">SOUP_STATUS_CANCELLED</code></a>.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.5.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>a client <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> (which must not already be connected)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.5.7"></a><h4>Returns</h4> +<p> a success or failure code.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-listen"></a><h3>soup_socket_listen ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_socket_listen (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>);</pre> +<p>Makes <em class="parameter"><code>sock</code></em> + start listening on its local address. When connections +come in, <em class="parameter"><code>sock</code></em> + will emit <a class="link" href="SoupSocket.html#SoupSocket-new-connection" title="The “new-connection” signal"><span class="type">“new_connection”</span></a>.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>a server <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> (which must not already be connected or +listening)</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.6.6"></a><h4>Returns</h4> +<p> whether or not <em class="parameter"><code>sock</code></em> +is now listening.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-start-ssl"></a><h3>soup_socket_start_ssl ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_socket_start_ssl (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>);</pre> +<p>Starts using SSL on <em class="parameter"><code>socket</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>the socket</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.7.6"></a><h4>Returns</h4> +<p> success or failure</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-start-proxy-ssl"></a><h3>soup_socket_start_proxy_ssl ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_socket_start_proxy_ssl (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *ssl_host</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>);</pre> +<p>Starts using SSL on <em class="parameter"><code>socket</code></em> +, expecting to find a host named +<em class="parameter"><code>ssl_host</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>the socket</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>ssl_host</p></td> +<td class="parameter_description"><p>hostname of the SSL server</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.8.6"></a><h4>Returns</h4> +<p> success or failure</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-is-ssl"></a><h3>soup_socket_is_ssl ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_socket_is_ssl (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>);</pre> +<p>Tests if <em class="parameter"><code>sock</code></em> + is doing (or has attempted to do) SSL.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.9.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>sock</code></em> +has SSL credentials set</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-disconnect"></a><h3>soup_socket_disconnect ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_socket_disconnect (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>);</pre> +<p>Disconnects <em class="parameter"><code>sock</code></em> +. Any further read or write attempts on it will +fail.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-is-connected"></a><h3>soup_socket_is_connected ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_socket_is_connected (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>);</pre> +<p>Tests if <em class="parameter"><code>sock</code></em> + is connected to another host</p> +<div class="refsect3"> +<a name="id-1.6.3.10.11.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.11.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-get-local-address"></a><h3>soup_socket_get_local_address ()</h3> +<pre class="programlisting"><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +soup_socket_get_local_address (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>);</pre> +<p>Returns the <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> corresponding to the local end of <em class="parameter"><code>sock</code></em> +.</p> +<p>Calling this method on an unconnected socket is considered to be +an error, and produces undefined results.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.12.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.12.7"></a><h4>Returns</h4> +<p> the <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a>. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-get-remote-address"></a><h3>soup_socket_get_remote_address ()</h3> +<pre class="programlisting"><a class="link" href="SoupAddress.html" title="SoupAddress"><span class="returnvalue">SoupAddress</span></a> * +soup_socket_get_remote_address (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>);</pre> +<p>Returns the <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> corresponding to the remote end of <em class="parameter"><code>sock</code></em> +.</p> +<p>Calling this method on an unconnected socket is considered to be +an error, and produces undefined results.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.13.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.13.7"></a><h4>Returns</h4> +<p> the <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a>. </p> +<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-get-fd"></a><h3>soup_socket_get_fd ()</h3> +<pre class="programlisting"><span class="returnvalue">int</span> +soup_socket_get_fd (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>);</pre> +<p>Gets <em class="parameter"><code>sock</code></em> +'s underlying file descriptor.</p> +<p>Note that fiddling with the file descriptor may break the +<a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a>.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.14.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.14.7"></a><h4>Returns</h4> +<p> <em class="parameter"><code>sock</code></em> +'s file descriptor.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-read"></a><h3>soup_socket_read ()</h3> +<pre class="programlisting"><a class="link" href="SoupSocket.html#SoupSocketIOStatus" title="enum SoupSocketIOStatus"><span class="returnvalue">SoupSocketIOStatus</span></a> +soup_socket_read (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> buffer</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> len</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> *nread</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Attempts to read up to <em class="parameter"><code>len</code></em> + bytes from <em class="parameter"><code>sock</code></em> + into <em class="parameter"><code>buffer</code></em> +. If some +data is successfully read, <a class="link" href="SoupSocket.html#soup-socket-read" title="soup_socket_read ()"><code class="function">soup_socket_read()</code></a> will return +<a class="link" href="SoupSocket.html#SOUP-SOCKET-OK:CAPS"><code class="literal">SOUP_SOCKET_OK</code></a>, and *<em class="parameter"><code>nread</code></em> + will contain the number of bytes +actually read (which may be less than <em class="parameter"><code>len</code></em> +).</p> +<p>If <em class="parameter"><code>sock</code></em> + is non-blocking, and no data is available, the return +value will be <a class="link" href="SoupSocket.html#SOUP-SOCKET-WOULD-BLOCK:CAPS"><code class="literal">SOUP_SOCKET_WOULD_BLOCK</code></a>. In this case, the caller +can connect to the <a class="link" href="SoupSocket.html#SoupSocket-readable" title="The “readable” signal"><span class="type">“readable”</span></a> signal to know when there +is more data to read. (NB: You MUST read all available data off the +socket first. <a class="link" href="SoupSocket.html#SoupSocket-readable" title="The “readable” signal"><span class="type">“readable”</span></a> is only emitted after +<a class="link" href="SoupSocket.html#soup-socket-read" title="soup_socket_read ()"><code class="function">soup_socket_read()</code></a> returns <a class="link" href="SoupSocket.html#SOUP-SOCKET-WOULD-BLOCK:CAPS"><code class="literal">SOUP_SOCKET_WOULD_BLOCK</code></a>, and it is only +emitted once. See the documentation for <a class="link" href="SoupSocket.html#SoupSocket--non-blocking" title="The “non-blocking” property"><span class="type">“non-blocking”</span></a>.)</p> +<div class="refsect3"> +<a name="id-1.6.3.10.15.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>the socket</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>buffer</p></td> +<td class="parameter_description"><p>buffer to read into</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>len</p></td> +<td class="parameter_description"><p>size of <em class="parameter"><code>buffer</code></em> +in bytes</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>nread</p></td> +<td class="parameter_description"><p> on return, the number of bytes read into <em class="parameter"><code>buffer</code></em> +. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>error pointer</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.15.7"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupSocket.html#SoupSocketIOStatus" title="enum SoupSocketIOStatus"><span class="type">SoupSocketIOStatus</span></a>, as described above (or +<a class="link" href="SoupSocket.html#SOUP-SOCKET-EOF:CAPS"><code class="literal">SOUP_SOCKET_EOF</code></a> if the socket is no longer connected, or +<a class="link" href="SoupSocket.html#SOUP-SOCKET-ERROR:CAPS"><code class="literal">SOUP_SOCKET_ERROR</code></a> on any other error, in which case <em class="parameter"><code>error</code></em> +will +also be set).</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-read-until"></a><h3>soup_socket_read_until ()</h3> +<pre class="programlisting"><a class="link" href="SoupSocket.html#SoupSocketIOStatus" title="enum SoupSocketIOStatus"><span class="returnvalue">SoupSocketIOStatus</span></a> +soup_socket_read_until (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> buffer</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> len</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> boundary</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> boundary_len</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> *nread</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> *got_boundary</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Like <a class="link" href="SoupSocket.html#soup-socket-read" title="soup_socket_read ()"><code class="function">soup_socket_read()</code></a>, but reads no further than the first +occurrence of <em class="parameter"><code>boundary</code></em> +. (If the boundary is found, it will be +included in the returned data, and *<em class="parameter"><code>got_boundary</code></em> + will be set to +<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>.) Any data after the boundary will returned in future reads.</p> +<p>soup_socket_read_until() will almost always return fewer than <em class="parameter"><code>len</code></em> + +bytes: if the boundary is found, then it will only return the bytes +up until the end of the boundary, and if the boundary is not found, +then it will leave the last <code class="literal">(boundary_len - 1)</code> +bytes in its internal buffer, in case they form the start of the +boundary string. Thus, <em class="parameter"><code>len</code></em> + normally needs to be at least 1 byte +longer than <em class="parameter"><code>boundary_len</code></em> + if you want to make any progress at all.</p> +<div class="refsect3"> +<a name="id-1.6.3.10.16.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>the socket</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>buffer</p></td> +<td class="parameter_description"><p>buffer to read into</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>len</p></td> +<td class="parameter_description"><p>size of <em class="parameter"><code>buffer</code></em> +in bytes</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>boundary</p></td> +<td class="parameter_description"><p>boundary to read until</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>boundary_len</p></td> +<td class="parameter_description"><p>length of <em class="parameter"><code>boundary</code></em> +in bytes</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>nread</p></td> +<td class="parameter_description"><p> on return, the number of bytes read into <em class="parameter"><code>buffer</code></em> +. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>got_boundary</p></td> +<td class="parameter_description"><p>on return, whether or not the data in <em class="parameter"><code>buffer</code></em> +ends with the boundary string</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>error pointer</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.16.7"></a><h4>Returns</h4> +<p> as for <a class="link" href="SoupSocket.html#soup-socket-read" title="soup_socket_read ()"><code class="function">soup_socket_read()</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-socket-write"></a><h3>soup_socket_write ()</h3> +<pre class="programlisting"><a class="link" href="SoupSocket.html#SoupSocketIOStatus" title="enum SoupSocketIOStatus"><span class="returnvalue">SoupSocketIOStatus</span></a> +soup_socket_write (<em class="parameter"><code><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> buffer</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> len</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> *nwrote</code></em>, + <em class="parameter"><code><span class="type">GCancellable</span> *cancellable</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Attempts to write <em class="parameter"><code>len</code></em> + bytes from <em class="parameter"><code>buffer</code></em> + to <em class="parameter"><code>sock</code></em> +. If some data is +successfully written, the return status will be <a class="link" href="SoupSocket.html#SOUP-SOCKET-OK:CAPS"><code class="literal">SOUP_SOCKET_OK</code></a>, +and *<em class="parameter"><code>nwrote</code></em> + will contain the number of bytes actually written +(which may be less than <em class="parameter"><code>len</code></em> +).</p> +<p>If <em class="parameter"><code>sock</code></em> + is non-blocking, and no data could be written right away, +the return value will be <a class="link" href="SoupSocket.html#SOUP-SOCKET-WOULD-BLOCK:CAPS"><code class="literal">SOUP_SOCKET_WOULD_BLOCK</code></a>. In this case, +the caller can connect to the <a class="link" href="SoupSocket.html#SoupSocket-writable" title="The “writable” signal"><span class="type">“writable”</span></a> signal to know +when more data can be written. (NB: <a class="link" href="SoupSocket.html#SoupSocket-writable" title="The “writable” signal"><span class="type">“writable”</span></a> is only +emitted after <a class="link" href="SoupSocket.html#soup-socket-write" title="soup_socket_write ()"><code class="function">soup_socket_write()</code></a> returns <a class="link" href="SoupSocket.html#SOUP-SOCKET-WOULD-BLOCK:CAPS"><code class="literal">SOUP_SOCKET_WOULD_BLOCK</code></a>, +and it is only emitted once. See the documentation for +<a class="link" href="SoupSocket.html#SoupSocket--non-blocking" title="The “non-blocking” property"><span class="type">“non-blocking”</span></a>.)</p> +<div class="refsect3"> +<a name="id-1.6.3.10.17.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>the socket</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>buffer</p></td> +<td class="parameter_description"><p>data to write</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>len</p></td> +<td class="parameter_description"><p>size of <em class="parameter"><code>buffer</code></em> +, in bytes</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>nwrote</p></td> +<td class="parameter_description"><p> on return, number of bytes written. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>cancellable</p></td> +<td class="parameter_description"><p>a <span class="type">GCancellable</span>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>error pointer</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.6.3.10.17.7"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupSocket.html#SoupSocketIOStatus" title="enum SoupSocketIOStatus"><span class="type">SoupSocketIOStatus</span></a>, as described above (or +<a class="link" href="SoupSocket.html#SOUP-SOCKET-EOF:CAPS"><code class="literal">SOUP_SOCKET_EOF</code></a> or <a class="link" href="SoupSocket.html#SOUP-SOCKET-ERROR:CAPS"><code class="literal">SOUP_SOCKET_ERROR</code></a>. <em class="parameter"><code>error</code></em> +will be set if the +return value is <a class="link" href="SoupSocket.html#SOUP-SOCKET-ERROR:CAPS"><code class="literal">SOUP_SOCKET_ERROR</code></a>.)</p> +<p></p> +</div> +</div> +</div> +<div class="refsect1"> +<a name="SoupSocket.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupSocket-struct"></a><h3>SoupSocket</h3> +<pre class="programlisting">typedef struct _SoupSocket SoupSocket;</pre> +<p> +</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocketIOStatus"></a><h3>enum SoupSocketIOStatus</h3> +<p>Return value from the <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> IO methods.</p> +<div class="refsect3"> +<a name="id-1.6.3.11.3.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-SOCKET-OK:CAPS"></a>SOUP_SOCKET_OK</p></td> +<td class="enum_member_description"> +<p>Success</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-SOCKET-WOULD-BLOCK:CAPS"></a>SOUP_SOCKET_WOULD_BLOCK</p></td> +<td class="enum_member_description"> +<p>Cannot read/write any more at this time</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-SOCKET-EOF:CAPS"></a>SOUP_SOCKET_EOF</p></td> +<td class="enum_member_description"> +<p>End of file</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-SOCKET-ERROR:CAPS"></a>SOUP_SOCKET_ERROR</p></td> +<td class="enum_member_description"> +<p>Other error</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-LOCAL-ADDRESS:CAPS"></a><h3>SOUP_SOCKET_LOCAL_ADDRESS</h3> +<pre class="programlisting">#define SOUP_SOCKET_LOCAL_ADDRESS "local-address" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--local-address" title="The “local-address” property"><span class="type">“local-address”</span></a> property. (Address +of local end of socket.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-REMOTE-ADDRESS:CAPS"></a><h3>SOUP_SOCKET_REMOTE_ADDRESS</h3> +<pre class="programlisting">#define SOUP_SOCKET_REMOTE_ADDRESS "remote-address" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--remote-address" title="The “remote-address” property"><span class="type">“remote-address”</span></a> property. (Address +of remote end of socket.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-FLAG-NONBLOCKING:CAPS"></a><h3>SOUP_SOCKET_FLAG_NONBLOCKING</h3> +<pre class="programlisting">#define SOUP_SOCKET_FLAG_NONBLOCKING "non-blocking" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--non-blocking" title="The “non-blocking” property"><span class="type">“non-blocking”</span></a> property. (Whether +or not the socket uses non-blocking I/O.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-IS-SERVER:CAPS"></a><h3>SOUP_SOCKET_IS_SERVER</h3> +<pre class="programlisting">#define SOUP_SOCKET_IS_SERVER "is-server" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--is-server" title="The “is-server” property"><span class="type">“is-server”</span></a> property. (Whether or +not the socket is a server socket.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-SSL-CREDENTIALS:CAPS"></a><h3>SOUP_SOCKET_SSL_CREDENTIALS</h3> +<pre class="programlisting">#define SOUP_SOCKET_SSL_CREDENTIALS "ssl-creds" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--ssl-creds" title="The “ssl-creds” property"><span class="type">“ssl-creds”</span></a> property. +(SSL credential information.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-ASYNC-CONTEXT:CAPS"></a><h3>SOUP_SOCKET_ASYNC_CONTEXT</h3> +<pre class="programlisting">#define SOUP_SOCKET_ASYNC_CONTEXT "async-context" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--async-context" title="The “async-context” property"><span class="type">“async-context”</span></a> property. (The +socket's <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-TIMEOUT:CAPS"></a><h3>SOUP_SOCKET_TIMEOUT</h3> +<pre class="programlisting">#define SOUP_SOCKET_TIMEOUT "timeout" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--timeout" title="The “timeout” property"><span class="type">“timeout”</span></a> property. (The timeout +in seconds for blocking socket I/O operations.)</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-SSL-FALLBACK:CAPS"></a><h3>SOUP_SOCKET_SSL_FALLBACK</h3> +<pre class="programlisting">#define SOUP_SOCKET_SSL_FALLBACK "ssl-fallback" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--ssl-fallback" title="The “ssl-fallback” property"><span class="type">“ssl-fallback”</span></a> property.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-SSL-STRICT:CAPS"></a><h3>SOUP_SOCKET_SSL_STRICT</h3> +<pre class="programlisting">#define SOUP_SOCKET_SSL_STRICT "ssl-strict" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--ssl-strict" title="The “ssl-strict” property"><span class="type">“ssl-strict”</span></a> property.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-TLS-CERTIFICATE:CAPS"></a><h3>SOUP_SOCKET_TLS_CERTIFICATE</h3> +<pre class="programlisting">#define SOUP_SOCKET_TLS_CERTIFICATE "tls-certificate" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--tls-certificate" title="The “tls-certificate” property"><span class="type">“tls-certificate”</span></a> +property. Note that this property's value is only useful +if the socket is for a TLS connection, and only reliable +after some data has been transferred to or from it.</p> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-TLS-ERRORS:CAPS"></a><h3>SOUP_SOCKET_TLS_ERRORS</h3> +<pre class="programlisting">#define SOUP_SOCKET_TLS_ERRORS "tls-errors" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--tls-errors" title="The “tls-errors” property"><span class="type">“tls-errors”</span></a> +property. Note that this property's value is only useful +if the socket is for a TLS connection, and only reliable +after some data has been transferred to or from it.</p> +<p class="since">Since 2.34</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-TRUSTED-CERTIFICATE:CAPS"></a><h3>SOUP_SOCKET_TRUSTED_CERTIFICATE</h3> +<pre class="programlisting">#define SOUP_SOCKET_TRUSTED_CERTIFICATE "trusted-certificate" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--trusted-certificate" title="The “trusted-certificate” property"><span class="type">“trusted-certificate”</span></a> +property.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-SOCKET-USE-THREAD-CONTEXT:CAPS"></a><h3>SOUP_SOCKET_USE_THREAD_CONTEXT</h3> +<pre class="programlisting">#define SOUP_SOCKET_USE_THREAD_CONTEXT "use-thread-context" +</pre> +<p>Alias for the <a class="link" href="SoupSocket.html#SoupSocket--use-thread-context" title="The “use-thread-context” property"><span class="type">“use-thread-context”</span></a> property. (Use +<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-main-context-get-thread-default"><code class="function">g_main_context_get_thread_default()</code></a>)</p> +<p class="since">Since 2.38</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupSocket.property-details"></a><h2>Property Details</h2> +<div class="refsect2"> +<a name="SoupSocket--async-context"></a><h3>The <code class="literal">“async-context”</code> property</h3> +<pre class="programlisting"> “async-context” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>The GMainContext to dispatch this socket's async I/O in.</p> +<p>Flags: Read / Write / Construct Only</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--clean-dispose"></a><h3>The <code class="literal">“clean-dispose”</code> property</h3> +<pre class="programlisting"> “clean-dispose” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Warn on unclean dispose.</p> +<p>Flags: Write / Construct Only</p> +<p>Default value: FALSE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--is-server"></a><h3>The <code class="literal">“is-server”</code> property</h3> +<pre class="programlisting"> “is-server” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Whether or not the socket is a server socket.</p> +<p>Flags: Read</p> +<p>Default value: FALSE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--local-address"></a><h3>The <code class="literal">“local-address”</code> property</h3> +<pre class="programlisting"> “local-address” <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *</pre> +<p>Address of local end of socket.</p> +<p>Flags: Read / Write / Construct Only</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--non-blocking"></a><h3>The <code class="literal">“non-blocking”</code> property</h3> +<pre class="programlisting"> “non-blocking” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Whether or not the socket uses non-blocking I/O.</p> +<p><a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a>'s I/O methods are designed around the idea of +using a single codepath for both synchronous and +asynchronous I/O. If you want to read off a <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a>, +the "correct" way to do it is to call <a class="link" href="SoupSocket.html#soup-socket-read" title="soup_socket_read ()"><code class="function">soup_socket_read()</code></a> or +<a class="link" href="SoupSocket.html#soup-socket-read-until" title="soup_socket_read_until ()"><code class="function">soup_socket_read_until()</code></a> repeatedly until you have read +everything you want. If it returns <a class="link" href="SoupSocket.html#SOUP-SOCKET-WOULD-BLOCK:CAPS"><code class="literal">SOUP_SOCKET_WOULD_BLOCK</code></a> +at any point, stop reading and wait for it to emit the +<a class="link" href="SoupSocket.html#SoupSocket-readable" title="The “readable” signal"><span class="type">“readable”</span></a> signal. Then go back to the +reading-as-much-as-you-can loop. Likewise, for writing to a +<a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a>, you should call <a class="link" href="SoupSocket.html#soup-socket-write" title="soup_socket_write ()"><code class="function">soup_socket_write()</code></a> either +until you have written everything, or it returns +<a class="link" href="SoupSocket.html#SOUP-SOCKET-WOULD-BLOCK:CAPS"><code class="literal">SOUP_SOCKET_WOULD_BLOCK</code></a> (in which case you wait for +<a class="link" href="SoupSocket.html#SoupSocket-writable" title="The “writable” signal"><span class="type">“writable”</span></a> and then go back into the loop).</p> +<p>Code written this way will work correctly with both +blocking and non-blocking sockets; blocking sockets will +simply never return <a class="link" href="SoupSocket.html#SOUP-SOCKET-WOULD-BLOCK:CAPS"><code class="literal">SOUP_SOCKET_WOULD_BLOCK</code></a>, and so the +code that handles that case just won't get used for them.</p> +<p>Flags: Read / Write</p> +<p>Default value: TRUE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--proxy-resolver"></a><h3>The <code class="literal">“proxy-resolver”</code> property</h3> +<pre class="programlisting"> “proxy-resolver” <span class="type">GProxyResolver</span> *</pre> +<p>GProxyResolver to use.</p> +<p>Flags: Read / Write / Construct Only</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--remote-address"></a><h3>The <code class="literal">“remote-address”</code> property</h3> +<pre class="programlisting"> “remote-address” <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a> *</pre> +<p>Address of remote end of socket.</p> +<p>Flags: Read / Write / Construct Only</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--ssl-creds"></a><h3>The <code class="literal">“ssl-creds”</code> property</h3> +<pre class="programlisting"> “ssl-creds” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a></pre> +<p>SSL credential information, passed from the session to the SSL implementation.</p> +<p>Flags: Read / Write</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--ssl-fallback"></a><h3>The <code class="literal">“ssl-fallback”</code> property</h3> +<pre class="programlisting"> “ssl-fallback” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Use SSLv3 instead of TLS (client-side only).</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: FALSE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--ssl-strict"></a><h3>The <code class="literal">“ssl-strict”</code> property</h3> +<pre class="programlisting"> “ssl-strict” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Whether certificate errors should be considered a connection error.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: TRUE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--timeout"></a><h3>The <code class="literal">“timeout”</code> property</h3> +<pre class="programlisting"> “timeout” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a></pre> +<p>Value in seconds to timeout a blocking I/O.</p> +<p>Flags: Read / Write</p> +<p>Default value: 0</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--tls-certificate"></a><h3>The <code class="literal">“tls-certificate”</code> property</h3> +<pre class="programlisting"> “tls-certificate” <span class="type">GTlsCertificate</span> *</pre> +<p>The peer's TLS certificate.</p> +<p>Flags: Read</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--tls-errors"></a><h3>The <code class="literal">“tls-errors”</code> property</h3> +<pre class="programlisting"> “tls-errors” <span class="type">GTlsCertificateFlags</span></pre> +<p>Errors with the peer's TLS certificate.</p> +<p>Flags: Read</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--trusted-certificate"></a><h3>The <code class="literal">“trusted-certificate”</code> property</h3> +<pre class="programlisting"> “trusted-certificate” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Whether the server certificate is trusted, if this is an SSL socket.</p> +<p>Flags: Read</p> +<p>Default value: FALSE</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket--use-thread-context"></a><h3>The <code class="literal">“use-thread-context”</code> property</h3> +<pre class="programlisting"> “use-thread-context” <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a></pre> +<p>Use <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-main-context-get-thread-default"><code class="function">g_main_context_get_thread_default()</code></a>.</p> +<p>Flags: Read / Write / Construct Only</p> +<p>Default value: FALSE</p> +<p class="since">Since 2.38</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupSocket.signal-details"></a><h2>Signal Details</h2> +<div class="refsect2"> +<a name="SoupSocket-disconnected"></a><h3>The <code class="literal">“disconnected”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when the socket is disconnected, for whatever +reason.</p> +<div class="refsect3"> +<a name="id-1.6.3.13.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>the socket</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS">Run Last</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket-event"></a><h3>The <code class="literal">“event”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock, + <span class="type">GSocketClientEvent</span> event, + <span class="type">GIOStream</span> *connection, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when a network-related event occurs. See +<span class="type">“event”</span> for more details.</p> +<div class="refsect3"> +<a name="id-1.6.3.13.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>the socket</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>event</p></td> +<td class="parameter_description"><p>the event that occurred</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>connection</p></td> +<td class="parameter_description"><p>the current connection state</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS">Run Last</a></p> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket-new-connection"></a><h3>The <code class="literal">“new-connection”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock, + <a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *new, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when a listening socket (set up with +<a class="link" href="SoupSocket.html#soup-socket-listen" title="soup_socket_listen ()"><code class="function">soup_socket_listen()</code></a>) receives a new connection.</p> +<p>You must ref the <em class="parameter"><code>new</code></em> + if you want to keep it; otherwise it +will be destroyed after the signal is emitted.</p> +<div class="refsect3"> +<a name="id-1.6.3.13.4.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>the socket</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>new</p></td> +<td class="parameter_description"><p>the new socket</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS">Run First</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket-readable"></a><h3>The <code class="literal">“readable”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when an async socket is readable. See +<a class="link" href="SoupSocket.html#soup-socket-read" title="soup_socket_read ()"><code class="function">soup_socket_read()</code></a>, <a class="link" href="SoupSocket.html#soup-socket-read-until" title="soup_socket_read_until ()"><code class="function">soup_socket_read_until()</code></a> and +<a class="link" href="SoupSocket.html#SoupSocket--non-blocking" title="The “non-blocking” property"><span class="type">“non-blocking”</span></a>.</p> +<div class="refsect3"> +<a name="id-1.6.3.13.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>the socket</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS">Run Last</a></p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupSocket-writable"></a><h3>The <code class="literal">“writable”</code> signal</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +user_function (<a class="link" href="SoupSocket.html" title="SoupSocket"><span class="type">SoupSocket</span></a> *sock, + <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data)</pre> +<p>Emitted when an async socket is writable. See +<a class="link" href="SoupSocket.html#soup-socket-write" title="soup_socket_write ()"><code class="function">soup_socket_write()</code></a> and <a class="link" href="SoupSocket.html#SoupSocket--non-blocking" title="The “non-blocking” property"><span class="type">“non-blocking”</span></a>.</p> +<div class="refsect3"> +<a name="id-1.6.3.13.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>sock</p></td> +<td class="parameter_description"><p>the socket</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user_data</p></td> +<td class="parameter_description"><p>user data set when the signal handler was connected.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p>Flags: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-LAST:CAPS">Run Last</a></p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/SoupURI.html b/docs/reference/html/SoupURI.html new file mode 100644 index 00000000..9e0ca074 --- /dev/null +++ b/docs/reference/html/SoupURI.html @@ -0,0 +1,1664 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: SoupURI</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="libsoup-2.4-Top-Level-Domain-utils.html" title="Top Level Domain utils"> +<link rel="next" href="libsoup-2.4-Version-Information.html" title="Version Information"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#SoupURI.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#SoupURI.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="libsoup-2.4-Top-Level-Domain-utils.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-2.4-Version-Information.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="SoupURI"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="SoupURI.top_of_page"></a>SoupURI</span></h2> +<p>SoupURI — URIs</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="SoupURI.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-new-with-base" title="soup_uri_new_with_base ()">soup_uri_new_with_base</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-new" title="soup_uri_new ()">soup_uri_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-to-string" title="soup_uri_to_string ()">soup_uri_to_string</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-copy" title="soup_uri_copy ()">soup_uri_copy</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-copy-host" title="soup_uri_copy_host ()">soup_uri_copy_host</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-equal" title="soup_uri_equal ()">soup_uri_equal</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-host-equal" title="soup_uri_host_equal ()">soup_uri_host_equal</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-host-hash" title="soup_uri_host_hash ()">soup_uri_host_hash</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-free" title="soup_uri_free ()">soup_uri_free</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-encode" title="soup_uri_encode ()">soup_uri_encode</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-decode" title="soup_uri_decode ()">soup_uri_decode</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-normalize" title="soup_uri_normalize ()">soup_uri_normalize</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-uses-default-port" title="soup_uri_uses_default_port ()">soup_uri_uses_default_port</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#SOUP-URI-IS-VALID:CAPS" title="SOUP_URI_IS_VALID()">SOUP_URI_IS_VALID</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#SOUP-URI-VALID-FOR-HTTP:CAPS" title="SOUP_URI_VALID_FOR_HTTP()">SOUP_URI_VALID_FOR_HTTP</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-set-scheme" title="soup_uri_set_scheme ()">soup_uri_set_scheme</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-get-scheme" title="soup_uri_get_scheme ()">soup_uri_get_scheme</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-set-user" title="soup_uri_set_user ()">soup_uri_set_user</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-get-user" title="soup_uri_get_user ()">soup_uri_get_user</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-set-password" title="soup_uri_set_password ()">soup_uri_set_password</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-get-password" title="soup_uri_get_password ()">soup_uri_get_password</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-set-host" title="soup_uri_set_host ()">soup_uri_set_host</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-get-host" title="soup_uri_get_host ()">soup_uri_get_host</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-set-port" title="soup_uri_set_port ()">soup_uri_set_port</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-get-port" title="soup_uri_get_port ()">soup_uri_get_port</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-set-path" title="soup_uri_set_path ()">soup_uri_set_path</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-get-path" title="soup_uri_get_path ()">soup_uri_get_path</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-set-query" title="soup_uri_set_query ()">soup_uri_set_query</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-set-query-from-form" title="soup_uri_set_query_from_form ()">soup_uri_set_query_from_form</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-set-query-from-fields" title="soup_uri_set_query_from_fields ()">soup_uri_set_query_from_fields</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-get-query" title="soup_uri_get_query ()">soup_uri_get_query</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-set-fragment" title="soup_uri_set_fragment ()">soup_uri_set_fragment</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="SoupURI.html#soup-uri-get-fragment" title="soup_uri_get_fragment ()">soup_uri_get_fragment</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupURI.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="SoupURI.html#SoupURI-struct" title="SoupURI">SoupURI</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupURI.html#SOUP-URI-SCHEME-HTTP:CAPS" title="SOUP_URI_SCHEME_HTTP">SOUP_URI_SCHEME_HTTP</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupURI.html#SOUP-URI-SCHEME-HTTPS:CAPS" title="SOUP_URI_SCHEME_HTTPS">SOUP_URI_SCHEME_HTTPS</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupURI.html#SOUP-URI-SCHEME-DATA:CAPS" title="SOUP_URI_SCHEME_DATA">SOUP_URI_SCHEME_DATA</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupURI.html#SOUP-URI-SCHEME-FILE:CAPS" title="SOUP_URI_SCHEME_FILE">SOUP_URI_SCHEME_FILE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupURI.html#SOUP-URI-SCHEME-FTP:CAPS" title="SOUP_URI_SCHEME_FTP">SOUP_URI_SCHEME_FTP</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="SoupURI.html#SOUP-URI-SCHEME-RESOURCE:CAPS" title="SOUP_URI_SCHEME_RESOURCE">SOUP_URI_SCHEME_RESOURCE</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="SoupURI.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> GBoxed + <span class="lineart">╰──</span> SoupURI +</pre> +</div> +<div class="refsect1"> +<a name="SoupURI.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="SoupURI.description"></a><h2>Description</h2> +<p>A <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> represents a (parsed) URI.</p> +<p>Many applications will not need to use <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> directly at all; on +the client side, <a class="link" href="SoupMessage.html#soup-message-new" title="soup_message_new ()"><code class="function">soup_message_new()</code></a> takes a stringified URI, and on +the server side, the path and query components are provided for you +in the server callback.</p> +</div> +<div class="refsect1"> +<a name="SoupURI.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-uri-new-with-base"></a><h3>soup_uri_new_with_base ()</h3> +<pre class="programlisting"><a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +soup_uri_new_with_base (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *base</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *uri_string</code></em>);</pre> +<p>Parses <em class="parameter"><code>uri_string</code></em> + relative to <em class="parameter"><code>base</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>base</p></td> +<td class="parameter_description"><p>a base URI</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri_string</p></td> +<td class="parameter_description"><p>the URI</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.2.6"></a><h4>Returns</h4> +<p> a parsed <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-new"></a><h3>soup_uri_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +soup_uri_new (<em class="parameter"><code>const <span class="type">char</span> *uri_string</code></em>);</pre> +<p>Parses an absolute URI.</p> +<p>You can also pass <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> for <em class="parameter"><code>uri_string</code></em> + if you want to get back an +"empty" <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> that you can fill in by hand. (You will need to +call at least <a class="link" href="SoupURI.html#soup-uri-set-scheme" title="soup_uri_set_scheme ()"><code class="function">soup_uri_set_scheme()</code></a> and <a class="link" href="SoupURI.html#soup-uri-set-path" title="soup_uri_set_path ()"><code class="function">soup_uri_set_path()</code></a>, since +those fields are required.)</p> +<div class="refsect3"> +<a name="id-1.3.25.8.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri_string</p></td> +<td class="parameter_description"><p> a URI. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.3.7"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if the given string was found to be +invalid.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-to-string"></a><h3>soup_uri_to_string ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_uri_to_string (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> just_path_and_query</code></em>);</pre> +<p>Returns a string representing <em class="parameter"><code>uri</code></em> +.</p> +<p>If <em class="parameter"><code>just_path_and_query</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, this concatenates the path and query +together. That is, it constructs the string that would be needed in +the Request-Line of an HTTP request for <em class="parameter"><code>uri</code></em> +.</p> +<p>Note that the output will never contain a password, even if <em class="parameter"><code>uri</code></em> + +does.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.4.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>just_path_and_query</p></td> +<td class="parameter_description"><p>if <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, output just the path and query portions</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.4.8"></a><h4>Returns</h4> +<p> a string representing <em class="parameter"><code>uri</code></em> +, which the caller must free.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-copy"></a><h3>soup_uri_copy ()</h3> +<pre class="programlisting"><a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +soup_uri_copy (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Copies <em class="parameter"><code>uri</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.25.8.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.5.6"></a><h4>Returns</h4> +<p> a copy of <em class="parameter"><code>uri</code></em> +, which must be freed with <a class="link" href="SoupURI.html#soup-uri-free" title="soup_uri_free ()"><code class="function">soup_uri_free()</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-copy-host"></a><h3>soup_uri_copy_host ()</h3> +<pre class="programlisting"><a class="link" href="SoupURI.html" title="SoupURI"><span class="returnvalue">SoupURI</span></a> * +soup_uri_copy_host (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Makes a copy of <em class="parameter"><code>uri</code></em> +, considering only the protocol, host, and port</p> +<div class="refsect3"> +<a name="id-1.3.25.8.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.6.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p> +<p></p> +</div> +<p class="since">Since 2.28</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-equal"></a><h3>soup_uri_equal ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_uri_equal (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri1</code></em>, + <em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri2</code></em>);</pre> +<p>Tests whether or not <em class="parameter"><code>uri1</code></em> + and <em class="parameter"><code>uri2</code></em> + are equal in all parts</p> +<div class="refsect3"> +<a name="id-1.3.25.8.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri1</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri2</p></td> +<td class="parameter_description"><p>another <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.7.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-host-equal"></a><h3>soup_uri_host_equal ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_uri_host_equal (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> v1</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> v2</code></em>);</pre> +<p>Compares <em class="parameter"><code>v1</code></em> + and <em class="parameter"><code>v2</code></em> +, considering only the scheme, host, and port.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>v1</p></td> +<td class="parameter_description"><p> a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> with a non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> <em class="parameter"><code>host</code></em> +member. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> Soup.URI]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>v2</p></td> +<td class="parameter_description"><p> a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> with a non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> <em class="parameter"><code>host</code></em> +member. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> Soup.URI]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.8.6"></a><h4>Returns</h4> +<p> whether or not the URIs are equal in scheme, host, +and port.</p> +<p></p> +</div> +<p class="since">Since 2.28</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-host-hash"></a><h3>soup_uri_host_hash ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_uri_host_hash (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> key</code></em>);</pre> +<p>Hashes <em class="parameter"><code>key</code></em> +, considering only the scheme, host, and port.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>key</p></td> +<td class="parameter_description"><p> a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> with a non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> <em class="parameter"><code>host</code></em> +member. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Override the parsed C type with given type."><span class="acronym">type</span></acronym> Soup.URI]</span></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.9.6"></a><h4>Returns</h4> +<p> a hash</p> +<p></p> +</div> +<p class="since">Since 2.28</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-free"></a><h3>soup_uri_free ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_uri_free (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Frees <em class="parameter"><code>uri</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-encode"></a><h3>soup_uri_encode ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_uri_encode (<em class="parameter"><code>const <span class="type">char</span> *part</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *escape_extra</code></em>);</pre> +<p>This %-encodes the given URI part and returns the escaped +version in allocated memory, which the caller must free when it is +done.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.11.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>part</p></td> +<td class="parameter_description"><p>a URI part</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>escape_extra</p></td> +<td class="parameter_description"><p> additional reserved characters to +escape (or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>). </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.11.6"></a><h4>Returns</h4> +<p> the encoded URI part</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-decode"></a><h3>soup_uri_decode ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_uri_decode (<em class="parameter"><code>const <span class="type">char</span> *part</code></em>);</pre> +<p>Fully %-decodes <em class="parameter"><code>part</code></em> +.</p> +<p>In the past, this would return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if <em class="parameter"><code>part</code></em> + contained invalid +percent-encoding, but now it just ignores the problem (as +<a class="link" href="SoupURI.html#soup-uri-new" title="soup_uri_new ()"><code class="function">soup_uri_new()</code></a> already did).</p> +<div class="refsect3"> +<a name="id-1.3.25.8.12.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>part</p></td> +<td class="parameter_description"><p>a URI part</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.12.7"></a><h4>Returns</h4> +<p> the decoded URI part.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-normalize"></a><h3>soup_uri_normalize ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_uri_normalize (<em class="parameter"><code>const <span class="type">char</span> *part</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *unescape_extra</code></em>);</pre> +<p>%-decodes any "unreserved" characters (or characters in +<em class="parameter"><code>unescape_extra</code></em> +) in <em class="parameter"><code>part</code></em> +.</p> +<p>"Unreserved" characters are those that are not allowed to be used +for punctuation according to the URI spec. For example, letters are +unreserved, so <a class="link" href="SoupURI.html#soup-uri-normalize" title="soup_uri_normalize ()"><code class="function">soup_uri_normalize()</code></a> will turn +<code class="literal">http://example.com/foo/b%61r</code> into +<code class="literal">http://example.com/foo/bar</code>, which is guaranteed +to mean the same thing. However, "/" is "reserved", so +<code class="literal">http://example.com/foo%2Fbar</code> would not +be changed, because it might mean something different to the +server.</p> +<p>In the past, this would return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if <em class="parameter"><code>part</code></em> + contained invalid +percent-encoding, but now it just ignores the problem (as +<a class="link" href="SoupURI.html#soup-uri-new" title="soup_uri_new ()"><code class="function">soup_uri_new()</code></a> already did).</p> +<div class="refsect3"> +<a name="id-1.3.25.8.13.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>part</p></td> +<td class="parameter_description"><p>a URI part</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>unescape_extra</p></td> +<td class="parameter_description"><p>reserved characters to unescape (or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>)</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.13.8"></a><h4>Returns</h4> +<p> the normalized URI part</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-uses-default-port"></a><h3>soup_uri_uses_default_port ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_uri_uses_default_port (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Tests if <em class="parameter"><code>uri</code></em> + uses the default port for its scheme. (Eg, 80 for +http.) (This only works for http, https and ftp; libsoup does not know +the default ports of other protocols.)</p> +<div class="refsect3"> +<a name="id-1.3.25.8.14.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.14.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-URI-IS-VALID:CAPS"></a><h3>SOUP_URI_IS_VALID()</h3> +<pre class="programlisting">#define SOUP_URI_IS_VALID(uri) ((uri) && (uri)->scheme && (uri)->path) +</pre> +<p>Tests whether <em class="parameter"><code>uri</code></em> + is a valid <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>; that is, that it is non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> +and its <em class="parameter"><code>scheme</code></em> + and <em class="parameter"><code>path</code></em> + members are also non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</p> +<p>This macro does not check whether http and https URIs have a non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> +<em class="parameter"><code>host</code></em> + member.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.15.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.15.7"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>uri</code></em> +is valid for use.</p> +<p></p> +</div> +<p class="since">Since 2.38</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-URI-VALID-FOR-HTTP:CAPS"></a><h3>SOUP_URI_VALID_FOR_HTTP()</h3> +<pre class="programlisting">#define SOUP_URI_VALID_FOR_HTTP(uri) ((uri) && ((uri)->scheme == SOUP_URI_SCHEME_HTTP || (uri)->scheme == SOUP_URI_SCHEME_HTTPS) && (uri)->host && (uri)->path) +</pre> +<p>Tests if <em class="parameter"><code>uri</code></em> + is a valid <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> for HTTP communication; that is, if +it can be used to construct a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.16.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.16.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>uri</code></em> +is a valid "http" or "https" URI.</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-set-scheme"></a><h3>soup_uri_set_scheme ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_uri_set_scheme (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *scheme</code></em>);</pre> +<p>Sets <em class="parameter"><code>uri</code></em> +'s scheme to <em class="parameter"><code>scheme</code></em> +. This will also set <em class="parameter"><code>uri</code></em> +'s port to +the default port for <em class="parameter"><code>scheme</code></em> +, if known.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.17.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>scheme</p></td> +<td class="parameter_description"><p>the URI scheme</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-get-scheme"></a><h3>soup_uri_get_scheme ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_uri_get_scheme (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Gets <em class="parameter"><code>uri</code></em> +'s scheme.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.18.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.18.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>uri</code></em> +'s scheme.</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-set-user"></a><h3>soup_uri_set_user ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_uri_set_user (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *user</code></em>);</pre> +<p>Sets <em class="parameter"><code>uri</code></em> +'s user to <em class="parameter"><code>user</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.19.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>user</p></td> +<td class="parameter_description"><p> the username, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-get-user"></a><h3>soup_uri_get_user ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_uri_get_user (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Gets <em class="parameter"><code>uri</code></em> +'s user.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.20.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.20.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>uri</code></em> +'s user.</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-set-password"></a><h3>soup_uri_set_password ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_uri_set_password (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *password</code></em>);</pre> +<p>Sets <em class="parameter"><code>uri</code></em> +'s password to <em class="parameter"><code>password</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.21.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>password</p></td> +<td class="parameter_description"><p> the password, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-get-password"></a><h3>soup_uri_get_password ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_uri_get_password (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Gets <em class="parameter"><code>uri</code></em> +'s password.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.22.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.22.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>uri</code></em> +'s password.</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-set-host"></a><h3>soup_uri_set_host ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_uri_set_host (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *host</code></em>);</pre> +<p>Sets <em class="parameter"><code>uri</code></em> +'s host to <em class="parameter"><code>host</code></em> +.</p> +<p>If <em class="parameter"><code>host</code></em> + is an IPv6 IP address, it should not include the brackets +required by the URI syntax; they will be added automatically when +converting <em class="parameter"><code>uri</code></em> + to a string.</p> +<p>http and https URIs should not have a <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> <em class="parameter"><code>host</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.23.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>host</p></td> +<td class="parameter_description"><p> the hostname or IP address, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-get-host"></a><h3>soup_uri_get_host ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_uri_get_host (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Gets <em class="parameter"><code>uri</code></em> +'s host.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.24.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.24.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>uri</code></em> +'s host.</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-set-port"></a><h3>soup_uri_set_port ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_uri_set_port (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> port</code></em>);</pre> +<p>Sets <em class="parameter"><code>uri</code></em> +'s port to <em class="parameter"><code>port</code></em> +. If <em class="parameter"><code>port</code></em> + is 0, <em class="parameter"><code>uri</code></em> + will not have an +explicitly-specified port.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.25.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>port</p></td> +<td class="parameter_description"><p>the port, or 0</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-get-port"></a><h3>soup_uri_get_port ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_uri_get_port (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Gets <em class="parameter"><code>uri</code></em> +'s port.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.26.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.26.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>uri</code></em> +'s port.</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-set-path"></a><h3>soup_uri_set_path ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_uri_set_path (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *path</code></em>);</pre> +<p>Sets <em class="parameter"><code>uri</code></em> +'s path to <em class="parameter"><code>path</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.27.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>path</p></td> +<td class="parameter_description"><p>the non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> path</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-get-path"></a><h3>soup_uri_get_path ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_uri_get_path (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Gets <em class="parameter"><code>uri</code></em> +'s path.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.28.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.28.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>uri</code></em> +'s path.</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-set-query"></a><h3>soup_uri_set_query ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_uri_set_query (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *query</code></em>);</pre> +<p>Sets <em class="parameter"><code>uri</code></em> +'s query to <em class="parameter"><code>query</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.29.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>query</p></td> +<td class="parameter_description"><p> the query. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-set-query-from-form"></a><h3>soup_uri_set_query_from_form ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_uri_set_query_from_form (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *form</code></em>);</pre> +<p>Sets <em class="parameter"><code>uri</code></em> +'s query to the result of encoding <em class="parameter"><code>form</code></em> + according to the +HTML form rules. See <a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-hash" title="soup_form_encode_hash ()"><code class="function">soup_form_encode_hash()</code></a> for more information.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.30.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>form</p></td> +<td class="parameter_description"><p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> containing HTML form +information. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8]</span></td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-set-query-from-fields"></a><h3>soup_uri_set_query_from_fields ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_uri_set_query_from_fields (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *first_field</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Sets <em class="parameter"><code>uri</code></em> +'s query to the result of encoding the given form fields +and values according to the * HTML form rules. See +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode" title="soup_form_encode ()"><code class="function">soup_form_encode()</code></a> for more information.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.31.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>first_field</p></td> +<td class="parameter_description"><p>name of the first form field to encode into query</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>value of <em class="parameter"><code>first_field</code></em> +, followed by additional field names +and values, terminated by <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-get-query"></a><h3>soup_uri_get_query ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_uri_get_query (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Gets <em class="parameter"><code>uri</code></em> +'s query.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.32.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.32.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>uri</code></em> +'s query.</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-set-fragment"></a><h3>soup_uri_set_fragment ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_uri_set_fragment (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *fragment</code></em>);</pre> +<p>Sets <em class="parameter"><code>uri</code></em> +'s fragment to <em class="parameter"><code>fragment</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.33.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>fragment</p></td> +<td class="parameter_description"><p> the fragment. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-uri-get-fragment"></a><h3>soup_uri_get_fragment ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_uri_get_fragment (<em class="parameter"><code><a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> *uri</code></em>);</pre> +<p>Gets <em class="parameter"><code>uri</code></em> +'s fragment.</p> +<div class="refsect3"> +<a name="id-1.3.25.8.34.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.25.8.34.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>uri</code></em> +'s fragment.</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +</div> +<div class="refsect1"> +<a name="SoupURI.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupURI-struct"></a><h3>SoupURI</h3> +<pre class="programlisting">typedef struct { + const char *scheme; + + char *user; + char *password; + + char *host; + guint port; + + char *path; + char *query; + + char *fragment; +} SoupURI; +</pre> +<p>A <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> represents a (parsed) URI. <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> supports RFC 3986 +(URI Generic Syntax), and can parse any valid URI. However, libsoup +only uses "http" and "https" URIs internally; You can use +<a class="link" href="SoupURI.html#SOUP-URI-VALID-FOR-HTTP:CAPS" title="SOUP_URI_VALID_FOR_HTTP()"><code class="function">SOUP_URI_VALID_FOR_HTTP()</code></a> to test if a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> is a valid HTTP +URI.</p> +<p><em class="parameter"><code>scheme</code></em> + will always be set in any URI. It is an interned string and +is always all lowercase. (If you parse a URI with a non-lowercase +scheme, it will be converted to lowercase.) The macros +<a class="link" href="SoupURI.html#SOUP-URI-SCHEME-HTTP:CAPS" title="SOUP_URI_SCHEME_HTTP"><code class="literal">SOUP_URI_SCHEME_HTTP</code></a> and <a class="link" href="SoupURI.html#SOUP-URI-SCHEME-HTTPS:CAPS" title="SOUP_URI_SCHEME_HTTPS"><code class="literal">SOUP_URI_SCHEME_HTTPS</code></a> provide the +interned values for "http" and "https" and can be compared against +URI <em class="parameter"><code>scheme</code></em> + values.</p> +<p><em class="parameter"><code>user</code></em> + and <em class="parameter"><code>password</code></em> + are parsed as defined in the older URI specs +(ie, separated by a colon; RFC 3986 only talks about a single +"userinfo" field). Note that <em class="parameter"><code>password</code></em> + is not included in the +output of <a class="link" href="SoupURI.html#soup-uri-to-string" title="soup_uri_to_string ()"><code class="function">soup_uri_to_string()</code></a>. libsoup does not normally use these +fields; authentication is handled via <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> signals.</p> +<p><em class="parameter"><code>host</code></em> + contains the hostname, and <em class="parameter"><code>port</code></em> + the port specified in the +URI. If the URI doesn't contain a hostname, <em class="parameter"><code>host</code></em> + will be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, +and if it doesn't specify a port, <em class="parameter"><code>port</code></em> + may be 0. However, for +"http" and "https" URIs, <em class="parameter"><code>host</code></em> + is guaranteed to be non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> +(trying to parse an http URI with no <em class="parameter"><code>host</code></em> + will return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>), and +<em class="parameter"><code>port</code></em> + will always be non-0 (because libsoup knows the default value +to use when it is not specified in the URI).</p> +<p><em class="parameter"><code>path</code></em> + is always non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. For http/https URIs, <em class="parameter"><code>path</code></em> + will never be +an empty string either; if the input URI has no path, the parsed +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> will have a <em class="parameter"><code>path</code></em> + of "/".</p> +<p><em class="parameter"><code>query</code></em> + and <em class="parameter"><code>fragment</code></em> + are optional for all URI types. +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-decode" title="soup_form_decode ()"><code class="function">soup_form_decode()</code></a> may be useful for parsing <em class="parameter"><code>query</code></em> +.</p> +<p>Note that <em class="parameter"><code>path</code></em> +, <em class="parameter"><code>query</code></em> +, and <em class="parameter"><code>fragment</code></em> + may contain +%-encoded characters. <a class="link" href="SoupURI.html#soup-uri-new" title="soup_uri_new ()"><code class="function">soup_uri_new()</code></a> calls +<a class="link" href="SoupURI.html#soup-uri-normalize" title="soup_uri_normalize ()"><code class="function">soup_uri_normalize()</code></a> on them, but not <a class="link" href="SoupURI.html#soup-uri-decode" title="soup_uri_decode ()"><code class="function">soup_uri_decode()</code></a>. This is +necessary to ensure that <a class="link" href="SoupURI.html#soup-uri-to-string" title="soup_uri_to_string ()"><code class="function">soup_uri_to_string()</code></a> will generate a URI +that has exactly the same meaning as the original. (In theory, +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a> should leave <em class="parameter"><code>user</code></em> +, <em class="parameter"><code>password</code></em> +, and <em class="parameter"><code>host</code></em> + partially-encoded +as well, but this would be more annoying than useful.)</p> +<div class="refsect3"> +<a name="id-1.3.25.9.2.11"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="struct_members_name"> +<col class="struct_members_description"> +<col width="200px" class="struct_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="struct_member_name"><p>const <span class="type">char</span> *<em class="structfield"><code><a name="SoupURI-struct.scheme"></a>scheme</code></em>;</p></td> +<td class="struct_member_description"><p>the URI scheme (eg, "http")</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">char</span> *<em class="structfield"><code><a name="SoupURI-struct.user"></a>user</code></em>;</p></td> +<td class="struct_member_description"><p>a username, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">char</span> *<em class="structfield"><code><a name="SoupURI-struct.password"></a>password</code></em>;</p></td> +<td class="struct_member_description"><p>a password, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">char</span> *<em class="structfield"><code><a name="SoupURI-struct.host"></a>host</code></em>;</p></td> +<td class="struct_member_description"><p>the hostname or IP address</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> <em class="structfield"><code><a name="SoupURI-struct.port"></a>port</code></em>;</p></td> +<td class="struct_member_description"><p>the port number on <em class="parameter"><code>host</code></em> +</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">char</span> *<em class="structfield"><code><a name="SoupURI-struct.path"></a>path</code></em>;</p></td> +<td class="struct_member_description"><p>the path on <em class="parameter"><code>host</code></em> +</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">char</span> *<em class="structfield"><code><a name="SoupURI-struct.query"></a>query</code></em>;</p></td> +<td class="struct_member_description"><p>a query for <em class="parameter"><code>path</code></em> +, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">char</span> *<em class="structfield"><code><a name="SoupURI-struct.fragment"></a>fragment</code></em>;</p></td> +<td class="struct_member_description"><p>a fragment identifier within <em class="parameter"><code>path</code></em> +, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="struct_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-URI-SCHEME-HTTP:CAPS"></a><h3>SOUP_URI_SCHEME_HTTP</h3> +<pre class="programlisting">#define SOUP_URI_SCHEME_HTTP _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_HTTP, "http") +</pre> +<p>"http" as an interned string; you can compare this directly to a +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>'s <code class="literal">scheme</code> field using +<code class="literal">==</code>.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-URI-SCHEME-HTTPS:CAPS"></a><h3>SOUP_URI_SCHEME_HTTPS</h3> +<pre class="programlisting">#define SOUP_URI_SCHEME_HTTPS _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_HTTPS, "https") +</pre> +<p>"https" as an interned string; you can compare this directly to a +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>'s <code class="literal">scheme</code> field using +<code class="literal">==</code>.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-URI-SCHEME-DATA:CAPS"></a><h3>SOUP_URI_SCHEME_DATA</h3> +<pre class="programlisting">#define SOUP_URI_SCHEME_DATA _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_DATA, "data") +</pre> +<p>"data" as an interned string; you can compare this directly to a +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>'s <code class="literal">scheme</code> field using +<code class="literal">==</code>.</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-URI-SCHEME-FILE:CAPS"></a><h3>SOUP_URI_SCHEME_FILE</h3> +<pre class="programlisting">#define SOUP_URI_SCHEME_FILE _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_FILE, "file") +</pre> +<p>"file" as an interned string; you can compare this directly to a +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>'s <code class="literal">scheme</code> field using +<code class="literal">==</code>.</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-URI-SCHEME-FTP:CAPS"></a><h3>SOUP_URI_SCHEME_FTP</h3> +<pre class="programlisting">#define SOUP_URI_SCHEME_FTP _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_FTP, "ftp") +</pre> +<p>"ftp" as an interned string; you can compare this directly to a +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>'s <code class="literal">scheme</code> field using +<code class="literal">==</code>.</p> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-URI-SCHEME-RESOURCE:CAPS"></a><h3>SOUP_URI_SCHEME_RESOURCE</h3> +<pre class="programlisting">#define SOUP_URI_SCHEME_RESOURCE _SOUP_ATOMIC_INTERN_STRING (_SOUP_URI_SCHEME_RESOURCE, "resource") +</pre> +<p>"data" as an interned string; you can compare this directly to a +<a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>'s <code class="literal">scheme</code> field using +<code class="literal">==</code>.</p> +<p class="since">Since 2.42</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/annotation-glossary.html b/docs/reference/html/annotation-glossary.html new file mode 100644 index 00000000..3ab52763 --- /dev/null +++ b/docs/reference/html/annotation-glossary.html @@ -0,0 +1,67 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Annotation Glossary</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="index.html" title="libsoup Reference Manual"> +<link rel="prev" href="ix01.html" title="Index"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"><span id="nav_glossary"><a class="shortcut" href="#glsA">A</a> + <span class="dim">|</span> + <a class="shortcut" href="#glsE">E</a> + <span class="dim">|</span> + <a class="shortcut" href="#glsI">I</a> + <span class="dim">|</span> + <a class="shortcut" href="#glsO">O</a> + <span class="dim">|</span> + <a class="shortcut" href="#glsS">S</a> + <span class="dim">|</span> + <a class="shortcut" href="#glsT">T</a></span></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><img src="up-insensitive.png" width="16" height="16" border="0"></td> +<td><a accesskey="p" href="ix01.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><img src="right-insensitive.png" width="16" height="16" border="0"></td> +</tr></table> +<div class="glossary"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="annotation-glossary"></a>Annotation Glossary</h1></div></div></div> +<a name="glsA"></a><h3 class="title">A</h3> +<dt><span class="glossterm"><a name="annotation-glossterm-allow-none"></a>allow-none</span></dt> +<dd class="glossdef"><p>NULL is ok, both for passing and for returning.</p></dd> +<dt><span class="glossterm"><a name="annotation-glossterm-array"></a>array</span></dt> +<dd class="glossdef"><p>Parameter points to an array of items.</p></dd> +<a name="glsE"></a><h3 class="title">E</h3> +<dt><span class="glossterm"><a name="annotation-glossterm-element-type"></a>element-type</span></dt> +<dd class="glossdef"><p>Generics and defining elements of containers and arrays.</p></dd> +<a name="glsI"></a><h3 class="title">I</h3> +<dt><span class="glossterm"><a name="annotation-glossterm-inout"></a>inout</span></dt> +<dd class="glossdef"><p>Parameter for input and for returning results. Default is <acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>.</p></dd> +<a name="glsO"></a><h3 class="title">O</h3> +<dt><span class="glossterm"><a name="annotation-glossterm-out"></a>out</span></dt> +<dd class="glossdef"><p>Parameter for returning results. Default is <acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>.</p></dd> +<a name="glsS"></a><h3 class="title">S</h3> +<dt><span class="glossterm"><a name="annotation-glossterm-scope%20async"></a>scope async</span></dt> +<dd class="glossdef"><p>The callback is valid until first called.</p></dd> +<dt><span class="glossterm"><a name="annotation-glossterm-scope%20call"></a>scope call</span></dt> +<dd class="glossdef"><p>The callback is valid only during the call to the method.</p></dd> +<a name="glsT"></a><h3 class="title">T</h3> +<dt><span class="glossterm"><a name="annotation-glossterm-transfer%20container"></a>transfer container</span></dt> +<dd class="glossdef"><p>Free data container after the code is done.</p></dd> +<dt><span class="glossterm"><a name="annotation-glossterm-transfer%20full"></a>transfer full</span></dt> +<dd class="glossdef"><p>Free data after the code is done.</p></dd> +<dt><span class="glossterm"><a name="annotation-glossterm-transfer%20none"></a>transfer none</span></dt> +<dd class="glossdef"><p>Don't free data after the code is done.</p></dd> +<dt><span class="glossterm"><a name="annotation-glossterm-type"></a>type</span></dt> +<dd class="glossdef"><p>Override the parsed C type with given type.</p></dd> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/ch01.html b/docs/reference/html/ch01.html new file mode 100644 index 00000000..4c7ea5e7 --- /dev/null +++ b/docs/reference/html/ch01.html @@ -0,0 +1,49 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Tutorial</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="index.html" title="libsoup Reference Manual"> +<link rel="prev" href="index.html" title="libsoup Reference Manual"> +<link rel="next" href="libsoup-build-howto.html" title="Compiling with libsoup"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><img src="up-insensitive.png" width="16" height="16" border="0"></td> +<td><a accesskey="p" href="index.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-build-howto.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="id-1.2"></a>Tutorial</h1></div></div></div> +<div class="toc"><dl class="toc"> +<dt> +<span class="refentrytitle"><a href="libsoup-build-howto.html">Compiling with libsoup</a></span><span class="refpurpose"> — Notes on compiling</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-client-howto.html">libsoup Client Basics</a></span><span class="refpurpose"> — Client-side tutorial</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-request-howto.html">libsoup Client SoupRequest API</a></span><span class="refpurpose"> — Using +libsoup with a mix of <code class="literal">http</code> and non-<code class="literal">http</code> URIs.</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-server-howto.html">Soup Server Basics</a></span><span class="refpurpose"> — Server-side tutorial</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-session-porting.html">Porting to the new SoupSession</a></span><span class="refpurpose"> — Notes on +porting from SoupSessionAsync and SoupSessionSync to SoupSession</span> +</dt> +</dl></div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/ch02.html b/docs/reference/html/ch02.html new file mode 100644 index 00000000..f81b5c84 --- /dev/null +++ b/docs/reference/html/ch02.html @@ -0,0 +1,109 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Core API</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="index.html" title="libsoup Reference Manual"> +<link rel="prev" href="libsoup-session-porting.html" title="Porting to the new SoupSession"> +<link rel="next" href="SoupAuth.html" title="SoupAuth"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><img src="up-insensitive.png" width="16" height="16" border="0"></td> +<td><a accesskey="p" href="libsoup-session-porting.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupAuth.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="id-1.3"></a>Core API</h1></div></div></div> +<div class="toc"><dl class="toc"> +<dt> +<span class="refentrytitle"><a href="SoupAuth.html">SoupAuth</a></span><span class="refpurpose"> — HTTP client-side authentication support</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupAuthDomain.html">SoupAuthDomain</a></span><span class="refpurpose"> — Server-side authentication</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupAuthDomainBasic.html">SoupAuthDomainBasic</a></span><span class="refpurpose"> — Server-side "Basic" authentication</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupAuthDomainDigest.html">SoupAuthDomainDigest</a></span><span class="refpurpose"> — Server-side "Digest" authentication</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupCache.html">SoupCache</a></span><span class="refpurpose"> — Caching support</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupCookie.html">SoupCookie</a></span><span class="refpurpose"> — HTTP Cookies</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupMessage.html">SoupMessage</a></span><span class="refpurpose"> — An HTTP request and response.</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupMessageHeaders.html">SoupMessageHeaders</a></span><span class="refpurpose"> — HTTP message headers</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupMessageBody.html">SoupMessageBody</a></span><span class="refpurpose"> — HTTP message body</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-soup-method.html">soup-method</a></span><span class="refpurpose"> — HTTP method definitions</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-Soup-Miscellaneous-Utilities.html">Soup Miscellaneous Utilities</a></span><span class="refpurpose"> — Miscellaneous functions</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupMultipart.html">SoupMultipart</a></span><span class="refpurpose"> — multipart HTTP message bodies</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupMultipartInputStream.html">SoupMultipartInputStream</a></span><span class="refpurpose"> — Multipart input handling stream</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupRequest.html">SoupRequest</a></span><span class="refpurpose"> — Protocol-independent streaming request interface</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupRequestHTTP.html">SoupRequestHTTP</a></span><span class="refpurpose"> — SoupRequest support for "http" and "https" URIs</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupRequestFile.html">SoupRequestFile</a></span><span class="refpurpose"> — SoupRequest support for "file" and "resource" URIs</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupRequestData.html">SoupRequestData</a></span><span class="refpurpose"> — SoupRequest support for "data" URIs</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupServer.html">SoupServer</a></span><span class="refpurpose"> — HTTP server</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupSession.html">SoupSession</a></span><span class="refpurpose"> — Soup session state object</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupSessionAsync.html">SoupSessionAsync</a></span><span class="refpurpose"> — (Deprecated) SoupSession for asynchronous + (main-loop-based) I/O.</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupSessionSync.html">SoupSessionSync</a></span><span class="refpurpose"> — (Deprecated) SoupSession for blocking I/O in + multithreaded programs.</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-soup-status.html">soup-status</a></span><span class="refpurpose"> — HTTP (and libsoup) status codes</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-Top-Level-Domain-utils.html">Top Level Domain utils</a></span><span class="refpurpose"> — Top-Level Domain Utilities</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupURI.html">SoupURI</a></span><span class="refpurpose"> — URIs</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-Version-Information.html">Version Information</a></span><span class="refpurpose"> — Variables and functions to check the libsoup version</span> +</dt> +</dl></div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/ch03.html b/docs/reference/html/ch03.html new file mode 100644 index 00000000..4a5a225c --- /dev/null +++ b/docs/reference/html/ch03.html @@ -0,0 +1,59 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Additional Features</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="index.html" title="libsoup Reference Manual"> +<link rel="prev" href="libsoup-2.4-Version-Information.html" title="Version Information"> +<link rel="next" href="SoupSessionFeature.html" title="SoupSessionFeature"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><img src="up-insensitive.png" width="16" height="16" border="0"></td> +<td><a accesskey="p" href="libsoup-2.4-Version-Information.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupSessionFeature.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="id-1.4"></a>Additional Features</h1></div></div></div> +<div class="toc"><dl class="toc"> +<dt> +<span class="refentrytitle"><a href="SoupSessionFeature.html">SoupSessionFeature</a></span><span class="refpurpose"> — Interface for miscellaneous session features</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupAuthManager.html">SoupAuthManager</a></span><span class="refpurpose"> — HTTP client-side authentication handler</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupContentDecoder.html">SoupContentDecoder</a></span><span class="refpurpose"> — Content-Encoding handler</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupContentSniffer.html">SoupContentSniffer</a></span><span class="refpurpose"> — Content sniffing for SoupSession</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupCookieJar.html">SoupCookieJar</a></span><span class="refpurpose"> — Automatic cookie handling for SoupSession</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupCookieJarText.html">SoupCookieJarText</a></span><span class="refpurpose"> — Text-file-based ("cookies.txt") Cookie Jar</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupCookieJarDB.html">SoupCookieJarDB</a></span><span class="refpurpose"> — Database-based Cookie Jar</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupLogger.html">SoupLogger</a></span><span class="refpurpose"> — Debug logging support</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupProxyResolverDefault.html">SoupProxyResolverDefault</a></span><span class="refpurpose"> — System proxy configuration integration</span> +</dt> +</dl></div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/ch04.html b/docs/reference/html/ch04.html new file mode 100644 index 00000000..293cb26a --- /dev/null +++ b/docs/reference/html/ch04.html @@ -0,0 +1,41 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Web Services APIs</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="index.html" title="libsoup Reference Manual"> +<link rel="prev" href="SoupProxyResolverDefault.html" title="SoupProxyResolverDefault"> +<link rel="next" href="libsoup-2.4-HTML-Form-Support.html" title="HTML Form Support"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><img src="up-insensitive.png" width="16" height="16" border="0"></td> +<td><a accesskey="p" href="SoupProxyResolverDefault.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-2.4-HTML-Form-Support.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="id-1.5"></a>Web Services APIs</h1></div></div></div> +<div class="toc"><dl class="toc"> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-HTML-Form-Support.html">HTML Form Support</a></span><span class="refpurpose"> — HTML form handling</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-XMLRPC-Support.html">XMLRPC Support</a></span><span class="refpurpose"> — XML-RPC support</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-GValue-Support.html">GValue Support</a></span><span class="refpurpose"> — GValue utilities</span> +</dt> +</dl></div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/ch05.html b/docs/reference/html/ch05.html new file mode 100644 index 00000000..3504c583 --- /dev/null +++ b/docs/reference/html/ch05.html @@ -0,0 +1,38 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Low-level Networking API</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="index.html" title="libsoup Reference Manual"> +<link rel="prev" href="libsoup-2.4-GValue-Support.html" title="GValue Support"> +<link rel="next" href="SoupAddress.html" title="SoupAddress"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><img src="up-insensitive.png" width="16" height="16" border="0"></td> +<td><a accesskey="p" href="libsoup-2.4-GValue-Support.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupAddress.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="chapter"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="id-1.6"></a>Low-level Networking API</h1></div></div></div> +<div class="toc"><dl class="toc"> +<dt> +<span class="refentrytitle"><a href="SoupAddress.html">SoupAddress</a></span><span class="refpurpose"> — DNS support</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupSocket.html">SoupSocket</a></span><span class="refpurpose"> — A network socket</span> +</dt> +</dl></div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/home.png b/docs/reference/html/home.png Binary files differnew file mode 100644 index 00000000..9346b336 --- /dev/null +++ b/docs/reference/html/home.png diff --git a/docs/reference/html/index.html b/docs/reference/html/index.html new file mode 100644 index 00000000..a7fdeb6c --- /dev/null +++ b/docs/reference/html/index.html @@ -0,0 +1,178 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: libsoup Reference Manual</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="next" href="ch01.html" title="Tutorial"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="book"> +<div class="titlepage"> +<div><div><table class="navigation" id="top" width="100%" cellpadding="2" cellspacing="0"><tr><th valign="middle"><p class="title">libsoup Reference Manual</p></th></tr></table></div></div> +<hr> +</div> +<div class="toc"><dl class="toc"> +<dt><span class="chapter"><a href="ch01.html">Tutorial</a></span></dt> +<dd><dl> +<dt> +<span class="refentrytitle"><a href="libsoup-build-howto.html">Compiling with libsoup</a></span><span class="refpurpose"> — Notes on compiling</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-client-howto.html">libsoup Client Basics</a></span><span class="refpurpose"> — Client-side tutorial</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-request-howto.html">libsoup Client SoupRequest API</a></span><span class="refpurpose"> — Using +libsoup with a mix of <code class="literal">http</code> and non-<code class="literal">http</code> URIs.</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-server-howto.html">Soup Server Basics</a></span><span class="refpurpose"> — Server-side tutorial</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-session-porting.html">Porting to the new SoupSession</a></span><span class="refpurpose"> — Notes on +porting from SoupSessionAsync and SoupSessionSync to SoupSession</span> +</dt> +</dl></dd> +<dt><span class="chapter"><a href="ch02.html">Core API</a></span></dt> +<dd><dl> +<dt> +<span class="refentrytitle"><a href="SoupAuth.html">SoupAuth</a></span><span class="refpurpose"> — HTTP client-side authentication support</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupAuthDomain.html">SoupAuthDomain</a></span><span class="refpurpose"> — Server-side authentication</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupAuthDomainBasic.html">SoupAuthDomainBasic</a></span><span class="refpurpose"> — Server-side "Basic" authentication</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupAuthDomainDigest.html">SoupAuthDomainDigest</a></span><span class="refpurpose"> — Server-side "Digest" authentication</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupCache.html">SoupCache</a></span><span class="refpurpose"> — Caching support</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupCookie.html">SoupCookie</a></span><span class="refpurpose"> — HTTP Cookies</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupMessage.html">SoupMessage</a></span><span class="refpurpose"> — An HTTP request and response.</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupMessageHeaders.html">SoupMessageHeaders</a></span><span class="refpurpose"> — HTTP message headers</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupMessageBody.html">SoupMessageBody</a></span><span class="refpurpose"> — HTTP message body</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-soup-method.html">soup-method</a></span><span class="refpurpose"> — HTTP method definitions</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-Soup-Miscellaneous-Utilities.html">Soup Miscellaneous Utilities</a></span><span class="refpurpose"> — Miscellaneous functions</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupMultipart.html">SoupMultipart</a></span><span class="refpurpose"> — multipart HTTP message bodies</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupMultipartInputStream.html">SoupMultipartInputStream</a></span><span class="refpurpose"> — Multipart input handling stream</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupRequest.html">SoupRequest</a></span><span class="refpurpose"> — Protocol-independent streaming request interface</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupRequestHTTP.html">SoupRequestHTTP</a></span><span class="refpurpose"> — SoupRequest support for "http" and "https" URIs</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupRequestFile.html">SoupRequestFile</a></span><span class="refpurpose"> — SoupRequest support for "file" and "resource" URIs</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupRequestData.html">SoupRequestData</a></span><span class="refpurpose"> — SoupRequest support for "data" URIs</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupServer.html">SoupServer</a></span><span class="refpurpose"> — HTTP server</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupSession.html">SoupSession</a></span><span class="refpurpose"> — Soup session state object</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupSessionAsync.html">SoupSessionAsync</a></span><span class="refpurpose"> — (Deprecated) SoupSession for asynchronous + (main-loop-based) I/O.</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupSessionSync.html">SoupSessionSync</a></span><span class="refpurpose"> — (Deprecated) SoupSession for blocking I/O in + multithreaded programs.</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-soup-status.html">soup-status</a></span><span class="refpurpose"> — HTTP (and libsoup) status codes</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-Top-Level-Domain-utils.html">Top Level Domain utils</a></span><span class="refpurpose"> — Top-Level Domain Utilities</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupURI.html">SoupURI</a></span><span class="refpurpose"> — URIs</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-Version-Information.html">Version Information</a></span><span class="refpurpose"> — Variables and functions to check the libsoup version</span> +</dt> +</dl></dd> +<dt><span class="chapter"><a href="ch03.html">Additional Features</a></span></dt> +<dd><dl> +<dt> +<span class="refentrytitle"><a href="SoupSessionFeature.html">SoupSessionFeature</a></span><span class="refpurpose"> — Interface for miscellaneous session features</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupAuthManager.html">SoupAuthManager</a></span><span class="refpurpose"> — HTTP client-side authentication handler</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupContentDecoder.html">SoupContentDecoder</a></span><span class="refpurpose"> — Content-Encoding handler</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupContentSniffer.html">SoupContentSniffer</a></span><span class="refpurpose"> — Content sniffing for SoupSession</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupCookieJar.html">SoupCookieJar</a></span><span class="refpurpose"> — Automatic cookie handling for SoupSession</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupCookieJarText.html">SoupCookieJarText</a></span><span class="refpurpose"> — Text-file-based ("cookies.txt") Cookie Jar</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupCookieJarDB.html">SoupCookieJarDB</a></span><span class="refpurpose"> — Database-based Cookie Jar</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupLogger.html">SoupLogger</a></span><span class="refpurpose"> — Debug logging support</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupProxyResolverDefault.html">SoupProxyResolverDefault</a></span><span class="refpurpose"> — System proxy configuration integration</span> +</dt> +</dl></dd> +<dt><span class="chapter"><a href="ch04.html">Web Services APIs</a></span></dt> +<dd><dl> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-HTML-Form-Support.html">HTML Form Support</a></span><span class="refpurpose"> — HTML form handling</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-XMLRPC-Support.html">XMLRPC Support</a></span><span class="refpurpose"> — XML-RPC support</span> +</dt> +<dt> +<span class="refentrytitle"><a href="libsoup-2.4-GValue-Support.html">GValue Support</a></span><span class="refpurpose"> — GValue utilities</span> +</dt> +</dl></dd> +<dt><span class="chapter"><a href="ch05.html">Low-level Networking API</a></span></dt> +<dd><dl> +<dt> +<span class="refentrytitle"><a href="SoupAddress.html">SoupAddress</a></span><span class="refpurpose"> — DNS support</span> +</dt> +<dt> +<span class="refentrytitle"><a href="SoupSocket.html">SoupSocket</a></span><span class="refpurpose"> — A network socket</span> +</dt> +</dl></dd> +<dt><span class="index"><a href="ix01.html">Index</a></span></dt> +<dt><span class="glossary"><a href="annotation-glossary.html">Annotation Glossary</a></span></dt> +</dl></div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/index.sgml b/docs/reference/html/index.sgml new file mode 100644 index 00000000..1bdba53b --- /dev/null +++ b/docs/reference/html/index.sgml @@ -0,0 +1,1128 @@ +<ANCHOR id="libsoup-build-howto" href="libsoup-2.4/libsoup-build-howto.html"> +<ANCHOR id="libsoup-client-howto" href="libsoup-2.4/libsoup-client-howto.html"> +<ANCHOR id="session-features" href="libsoup-2.4/libsoup-client-howto.html#session-features"> +<ANCHOR id="libsoup-request-howto" href="libsoup-2.4/libsoup-request-howto.html"> +<ANCHOR id="libsoup-server-howto" href="libsoup-2.4/libsoup-server-howto.html"> +<ANCHOR id="libsoup-session-porting" href="libsoup-2.4/libsoup-session-porting.html"> +<ANCHOR id="intro" href="libsoup-2.4/libsoup-session-porting.html#intro"> +<ANCHOR id="defaults" href="libsoup-2.4/libsoup-session-porting.html#defaults"> +<ANCHOR id="behavior" href="libsoup-2.4/libsoup-session-porting.html#behavior"> +<ANCHOR id="apis" href="libsoup-2.4/libsoup-session-porting.html#apis"> +<ANCHOR id="async" href="libsoup-2.4/libsoup-session-porting.html#async"> +<ANCHOR id="SoupAuth" href="libsoup-2.4/SoupAuth.html"> +<ANCHOR id="SoupAuth.functions" href="libsoup-2.4/SoupAuth.html#SoupAuth.functions"> +<ANCHOR id="SoupAuth.properties" href="libsoup-2.4/SoupAuth.html#SoupAuth.properties"> +<ANCHOR id="SoupAuth.other" href="libsoup-2.4/SoupAuth.html#SoupAuth.other"> +<ANCHOR id="SoupAuth.object-hierarchy" href="libsoup-2.4/SoupAuth.html#SoupAuth.object-hierarchy"> +<ANCHOR id="SoupAuth.includes" href="libsoup-2.4/SoupAuth.html#SoupAuth.includes"> +<ANCHOR id="SoupAuth.description" href="libsoup-2.4/SoupAuth.html#SoupAuth.description"> +<ANCHOR id="SoupAuth.functions_details" href="libsoup-2.4/SoupAuth.html#SoupAuth.functions_details"> +<ANCHOR id="soup-auth-new" href="libsoup-2.4/SoupAuth.html#soup-auth-new"> +<ANCHOR id="soup-auth-update" href="libsoup-2.4/SoupAuth.html#soup-auth-update"> +<ANCHOR id="SOUP-TYPE-AUTH-BASIC:CAPS" href="libsoup-2.4/SoupAuth.html#SOUP-TYPE-AUTH-BASIC:CAPS"> +<ANCHOR id="SOUP-TYPE-AUTH-DIGEST:CAPS" href="libsoup-2.4/SoupAuth.html#SOUP-TYPE-AUTH-DIGEST:CAPS"> +<ANCHOR id="SOUP-TYPE-AUTH-NTLM:CAPS" href="libsoup-2.4/SoupAuth.html#SOUP-TYPE-AUTH-NTLM:CAPS"> +<ANCHOR id="soup-auth-is-for-proxy" href="libsoup-2.4/SoupAuth.html#soup-auth-is-for-proxy"> +<ANCHOR id="soup-auth-get-scheme-name" href="libsoup-2.4/SoupAuth.html#soup-auth-get-scheme-name"> +<ANCHOR id="soup-auth-get-host" href="libsoup-2.4/SoupAuth.html#soup-auth-get-host"> +<ANCHOR id="soup-auth-get-realm" href="libsoup-2.4/SoupAuth.html#soup-auth-get-realm"> +<ANCHOR id="soup-auth-get-info" href="libsoup-2.4/SoupAuth.html#soup-auth-get-info"> +<ANCHOR id="soup-auth-authenticate" href="libsoup-2.4/SoupAuth.html#soup-auth-authenticate"> +<ANCHOR id="soup-auth-is-authenticated" href="libsoup-2.4/SoupAuth.html#soup-auth-is-authenticated"> +<ANCHOR id="soup-auth-is-ready" href="libsoup-2.4/SoupAuth.html#soup-auth-is-ready"> +<ANCHOR id="soup-auth-get-authorization" href="libsoup-2.4/SoupAuth.html#soup-auth-get-authorization"> +<ANCHOR id="soup-auth-get-protection-space" href="libsoup-2.4/SoupAuth.html#soup-auth-get-protection-space"> +<ANCHOR id="soup-auth-free-protection-space" href="libsoup-2.4/SoupAuth.html#soup-auth-free-protection-space"> +<ANCHOR id="SoupAuth.other_details" href="libsoup-2.4/SoupAuth.html#SoupAuth.other_details"> +<ANCHOR id="SoupAuth-struct" href="libsoup-2.4/SoupAuth.html#SoupAuth-struct"> +<ANCHOR id="SOUP-AUTH-SCHEME-NAME:CAPS" href="libsoup-2.4/SoupAuth.html#SOUP-AUTH-SCHEME-NAME:CAPS"> +<ANCHOR id="SOUP-AUTH-REALM:CAPS" href="libsoup-2.4/SoupAuth.html#SOUP-AUTH-REALM:CAPS"> +<ANCHOR id="SOUP-AUTH-HOST:CAPS" href="libsoup-2.4/SoupAuth.html#SOUP-AUTH-HOST:CAPS"> +<ANCHOR id="SOUP-AUTH-IS-FOR-PROXY:CAPS" href="libsoup-2.4/SoupAuth.html#SOUP-AUTH-IS-FOR-PROXY:CAPS"> +<ANCHOR id="SOUP-AUTH-IS-AUTHENTICATED:CAPS" href="libsoup-2.4/SoupAuth.html#SOUP-AUTH-IS-AUTHENTICATED:CAPS"> +<ANCHOR id="SoupAuth.property-details" href="libsoup-2.4/SoupAuth.html#SoupAuth.property-details"> +<ANCHOR id="SoupAuth--host" href="libsoup-2.4/SoupAuth.html#SoupAuth--host"> +<ANCHOR id="SoupAuth--is-authenticated" href="libsoup-2.4/SoupAuth.html#SoupAuth--is-authenticated"> +<ANCHOR id="SoupAuth--is-for-proxy" href="libsoup-2.4/SoupAuth.html#SoupAuth--is-for-proxy"> +<ANCHOR id="SoupAuth--realm" href="libsoup-2.4/SoupAuth.html#SoupAuth--realm"> +<ANCHOR id="SoupAuth--scheme-name" href="libsoup-2.4/SoupAuth.html#SoupAuth--scheme-name"> +<ANCHOR id="SoupAuth.see-also" href="libsoup-2.4/SoupAuth.html#SoupAuth.see-also"> +<ANCHOR id="SoupAuthDomain" href="libsoup-2.4/SoupAuthDomain.html"> +<ANCHOR id="SoupAuthDomain.functions" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain.functions"> +<ANCHOR id="SoupAuthDomain.properties" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain.properties"> +<ANCHOR id="SoupAuthDomain.other" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain.other"> +<ANCHOR id="SoupAuthDomain.object-hierarchy" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain.object-hierarchy"> +<ANCHOR id="SoupAuthDomain.includes" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain.includes"> +<ANCHOR id="SoupAuthDomain.description" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain.description"> +<ANCHOR id="SoupAuthDomain.functions_details" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain.functions_details"> +<ANCHOR id="soup-auth-domain-add-path" href="libsoup-2.4/SoupAuthDomain.html#soup-auth-domain-add-path"> +<ANCHOR id="soup-auth-domain-remove-path" href="libsoup-2.4/SoupAuthDomain.html#soup-auth-domain-remove-path"> +<ANCHOR id="SoupAuthDomainFilter" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomainFilter"> +<ANCHOR id="soup-auth-domain-set-filter" href="libsoup-2.4/SoupAuthDomain.html#soup-auth-domain-set-filter"> +<ANCHOR id="soup-auth-domain-get-realm" href="libsoup-2.4/SoupAuthDomain.html#soup-auth-domain-get-realm"> +<ANCHOR id="SoupAuthDomainGenericAuthCallback" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomainGenericAuthCallback"> +<ANCHOR id="soup-auth-domain-set-generic-auth-callback" href="libsoup-2.4/SoupAuthDomain.html#soup-auth-domain-set-generic-auth-callback"> +<ANCHOR id="soup-auth-domain-check-password" href="libsoup-2.4/SoupAuthDomain.html#soup-auth-domain-check-password"> +<ANCHOR id="soup-auth-domain-covers" href="libsoup-2.4/SoupAuthDomain.html#soup-auth-domain-covers"> +<ANCHOR id="soup-auth-domain-accepts" href="libsoup-2.4/SoupAuthDomain.html#soup-auth-domain-accepts"> +<ANCHOR id="soup-auth-domain-challenge" href="libsoup-2.4/SoupAuthDomain.html#soup-auth-domain-challenge"> +<ANCHOR id="SoupAuthDomain.other_details" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain.other_details"> +<ANCHOR id="SoupAuthDomain-struct" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain-struct"> +<ANCHOR id="SOUP-AUTH-DOMAIN-REALM:CAPS" href="libsoup-2.4/SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REALM:CAPS"> +<ANCHOR id="SOUP-AUTH-DOMAIN-PROXY:CAPS" href="libsoup-2.4/SoupAuthDomain.html#SOUP-AUTH-DOMAIN-PROXY:CAPS"> +<ANCHOR id="SOUP-AUTH-DOMAIN-ADD-PATH:CAPS" href="libsoup-2.4/SoupAuthDomain.html#SOUP-AUTH-DOMAIN-ADD-PATH:CAPS"> +<ANCHOR id="SOUP-AUTH-DOMAIN-REMOVE-PATH:CAPS" href="libsoup-2.4/SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REMOVE-PATH:CAPS"> +<ANCHOR id="SOUP-AUTH-DOMAIN-FILTER:CAPS" href="libsoup-2.4/SoupAuthDomain.html#SOUP-AUTH-DOMAIN-FILTER:CAPS"> +<ANCHOR id="SOUP-AUTH-DOMAIN-FILTER-DATA:CAPS" href="libsoup-2.4/SoupAuthDomain.html#SOUP-AUTH-DOMAIN-FILTER-DATA:CAPS"> +<ANCHOR id="SOUP-AUTH-DOMAIN-GENERIC-AUTH-CALLBACK:CAPS" href="libsoup-2.4/SoupAuthDomain.html#SOUP-AUTH-DOMAIN-GENERIC-AUTH-CALLBACK:CAPS"> +<ANCHOR id="SOUP-AUTH-DOMAIN-GENERIC-AUTH-DATA:CAPS" href="libsoup-2.4/SoupAuthDomain.html#SOUP-AUTH-DOMAIN-GENERIC-AUTH-DATA:CAPS"> +<ANCHOR id="SoupAuthDomain.property-details" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain.property-details"> +<ANCHOR id="SoupAuthDomain--add-path" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain--add-path"> +<ANCHOR id="SoupAuthDomain--filter" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain--filter"> +<ANCHOR id="SoupAuthDomain--filter-data" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain--filter-data"> +<ANCHOR id="SoupAuthDomain--generic-auth-callback" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain--generic-auth-callback"> +<ANCHOR id="SoupAuthDomain--generic-auth-data" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain--generic-auth-data"> +<ANCHOR id="SoupAuthDomain--proxy" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain--proxy"> +<ANCHOR id="SoupAuthDomain--realm" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain--realm"> +<ANCHOR id="SoupAuthDomain--remove-path" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain--remove-path"> +<ANCHOR id="SoupAuthDomain.see-also" href="libsoup-2.4/SoupAuthDomain.html#SoupAuthDomain.see-also"> +<ANCHOR id="SoupAuthDomainBasic" href="libsoup-2.4/SoupAuthDomainBasic.html"> +<ANCHOR id="SoupAuthDomainBasic.functions" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic.functions"> +<ANCHOR id="SoupAuthDomainBasic.properties" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic.properties"> +<ANCHOR id="SoupAuthDomainBasic.other" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic.other"> +<ANCHOR id="SoupAuthDomainBasic.object-hierarchy" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic.object-hierarchy"> +<ANCHOR id="SoupAuthDomainBasic.includes" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic.includes"> +<ANCHOR id="SoupAuthDomainBasic.description" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic.description"> +<ANCHOR id="SoupAuthDomainBasic.functions_details" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic.functions_details"> +<ANCHOR id="soup-auth-domain-basic-new" href="libsoup-2.4/SoupAuthDomainBasic.html#soup-auth-domain-basic-new"> +<ANCHOR id="SoupAuthDomainBasicAuthCallback" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasicAuthCallback"> +<ANCHOR id="soup-auth-domain-basic-set-auth-callback" href="libsoup-2.4/SoupAuthDomainBasic.html#soup-auth-domain-basic-set-auth-callback"> +<ANCHOR id="SoupAuthDomainBasic.other_details" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic.other_details"> +<ANCHOR id="SoupAuthDomainBasic-struct" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic-struct"> +<ANCHOR id="SOUP-AUTH-DOMAIN-BASIC-AUTH-CALLBACK:CAPS" href="libsoup-2.4/SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-CALLBACK:CAPS"> +<ANCHOR id="SOUP-AUTH-DOMAIN-BASIC-AUTH-DATA:CAPS" href="libsoup-2.4/SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-DATA:CAPS"> +<ANCHOR id="SoupAuthDomainBasic.property-details" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic.property-details"> +<ANCHOR id="SoupAuthDomainBasic--auth-callback" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic--auth-callback"> +<ANCHOR id="SoupAuthDomainBasic--auth-data" href="libsoup-2.4/SoupAuthDomainBasic.html#SoupAuthDomainBasic--auth-data"> +<ANCHOR id="SoupAuthDomainDigest" href="libsoup-2.4/SoupAuthDomainDigest.html"> +<ANCHOR id="SoupAuthDomainDigest.functions" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest.functions"> +<ANCHOR id="SoupAuthDomainDigest.properties" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest.properties"> +<ANCHOR id="SoupAuthDomainDigest.other" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest.other"> +<ANCHOR id="SoupAuthDomainDigest.object-hierarchy" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest.object-hierarchy"> +<ANCHOR id="SoupAuthDomainDigest.includes" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest.includes"> +<ANCHOR id="SoupAuthDomainDigest.description" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest.description"> +<ANCHOR id="SoupAuthDomainDigest.functions_details" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest.functions_details"> +<ANCHOR id="soup-auth-domain-digest-new" href="libsoup-2.4/SoupAuthDomainDigest.html#soup-auth-domain-digest-new"> +<ANCHOR id="SoupAuthDomainDigestAuthCallback" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigestAuthCallback"> +<ANCHOR id="soup-auth-domain-digest-set-auth-callback" href="libsoup-2.4/SoupAuthDomainDigest.html#soup-auth-domain-digest-set-auth-callback"> +<ANCHOR id="soup-auth-domain-digest-encode-password" href="libsoup-2.4/SoupAuthDomainDigest.html#soup-auth-domain-digest-encode-password"> +<ANCHOR id="SoupAuthDomainDigest.other_details" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest.other_details"> +<ANCHOR id="SoupAuthDomainDigest-struct" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest-struct"> +<ANCHOR id="SOUP-AUTH-DOMAIN-DIGEST-AUTH-CALLBACK:CAPS" href="libsoup-2.4/SoupAuthDomainDigest.html#SOUP-AUTH-DOMAIN-DIGEST-AUTH-CALLBACK:CAPS"> +<ANCHOR id="SOUP-AUTH-DOMAIN-DIGEST-AUTH-DATA:CAPS" href="libsoup-2.4/SoupAuthDomainDigest.html#SOUP-AUTH-DOMAIN-DIGEST-AUTH-DATA:CAPS"> +<ANCHOR id="SoupAuthDomainDigest.property-details" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest.property-details"> +<ANCHOR id="SoupAuthDomainDigest--auth-callback" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest--auth-callback"> +<ANCHOR id="SoupAuthDomainDigest--auth-data" href="libsoup-2.4/SoupAuthDomainDigest.html#SoupAuthDomainDigest--auth-data"> +<ANCHOR id="SoupCache" href="libsoup-2.4/SoupCache.html"> +<ANCHOR id="SoupCache.functions" href="libsoup-2.4/SoupCache.html#SoupCache.functions"> +<ANCHOR id="SoupCache.properties" href="libsoup-2.4/SoupCache.html#SoupCache.properties"> +<ANCHOR id="SoupCache.other" href="libsoup-2.4/SoupCache.html#SoupCache.other"> +<ANCHOR id="SoupCache.object-hierarchy" href="libsoup-2.4/SoupCache.html#SoupCache.object-hierarchy"> +<ANCHOR id="SoupCache.implemented-interfaces" href="libsoup-2.4/SoupCache.html#SoupCache.implemented-interfaces"> +<ANCHOR id="SoupCache.includes" href="libsoup-2.4/SoupCache.html#SoupCache.includes"> +<ANCHOR id="SoupCache.description" href="libsoup-2.4/SoupCache.html#SoupCache.description"> +<ANCHOR id="SoupCache.functions_details" href="libsoup-2.4/SoupCache.html#SoupCache.functions_details"> +<ANCHOR id="soup-cache-new" href="libsoup-2.4/SoupCache.html#soup-cache-new"> +<ANCHOR id="soup-cache-flush" href="libsoup-2.4/SoupCache.html#soup-cache-flush"> +<ANCHOR id="soup-cache-clear" href="libsoup-2.4/SoupCache.html#soup-cache-clear"> +<ANCHOR id="soup-cache-dump" href="libsoup-2.4/SoupCache.html#soup-cache-dump"> +<ANCHOR id="soup-cache-load" href="libsoup-2.4/SoupCache.html#soup-cache-load"> +<ANCHOR id="soup-cache-get-max-size" href="libsoup-2.4/SoupCache.html#soup-cache-get-max-size"> +<ANCHOR id="soup-cache-set-max-size" href="libsoup-2.4/SoupCache.html#soup-cache-set-max-size"> +<ANCHOR id="SoupCache.other_details" href="libsoup-2.4/SoupCache.html#SoupCache.other_details"> +<ANCHOR id="SoupCache-struct" href="libsoup-2.4/SoupCache.html#SoupCache-struct"> +<ANCHOR id="SoupCacheType" href="libsoup-2.4/SoupCache.html#SoupCacheType"> +<ANCHOR id="SoupCache.property-details" href="libsoup-2.4/SoupCache.html#SoupCache.property-details"> +<ANCHOR id="SoupCache--cache-dir" href="libsoup-2.4/SoupCache.html#SoupCache--cache-dir"> +<ANCHOR id="SoupCache--cache-type" href="libsoup-2.4/SoupCache.html#SoupCache--cache-type"> +<ANCHOR id="SoupCookie" href="libsoup-2.4/SoupCookie.html"> +<ANCHOR id="SoupCookie.functions" href="libsoup-2.4/SoupCookie.html#SoupCookie.functions"> +<ANCHOR id="SoupCookie.other" href="libsoup-2.4/SoupCookie.html#SoupCookie.other"> +<ANCHOR id="SoupCookie.object-hierarchy" href="libsoup-2.4/SoupCookie.html#SoupCookie.object-hierarchy"> +<ANCHOR id="SoupCookie.includes" href="libsoup-2.4/SoupCookie.html#SoupCookie.includes"> +<ANCHOR id="SoupCookie.description" href="libsoup-2.4/SoupCookie.html#SoupCookie.description"> +<ANCHOR id="SoupCookie.functions_details" href="libsoup-2.4/SoupCookie.html#SoupCookie.functions_details"> +<ANCHOR id="soup-cookie-new" href="libsoup-2.4/SoupCookie.html#soup-cookie-new"> +<ANCHOR id="soup-cookie-parse" href="libsoup-2.4/SoupCookie.html#soup-cookie-parse"> +<ANCHOR id="soup-cookie-copy" href="libsoup-2.4/SoupCookie.html#soup-cookie-copy"> +<ANCHOR id="soup-cookie-free" href="libsoup-2.4/SoupCookie.html#soup-cookie-free"> +<ANCHOR id="soup-cookie-set-name" href="libsoup-2.4/SoupCookie.html#soup-cookie-set-name"> +<ANCHOR id="soup-cookie-get-name" href="libsoup-2.4/SoupCookie.html#soup-cookie-get-name"> +<ANCHOR id="soup-cookie-set-value" href="libsoup-2.4/SoupCookie.html#soup-cookie-set-value"> +<ANCHOR id="soup-cookie-get-value" href="libsoup-2.4/SoupCookie.html#soup-cookie-get-value"> +<ANCHOR id="soup-cookie-set-domain" href="libsoup-2.4/SoupCookie.html#soup-cookie-set-domain"> +<ANCHOR id="soup-cookie-get-domain" href="libsoup-2.4/SoupCookie.html#soup-cookie-get-domain"> +<ANCHOR id="soup-cookie-set-path" href="libsoup-2.4/SoupCookie.html#soup-cookie-set-path"> +<ANCHOR id="soup-cookie-get-path" href="libsoup-2.4/SoupCookie.html#soup-cookie-get-path"> +<ANCHOR id="soup-cookie-set-max-age" href="libsoup-2.4/SoupCookie.html#soup-cookie-set-max-age"> +<ANCHOR id="SOUP-COOKIE-MAX-AGE-ONE-HOUR:CAPS" href="libsoup-2.4/SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-HOUR:CAPS"> +<ANCHOR id="SOUP-COOKIE-MAX-AGE-ONE-DAY:CAPS" href="libsoup-2.4/SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-DAY:CAPS"> +<ANCHOR id="SOUP-COOKIE-MAX-AGE-ONE-WEEK:CAPS" href="libsoup-2.4/SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-WEEK:CAPS"> +<ANCHOR id="SOUP-COOKIE-MAX-AGE-ONE-YEAR:CAPS" href="libsoup-2.4/SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-YEAR:CAPS"> +<ANCHOR id="soup-cookie-set-expires" href="libsoup-2.4/SoupCookie.html#soup-cookie-set-expires"> +<ANCHOR id="soup-cookie-get-expires" href="libsoup-2.4/SoupCookie.html#soup-cookie-get-expires"> +<ANCHOR id="soup-cookie-set-secure" href="libsoup-2.4/SoupCookie.html#soup-cookie-set-secure"> +<ANCHOR id="soup-cookie-get-secure" href="libsoup-2.4/SoupCookie.html#soup-cookie-get-secure"> +<ANCHOR id="soup-cookie-set-http-only" href="libsoup-2.4/SoupCookie.html#soup-cookie-set-http-only"> +<ANCHOR id="soup-cookie-get-http-only" href="libsoup-2.4/SoupCookie.html#soup-cookie-get-http-only"> +<ANCHOR id="soup-cookie-applies-to-uri" href="libsoup-2.4/SoupCookie.html#soup-cookie-applies-to-uri"> +<ANCHOR id="soup-cookie-domain-matches" href="libsoup-2.4/SoupCookie.html#soup-cookie-domain-matches"> +<ANCHOR id="soup-cookie-to-cookie-header" href="libsoup-2.4/SoupCookie.html#soup-cookie-to-cookie-header"> +<ANCHOR id="soup-cookie-to-set-cookie-header" href="libsoup-2.4/SoupCookie.html#soup-cookie-to-set-cookie-header"> +<ANCHOR id="soup-cookies-from-request" href="libsoup-2.4/SoupCookie.html#soup-cookies-from-request"> +<ANCHOR id="soup-cookies-from-response" href="libsoup-2.4/SoupCookie.html#soup-cookies-from-response"> +<ANCHOR id="soup-cookies-to-request" href="libsoup-2.4/SoupCookie.html#soup-cookies-to-request"> +<ANCHOR id="soup-cookies-to-response" href="libsoup-2.4/SoupCookie.html#soup-cookies-to-response"> +<ANCHOR id="soup-cookies-to-cookie-header" href="libsoup-2.4/SoupCookie.html#soup-cookies-to-cookie-header"> +<ANCHOR id="soup-cookies-free" href="libsoup-2.4/SoupCookie.html#soup-cookies-free"> +<ANCHOR id="SoupCookie.other_details" href="libsoup-2.4/SoupCookie.html#SoupCookie.other_details"> +<ANCHOR id="SoupCookie-struct" href="libsoup-2.4/SoupCookie.html#SoupCookie-struct"> +<ANCHOR id="SoupCookie.see-also" href="libsoup-2.4/SoupCookie.html#SoupCookie.see-also"> +<ANCHOR id="SoupMessage" href="libsoup-2.4/SoupMessage.html"> +<ANCHOR id="SoupMessage.functions" href="libsoup-2.4/SoupMessage.html#SoupMessage.functions"> +<ANCHOR id="SoupMessage.properties" href="libsoup-2.4/SoupMessage.html#SoupMessage.properties"> +<ANCHOR id="SoupMessage.signals" href="libsoup-2.4/SoupMessage.html#SoupMessage.signals"> +<ANCHOR id="SoupMessage.other" href="libsoup-2.4/SoupMessage.html#SoupMessage.other"> +<ANCHOR id="SoupMessage.object-hierarchy" href="libsoup-2.4/SoupMessage.html#SoupMessage.object-hierarchy"> +<ANCHOR id="SoupMessage.includes" href="libsoup-2.4/SoupMessage.html#SoupMessage.includes"> +<ANCHOR id="SoupMessage.description" href="libsoup-2.4/SoupMessage.html#SoupMessage.description"> +<ANCHOR id="SoupMessage.functions_details" href="libsoup-2.4/SoupMessage.html#SoupMessage.functions_details"> +<ANCHOR id="soup-message-new" href="libsoup-2.4/SoupMessage.html#soup-message-new"> +<ANCHOR id="soup-message-new-from-uri" href="libsoup-2.4/SoupMessage.html#soup-message-new-from-uri"> +<ANCHOR id="soup-message-set-request" href="libsoup-2.4/SoupMessage.html#soup-message-set-request"> +<ANCHOR id="soup-message-set-response" href="libsoup-2.4/SoupMessage.html#soup-message-set-response"> +<ANCHOR id="soup-message-set-http-version" href="libsoup-2.4/SoupMessage.html#soup-message-set-http-version"> +<ANCHOR id="soup-message-get-http-version" href="libsoup-2.4/SoupMessage.html#soup-message-get-http-version"> +<ANCHOR id="soup-message-get-uri" href="libsoup-2.4/SoupMessage.html#soup-message-get-uri"> +<ANCHOR id="soup-message-set-uri" href="libsoup-2.4/SoupMessage.html#soup-message-set-uri"> +<ANCHOR id="soup-message-get-address" href="libsoup-2.4/SoupMessage.html#soup-message-get-address"> +<ANCHOR id="soup-message-set-status" href="libsoup-2.4/SoupMessage.html#soup-message-set-status"> +<ANCHOR id="soup-message-set-status-full" href="libsoup-2.4/SoupMessage.html#soup-message-set-status-full"> +<ANCHOR id="soup-message-set-redirect" href="libsoup-2.4/SoupMessage.html#soup-message-set-redirect"> +<ANCHOR id="soup-message-is-keepalive" href="libsoup-2.4/SoupMessage.html#soup-message-is-keepalive"> +<ANCHOR id="soup-message-get-https-status" href="libsoup-2.4/SoupMessage.html#soup-message-get-https-status"> +<ANCHOR id="soup-message-set-first-party" href="libsoup-2.4/SoupMessage.html#soup-message-set-first-party"> +<ANCHOR id="soup-message-get-first-party" href="libsoup-2.4/SoupMessage.html#soup-message-get-first-party"> +<ANCHOR id="soup-message-add-header-handler" href="libsoup-2.4/SoupMessage.html#soup-message-add-header-handler"> +<ANCHOR id="soup-message-add-status-code-handler" href="libsoup-2.4/SoupMessage.html#soup-message-add-status-code-handler"> +<ANCHOR id="soup-message-set-flags" href="libsoup-2.4/SoupMessage.html#soup-message-set-flags"> +<ANCHOR id="soup-message-get-flags" href="libsoup-2.4/SoupMessage.html#soup-message-get-flags"> +<ANCHOR id="SoupChunkAllocator" href="libsoup-2.4/SoupMessage.html#SoupChunkAllocator"> +<ANCHOR id="soup-message-set-chunk-allocator" href="libsoup-2.4/SoupMessage.html#soup-message-set-chunk-allocator"> +<ANCHOR id="soup-message-disable-feature" href="libsoup-2.4/SoupMessage.html#soup-message-disable-feature"> +<ANCHOR id="soup-message-get-soup-request" href="libsoup-2.4/SoupMessage.html#soup-message-get-soup-request"> +<ANCHOR id="soup-message-get-priority" href="libsoup-2.4/SoupMessage.html#soup-message-get-priority"> +<ANCHOR id="soup-message-set-priority" href="libsoup-2.4/SoupMessage.html#soup-message-set-priority"> +<ANCHOR id="SoupMessage.other_details" href="libsoup-2.4/SoupMessage.html#SoupMessage.other_details"> +<ANCHOR id="SoupMessage-struct" href="libsoup-2.4/SoupMessage.html#SoupMessage-struct"> +<ANCHOR id="SoupHTTPVersion" href="libsoup-2.4/SoupMessage.html#SoupHTTPVersion"> +<ANCHOR id="SoupMessageFlags" href="libsoup-2.4/SoupMessage.html#SoupMessageFlags"> +<ANCHOR id="SoupMessagePriority" href="libsoup-2.4/SoupMessage.html#SoupMessagePriority"> +<ANCHOR id="SOUP-MESSAGE-METHOD:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-METHOD:CAPS"> +<ANCHOR id="SOUP-MESSAGE-URI:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-URI:CAPS"> +<ANCHOR id="SOUP-MESSAGE-HTTP-VERSION:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-HTTP-VERSION:CAPS"> +<ANCHOR id="SOUP-MESSAGE-FLAGS:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-FLAGS:CAPS"> +<ANCHOR id="SOUP-MESSAGE-STATUS-CODE:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-STATUS-CODE:CAPS"> +<ANCHOR id="SOUP-MESSAGE-REASON-PHRASE:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-REASON-PHRASE:CAPS"> +<ANCHOR id="SOUP-MESSAGE-SERVER-SIDE:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-SERVER-SIDE:CAPS"> +<ANCHOR id="SOUP-MESSAGE-FIRST-PARTY:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-FIRST-PARTY:CAPS"> +<ANCHOR id="SOUP-MESSAGE-PRIORITY:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-PRIORITY:CAPS"> +<ANCHOR id="SOUP-MESSAGE-REQUEST-BODY:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-REQUEST-BODY:CAPS"> +<ANCHOR id="SOUP-MESSAGE-REQUEST-BODY-DATA:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-REQUEST-BODY-DATA:CAPS"> +<ANCHOR id="SOUP-MESSAGE-REQUEST-HEADERS:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-REQUEST-HEADERS:CAPS"> +<ANCHOR id="SOUP-MESSAGE-RESPONSE-BODY:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-RESPONSE-BODY:CAPS"> +<ANCHOR id="SOUP-MESSAGE-RESPONSE-BODY-DATA:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-RESPONSE-BODY-DATA:CAPS"> +<ANCHOR id="SOUP-MESSAGE-RESPONSE-HEADERS:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-RESPONSE-HEADERS:CAPS"> +<ANCHOR id="SOUP-MESSAGE-TLS-CERTIFICATE:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-TLS-CERTIFICATE:CAPS"> +<ANCHOR id="SOUP-MESSAGE-TLS-ERRORS:CAPS" href="libsoup-2.4/SoupMessage.html#SOUP-MESSAGE-TLS-ERRORS:CAPS"> +<ANCHOR id="SoupMessage.property-details" href="libsoup-2.4/SoupMessage.html#SoupMessage.property-details"> +<ANCHOR id="SoupMessage--first-party" href="libsoup-2.4/SoupMessage.html#SoupMessage--first-party"> +<ANCHOR id="SoupMessage--flags" href="libsoup-2.4/SoupMessage.html#SoupMessage--flags"> +<ANCHOR id="SoupMessage--http-version" href="libsoup-2.4/SoupMessage.html#SoupMessage--http-version"> +<ANCHOR id="SoupMessage--method" href="libsoup-2.4/SoupMessage.html#SoupMessage--method"> +<ANCHOR id="SoupMessage--priority" href="libsoup-2.4/SoupMessage.html#SoupMessage--priority"> +<ANCHOR id="SoupMessage--reason-phrase" href="libsoup-2.4/SoupMessage.html#SoupMessage--reason-phrase"> +<ANCHOR id="SoupMessage--request-body" href="libsoup-2.4/SoupMessage.html#SoupMessage--request-body"> +<ANCHOR id="SoupMessage--request-body-data" href="libsoup-2.4/SoupMessage.html#SoupMessage--request-body-data"> +<ANCHOR id="SoupMessage--request-headers" href="libsoup-2.4/SoupMessage.html#SoupMessage--request-headers"> +<ANCHOR id="SoupMessage--response-body" href="libsoup-2.4/SoupMessage.html#SoupMessage--response-body"> +<ANCHOR id="SoupMessage--response-body-data" href="libsoup-2.4/SoupMessage.html#SoupMessage--response-body-data"> +<ANCHOR id="SoupMessage--response-headers" href="libsoup-2.4/SoupMessage.html#SoupMessage--response-headers"> +<ANCHOR id="SoupMessage--server-side" href="libsoup-2.4/SoupMessage.html#SoupMessage--server-side"> +<ANCHOR id="SoupMessage--status-code" href="libsoup-2.4/SoupMessage.html#SoupMessage--status-code"> +<ANCHOR id="SoupMessage--tls-certificate" href="libsoup-2.4/SoupMessage.html#SoupMessage--tls-certificate"> +<ANCHOR id="SoupMessage--tls-errors" href="libsoup-2.4/SoupMessage.html#SoupMessage--tls-errors"> +<ANCHOR id="SoupMessage--uri" href="libsoup-2.4/SoupMessage.html#SoupMessage--uri"> +<ANCHOR id="SoupMessage.signal-details" href="libsoup-2.4/SoupMessage.html#SoupMessage.signal-details"> +<ANCHOR id="SoupMessage-content-sniffed" href="libsoup-2.4/SoupMessage.html#SoupMessage-content-sniffed"> +<ANCHOR id="SoupMessage-finished" href="libsoup-2.4/SoupMessage.html#SoupMessage-finished"> +<ANCHOR id="SoupMessage-got-body" href="libsoup-2.4/SoupMessage.html#SoupMessage-got-body"> +<ANCHOR id="SoupMessage-got-chunk" href="libsoup-2.4/SoupMessage.html#SoupMessage-got-chunk"> +<ANCHOR id="SoupMessage-got-headers" href="libsoup-2.4/SoupMessage.html#SoupMessage-got-headers"> +<ANCHOR id="SoupMessage-got-informational" href="libsoup-2.4/SoupMessage.html#SoupMessage-got-informational"> +<ANCHOR id="SoupMessage-network-event" href="libsoup-2.4/SoupMessage.html#SoupMessage-network-event"> +<ANCHOR id="SoupMessage-restarted" href="libsoup-2.4/SoupMessage.html#SoupMessage-restarted"> +<ANCHOR id="SoupMessage-wrote-body" href="libsoup-2.4/SoupMessage.html#SoupMessage-wrote-body"> +<ANCHOR id="SoupMessage-wrote-body-data" href="libsoup-2.4/SoupMessage.html#SoupMessage-wrote-body-data"> +<ANCHOR id="SoupMessage-wrote-chunk" href="libsoup-2.4/SoupMessage.html#SoupMessage-wrote-chunk"> +<ANCHOR id="SoupMessage-wrote-headers" href="libsoup-2.4/SoupMessage.html#SoupMessage-wrote-headers"> +<ANCHOR id="SoupMessage-wrote-informational" href="libsoup-2.4/SoupMessage.html#SoupMessage-wrote-informational"> +<ANCHOR id="SoupMessage.see-also" href="libsoup-2.4/SoupMessage.html#SoupMessage.see-also"> +<ANCHOR id="SoupMessageHeaders" href="libsoup-2.4/SoupMessageHeaders.html"> +<ANCHOR id="SoupMessageHeaders.functions" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeaders.functions"> +<ANCHOR id="SoupMessageHeaders.other" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeaders.other"> +<ANCHOR id="SoupMessageHeaders.object-hierarchy" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeaders.object-hierarchy"> +<ANCHOR id="SoupMessageHeaders.includes" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeaders.includes"> +<ANCHOR id="SoupMessageHeaders.description" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeaders.description"> +<ANCHOR id="SoupMessageHeaders.functions_details" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeaders.functions_details"> +<ANCHOR id="soup-message-headers-new" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-new"> +<ANCHOR id="soup-message-headers-free" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-free"> +<ANCHOR id="soup-message-headers-append" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-append"> +<ANCHOR id="soup-message-headers-replace" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-replace"> +<ANCHOR id="soup-message-headers-remove" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-remove"> +<ANCHOR id="soup-message-headers-clear" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-clear"> +<ANCHOR id="soup-message-headers-clean-connection-headers" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-clean-connection-headers"> +<ANCHOR id="soup-message-headers-get-one" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-get-one"> +<ANCHOR id="soup-message-headers-get-list" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-get-list"> +<ANCHOR id="soup-message-headers-get" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-get"> +<ANCHOR id="SoupMessageHeadersForeachFunc" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeadersForeachFunc"> +<ANCHOR id="soup-message-headers-foreach" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-foreach"> +<ANCHOR id="soup-message-headers-iter-init" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-iter-init"> +<ANCHOR id="soup-message-headers-iter-next" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-iter-next"> +<ANCHOR id="soup-message-headers-get-encoding" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-get-encoding"> +<ANCHOR id="soup-message-headers-set-encoding" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-set-encoding"> +<ANCHOR id="soup-message-headers-get-content-length" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-get-content-length"> +<ANCHOR id="soup-message-headers-set-content-length" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-set-content-length"> +<ANCHOR id="soup-message-headers-get-expectations" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-get-expectations"> +<ANCHOR id="soup-message-headers-set-expectations" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-set-expectations"> +<ANCHOR id="soup-message-headers-get-content-type" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-get-content-type"> +<ANCHOR id="soup-message-headers-set-content-type" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-set-content-type"> +<ANCHOR id="soup-message-headers-get-content-disposition" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-get-content-disposition"> +<ANCHOR id="soup-message-headers-set-content-disposition" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-set-content-disposition"> +<ANCHOR id="soup-message-headers-get-ranges" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-get-ranges"> +<ANCHOR id="soup-message-headers-set-ranges" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-set-ranges"> +<ANCHOR id="soup-message-headers-set-range" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-set-range"> +<ANCHOR id="soup-message-headers-free-ranges" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-free-ranges"> +<ANCHOR id="soup-message-headers-get-content-range" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-get-content-range"> +<ANCHOR id="soup-message-headers-set-content-range" href="libsoup-2.4/SoupMessageHeaders.html#soup-message-headers-set-content-range"> +<ANCHOR id="SoupMessageHeaders.other_details" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeaders.other_details"> +<ANCHOR id="SoupMessageHeaders" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeaders"> +<ANCHOR id="SoupMessageHeadersType" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeadersType"> +<ANCHOR id="SoupMessageHeadersIter" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeadersIter"> +<ANCHOR id="SoupEncoding" href="libsoup-2.4/SoupMessageHeaders.html#SoupEncoding"> +<ANCHOR id="SoupExpectation" href="libsoup-2.4/SoupMessageHeaders.html#SoupExpectation"> +<ANCHOR id="SoupRange" href="libsoup-2.4/SoupMessageHeaders.html#SoupRange"> +<ANCHOR id="SoupMessageHeaders.see-also" href="libsoup-2.4/SoupMessageHeaders.html#SoupMessageHeaders.see-also"> +<ANCHOR id="SoupMessageBody" href="libsoup-2.4/SoupMessageBody.html"> +<ANCHOR id="SoupMessageBody.functions" href="libsoup-2.4/SoupMessageBody.html#SoupMessageBody.functions"> +<ANCHOR id="SoupBuffer" href="libsoup-2.4/SoupMessageBody.html#SoupBuffer"> +<ANCHOR id="SoupMessageBody.other" href="libsoup-2.4/SoupMessageBody.html#SoupMessageBody.other"> +<ANCHOR id="SoupMessageBody.object-hierarchy" href="libsoup-2.4/SoupMessageBody.html#SoupMessageBody.object-hierarchy"> +<ANCHOR id="SoupMessageBody.includes" href="libsoup-2.4/SoupMessageBody.html#SoupMessageBody.includes"> +<ANCHOR id="SoupMessageBody.description" href="libsoup-2.4/SoupMessageBody.html#SoupMessageBody.description"> +<ANCHOR id="SoupMessageBody.functions_details" href="libsoup-2.4/SoupMessageBody.html#SoupMessageBody.functions_details"> +<ANCHOR id="soup-buffer-new" href="libsoup-2.4/SoupMessageBody.html#soup-buffer-new"> +<ANCHOR id="soup-buffer-new-subbuffer" href="libsoup-2.4/SoupMessageBody.html#soup-buffer-new-subbuffer"> +<ANCHOR id="soup-buffer-new-with-owner" href="libsoup-2.4/SoupMessageBody.html#soup-buffer-new-with-owner"> +<ANCHOR id="soup-buffer-new-take" href="libsoup-2.4/SoupMessageBody.html#soup-buffer-new-take"> +<ANCHOR id="soup-buffer-get-owner" href="libsoup-2.4/SoupMessageBody.html#soup-buffer-get-owner"> +<ANCHOR id="soup-buffer-get-data" href="libsoup-2.4/SoupMessageBody.html#soup-buffer-get-data"> +<ANCHOR id="soup-buffer-copy" href="libsoup-2.4/SoupMessageBody.html#soup-buffer-copy"> +<ANCHOR id="soup-buffer-free" href="libsoup-2.4/SoupMessageBody.html#soup-buffer-free"> +<ANCHOR id="soup-buffer-get-as-bytes" href="libsoup-2.4/SoupMessageBody.html#soup-buffer-get-as-bytes"> +<ANCHOR id="soup-message-body-new" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-new"> +<ANCHOR id="soup-message-body-free" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-free"> +<ANCHOR id="soup-message-body-set-accumulate" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-set-accumulate"> +<ANCHOR id="soup-message-body-get-accumulate" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-get-accumulate"> +<ANCHOR id="soup-message-body-append" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-append"> +<ANCHOR id="soup-message-body-append-buffer" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-append-buffer"> +<ANCHOR id="soup-message-body-append-take" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-append-take"> +<ANCHOR id="soup-message-body-truncate" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-truncate"> +<ANCHOR id="soup-message-body-complete" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-complete"> +<ANCHOR id="soup-message-body-flatten" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-flatten"> +<ANCHOR id="soup-message-body-get-chunk" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-get-chunk"> +<ANCHOR id="soup-message-body-got-chunk" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-got-chunk"> +<ANCHOR id="soup-message-body-wrote-chunk" href="libsoup-2.4/SoupMessageBody.html#soup-message-body-wrote-chunk"> +<ANCHOR id="SoupMessageBody.other_details" href="libsoup-2.4/SoupMessageBody.html#SoupMessageBody.other_details"> +<ANCHOR id="SoupBuffer-struct" href="libsoup-2.4/SoupMessageBody.html#SoupBuffer-struct"> +<ANCHOR id="SoupMemoryUse" href="libsoup-2.4/SoupMessageBody.html#SoupMemoryUse"> +<ANCHOR id="SoupMessageBody-struct" href="libsoup-2.4/SoupMessageBody.html#SoupMessageBody-struct"> +<ANCHOR id="SoupMessageBody.see-also" href="libsoup-2.4/SoupMessageBody.html#SoupMessageBody.see-also"> +<ANCHOR id="libsoup-2.4-soup-method" href="libsoup-2.4/libsoup-2.4-soup-method.html"> +<ANCHOR id="libsoup-2.4-soup-method.other" href="libsoup-2.4/libsoup-2.4-soup-method.html#libsoup-2.4-soup-method.other"> +<ANCHOR id="libsoup-2.4-soup-method.object-hierarchy" href="libsoup-2.4/libsoup-2.4-soup-method.html#libsoup-2.4-soup-method.object-hierarchy"> +<ANCHOR id="libsoup-2.4-soup-method.includes" href="libsoup-2.4/libsoup-2.4-soup-method.html#libsoup-2.4-soup-method.includes"> +<ANCHOR id="libsoup-2.4-soup-method.description" href="libsoup-2.4/libsoup-2.4-soup-method.html#libsoup-2.4-soup-method.description"> +<ANCHOR id="libsoup-2.4-soup-method.functions_details" href="libsoup-2.4/libsoup-2.4-soup-method.html#libsoup-2.4-soup-method.functions_details"> +<ANCHOR id="libsoup-2.4-soup-method.other_details" href="libsoup-2.4/libsoup-2.4-soup-method.html#libsoup-2.4-soup-method.other_details"> +<ANCHOR id="SOUP-METHOD-OPTIONS:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-OPTIONS:CAPS"> +<ANCHOR id="SOUP-METHOD-GET:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-GET:CAPS"> +<ANCHOR id="SOUP-METHOD-HEAD:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-HEAD:CAPS"> +<ANCHOR id="SOUP-METHOD-PUT:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-PUT:CAPS"> +<ANCHOR id="SOUP-METHOD-POST:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-POST:CAPS"> +<ANCHOR id="SOUP-METHOD-DELETE:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-DELETE:CAPS"> +<ANCHOR id="SOUP-METHOD-TRACE:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-TRACE:CAPS"> +<ANCHOR id="SOUP-METHOD-CONNECT:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-CONNECT:CAPS"> +<ANCHOR id="SOUP-METHOD-PROPFIND:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-PROPFIND:CAPS"> +<ANCHOR id="SOUP-METHOD-PROPPATCH:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-PROPPATCH:CAPS"> +<ANCHOR id="SOUP-METHOD-MKCOL:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-MKCOL:CAPS"> +<ANCHOR id="SOUP-METHOD-COPY:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-COPY:CAPS"> +<ANCHOR id="SOUP-METHOD-MOVE:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-MOVE:CAPS"> +<ANCHOR id="SOUP-METHOD-LOCK:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-LOCK:CAPS"> +<ANCHOR id="SOUP-METHOD-UNLOCK:CAPS" href="libsoup-2.4/libsoup-2.4-soup-method.html#SOUP-METHOD-UNLOCK:CAPS"> +<ANCHOR id="libsoup-2.4-Soup-Miscellaneous-Utilities" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html"> +<ANCHOR id="libsoup-2.4-Soup-Miscellaneous-Utilities.functions" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#libsoup-2.4-Soup-Miscellaneous-Utilities.functions"> +<ANCHOR id="SoupDate" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"> +<ANCHOR id="libsoup-2.4-Soup-Miscellaneous-Utilities.other" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#libsoup-2.4-Soup-Miscellaneous-Utilities.other"> +<ANCHOR id="libsoup-2.4-Soup-Miscellaneous-Utilities.object-hierarchy" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#libsoup-2.4-Soup-Miscellaneous-Utilities.object-hierarchy"> +<ANCHOR id="libsoup-2.4-Soup-Miscellaneous-Utilities.includes" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#libsoup-2.4-Soup-Miscellaneous-Utilities.includes"> +<ANCHOR id="libsoup-2.4-Soup-Miscellaneous-Utilities.description" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#libsoup-2.4-Soup-Miscellaneous-Utilities.description"> +<ANCHOR id="libsoup-2.4-Soup-Miscellaneous-Utilities.functions_details" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#libsoup-2.4-Soup-Miscellaneous-Utilities.functions_details"> +<ANCHOR id="soup-date-new" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new"> +<ANCHOR id="soup-date-new-from-string" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-string"> +<ANCHOR id="soup-date-new-from-time-t" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-time-t"> +<ANCHOR id="soup-date-new-from-now" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-now"> +<ANCHOR id="soup-date-to-string" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-string"> +<ANCHOR id="soup-date-to-time-t" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-time-t"> +<ANCHOR id="soup-date-to-timeval" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-timeval"> +<ANCHOR id="soup-date-is-past" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-is-past"> +<ANCHOR id="soup-date-get-day" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-day"> +<ANCHOR id="soup-date-get-hour" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-hour"> +<ANCHOR id="soup-date-get-minute" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-minute"> +<ANCHOR id="soup-date-get-month" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-month"> +<ANCHOR id="soup-date-get-offset" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-offset"> +<ANCHOR id="soup-date-get-second" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-second"> +<ANCHOR id="soup-date-get-utc" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-utc"> +<ANCHOR id="soup-date-get-year" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-year"> +<ANCHOR id="soup-date-free" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-free"> +<ANCHOR id="soup-headers-parse-request" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-request"> +<ANCHOR id="soup-headers-parse-response" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-response"> +<ANCHOR id="soup-headers-parse-status-line" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-status-line"> +<ANCHOR id="soup-headers-parse" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse"> +<ANCHOR id="soup-header-parse-list" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-list"> +<ANCHOR id="soup-header-parse-quality-list" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-quality-list"> +<ANCHOR id="soup-header-free-list" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-free-list"> +<ANCHOR id="soup-header-contains" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-contains"> +<ANCHOR id="soup-header-parse-param-list" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-param-list"> +<ANCHOR id="soup-header-parse-semi-param-list" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-semi-param-list"> +<ANCHOR id="soup-header-free-param-list" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-free-param-list"> +<ANCHOR id="soup-header-g-string-append-param" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-g-string-append-param"> +<ANCHOR id="soup-header-g-string-append-param-quoted" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-g-string-append-param-quoted"> +<ANCHOR id="soup-str-case-equal" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-str-case-equal"> +<ANCHOR id="soup-str-case-hash" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-str-case-hash"> +<ANCHOR id="soup-add-completion" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-completion"> +<ANCHOR id="soup-add-idle" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-idle"> +<ANCHOR id="soup-add-io-watch" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-io-watch"> +<ANCHOR id="soup-add-timeout" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-timeout"> +<ANCHOR id="libsoup-2.4-Soup-Miscellaneous-Utilities.other_details" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#libsoup-2.4-Soup-Miscellaneous-Utilities.other_details"> +<ANCHOR id="SoupDate-struct" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate-struct"> +<ANCHOR id="SoupDateFormat" href="libsoup-2.4/libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDateFormat"> +<ANCHOR id="SoupMultipart" href="libsoup-2.4/SoupMultipart.html"> +<ANCHOR id="SoupMultipart.functions" href="libsoup-2.4/SoupMultipart.html#SoupMultipart.functions"> +<ANCHOR id="SoupMultipart.other" href="libsoup-2.4/SoupMultipart.html#SoupMultipart.other"> +<ANCHOR id="SoupMultipart.object-hierarchy" href="libsoup-2.4/SoupMultipart.html#SoupMultipart.object-hierarchy"> +<ANCHOR id="SoupMultipart.includes" href="libsoup-2.4/SoupMultipart.html#SoupMultipart.includes"> +<ANCHOR id="SoupMultipart.description" href="libsoup-2.4/SoupMultipart.html#SoupMultipart.description"> +<ANCHOR id="SoupMultipart.functions_details" href="libsoup-2.4/SoupMultipart.html#SoupMultipart.functions_details"> +<ANCHOR id="soup-multipart-new" href="libsoup-2.4/SoupMultipart.html#soup-multipart-new"> +<ANCHOR id="soup-multipart-new-from-message" href="libsoup-2.4/SoupMultipart.html#soup-multipart-new-from-message"> +<ANCHOR id="soup-multipart-free" href="libsoup-2.4/SoupMultipart.html#soup-multipart-free"> +<ANCHOR id="soup-multipart-get-length" href="libsoup-2.4/SoupMultipart.html#soup-multipart-get-length"> +<ANCHOR id="soup-multipart-get-part" href="libsoup-2.4/SoupMultipart.html#soup-multipart-get-part"> +<ANCHOR id="soup-multipart-append-part" href="libsoup-2.4/SoupMultipart.html#soup-multipart-append-part"> +<ANCHOR id="soup-multipart-append-form-string" href="libsoup-2.4/SoupMultipart.html#soup-multipart-append-form-string"> +<ANCHOR id="soup-multipart-append-form-file" href="libsoup-2.4/SoupMultipart.html#soup-multipart-append-form-file"> +<ANCHOR id="soup-multipart-to-message" href="libsoup-2.4/SoupMultipart.html#soup-multipart-to-message"> +<ANCHOR id="SoupMultipart.other_details" href="libsoup-2.4/SoupMultipart.html#SoupMultipart.other_details"> +<ANCHOR id="SoupMultipart" href="libsoup-2.4/SoupMultipart.html#SoupMultipart"> +<ANCHOR id="SoupMultipart.see-also" href="libsoup-2.4/SoupMultipart.html#SoupMultipart.see-also"> +<ANCHOR id="SoupMultipartInputStream" href="libsoup-2.4/SoupMultipartInputStream.html"> +<ANCHOR id="SoupMultipartInputStream.functions" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream.functions"> +<ANCHOR id="SoupMultipartInputStream.properties" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream.properties"> +<ANCHOR id="SoupMultipartInputStream.other" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream.other"> +<ANCHOR id="SoupMultipartInputStream.object-hierarchy" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream.object-hierarchy"> +<ANCHOR id="SoupMultipartInputStream.implemented-interfaces" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream.implemented-interfaces"> +<ANCHOR id="SoupMultipartInputStream.includes" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream.includes"> +<ANCHOR id="SoupMultipartInputStream.description" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream.description"> +<ANCHOR id="SoupMultipartInputStream.functions_details" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream.functions_details"> +<ANCHOR id="soup-multipart-input-stream-new" href="libsoup-2.4/SoupMultipartInputStream.html#soup-multipart-input-stream-new"> +<ANCHOR id="soup-multipart-input-stream-get-headers" href="libsoup-2.4/SoupMultipartInputStream.html#soup-multipart-input-stream-get-headers"> +<ANCHOR id="soup-multipart-input-stream-next-part" href="libsoup-2.4/SoupMultipartInputStream.html#soup-multipart-input-stream-next-part"> +<ANCHOR id="soup-multipart-input-stream-next-part-async" href="libsoup-2.4/SoupMultipartInputStream.html#soup-multipart-input-stream-next-part-async"> +<ANCHOR id="soup-multipart-input-stream-next-part-finish" href="libsoup-2.4/SoupMultipartInputStream.html#soup-multipart-input-stream-next-part-finish"> +<ANCHOR id="SoupMultipartInputStream.other_details" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream.other_details"> +<ANCHOR id="SoupMultipartInputStream-struct" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream-struct"> +<ANCHOR id="SoupMultipartInputStream.property-details" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream.property-details"> +<ANCHOR id="SoupMultipartInputStream--message" href="libsoup-2.4/SoupMultipartInputStream.html#SoupMultipartInputStream--message"> +<ANCHOR id="SoupRequest" href="libsoup-2.4/SoupRequest.html"> +<ANCHOR id="SoupRequest.functions" href="libsoup-2.4/SoupRequest.html#SoupRequest.functions"> +<ANCHOR id="SoupRequest.properties" href="libsoup-2.4/SoupRequest.html#SoupRequest.properties"> +<ANCHOR id="SoupRequest.other" href="libsoup-2.4/SoupRequest.html#SoupRequest.other"> +<ANCHOR id="SoupRequest.object-hierarchy" href="libsoup-2.4/SoupRequest.html#SoupRequest.object-hierarchy"> +<ANCHOR id="SoupRequest.implemented-interfaces" href="libsoup-2.4/SoupRequest.html#SoupRequest.implemented-interfaces"> +<ANCHOR id="SoupRequest.includes" href="libsoup-2.4/SoupRequest.html#SoupRequest.includes"> +<ANCHOR id="SoupRequest.description" href="libsoup-2.4/SoupRequest.html#SoupRequest.description"> +<ANCHOR id="SoupRequest.functions_details" href="libsoup-2.4/SoupRequest.html#SoupRequest.functions_details"> +<ANCHOR id="soup-request-send" href="libsoup-2.4/SoupRequest.html#soup-request-send"> +<ANCHOR id="soup-request-send-async" href="libsoup-2.4/SoupRequest.html#soup-request-send-async"> +<ANCHOR id="soup-request-send-finish" href="libsoup-2.4/SoupRequest.html#soup-request-send-finish"> +<ANCHOR id="soup-request-get-content-length" href="libsoup-2.4/SoupRequest.html#soup-request-get-content-length"> +<ANCHOR id="soup-request-get-content-type" href="libsoup-2.4/SoupRequest.html#soup-request-get-content-type"> +<ANCHOR id="soup-request-get-session" href="libsoup-2.4/SoupRequest.html#soup-request-get-session"> +<ANCHOR id="soup-request-get-uri" href="libsoup-2.4/SoupRequest.html#soup-request-get-uri"> +<ANCHOR id="SoupRequest.other_details" href="libsoup-2.4/SoupRequest.html#SoupRequest.other_details"> +<ANCHOR id="SoupRequest-struct" href="libsoup-2.4/SoupRequest.html#SoupRequest-struct"> +<ANCHOR id="SOUP-REQUEST-SESSION:CAPS" href="libsoup-2.4/SoupRequest.html#SOUP-REQUEST-SESSION:CAPS"> +<ANCHOR id="SOUP-REQUEST-URI:CAPS" href="libsoup-2.4/SoupRequest.html#SOUP-REQUEST-URI:CAPS"> +<ANCHOR id="SoupRequest.property-details" href="libsoup-2.4/SoupRequest.html#SoupRequest.property-details"> +<ANCHOR id="SoupRequest--session" href="libsoup-2.4/SoupRequest.html#SoupRequest--session"> +<ANCHOR id="SoupRequest--uri" href="libsoup-2.4/SoupRequest.html#SoupRequest--uri"> +<ANCHOR id="SoupRequestHTTP" href="libsoup-2.4/SoupRequestHTTP.html"> +<ANCHOR id="SoupRequestHTTP.functions" href="libsoup-2.4/SoupRequestHTTP.html#SoupRequestHTTP.functions"> +<ANCHOR id="SoupRequestHTTP.other" href="libsoup-2.4/SoupRequestHTTP.html#SoupRequestHTTP.other"> +<ANCHOR id="SoupRequestHTTP.object-hierarchy" href="libsoup-2.4/SoupRequestHTTP.html#SoupRequestHTTP.object-hierarchy"> +<ANCHOR id="SoupRequestHTTP.implemented-interfaces" href="libsoup-2.4/SoupRequestHTTP.html#SoupRequestHTTP.implemented-interfaces"> +<ANCHOR id="SoupRequestHTTP.includes" href="libsoup-2.4/SoupRequestHTTP.html#SoupRequestHTTP.includes"> +<ANCHOR id="SoupRequestHTTP.description" href="libsoup-2.4/SoupRequestHTTP.html#SoupRequestHTTP.description"> +<ANCHOR id="SoupRequestHTTP.functions_details" href="libsoup-2.4/SoupRequestHTTP.html#SoupRequestHTTP.functions_details"> +<ANCHOR id="soup-request-http-get-message" href="libsoup-2.4/SoupRequestHTTP.html#soup-request-http-get-message"> +<ANCHOR id="SoupRequestHTTP.other_details" href="libsoup-2.4/SoupRequestHTTP.html#SoupRequestHTTP.other_details"> +<ANCHOR id="SoupRequestHTTP-struct" href="libsoup-2.4/SoupRequestHTTP.html#SoupRequestHTTP-struct"> +<ANCHOR id="SoupRequestFile" href="libsoup-2.4/SoupRequestFile.html"> +<ANCHOR id="SoupRequestFile.functions" href="libsoup-2.4/SoupRequestFile.html#SoupRequestFile.functions"> +<ANCHOR id="SoupRequestFile.other" href="libsoup-2.4/SoupRequestFile.html#SoupRequestFile.other"> +<ANCHOR id="SoupRequestFile.object-hierarchy" href="libsoup-2.4/SoupRequestFile.html#SoupRequestFile.object-hierarchy"> +<ANCHOR id="SoupRequestFile.implemented-interfaces" href="libsoup-2.4/SoupRequestFile.html#SoupRequestFile.implemented-interfaces"> +<ANCHOR id="SoupRequestFile.includes" href="libsoup-2.4/SoupRequestFile.html#SoupRequestFile.includes"> +<ANCHOR id="SoupRequestFile.description" href="libsoup-2.4/SoupRequestFile.html#SoupRequestFile.description"> +<ANCHOR id="SoupRequestFile.functions_details" href="libsoup-2.4/SoupRequestFile.html#SoupRequestFile.functions_details"> +<ANCHOR id="soup-request-file-get-file" href="libsoup-2.4/SoupRequestFile.html#soup-request-file-get-file"> +<ANCHOR id="SoupRequestFile.other_details" href="libsoup-2.4/SoupRequestFile.html#SoupRequestFile.other_details"> +<ANCHOR id="SoupRequestFile-struct" href="libsoup-2.4/SoupRequestFile.html#SoupRequestFile-struct"> +<ANCHOR id="SoupRequestData" href="libsoup-2.4/SoupRequestData.html"> +<ANCHOR id="SoupRequestData.other" href="libsoup-2.4/SoupRequestData.html#SoupRequestData.other"> +<ANCHOR id="SoupRequestData.object-hierarchy" href="libsoup-2.4/SoupRequestData.html#SoupRequestData.object-hierarchy"> +<ANCHOR id="SoupRequestData.implemented-interfaces" href="libsoup-2.4/SoupRequestData.html#SoupRequestData.implemented-interfaces"> +<ANCHOR id="SoupRequestData.includes" href="libsoup-2.4/SoupRequestData.html#SoupRequestData.includes"> +<ANCHOR id="SoupRequestData.description" href="libsoup-2.4/SoupRequestData.html#SoupRequestData.description"> +<ANCHOR id="SoupRequestData.functions_details" href="libsoup-2.4/SoupRequestData.html#SoupRequestData.functions_details"> +<ANCHOR id="SoupRequestData.other_details" href="libsoup-2.4/SoupRequestData.html#SoupRequestData.other_details"> +<ANCHOR id="SoupRequestData-struct" href="libsoup-2.4/SoupRequestData.html#SoupRequestData-struct"> +<ANCHOR id="SoupServer" href="libsoup-2.4/SoupServer.html"> +<ANCHOR id="SoupServer.functions" href="libsoup-2.4/SoupServer.html#SoupServer.functions"> +<ANCHOR id="SoupServer.properties" href="libsoup-2.4/SoupServer.html#SoupServer.properties"> +<ANCHOR id="SoupServer.signals" href="libsoup-2.4/SoupServer.html#SoupServer.signals"> +<ANCHOR id="SoupClientContext" href="libsoup-2.4/SoupServer.html#SoupClientContext"> +<ANCHOR id="SoupServer.other" href="libsoup-2.4/SoupServer.html#SoupServer.other"> +<ANCHOR id="SoupServer.object-hierarchy" href="libsoup-2.4/SoupServer.html#SoupServer.object-hierarchy"> +<ANCHOR id="SoupServer.includes" href="libsoup-2.4/SoupServer.html#SoupServer.includes"> +<ANCHOR id="SoupServer.description" href="libsoup-2.4/SoupServer.html#SoupServer.description"> +<ANCHOR id="SoupServer.functions_details" href="libsoup-2.4/SoupServer.html#SoupServer.functions_details"> +<ANCHOR id="soup-server-new" href="libsoup-2.4/SoupServer.html#soup-server-new"> +<ANCHOR id="soup-server-is-https" href="libsoup-2.4/SoupServer.html#soup-server-is-https"> +<ANCHOR id="soup-server-get-port" href="libsoup-2.4/SoupServer.html#soup-server-get-port"> +<ANCHOR id="soup-server-get-listener" href="libsoup-2.4/SoupServer.html#soup-server-get-listener"> +<ANCHOR id="soup-server-run" href="libsoup-2.4/SoupServer.html#soup-server-run"> +<ANCHOR id="soup-server-run-async" href="libsoup-2.4/SoupServer.html#soup-server-run-async"> +<ANCHOR id="soup-server-quit" href="libsoup-2.4/SoupServer.html#soup-server-quit"> +<ANCHOR id="soup-server-disconnect" href="libsoup-2.4/SoupServer.html#soup-server-disconnect"> +<ANCHOR id="soup-server-get-async-context" href="libsoup-2.4/SoupServer.html#soup-server-get-async-context"> +<ANCHOR id="SoupServerCallback" href="libsoup-2.4/SoupServer.html#SoupServerCallback"> +<ANCHOR id="soup-server-add-handler" href="libsoup-2.4/SoupServer.html#soup-server-add-handler"> +<ANCHOR id="soup-server-remove-handler" href="libsoup-2.4/SoupServer.html#soup-server-remove-handler"> +<ANCHOR id="soup-client-context-get-socket" href="libsoup-2.4/SoupServer.html#soup-client-context-get-socket"> +<ANCHOR id="soup-client-context-get-address" href="libsoup-2.4/SoupServer.html#soup-client-context-get-address"> +<ANCHOR id="soup-client-context-get-host" href="libsoup-2.4/SoupServer.html#soup-client-context-get-host"> +<ANCHOR id="soup-client-context-get-auth-domain" href="libsoup-2.4/SoupServer.html#soup-client-context-get-auth-domain"> +<ANCHOR id="soup-client-context-get-auth-user" href="libsoup-2.4/SoupServer.html#soup-client-context-get-auth-user"> +<ANCHOR id="soup-server-add-auth-domain" href="libsoup-2.4/SoupServer.html#soup-server-add-auth-domain"> +<ANCHOR id="soup-server-remove-auth-domain" href="libsoup-2.4/SoupServer.html#soup-server-remove-auth-domain"> +<ANCHOR id="soup-server-pause-message" href="libsoup-2.4/SoupServer.html#soup-server-pause-message"> +<ANCHOR id="soup-server-unpause-message" href="libsoup-2.4/SoupServer.html#soup-server-unpause-message"> +<ANCHOR id="SoupServer.other_details" href="libsoup-2.4/SoupServer.html#SoupServer.other_details"> +<ANCHOR id="SoupServer-struct" href="libsoup-2.4/SoupServer.html#SoupServer-struct"> +<ANCHOR id="SoupClientContext" href="libsoup-2.4/SoupServer.html#SoupClientContext"> +<ANCHOR id="SOUP-SERVER-PORT:CAPS" href="libsoup-2.4/SoupServer.html#SOUP-SERVER-PORT:CAPS"> +<ANCHOR id="SOUP-SERVER-INTERFACE:CAPS" href="libsoup-2.4/SoupServer.html#SOUP-SERVER-INTERFACE:CAPS"> +<ANCHOR id="SOUP-SERVER-SSL-CERT-FILE:CAPS" href="libsoup-2.4/SoupServer.html#SOUP-SERVER-SSL-CERT-FILE:CAPS"> +<ANCHOR id="SOUP-SERVER-SSL-KEY-FILE:CAPS" href="libsoup-2.4/SoupServer.html#SOUP-SERVER-SSL-KEY-FILE:CAPS"> +<ANCHOR id="SOUP-SERVER-TLS-CERTIFICATE:CAPS" href="libsoup-2.4/SoupServer.html#SOUP-SERVER-TLS-CERTIFICATE:CAPS"> +<ANCHOR id="SOUP-SERVER-ASYNC-CONTEXT:CAPS" href="libsoup-2.4/SoupServer.html#SOUP-SERVER-ASYNC-CONTEXT:CAPS"> +<ANCHOR id="SOUP-SERVER-RAW-PATHS:CAPS" href="libsoup-2.4/SoupServer.html#SOUP-SERVER-RAW-PATHS:CAPS"> +<ANCHOR id="SOUP-SERVER-SERVER-HEADER:CAPS" href="libsoup-2.4/SoupServer.html#SOUP-SERVER-SERVER-HEADER:CAPS"> +<ANCHOR id="SOUP-SERVER-HTTP-ALIASES:CAPS" href="libsoup-2.4/SoupServer.html#SOUP-SERVER-HTTP-ALIASES:CAPS"> +<ANCHOR id="SOUP-SERVER-HTTPS-ALIASES:CAPS" href="libsoup-2.4/SoupServer.html#SOUP-SERVER-HTTPS-ALIASES:CAPS"> +<ANCHOR id="SoupServer.property-details" href="libsoup-2.4/SoupServer.html#SoupServer.property-details"> +<ANCHOR id="SoupServer--async-context" href="libsoup-2.4/SoupServer.html#SoupServer--async-context"> +<ANCHOR id="SoupServer--http-aliases" href="libsoup-2.4/SoupServer.html#SoupServer--http-aliases"> +<ANCHOR id="SoupServer--https-aliases" href="libsoup-2.4/SoupServer.html#SoupServer--https-aliases"> +<ANCHOR id="SoupServer--interface" href="libsoup-2.4/SoupServer.html#SoupServer--interface"> +<ANCHOR id="SoupServer--port" href="libsoup-2.4/SoupServer.html#SoupServer--port"> +<ANCHOR id="SoupServer--raw-paths" href="libsoup-2.4/SoupServer.html#SoupServer--raw-paths"> +<ANCHOR id="SoupServer--server-header" href="libsoup-2.4/SoupServer.html#SoupServer--server-header"> +<ANCHOR id="SoupServer--ssl-cert-file" href="libsoup-2.4/SoupServer.html#SoupServer--ssl-cert-file"> +<ANCHOR id="SoupServer--ssl-key-file" href="libsoup-2.4/SoupServer.html#SoupServer--ssl-key-file"> +<ANCHOR id="SoupServer--tls-certificate" href="libsoup-2.4/SoupServer.html#SoupServer--tls-certificate"> +<ANCHOR id="SoupServer.signal-details" href="libsoup-2.4/SoupServer.html#SoupServer.signal-details"> +<ANCHOR id="SoupServer-request-aborted" href="libsoup-2.4/SoupServer.html#SoupServer-request-aborted"> +<ANCHOR id="SoupServer-request-finished" href="libsoup-2.4/SoupServer.html#SoupServer-request-finished"> +<ANCHOR id="SoupServer-request-read" href="libsoup-2.4/SoupServer.html#SoupServer-request-read"> +<ANCHOR id="SoupServer-request-started" href="libsoup-2.4/SoupServer.html#SoupServer-request-started"> +<ANCHOR id="SoupServer.see-also" href="libsoup-2.4/SoupServer.html#SoupServer.see-also"> +<ANCHOR id="SoupSession" href="libsoup-2.4/SoupSession.html"> +<ANCHOR id="SoupSession.functions" href="libsoup-2.4/SoupSession.html#SoupSession.functions"> +<ANCHOR id="SoupSession.properties" href="libsoup-2.4/SoupSession.html#SoupSession.properties"> +<ANCHOR id="SoupSession.signals" href="libsoup-2.4/SoupSession.html#SoupSession.signals"> +<ANCHOR id="SoupSession.other" href="libsoup-2.4/SoupSession.html#SoupSession.other"> +<ANCHOR id="SoupSession.object-hierarchy" href="libsoup-2.4/SoupSession.html#SoupSession.object-hierarchy"> +<ANCHOR id="SoupSession.includes" href="libsoup-2.4/SoupSession.html#SoupSession.includes"> +<ANCHOR id="SoupSession.description" href="libsoup-2.4/SoupSession.html#SoupSession.description"> +<ANCHOR id="SoupSession.functions_details" href="libsoup-2.4/SoupSession.html#SoupSession.functions_details"> +<ANCHOR id="soup-session-new" href="libsoup-2.4/SoupSession.html#soup-session-new"> +<ANCHOR id="soup-session-new-with-options" href="libsoup-2.4/SoupSession.html#soup-session-new-with-options"> +<ANCHOR id="soup-session-request" href="libsoup-2.4/SoupSession.html#soup-session-request"> +<ANCHOR id="soup-session-request-uri" href="libsoup-2.4/SoupSession.html#soup-session-request-uri"> +<ANCHOR id="soup-session-request-http" href="libsoup-2.4/SoupSession.html#soup-session-request-http"> +<ANCHOR id="soup-session-request-http-uri" href="libsoup-2.4/SoupSession.html#soup-session-request-http-uri"> +<ANCHOR id="SoupSessionCallback" href="libsoup-2.4/SoupSession.html#SoupSessionCallback"> +<ANCHOR id="soup-session-queue-message" href="libsoup-2.4/SoupSession.html#soup-session-queue-message"> +<ANCHOR id="soup-session-requeue-message" href="libsoup-2.4/SoupSession.html#soup-session-requeue-message"> +<ANCHOR id="soup-session-send-message" href="libsoup-2.4/SoupSession.html#soup-session-send-message"> +<ANCHOR id="soup-session-cancel-message" href="libsoup-2.4/SoupSession.html#soup-session-cancel-message"> +<ANCHOR id="soup-session-send" href="libsoup-2.4/SoupSession.html#soup-session-send"> +<ANCHOR id="soup-session-send-async" href="libsoup-2.4/SoupSession.html#soup-session-send-async"> +<ANCHOR id="soup-session-send-finish" href="libsoup-2.4/SoupSession.html#soup-session-send-finish"> +<ANCHOR id="soup-session-prefetch-dns" href="libsoup-2.4/SoupSession.html#soup-session-prefetch-dns"> +<ANCHOR id="soup-session-prepare-for-uri" href="libsoup-2.4/SoupSession.html#soup-session-prepare-for-uri"> +<ANCHOR id="soup-session-abort" href="libsoup-2.4/SoupSession.html#soup-session-abort"> +<ANCHOR id="soup-session-would-redirect" href="libsoup-2.4/SoupSession.html#soup-session-would-redirect"> +<ANCHOR id="soup-session-redirect-message" href="libsoup-2.4/SoupSession.html#soup-session-redirect-message"> +<ANCHOR id="soup-session-pause-message" href="libsoup-2.4/SoupSession.html#soup-session-pause-message"> +<ANCHOR id="soup-session-unpause-message" href="libsoup-2.4/SoupSession.html#soup-session-unpause-message"> +<ANCHOR id="soup-session-get-async-context" href="libsoup-2.4/SoupSession.html#soup-session-get-async-context"> +<ANCHOR id="soup-session-add-feature" href="libsoup-2.4/SoupSession.html#soup-session-add-feature"> +<ANCHOR id="soup-session-add-feature-by-type" href="libsoup-2.4/SoupSession.html#soup-session-add-feature-by-type"> +<ANCHOR id="soup-session-remove-feature" href="libsoup-2.4/SoupSession.html#soup-session-remove-feature"> +<ANCHOR id="soup-session-remove-feature-by-type" href="libsoup-2.4/SoupSession.html#soup-session-remove-feature-by-type"> +<ANCHOR id="soup-session-get-features" href="libsoup-2.4/SoupSession.html#soup-session-get-features"> +<ANCHOR id="soup-session-get-feature" href="libsoup-2.4/SoupSession.html#soup-session-get-feature"> +<ANCHOR id="soup-session-get-feature-for-message" href="libsoup-2.4/SoupSession.html#soup-session-get-feature-for-message"> +<ANCHOR id="soup-session-has-feature" href="libsoup-2.4/SoupSession.html#soup-session-has-feature"> +<ANCHOR id="SoupSession.other_details" href="libsoup-2.4/SoupSession.html#SoupSession.other_details"> +<ANCHOR id="SoupSession-struct" href="libsoup-2.4/SoupSession.html#SoupSession-struct"> +<ANCHOR id="SoupRequestError" href="libsoup-2.4/SoupSession.html#SoupRequestError"> +<ANCHOR id="SOUP-REQUEST-ERROR:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-REQUEST-ERROR:CAPS"> +<ANCHOR id="SOUP-SESSION-PROXY-URI:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-PROXY-URI:CAPS"> +<ANCHOR id="SOUP-SESSION-PROXY-RESOLVER:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-PROXY-RESOLVER:CAPS"> +<ANCHOR id="SOUP-SESSION-MAX-CONNS:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-MAX-CONNS:CAPS"> +<ANCHOR id="SOUP-SESSION-MAX-CONNS-PER-HOST:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-MAX-CONNS-PER-HOST:CAPS"> +<ANCHOR id="SOUP-SESSION-TLS-DATABASE:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-TLS-DATABASE:CAPS"> +<ANCHOR id="SOUP-SESSION-SSL-USE-SYSTEM-CA-FILE:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-SSL-USE-SYSTEM-CA-FILE:CAPS"> +<ANCHOR id="SOUP-SESSION-SSL-CA-FILE:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-SSL-CA-FILE:CAPS"> +<ANCHOR id="SOUP-SESSION-SSL-STRICT:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-SSL-STRICT:CAPS"> +<ANCHOR id="SOUP-SESSION-ASYNC-CONTEXT:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-ASYNC-CONTEXT:CAPS"> +<ANCHOR id="SOUP-SESSION-USE-THREAD-CONTEXT:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-USE-THREAD-CONTEXT:CAPS"> +<ANCHOR id="SOUP-SESSION-TIMEOUT:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-TIMEOUT:CAPS"> +<ANCHOR id="SOUP-SESSION-IDLE-TIMEOUT:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-IDLE-TIMEOUT:CAPS"> +<ANCHOR id="SOUP-SESSION-USER-AGENT:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-USER-AGENT:CAPS"> +<ANCHOR id="SOUP-SESSION-ADD-FEATURE:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-ADD-FEATURE:CAPS"> +<ANCHOR id="SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS"> +<ANCHOR id="SOUP-SESSION-REMOVE-FEATURE-BY-TYPE:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-REMOVE-FEATURE-BY-TYPE:CAPS"> +<ANCHOR id="SOUP-SESSION-ACCEPT-LANGUAGE:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-ACCEPT-LANGUAGE:CAPS"> +<ANCHOR id="SOUP-SESSION-ACCEPT-LANGUAGE-AUTO:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-ACCEPT-LANGUAGE-AUTO:CAPS"> +<ANCHOR id="SOUP-SESSION-HTTP-ALIASES:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-HTTP-ALIASES:CAPS"> +<ANCHOR id="SOUP-SESSION-HTTPS-ALIASES:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-HTTPS-ALIASES:CAPS"> +<ANCHOR id="SOUP-SESSION-LOCAL-ADDRESS:CAPS" href="libsoup-2.4/SoupSession.html#SOUP-SESSION-LOCAL-ADDRESS:CAPS"> +<ANCHOR id="SoupSession.property-details" href="libsoup-2.4/SoupSession.html#SoupSession.property-details"> +<ANCHOR id="SoupSession--accept-language" href="libsoup-2.4/SoupSession.html#SoupSession--accept-language"> +<ANCHOR id="SoupSession--accept-language-auto" href="libsoup-2.4/SoupSession.html#SoupSession--accept-language-auto"> +<ANCHOR id="SoupSession--add-feature" href="libsoup-2.4/SoupSession.html#SoupSession--add-feature"> +<ANCHOR id="SoupSession--add-feature-by-type" href="libsoup-2.4/SoupSession.html#SoupSession--add-feature-by-type"> +<ANCHOR id="SoupSession--async-context" href="libsoup-2.4/SoupSession.html#SoupSession--async-context"> +<ANCHOR id="SoupSession--http-aliases" href="libsoup-2.4/SoupSession.html#SoupSession--http-aliases"> +<ANCHOR id="SoupSession--https-aliases" href="libsoup-2.4/SoupSession.html#SoupSession--https-aliases"> +<ANCHOR id="SoupSession--idle-timeout" href="libsoup-2.4/SoupSession.html#SoupSession--idle-timeout"> +<ANCHOR id="SoupSession--local-address" href="libsoup-2.4/SoupSession.html#SoupSession--local-address"> +<ANCHOR id="SoupSession--max-conns" href="libsoup-2.4/SoupSession.html#SoupSession--max-conns"> +<ANCHOR id="SoupSession--max-conns-per-host" href="libsoup-2.4/SoupSession.html#SoupSession--max-conns-per-host"> +<ANCHOR id="SoupSession--proxy-resolver" href="libsoup-2.4/SoupSession.html#SoupSession--proxy-resolver"> +<ANCHOR id="SoupSession--proxy-uri" href="libsoup-2.4/SoupSession.html#SoupSession--proxy-uri"> +<ANCHOR id="SoupSession--remove-feature-by-type" href="libsoup-2.4/SoupSession.html#SoupSession--remove-feature-by-type"> +<ANCHOR id="SoupSession--ssl-ca-file" href="libsoup-2.4/SoupSession.html#SoupSession--ssl-ca-file"> +<ANCHOR id="SoupSession--ssl-strict" href="libsoup-2.4/SoupSession.html#SoupSession--ssl-strict"> +<ANCHOR id="SoupSession--ssl-use-system-ca-file" href="libsoup-2.4/SoupSession.html#SoupSession--ssl-use-system-ca-file"> +<ANCHOR id="SoupSession--timeout" href="libsoup-2.4/SoupSession.html#SoupSession--timeout"> +<ANCHOR id="SoupSession--tls-database" href="libsoup-2.4/SoupSession.html#SoupSession--tls-database"> +<ANCHOR id="SoupSession--use-ntlm" href="libsoup-2.4/SoupSession.html#SoupSession--use-ntlm"> +<ANCHOR id="SoupSession--use-thread-context" href="libsoup-2.4/SoupSession.html#SoupSession--use-thread-context"> +<ANCHOR id="SoupSession--user-agent" href="libsoup-2.4/SoupSession.html#SoupSession--user-agent"> +<ANCHOR id="SoupSession.signal-details" href="libsoup-2.4/SoupSession.html#SoupSession.signal-details"> +<ANCHOR id="SoupSession-authenticate" href="libsoup-2.4/SoupSession.html#SoupSession-authenticate"> +<ANCHOR id="SoupSession-connection-created" href="libsoup-2.4/SoupSession.html#SoupSession-connection-created"> +<ANCHOR id="SoupSession-request-queued" href="libsoup-2.4/SoupSession.html#SoupSession-request-queued"> +<ANCHOR id="SoupSession-request-started" href="libsoup-2.4/SoupSession.html#SoupSession-request-started"> +<ANCHOR id="SoupSession-request-unqueued" href="libsoup-2.4/SoupSession.html#SoupSession-request-unqueued"> +<ANCHOR id="SoupSession-tunneling" href="libsoup-2.4/SoupSession.html#SoupSession-tunneling"> +<ANCHOR id="SoupSessionAsync" href="libsoup-2.4/SoupSessionAsync.html"> +<ANCHOR id="SoupSessionAsync.functions" href="libsoup-2.4/SoupSessionAsync.html#SoupSessionAsync.functions"> +<ANCHOR id="SoupSessionAsync.other" href="libsoup-2.4/SoupSessionAsync.html#SoupSessionAsync.other"> +<ANCHOR id="SoupSessionAsync.object-hierarchy" href="libsoup-2.4/SoupSessionAsync.html#SoupSessionAsync.object-hierarchy"> +<ANCHOR id="SoupSessionAsync.includes" href="libsoup-2.4/SoupSessionAsync.html#SoupSessionAsync.includes"> +<ANCHOR id="SoupSessionAsync.description" href="libsoup-2.4/SoupSessionAsync.html#SoupSessionAsync.description"> +<ANCHOR id="SoupSessionAsync.functions_details" href="libsoup-2.4/SoupSessionAsync.html#SoupSessionAsync.functions_details"> +<ANCHOR id="soup-session-async-new" href="libsoup-2.4/SoupSessionAsync.html#soup-session-async-new"> +<ANCHOR id="soup-session-async-new-with-options" href="libsoup-2.4/SoupSessionAsync.html#soup-session-async-new-with-options"> +<ANCHOR id="SoupSessionAsync.other_details" href="libsoup-2.4/SoupSessionAsync.html#SoupSessionAsync.other_details"> +<ANCHOR id="SoupSessionAsync-struct" href="libsoup-2.4/SoupSessionAsync.html#SoupSessionAsync-struct"> +<ANCHOR id="SoupSessionSync" href="libsoup-2.4/SoupSessionSync.html"> +<ANCHOR id="SoupSessionSync.functions" href="libsoup-2.4/SoupSessionSync.html#SoupSessionSync.functions"> +<ANCHOR id="SoupSessionSync.other" href="libsoup-2.4/SoupSessionSync.html#SoupSessionSync.other"> +<ANCHOR id="SoupSessionSync.object-hierarchy" href="libsoup-2.4/SoupSessionSync.html#SoupSessionSync.object-hierarchy"> +<ANCHOR id="SoupSessionSync.includes" href="libsoup-2.4/SoupSessionSync.html#SoupSessionSync.includes"> +<ANCHOR id="SoupSessionSync.description" href="libsoup-2.4/SoupSessionSync.html#SoupSessionSync.description"> +<ANCHOR id="SoupSessionSync.functions_details" href="libsoup-2.4/SoupSessionSync.html#SoupSessionSync.functions_details"> +<ANCHOR id="soup-session-sync-new" href="libsoup-2.4/SoupSessionSync.html#soup-session-sync-new"> +<ANCHOR id="soup-session-sync-new-with-options" href="libsoup-2.4/SoupSessionSync.html#soup-session-sync-new-with-options"> +<ANCHOR id="SoupSessionSync.other_details" href="libsoup-2.4/SoupSessionSync.html#SoupSessionSync.other_details"> +<ANCHOR id="SoupSessionSync-struct" href="libsoup-2.4/SoupSessionSync.html#SoupSessionSync-struct"> +<ANCHOR id="libsoup-2.4-soup-status" href="libsoup-2.4/libsoup-2.4-soup-status.html"> +<ANCHOR id="libsoup-2.4-soup-status.functions" href="libsoup-2.4/libsoup-2.4-soup-status.html#libsoup-2.4-soup-status.functions"> +<ANCHOR id="libsoup-2.4-soup-status.other" href="libsoup-2.4/libsoup-2.4-soup-status.html#libsoup-2.4-soup-status.other"> +<ANCHOR id="libsoup-2.4-soup-status.object-hierarchy" href="libsoup-2.4/libsoup-2.4-soup-status.html#libsoup-2.4-soup-status.object-hierarchy"> +<ANCHOR id="libsoup-2.4-soup-status.includes" href="libsoup-2.4/libsoup-2.4-soup-status.html#libsoup-2.4-soup-status.includes"> +<ANCHOR id="libsoup-2.4-soup-status.description" href="libsoup-2.4/libsoup-2.4-soup-status.html#libsoup-2.4-soup-status.description"> +<ANCHOR id="libsoup-2.4-soup-status.functions_details" href="libsoup-2.4/libsoup-2.4-soup-status.html#libsoup-2.4-soup-status.functions_details"> +<ANCHOR id="SOUP-STATUS-IS-TRANSPORT-ERROR:CAPS" href="libsoup-2.4/libsoup-2.4-soup-status.html#SOUP-STATUS-IS-TRANSPORT-ERROR:CAPS"> +<ANCHOR id="SOUP-STATUS-IS-INFORMATIONAL:CAPS" href="libsoup-2.4/libsoup-2.4-soup-status.html#SOUP-STATUS-IS-INFORMATIONAL:CAPS"> +<ANCHOR id="SOUP-STATUS-IS-SUCCESSFUL:CAPS" href="libsoup-2.4/libsoup-2.4-soup-status.html#SOUP-STATUS-IS-SUCCESSFUL:CAPS"> +<ANCHOR id="SOUP-STATUS-IS-REDIRECTION:CAPS" href="libsoup-2.4/libsoup-2.4-soup-status.html#SOUP-STATUS-IS-REDIRECTION:CAPS"> +<ANCHOR id="SOUP-STATUS-IS-CLIENT-ERROR:CAPS" href="libsoup-2.4/libsoup-2.4-soup-status.html#SOUP-STATUS-IS-CLIENT-ERROR:CAPS"> +<ANCHOR id="SOUP-STATUS-IS-SERVER-ERROR:CAPS" href="libsoup-2.4/libsoup-2.4-soup-status.html#SOUP-STATUS-IS-SERVER-ERROR:CAPS"> +<ANCHOR id="soup-status-get-phrase" href="libsoup-2.4/libsoup-2.4-soup-status.html#soup-status-get-phrase"> +<ANCHOR id="soup-status-proxify" href="libsoup-2.4/libsoup-2.4-soup-status.html#soup-status-proxify"> +<ANCHOR id="libsoup-2.4-soup-status.other_details" href="libsoup-2.4/libsoup-2.4-soup-status.html#libsoup-2.4-soup-status.other_details"> +<ANCHOR id="SoupStatus" href="libsoup-2.4/libsoup-2.4-soup-status.html#SoupStatus"> +<ANCHOR id="SOUP-HTTP-ERROR:CAPS" href="libsoup-2.4/libsoup-2.4-soup-status.html#SOUP-HTTP-ERROR:CAPS"> +<ANCHOR id="libsoup-2.4-Top-Level-Domain-utils" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html"> +<ANCHOR id="libsoup-2.4-Top-Level-Domain-utils.functions" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html#libsoup-2.4-Top-Level-Domain-utils.functions"> +<ANCHOR id="libsoup-2.4-Top-Level-Domain-utils.other" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html#libsoup-2.4-Top-Level-Domain-utils.other"> +<ANCHOR id="libsoup-2.4-Top-Level-Domain-utils.object-hierarchy" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html#libsoup-2.4-Top-Level-Domain-utils.object-hierarchy"> +<ANCHOR id="libsoup-2.4-Top-Level-Domain-utils.includes" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html#libsoup-2.4-Top-Level-Domain-utils.includes"> +<ANCHOR id="libsoup-2.4-Top-Level-Domain-utils.description" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html#libsoup-2.4-Top-Level-Domain-utils.description"> +<ANCHOR id="libsoup-2.4-Top-Level-Domain-utils.functions_details" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html#libsoup-2.4-Top-Level-Domain-utils.functions_details"> +<ANCHOR id="soup-tld-get-base-domain" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html#soup-tld-get-base-domain"> +<ANCHOR id="soup-tld-domain-is-public-suffix" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html#soup-tld-domain-is-public-suffix"> +<ANCHOR id="libsoup-2.4-Top-Level-Domain-utils.other_details" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html#libsoup-2.4-Top-Level-Domain-utils.other_details"> +<ANCHOR id="SOUP-TLD-ERROR:CAPS" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html#SOUP-TLD-ERROR:CAPS"> +<ANCHOR id="SoupTLDError" href="libsoup-2.4/libsoup-2.4-Top-Level-Domain-utils.html#SoupTLDError"> +<ANCHOR id="SoupURI" href="libsoup-2.4/SoupURI.html"> +<ANCHOR id="SoupURI.functions" href="libsoup-2.4/SoupURI.html#SoupURI.functions"> +<ANCHOR id="SoupURI.other" href="libsoup-2.4/SoupURI.html#SoupURI.other"> +<ANCHOR id="SoupURI.object-hierarchy" href="libsoup-2.4/SoupURI.html#SoupURI.object-hierarchy"> +<ANCHOR id="SoupURI.includes" href="libsoup-2.4/SoupURI.html#SoupURI.includes"> +<ANCHOR id="SoupURI.description" href="libsoup-2.4/SoupURI.html#SoupURI.description"> +<ANCHOR id="SoupURI.functions_details" href="libsoup-2.4/SoupURI.html#SoupURI.functions_details"> +<ANCHOR id="soup-uri-new-with-base" href="libsoup-2.4/SoupURI.html#soup-uri-new-with-base"> +<ANCHOR id="soup-uri-new" href="libsoup-2.4/SoupURI.html#soup-uri-new"> +<ANCHOR id="soup-uri-to-string" href="libsoup-2.4/SoupURI.html#soup-uri-to-string"> +<ANCHOR id="soup-uri-copy" href="libsoup-2.4/SoupURI.html#soup-uri-copy"> +<ANCHOR id="soup-uri-copy-host" href="libsoup-2.4/SoupURI.html#soup-uri-copy-host"> +<ANCHOR id="soup-uri-equal" href="libsoup-2.4/SoupURI.html#soup-uri-equal"> +<ANCHOR id="soup-uri-host-equal" href="libsoup-2.4/SoupURI.html#soup-uri-host-equal"> +<ANCHOR id="soup-uri-host-hash" href="libsoup-2.4/SoupURI.html#soup-uri-host-hash"> +<ANCHOR id="soup-uri-free" href="libsoup-2.4/SoupURI.html#soup-uri-free"> +<ANCHOR id="soup-uri-encode" href="libsoup-2.4/SoupURI.html#soup-uri-encode"> +<ANCHOR id="soup-uri-decode" href="libsoup-2.4/SoupURI.html#soup-uri-decode"> +<ANCHOR id="soup-uri-normalize" href="libsoup-2.4/SoupURI.html#soup-uri-normalize"> +<ANCHOR id="soup-uri-uses-default-port" href="libsoup-2.4/SoupURI.html#soup-uri-uses-default-port"> +<ANCHOR id="SOUP-URI-IS-VALID:CAPS" href="libsoup-2.4/SoupURI.html#SOUP-URI-IS-VALID:CAPS"> +<ANCHOR id="SOUP-URI-VALID-FOR-HTTP:CAPS" href="libsoup-2.4/SoupURI.html#SOUP-URI-VALID-FOR-HTTP:CAPS"> +<ANCHOR id="soup-uri-set-scheme" href="libsoup-2.4/SoupURI.html#soup-uri-set-scheme"> +<ANCHOR id="soup-uri-get-scheme" href="libsoup-2.4/SoupURI.html#soup-uri-get-scheme"> +<ANCHOR id="soup-uri-set-user" href="libsoup-2.4/SoupURI.html#soup-uri-set-user"> +<ANCHOR id="soup-uri-get-user" href="libsoup-2.4/SoupURI.html#soup-uri-get-user"> +<ANCHOR id="soup-uri-set-password" href="libsoup-2.4/SoupURI.html#soup-uri-set-password"> +<ANCHOR id="soup-uri-get-password" href="libsoup-2.4/SoupURI.html#soup-uri-get-password"> +<ANCHOR id="soup-uri-set-host" href="libsoup-2.4/SoupURI.html#soup-uri-set-host"> +<ANCHOR id="soup-uri-get-host" href="libsoup-2.4/SoupURI.html#soup-uri-get-host"> +<ANCHOR id="soup-uri-set-port" href="libsoup-2.4/SoupURI.html#soup-uri-set-port"> +<ANCHOR id="soup-uri-get-port" href="libsoup-2.4/SoupURI.html#soup-uri-get-port"> +<ANCHOR id="soup-uri-set-path" href="libsoup-2.4/SoupURI.html#soup-uri-set-path"> +<ANCHOR id="soup-uri-get-path" href="libsoup-2.4/SoupURI.html#soup-uri-get-path"> +<ANCHOR id="soup-uri-set-query" href="libsoup-2.4/SoupURI.html#soup-uri-set-query"> +<ANCHOR id="soup-uri-set-query-from-form" href="libsoup-2.4/SoupURI.html#soup-uri-set-query-from-form"> +<ANCHOR id="soup-uri-set-query-from-fields" href="libsoup-2.4/SoupURI.html#soup-uri-set-query-from-fields"> +<ANCHOR id="soup-uri-get-query" href="libsoup-2.4/SoupURI.html#soup-uri-get-query"> +<ANCHOR id="soup-uri-set-fragment" href="libsoup-2.4/SoupURI.html#soup-uri-set-fragment"> +<ANCHOR id="soup-uri-get-fragment" href="libsoup-2.4/SoupURI.html#soup-uri-get-fragment"> +<ANCHOR id="SoupURI.other_details" href="libsoup-2.4/SoupURI.html#SoupURI.other_details"> +<ANCHOR id="SoupURI-struct" href="libsoup-2.4/SoupURI.html#SoupURI-struct"> +<ANCHOR id="SOUP-URI-SCHEME-HTTP:CAPS" href="libsoup-2.4/SoupURI.html#SOUP-URI-SCHEME-HTTP:CAPS"> +<ANCHOR id="SOUP-URI-SCHEME-HTTPS:CAPS" href="libsoup-2.4/SoupURI.html#SOUP-URI-SCHEME-HTTPS:CAPS"> +<ANCHOR id="SOUP-URI-SCHEME-DATA:CAPS" href="libsoup-2.4/SoupURI.html#SOUP-URI-SCHEME-DATA:CAPS"> +<ANCHOR id="SOUP-URI-SCHEME-FILE:CAPS" href="libsoup-2.4/SoupURI.html#SOUP-URI-SCHEME-FILE:CAPS"> +<ANCHOR id="SOUP-URI-SCHEME-FTP:CAPS" href="libsoup-2.4/SoupURI.html#SOUP-URI-SCHEME-FTP:CAPS"> +<ANCHOR id="SOUP-URI-SCHEME-RESOURCE:CAPS" href="libsoup-2.4/SoupURI.html#SOUP-URI-SCHEME-RESOURCE:CAPS"> +<ANCHOR id="libsoup-2.4-Version-Information" href="libsoup-2.4/libsoup-2.4-Version-Information.html"> +<ANCHOR id="libsoup-2.4-Version-Information.functions" href="libsoup-2.4/libsoup-2.4-Version-Information.html#libsoup-2.4-Version-Information.functions"> +<ANCHOR id="libsoup-2.4-Version-Information.object-hierarchy" href="libsoup-2.4/libsoup-2.4-Version-Information.html#libsoup-2.4-Version-Information.object-hierarchy"> +<ANCHOR id="libsoup-2.4-Version-Information.includes" href="libsoup-2.4/libsoup-2.4-Version-Information.html#libsoup-2.4-Version-Information.includes"> +<ANCHOR id="libsoup-2.4-Version-Information.description" href="libsoup-2.4/libsoup-2.4-Version-Information.html#libsoup-2.4-Version-Information.description"> +<ANCHOR id="libsoup-2.4-Version-Information.functions_details" href="libsoup-2.4/libsoup-2.4-Version-Information.html#libsoup-2.4-Version-Information.functions_details"> +<ANCHOR id="soup-get-major-version" href="libsoup-2.4/libsoup-2.4-Version-Information.html#soup-get-major-version"> +<ANCHOR id="soup-get-minor-version" href="libsoup-2.4/libsoup-2.4-Version-Information.html#soup-get-minor-version"> +<ANCHOR id="soup-get-micro-version" href="libsoup-2.4/libsoup-2.4-Version-Information.html#soup-get-micro-version"> +<ANCHOR id="soup-check-version" href="libsoup-2.4/libsoup-2.4-Version-Information.html#soup-check-version"> +<ANCHOR id="SOUP-MAJOR-VERSION:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-MAJOR-VERSION:CAPS"> +<ANCHOR id="SOUP-MINOR-VERSION:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-MINOR-VERSION:CAPS"> +<ANCHOR id="SOUP-MICRO-VERSION:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-MICRO-VERSION:CAPS"> +<ANCHOR id="SOUP-CHECK-VERSION:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-CHECK-VERSION:CAPS"> +<ANCHOR id="SOUP-VERSION-MIN-REQUIRED:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS"> +<ANCHOR id="SOUP-VERSION-MAX-ALLOWED:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS"> +<ANCHOR id="SOUP-VERSION-2-24:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-24:CAPS"> +<ANCHOR id="SOUP-VERSION-2-26:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-26:CAPS"> +<ANCHOR id="SOUP-VERSION-2-28:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-28:CAPS"> +<ANCHOR id="SOUP-VERSION-2-30:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-30:CAPS"> +<ANCHOR id="SOUP-VERSION-2-32:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-32:CAPS"> +<ANCHOR id="SOUP-VERSION-2-34:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-34:CAPS"> +<ANCHOR id="SOUP-VERSION-2-36:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-36:CAPS"> +<ANCHOR id="SOUP-VERSION-2-38:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-38:CAPS"> +<ANCHOR id="SOUP-VERSION-2-40:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-40:CAPS"> +<ANCHOR id="SOUP-VERSION-2-42:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-42:CAPS"> +<ANCHOR id="SOUP-VERSION-2-44:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-44:CAPS"> +<ANCHOR id="SOUP-VERSION-2-46:CAPS" href="libsoup-2.4/libsoup-2.4-Version-Information.html#SOUP-VERSION-2-46:CAPS"> +<ANCHOR id="libsoup-2.4-Version-Information.other_details" href="libsoup-2.4/libsoup-2.4-Version-Information.html#libsoup-2.4-Version-Information.other_details"> +<ANCHOR id="SoupSessionFeature" href="libsoup-2.4/SoupSessionFeature.html"> +<ANCHOR id="SoupSessionFeature.other" href="libsoup-2.4/SoupSessionFeature.html#SoupSessionFeature.other"> +<ANCHOR id="SoupSessionFeature.object-hierarchy" href="libsoup-2.4/SoupSessionFeature.html#SoupSessionFeature.object-hierarchy"> +<ANCHOR id="SoupSessionFeature.prerequisites" href="libsoup-2.4/SoupSessionFeature.html#SoupSessionFeature.prerequisites"> +<ANCHOR id="SoupSessionFeature.implementations" href="libsoup-2.4/SoupSessionFeature.html#SoupSessionFeature.implementations"> +<ANCHOR id="SoupSessionFeature.includes" href="libsoup-2.4/SoupSessionFeature.html#SoupSessionFeature.includes"> +<ANCHOR id="SoupSessionFeature.description" href="libsoup-2.4/SoupSessionFeature.html#SoupSessionFeature.description"> +<ANCHOR id="SoupSessionFeature.functions_details" href="libsoup-2.4/SoupSessionFeature.html#SoupSessionFeature.functions_details"> +<ANCHOR id="SoupSessionFeature.other_details" href="libsoup-2.4/SoupSessionFeature.html#SoupSessionFeature.other_details"> +<ANCHOR id="SoupSessionFeature-struct" href="libsoup-2.4/SoupSessionFeature.html#SoupSessionFeature-struct"> +<ANCHOR id="SoupSessionFeatureInterface" href="libsoup-2.4/SoupSessionFeature.html#SoupSessionFeatureInterface"> +<ANCHOR id="SoupAuthManager" href="libsoup-2.4/SoupAuthManager.html"> +<ANCHOR id="SoupAuthManager.functions" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager.functions"> +<ANCHOR id="SoupAuthManager.signals" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager.signals"> +<ANCHOR id="SoupAuthManager.other" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager.other"> +<ANCHOR id="SoupAuthManager.object-hierarchy" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager.object-hierarchy"> +<ANCHOR id="SoupAuthManager.implemented-interfaces" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager.implemented-interfaces"> +<ANCHOR id="SoupAuthManager.includes" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager.includes"> +<ANCHOR id="SoupAuthManager.description" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager.description"> +<ANCHOR id="SoupAuthManager.functions_details" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager.functions_details"> +<ANCHOR id="SOUP-TYPE-AUTH-MANAGER:CAPS" href="libsoup-2.4/SoupAuthManager.html#SOUP-TYPE-AUTH-MANAGER:CAPS"> +<ANCHOR id="soup-auth-manager-use-auth" href="libsoup-2.4/SoupAuthManager.html#soup-auth-manager-use-auth"> +<ANCHOR id="SoupAuthManager.other_details" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager.other_details"> +<ANCHOR id="SoupAuthManager-struct" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager-struct"> +<ANCHOR id="SoupAuthManager.signal-details" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager.signal-details"> +<ANCHOR id="SoupAuthManager-authenticate" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager-authenticate"> +<ANCHOR id="SoupAuthManager.see-also" href="libsoup-2.4/SoupAuthManager.html#SoupAuthManager.see-also"> +<ANCHOR id="SoupContentDecoder" href="libsoup-2.4/SoupContentDecoder.html"> +<ANCHOR id="SoupContentDecoder.other" href="libsoup-2.4/SoupContentDecoder.html#SoupContentDecoder.other"> +<ANCHOR id="SoupContentDecoder.object-hierarchy" href="libsoup-2.4/SoupContentDecoder.html#SoupContentDecoder.object-hierarchy"> +<ANCHOR id="SoupContentDecoder.implemented-interfaces" href="libsoup-2.4/SoupContentDecoder.html#SoupContentDecoder.implemented-interfaces"> +<ANCHOR id="SoupContentDecoder.includes" href="libsoup-2.4/SoupContentDecoder.html#SoupContentDecoder.includes"> +<ANCHOR id="SoupContentDecoder.description" href="libsoup-2.4/SoupContentDecoder.html#SoupContentDecoder.description"> +<ANCHOR id="SoupContentDecoder.functions_details" href="libsoup-2.4/SoupContentDecoder.html#SoupContentDecoder.functions_details"> +<ANCHOR id="SoupContentDecoder.other_details" href="libsoup-2.4/SoupContentDecoder.html#SoupContentDecoder.other_details"> +<ANCHOR id="SoupContentDecoder-struct" href="libsoup-2.4/SoupContentDecoder.html#SoupContentDecoder-struct"> +<ANCHOR id="SoupContentSniffer" href="libsoup-2.4/SoupContentSniffer.html"> +<ANCHOR id="SoupContentSniffer.functions" href="libsoup-2.4/SoupContentSniffer.html#SoupContentSniffer.functions"> +<ANCHOR id="SoupContentSniffer.other" href="libsoup-2.4/SoupContentSniffer.html#SoupContentSniffer.other"> +<ANCHOR id="SoupContentSniffer.object-hierarchy" href="libsoup-2.4/SoupContentSniffer.html#SoupContentSniffer.object-hierarchy"> +<ANCHOR id="SoupContentSniffer.implemented-interfaces" href="libsoup-2.4/SoupContentSniffer.html#SoupContentSniffer.implemented-interfaces"> +<ANCHOR id="SoupContentSniffer.includes" href="libsoup-2.4/SoupContentSniffer.html#SoupContentSniffer.includes"> +<ANCHOR id="SoupContentSniffer.description" href="libsoup-2.4/SoupContentSniffer.html#SoupContentSniffer.description"> +<ANCHOR id="SoupContentSniffer.functions_details" href="libsoup-2.4/SoupContentSniffer.html#SoupContentSniffer.functions_details"> +<ANCHOR id="soup-content-sniffer-new" href="libsoup-2.4/SoupContentSniffer.html#soup-content-sniffer-new"> +<ANCHOR id="soup-content-sniffer-sniff" href="libsoup-2.4/SoupContentSniffer.html#soup-content-sniffer-sniff"> +<ANCHOR id="soup-content-sniffer-get-buffer-size" href="libsoup-2.4/SoupContentSniffer.html#soup-content-sniffer-get-buffer-size"> +<ANCHOR id="SoupContentSniffer.other_details" href="libsoup-2.4/SoupContentSniffer.html#SoupContentSniffer.other_details"> +<ANCHOR id="SoupContentSniffer-struct" href="libsoup-2.4/SoupContentSniffer.html#SoupContentSniffer-struct"> +<ANCHOR id="SoupCookieJar" href="libsoup-2.4/SoupCookieJar.html"> +<ANCHOR id="SoupCookieJar.functions" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.functions"> +<ANCHOR id="SoupCookieJar.properties" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.properties"> +<ANCHOR id="SoupCookieJar.signals" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.signals"> +<ANCHOR id="SoupCookieJar.other" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.other"> +<ANCHOR id="SoupCookieJar.object-hierarchy" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.object-hierarchy"> +<ANCHOR id="SoupCookieJar.implemented-interfaces" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.implemented-interfaces"> +<ANCHOR id="SoupCookieJar.includes" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.includes"> +<ANCHOR id="SoupCookieJar.description" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.description"> +<ANCHOR id="SoupCookieJar.functions_details" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.functions_details"> +<ANCHOR id="soup-cookie-jar-new" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-new"> +<ANCHOR id="soup-cookie-jar-get-cookies" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-get-cookies"> +<ANCHOR id="soup-cookie-jar-get-cookie-list" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-get-cookie-list"> +<ANCHOR id="soup-cookie-jar-set-cookie" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-set-cookie"> +<ANCHOR id="soup-cookie-jar-set-cookie-with-first-party" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-set-cookie-with-first-party"> +<ANCHOR id="soup-cookie-jar-add-cookie" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-add-cookie"> +<ANCHOR id="soup-cookie-jar-add-cookie-with-first-party" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-add-cookie-with-first-party"> +<ANCHOR id="soup-cookie-jar-delete-cookie" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-delete-cookie"> +<ANCHOR id="soup-cookie-jar-all-cookies" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-all-cookies"> +<ANCHOR id="soup-cookie-jar-get-accept-policy" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-get-accept-policy"> +<ANCHOR id="soup-cookie-jar-set-accept-policy" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-set-accept-policy"> +<ANCHOR id="soup-cookie-jar-is-persistent" href="libsoup-2.4/SoupCookieJar.html#soup-cookie-jar-is-persistent"> +<ANCHOR id="SoupCookieJar.other_details" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.other_details"> +<ANCHOR id="SoupCookieJar-struct" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar-struct"> +<ANCHOR id="SoupCookieJarAcceptPolicy" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJarAcceptPolicy"> +<ANCHOR id="SOUP-COOKIE-JAR-READ-ONLY:CAPS" href="libsoup-2.4/SoupCookieJar.html#SOUP-COOKIE-JAR-READ-ONLY:CAPS"> +<ANCHOR id="SOUP-COOKIE-JAR-ACCEPT-POLICY:CAPS" href="libsoup-2.4/SoupCookieJar.html#SOUP-COOKIE-JAR-ACCEPT-POLICY:CAPS"> +<ANCHOR id="SoupCookieJar.property-details" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.property-details"> +<ANCHOR id="SoupCookieJar--accept-policy" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar--accept-policy"> +<ANCHOR id="SoupCookieJar--read-only" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar--read-only"> +<ANCHOR id="SoupCookieJar.signal-details" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar.signal-details"> +<ANCHOR id="SoupCookieJar-changed" href="libsoup-2.4/SoupCookieJar.html#SoupCookieJar-changed"> +<ANCHOR id="SoupCookieJarText" href="libsoup-2.4/SoupCookieJarText.html"> +<ANCHOR id="SoupCookieJarText.functions" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText.functions"> +<ANCHOR id="SoupCookieJarText.properties" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText.properties"> +<ANCHOR id="SoupCookieJarText.other" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText.other"> +<ANCHOR id="SoupCookieJarText.object-hierarchy" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText.object-hierarchy"> +<ANCHOR id="SoupCookieJarText.implemented-interfaces" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText.implemented-interfaces"> +<ANCHOR id="SoupCookieJarText.includes" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText.includes"> +<ANCHOR id="SoupCookieJarText.description" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText.description"> +<ANCHOR id="SoupCookieJarText.functions_details" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText.functions_details"> +<ANCHOR id="soup-cookie-jar-text-new" href="libsoup-2.4/SoupCookieJarText.html#soup-cookie-jar-text-new"> +<ANCHOR id="SoupCookieJarText.other_details" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText.other_details"> +<ANCHOR id="SoupCookieJarText-struct" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText-struct"> +<ANCHOR id="SOUP-COOKIE-JAR-TEXT-FILENAME:CAPS" href="libsoup-2.4/SoupCookieJarText.html#SOUP-COOKIE-JAR-TEXT-FILENAME:CAPS"> +<ANCHOR id="SoupCookieJarText.property-details" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText.property-details"> +<ANCHOR id="SoupCookieJarText--filename" href="libsoup-2.4/SoupCookieJarText.html#SoupCookieJarText--filename"> +<ANCHOR id="SoupCookieJarDB" href="libsoup-2.4/SoupCookieJarDB.html"> +<ANCHOR id="SoupCookieJarDB.functions" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB.functions"> +<ANCHOR id="SoupCookieJarDB.properties" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB.properties"> +<ANCHOR id="SoupCookieJarDB.other" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB.other"> +<ANCHOR id="SoupCookieJarDB.object-hierarchy" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB.object-hierarchy"> +<ANCHOR id="SoupCookieJarDB.implemented-interfaces" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB.implemented-interfaces"> +<ANCHOR id="SoupCookieJarDB.includes" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB.includes"> +<ANCHOR id="SoupCookieJarDB.description" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB.description"> +<ANCHOR id="SoupCookieJarDB.functions_details" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB.functions_details"> +<ANCHOR id="soup-cookie-jar-db-new" href="libsoup-2.4/SoupCookieJarDB.html#soup-cookie-jar-db-new"> +<ANCHOR id="SoupCookieJarDB.other_details" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB.other_details"> +<ANCHOR id="SoupCookieJarDB-struct" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB-struct"> +<ANCHOR id="SOUP-COOKIE-JAR-DB-FILENAME:CAPS" href="libsoup-2.4/SoupCookieJarDB.html#SOUP-COOKIE-JAR-DB-FILENAME:CAPS"> +<ANCHOR id="SoupCookieJarDB.property-details" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB.property-details"> +<ANCHOR id="SoupCookieJarDB--filename" href="libsoup-2.4/SoupCookieJarDB.html#SoupCookieJarDB--filename"> +<ANCHOR id="SoupLogger" href="libsoup-2.4/SoupLogger.html"> +<ANCHOR id="SoupLogger.functions" href="libsoup-2.4/SoupLogger.html#SoupLogger.functions"> +<ANCHOR id="SoupLogger.other" href="libsoup-2.4/SoupLogger.html#SoupLogger.other"> +<ANCHOR id="SoupLogger.object-hierarchy" href="libsoup-2.4/SoupLogger.html#SoupLogger.object-hierarchy"> +<ANCHOR id="SoupLogger.implemented-interfaces" href="libsoup-2.4/SoupLogger.html#SoupLogger.implemented-interfaces"> +<ANCHOR id="SoupLogger.includes" href="libsoup-2.4/SoupLogger.html#SoupLogger.includes"> +<ANCHOR id="SoupLogger.description" href="libsoup-2.4/SoupLogger.html#SoupLogger.description"> +<ANCHOR id="SoupLogger.functions_details" href="libsoup-2.4/SoupLogger.html#SoupLogger.functions_details"> +<ANCHOR id="soup-logger-new" href="libsoup-2.4/SoupLogger.html#soup-logger-new"> +<ANCHOR id="soup-logger-attach" href="libsoup-2.4/SoupLogger.html#soup-logger-attach"> +<ANCHOR id="soup-logger-detach" href="libsoup-2.4/SoupLogger.html#soup-logger-detach"> +<ANCHOR id="SoupLoggerFilter" href="libsoup-2.4/SoupLogger.html#SoupLoggerFilter"> +<ANCHOR id="soup-logger-set-request-filter" href="libsoup-2.4/SoupLogger.html#soup-logger-set-request-filter"> +<ANCHOR id="soup-logger-set-response-filter" href="libsoup-2.4/SoupLogger.html#soup-logger-set-response-filter"> +<ANCHOR id="SoupLoggerPrinter" href="libsoup-2.4/SoupLogger.html#SoupLoggerPrinter"> +<ANCHOR id="soup-logger-set-printer" href="libsoup-2.4/SoupLogger.html#soup-logger-set-printer"> +<ANCHOR id="SoupLogger.other_details" href="libsoup-2.4/SoupLogger.html#SoupLogger.other_details"> +<ANCHOR id="SoupLogger-struct" href="libsoup-2.4/SoupLogger.html#SoupLogger-struct"> +<ANCHOR id="SoupLoggerLogLevel" href="libsoup-2.4/SoupLogger.html#SoupLoggerLogLevel"> +<ANCHOR id="SoupProxyResolverDefault" href="libsoup-2.4/SoupProxyResolverDefault.html"> +<ANCHOR id="SoupProxyResolverDefault.properties" href="libsoup-2.4/SoupProxyResolverDefault.html#SoupProxyResolverDefault.properties"> +<ANCHOR id="SoupProxyResolverDefault.other" href="libsoup-2.4/SoupProxyResolverDefault.html#SoupProxyResolverDefault.other"> +<ANCHOR id="SoupProxyResolverDefault.object-hierarchy" href="libsoup-2.4/SoupProxyResolverDefault.html#SoupProxyResolverDefault.object-hierarchy"> +<ANCHOR id="SoupProxyResolverDefault.implemented-interfaces" href="libsoup-2.4/SoupProxyResolverDefault.html#SoupProxyResolverDefault.implemented-interfaces"> +<ANCHOR id="SoupProxyResolverDefault.includes" href="libsoup-2.4/SoupProxyResolverDefault.html#SoupProxyResolverDefault.includes"> +<ANCHOR id="SoupProxyResolverDefault.description" href="libsoup-2.4/SoupProxyResolverDefault.html#SoupProxyResolverDefault.description"> +<ANCHOR id="SoupProxyResolverDefault.functions_details" href="libsoup-2.4/SoupProxyResolverDefault.html#SoupProxyResolverDefault.functions_details"> +<ANCHOR id="SoupProxyResolverDefault.other_details" href="libsoup-2.4/SoupProxyResolverDefault.html#SoupProxyResolverDefault.other_details"> +<ANCHOR id="SoupProxyResolverDefault-struct" href="libsoup-2.4/SoupProxyResolverDefault.html#SoupProxyResolverDefault-struct"> +<ANCHOR id="SoupProxyResolverDefault.property-details" href="libsoup-2.4/SoupProxyResolverDefault.html#SoupProxyResolverDefault.property-details"> +<ANCHOR id="SoupProxyResolverDefault--gproxy-resolver" href="libsoup-2.4/SoupProxyResolverDefault.html#SoupProxyResolverDefault--gproxy-resolver"> +<ANCHOR id="libsoup-2.4-HTML-Form-Support" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html"> +<ANCHOR id="libsoup-2.4-HTML-Form-Support.functions" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#libsoup-2.4-HTML-Form-Support.functions"> +<ANCHOR id="libsoup-2.4-HTML-Form-Support.other" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#libsoup-2.4-HTML-Form-Support.other"> +<ANCHOR id="libsoup-2.4-HTML-Form-Support.object-hierarchy" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#libsoup-2.4-HTML-Form-Support.object-hierarchy"> +<ANCHOR id="libsoup-2.4-HTML-Form-Support.includes" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#libsoup-2.4-HTML-Form-Support.includes"> +<ANCHOR id="libsoup-2.4-HTML-Form-Support.description" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#libsoup-2.4-HTML-Form-Support.description"> +<ANCHOR id="libsoup-2.4-HTML-Form-Support.functions_details" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#libsoup-2.4-HTML-Form-Support.functions_details"> +<ANCHOR id="soup-form-decode" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#soup-form-decode"> +<ANCHOR id="soup-form-decode-multipart" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#soup-form-decode-multipart"> +<ANCHOR id="soup-form-encode" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#soup-form-encode"> +<ANCHOR id="soup-form-encode-datalist" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#soup-form-encode-datalist"> +<ANCHOR id="soup-form-encode-hash" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#soup-form-encode-hash"> +<ANCHOR id="soup-form-encode-valist" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#soup-form-encode-valist"> +<ANCHOR id="soup-form-request-new" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#soup-form-request-new"> +<ANCHOR id="soup-form-request-new-from-datalist" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-datalist"> +<ANCHOR id="soup-form-request-new-from-hash" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-hash"> +<ANCHOR id="soup-form-request-new-from-multipart" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-multipart"> +<ANCHOR id="libsoup-2.4-HTML-Form-Support.other_details" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#libsoup-2.4-HTML-Form-Support.other_details"> +<ANCHOR id="SOUP-FORM-MIME-TYPE-MULTIPART:CAPS" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#SOUP-FORM-MIME-TYPE-MULTIPART:CAPS"> +<ANCHOR id="SOUP-FORM-MIME-TYPE-URLENCODED:CAPS" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#SOUP-FORM-MIME-TYPE-URLENCODED:CAPS"> +<ANCHOR id="libsoup-2.4-HTML-Form-Support.see-also" href="libsoup-2.4/libsoup-2.4-HTML-Form-Support.html#libsoup-2.4-HTML-Form-Support.see-also"> +<ANCHOR id="libsoup-2.4-XMLRPC-Support" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html"> +<ANCHOR id="libsoup-2.4-XMLRPC-Support.functions" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#libsoup-2.4-XMLRPC-Support.functions"> +<ANCHOR id="libsoup-2.4-XMLRPC-Support.other" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#libsoup-2.4-XMLRPC-Support.other"> +<ANCHOR id="libsoup-2.4-XMLRPC-Support.object-hierarchy" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#libsoup-2.4-XMLRPC-Support.object-hierarchy"> +<ANCHOR id="libsoup-2.4-XMLRPC-Support.includes" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#libsoup-2.4-XMLRPC-Support.includes"> +<ANCHOR id="libsoup-2.4-XMLRPC-Support.description" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#libsoup-2.4-XMLRPC-Support.description"> +<ANCHOR id="libsoup-2.4-XMLRPC-Support.functions_details" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#libsoup-2.4-XMLRPC-Support.functions_details"> +<ANCHOR id="soup-xmlrpc-build-method-call" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-method-call"> +<ANCHOR id="soup-xmlrpc-request-new" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-request-new"> +<ANCHOR id="soup-xmlrpc-parse-method-response" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-parse-method-response"> +<ANCHOR id="soup-xmlrpc-extract-method-response" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-extract-method-response"> +<ANCHOR id="soup-xmlrpc-parse-method-call" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-parse-method-call"> +<ANCHOR id="soup-xmlrpc-extract-method-call" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-extract-method-call"> +<ANCHOR id="soup-xmlrpc-build-method-response" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-method-response"> +<ANCHOR id="soup-xmlrpc-build-fault" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-fault"> +<ANCHOR id="soup-xmlrpc-set-response" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-set-response"> +<ANCHOR id="soup-xmlrpc-set-fault" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-set-fault"> +<ANCHOR id="libsoup-2.4-XMLRPC-Support.other_details" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#libsoup-2.4-XMLRPC-Support.other_details"> +<ANCHOR id="SOUP-XMLRPC-FAULT:CAPS" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#SOUP-XMLRPC-FAULT:CAPS"> +<ANCHOR id="SoupXMLRPCFault" href="libsoup-2.4/libsoup-2.4-XMLRPC-Support.html#SoupXMLRPCFault"> +<ANCHOR id="libsoup-2.4-GValue-Support" href="libsoup-2.4/libsoup-2.4-GValue-Support.html"> +<ANCHOR id="libsoup-2.4-GValue-Support.functions" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#libsoup-2.4-GValue-Support.functions"> +<ANCHOR id="libsoup-2.4-GValue-Support.object-hierarchy" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#libsoup-2.4-GValue-Support.object-hierarchy"> +<ANCHOR id="libsoup-2.4-GValue-Support.includes" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#libsoup-2.4-GValue-Support.includes"> +<ANCHOR id="libsoup-2.4-GValue-Support.description" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#libsoup-2.4-GValue-Support.description"> +<ANCHOR id="libsoup-2.4-GValue-Support.functions_details" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#libsoup-2.4-GValue-Support.functions_details"> +<ANCHOR id="soup-value-hash-new" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-hash-new"> +<ANCHOR id="soup-value-hash-new-with-vals" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-hash-new-with-vals"> +<ANCHOR id="soup-value-hash-insert-value" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-hash-insert-value"> +<ANCHOR id="soup-value-hash-insert" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-hash-insert"> +<ANCHOR id="soup-value-hash-insert-vals" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-hash-insert-vals"> +<ANCHOR id="soup-value-hash-lookup" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-hash-lookup"> +<ANCHOR id="soup-value-hash-lookup-vals" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-hash-lookup-vals"> +<ANCHOR id="soup-value-array-from-args" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-array-from-args"> +<ANCHOR id="soup-value-array-to-args" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-array-to-args"> +<ANCHOR id="soup-value-array-new" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-array-new"> +<ANCHOR id="soup-value-array-new-with-vals" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-array-new-with-vals"> +<ANCHOR id="soup-value-array-insert" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-array-insert"> +<ANCHOR id="soup-value-array-append" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-array-append"> +<ANCHOR id="soup-value-array-append-vals" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-array-append-vals"> +<ANCHOR id="soup-value-array-get-nth" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#soup-value-array-get-nth"> +<ANCHOR id="SOUP-VALUE-SETV:CAPS" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#SOUP-VALUE-SETV:CAPS"> +<ANCHOR id="SOUP-VALUE-GETV:CAPS" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#SOUP-VALUE-GETV:CAPS"> +<ANCHOR id="SOUP-TYPE-BYTE-ARRAY:CAPS" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#SOUP-TYPE-BYTE-ARRAY:CAPS"> +<ANCHOR id="libsoup-2.4-GValue-Support.other_details" href="libsoup-2.4/libsoup-2.4-GValue-Support.html#libsoup-2.4-GValue-Support.other_details"> +<ANCHOR id="SoupAddress" href="libsoup-2.4/SoupAddress.html"> +<ANCHOR id="SoupAddress.functions" href="libsoup-2.4/SoupAddress.html#SoupAddress.functions"> +<ANCHOR id="SoupAddress.properties" href="libsoup-2.4/SoupAddress.html#SoupAddress.properties"> +<ANCHOR id="SoupAddress.other" href="libsoup-2.4/SoupAddress.html#SoupAddress.other"> +<ANCHOR id="SoupAddress.object-hierarchy" href="libsoup-2.4/SoupAddress.html#SoupAddress.object-hierarchy"> +<ANCHOR id="SoupAddress.implemented-interfaces" href="libsoup-2.4/SoupAddress.html#SoupAddress.implemented-interfaces"> +<ANCHOR id="SoupAddress.includes" href="libsoup-2.4/SoupAddress.html#SoupAddress.includes"> +<ANCHOR id="SoupAddress.description" href="libsoup-2.4/SoupAddress.html#SoupAddress.description"> +<ANCHOR id="SoupAddress.functions_details" href="libsoup-2.4/SoupAddress.html#SoupAddress.functions_details"> +<ANCHOR id="soup-address-new" href="libsoup-2.4/SoupAddress.html#soup-address-new"> +<ANCHOR id="soup-address-new-from-sockaddr" href="libsoup-2.4/SoupAddress.html#soup-address-new-from-sockaddr"> +<ANCHOR id="soup-address-new-any" href="libsoup-2.4/SoupAddress.html#soup-address-new-any"> +<ANCHOR id="SoupAddressCallback" href="libsoup-2.4/SoupAddress.html#SoupAddressCallback"> +<ANCHOR id="soup-address-resolve-async" href="libsoup-2.4/SoupAddress.html#soup-address-resolve-async"> +<ANCHOR id="soup-address-resolve-sync" href="libsoup-2.4/SoupAddress.html#soup-address-resolve-sync"> +<ANCHOR id="soup-address-is-resolved" href="libsoup-2.4/SoupAddress.html#soup-address-is-resolved"> +<ANCHOR id="soup-address-get-name" href="libsoup-2.4/SoupAddress.html#soup-address-get-name"> +<ANCHOR id="soup-address-get-sockaddr" href="libsoup-2.4/SoupAddress.html#soup-address-get-sockaddr"> +<ANCHOR id="soup-address-get-gsockaddr" href="libsoup-2.4/SoupAddress.html#soup-address-get-gsockaddr"> +<ANCHOR id="soup-address-get-physical" href="libsoup-2.4/SoupAddress.html#soup-address-get-physical"> +<ANCHOR id="soup-address-get-port" href="libsoup-2.4/SoupAddress.html#soup-address-get-port"> +<ANCHOR id="soup-address-equal-by-name" href="libsoup-2.4/SoupAddress.html#soup-address-equal-by-name"> +<ANCHOR id="soup-address-hash-by-name" href="libsoup-2.4/SoupAddress.html#soup-address-hash-by-name"> +<ANCHOR id="soup-address-equal-by-ip" href="libsoup-2.4/SoupAddress.html#soup-address-equal-by-ip"> +<ANCHOR id="soup-address-hash-by-ip" href="libsoup-2.4/SoupAddress.html#soup-address-hash-by-ip"> +<ANCHOR id="SoupAddress.other_details" href="libsoup-2.4/SoupAddress.html#SoupAddress.other_details"> +<ANCHOR id="SoupAddress-struct" href="libsoup-2.4/SoupAddress.html#SoupAddress-struct"> +<ANCHOR id="SoupAddressFamily" href="libsoup-2.4/SoupAddress.html#SoupAddressFamily"> +<ANCHOR id="SOUP-ADDRESS-ANY-PORT:CAPS" href="libsoup-2.4/SoupAddress.html#SOUP-ADDRESS-ANY-PORT:CAPS"> +<ANCHOR id="SOUP-ADDRESS-FAMILY:CAPS" href="libsoup-2.4/SoupAddress.html#SOUP-ADDRESS-FAMILY:CAPS"> +<ANCHOR id="SOUP-ADDRESS-NAME:CAPS" href="libsoup-2.4/SoupAddress.html#SOUP-ADDRESS-NAME:CAPS"> +<ANCHOR id="SOUP-ADDRESS-PHYSICAL:CAPS" href="libsoup-2.4/SoupAddress.html#SOUP-ADDRESS-PHYSICAL:CAPS"> +<ANCHOR id="SOUP-ADDRESS-PORT:CAPS" href="libsoup-2.4/SoupAddress.html#SOUP-ADDRESS-PORT:CAPS"> +<ANCHOR id="SOUP-ADDRESS-SOCKADDR:CAPS" href="libsoup-2.4/SoupAddress.html#SOUP-ADDRESS-SOCKADDR:CAPS"> +<ANCHOR id="SOUP-ADDRESS-PROTOCOL:CAPS" href="libsoup-2.4/SoupAddress.html#SOUP-ADDRESS-PROTOCOL:CAPS"> +<ANCHOR id="SoupAddress.property-details" href="libsoup-2.4/SoupAddress.html#SoupAddress.property-details"> +<ANCHOR id="SoupAddress--family" href="libsoup-2.4/SoupAddress.html#SoupAddress--family"> +<ANCHOR id="SoupAddress--name" href="libsoup-2.4/SoupAddress.html#SoupAddress--name"> +<ANCHOR id="SoupAddress--physical" href="libsoup-2.4/SoupAddress.html#SoupAddress--physical"> +<ANCHOR id="SoupAddress--port" href="libsoup-2.4/SoupAddress.html#SoupAddress--port"> +<ANCHOR id="SoupAddress--protocol" href="libsoup-2.4/SoupAddress.html#SoupAddress--protocol"> +<ANCHOR id="SoupAddress--sockaddr" href="libsoup-2.4/SoupAddress.html#SoupAddress--sockaddr"> +<ANCHOR id="SoupSocket" href="libsoup-2.4/SoupSocket.html"> +<ANCHOR id="SoupSocket.functions" href="libsoup-2.4/SoupSocket.html#SoupSocket.functions"> +<ANCHOR id="SoupSocket.properties" href="libsoup-2.4/SoupSocket.html#SoupSocket.properties"> +<ANCHOR id="SoupSocket.signals" href="libsoup-2.4/SoupSocket.html#SoupSocket.signals"> +<ANCHOR id="SoupSocket.other" href="libsoup-2.4/SoupSocket.html#SoupSocket.other"> +<ANCHOR id="SoupSocket.object-hierarchy" href="libsoup-2.4/SoupSocket.html#SoupSocket.object-hierarchy"> +<ANCHOR id="SoupSocket.includes" href="libsoup-2.4/SoupSocket.html#SoupSocket.includes"> +<ANCHOR id="SoupSocket.description" href="libsoup-2.4/SoupSocket.html#SoupSocket.description"> +<ANCHOR id="SoupSocket.functions_details" href="libsoup-2.4/SoupSocket.html#SoupSocket.functions_details"> +<ANCHOR id="soup-socket-new" href="libsoup-2.4/SoupSocket.html#soup-socket-new"> +<ANCHOR id="SoupSocketCallback" href="libsoup-2.4/SoupSocket.html#SoupSocketCallback"> +<ANCHOR id="soup-socket-connect-async" href="libsoup-2.4/SoupSocket.html#soup-socket-connect-async"> +<ANCHOR id="soup-socket-connect-sync" href="libsoup-2.4/SoupSocket.html#soup-socket-connect-sync"> +<ANCHOR id="soup-socket-listen" href="libsoup-2.4/SoupSocket.html#soup-socket-listen"> +<ANCHOR id="soup-socket-start-ssl" href="libsoup-2.4/SoupSocket.html#soup-socket-start-ssl"> +<ANCHOR id="soup-socket-start-proxy-ssl" href="libsoup-2.4/SoupSocket.html#soup-socket-start-proxy-ssl"> +<ANCHOR id="soup-socket-is-ssl" href="libsoup-2.4/SoupSocket.html#soup-socket-is-ssl"> +<ANCHOR id="soup-socket-disconnect" href="libsoup-2.4/SoupSocket.html#soup-socket-disconnect"> +<ANCHOR id="soup-socket-is-connected" href="libsoup-2.4/SoupSocket.html#soup-socket-is-connected"> +<ANCHOR id="soup-socket-get-local-address" href="libsoup-2.4/SoupSocket.html#soup-socket-get-local-address"> +<ANCHOR id="soup-socket-get-remote-address" href="libsoup-2.4/SoupSocket.html#soup-socket-get-remote-address"> +<ANCHOR id="soup-socket-get-fd" href="libsoup-2.4/SoupSocket.html#soup-socket-get-fd"> +<ANCHOR id="soup-socket-read" href="libsoup-2.4/SoupSocket.html#soup-socket-read"> +<ANCHOR id="soup-socket-read-until" href="libsoup-2.4/SoupSocket.html#soup-socket-read-until"> +<ANCHOR id="soup-socket-write" href="libsoup-2.4/SoupSocket.html#soup-socket-write"> +<ANCHOR id="SoupSocket.other_details" href="libsoup-2.4/SoupSocket.html#SoupSocket.other_details"> +<ANCHOR id="SoupSocket-struct" href="libsoup-2.4/SoupSocket.html#SoupSocket-struct"> +<ANCHOR id="SoupSocketIOStatus" href="libsoup-2.4/SoupSocket.html#SoupSocketIOStatus"> +<ANCHOR id="SOUP-SOCKET-LOCAL-ADDRESS:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-LOCAL-ADDRESS:CAPS"> +<ANCHOR id="SOUP-SOCKET-REMOTE-ADDRESS:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-REMOTE-ADDRESS:CAPS"> +<ANCHOR id="SOUP-SOCKET-FLAG-NONBLOCKING:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-FLAG-NONBLOCKING:CAPS"> +<ANCHOR id="SOUP-SOCKET-IS-SERVER:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-IS-SERVER:CAPS"> +<ANCHOR id="SOUP-SOCKET-SSL-CREDENTIALS:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-SSL-CREDENTIALS:CAPS"> +<ANCHOR id="SOUP-SOCKET-ASYNC-CONTEXT:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-ASYNC-CONTEXT:CAPS"> +<ANCHOR id="SOUP-SOCKET-TIMEOUT:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-TIMEOUT:CAPS"> +<ANCHOR id="SOUP-SOCKET-SSL-FALLBACK:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-SSL-FALLBACK:CAPS"> +<ANCHOR id="SOUP-SOCKET-SSL-STRICT:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-SSL-STRICT:CAPS"> +<ANCHOR id="SOUP-SOCKET-TLS-CERTIFICATE:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-TLS-CERTIFICATE:CAPS"> +<ANCHOR id="SOUP-SOCKET-TLS-ERRORS:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-TLS-ERRORS:CAPS"> +<ANCHOR id="SOUP-SOCKET-TRUSTED-CERTIFICATE:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-TRUSTED-CERTIFICATE:CAPS"> +<ANCHOR id="SOUP-SOCKET-USE-THREAD-CONTEXT:CAPS" href="libsoup-2.4/SoupSocket.html#SOUP-SOCKET-USE-THREAD-CONTEXT:CAPS"> +<ANCHOR id="SoupSocket.property-details" href="libsoup-2.4/SoupSocket.html#SoupSocket.property-details"> +<ANCHOR id="SoupSocket--async-context" href="libsoup-2.4/SoupSocket.html#SoupSocket--async-context"> +<ANCHOR id="SoupSocket--clean-dispose" href="libsoup-2.4/SoupSocket.html#SoupSocket--clean-dispose"> +<ANCHOR id="SoupSocket--is-server" href="libsoup-2.4/SoupSocket.html#SoupSocket--is-server"> +<ANCHOR id="SoupSocket--local-address" href="libsoup-2.4/SoupSocket.html#SoupSocket--local-address"> +<ANCHOR id="SoupSocket--non-blocking" href="libsoup-2.4/SoupSocket.html#SoupSocket--non-blocking"> +<ANCHOR id="SoupSocket--proxy-resolver" href="libsoup-2.4/SoupSocket.html#SoupSocket--proxy-resolver"> +<ANCHOR id="SoupSocket--remote-address" href="libsoup-2.4/SoupSocket.html#SoupSocket--remote-address"> +<ANCHOR id="SoupSocket--ssl-creds" href="libsoup-2.4/SoupSocket.html#SoupSocket--ssl-creds"> +<ANCHOR id="SoupSocket--ssl-fallback" href="libsoup-2.4/SoupSocket.html#SoupSocket--ssl-fallback"> +<ANCHOR id="SoupSocket--ssl-strict" href="libsoup-2.4/SoupSocket.html#SoupSocket--ssl-strict"> +<ANCHOR id="SoupSocket--timeout" href="libsoup-2.4/SoupSocket.html#SoupSocket--timeout"> +<ANCHOR id="SoupSocket--tls-certificate" href="libsoup-2.4/SoupSocket.html#SoupSocket--tls-certificate"> +<ANCHOR id="SoupSocket--tls-errors" href="libsoup-2.4/SoupSocket.html#SoupSocket--tls-errors"> +<ANCHOR id="SoupSocket--trusted-certificate" href="libsoup-2.4/SoupSocket.html#SoupSocket--trusted-certificate"> +<ANCHOR id="SoupSocket--use-thread-context" href="libsoup-2.4/SoupSocket.html#SoupSocket--use-thread-context"> +<ANCHOR id="SoupSocket.signal-details" href="libsoup-2.4/SoupSocket.html#SoupSocket.signal-details"> +<ANCHOR id="SoupSocket-disconnected" href="libsoup-2.4/SoupSocket.html#SoupSocket-disconnected"> +<ANCHOR id="SoupSocket-event" href="libsoup-2.4/SoupSocket.html#SoupSocket-event"> +<ANCHOR id="SoupSocket-new-connection" href="libsoup-2.4/SoupSocket.html#SoupSocket-new-connection"> +<ANCHOR id="SoupSocket-readable" href="libsoup-2.4/SoupSocket.html#SoupSocket-readable"> +<ANCHOR id="SoupSocket-writable" href="libsoup-2.4/SoupSocket.html#SoupSocket-writable"> +<ANCHOR id="annotation-glossterm-allow-none" href="libsoup-2.4/annotation-glossary.html#annotation-glossterm-allow-none"> +<ANCHOR id="annotation-glossterm-array" href="libsoup-2.4/annotation-glossary.html#annotation-glossterm-array"> +<ANCHOR id="annotation-glossterm-element-type" href="libsoup-2.4/annotation-glossary.html#annotation-glossterm-element-type"> +<ANCHOR id="annotation-glossterm-inout" href="libsoup-2.4/annotation-glossary.html#annotation-glossterm-inout"> +<ANCHOR id="annotation-glossterm-out" href="libsoup-2.4/annotation-glossary.html#annotation-glossterm-out"> +<ANCHOR id="annotation-glossterm-scope async" href="libsoup-2.4/annotation-glossary.html#annotation-glossterm-scope async"> +<ANCHOR id="annotation-glossterm-scope call" href="libsoup-2.4/annotation-glossary.html#annotation-glossterm-scope call"> +<ANCHOR id="annotation-glossterm-transfer container" href="libsoup-2.4/annotation-glossary.html#annotation-glossterm-transfer container"> +<ANCHOR id="annotation-glossterm-transfer full" href="libsoup-2.4/annotation-glossary.html#annotation-glossterm-transfer full"> +<ANCHOR id="annotation-glossterm-transfer none" href="libsoup-2.4/annotation-glossary.html#annotation-glossterm-transfer none"> +<ANCHOR id="annotation-glossterm-type" href="libsoup-2.4/annotation-glossary.html#annotation-glossterm-type"> diff --git a/docs/reference/html/ix01.html b/docs/reference/html/ix01.html new file mode 100644 index 00000000..ab8df725 --- /dev/null +++ b/docs/reference/html/ix01.html @@ -0,0 +1,1489 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Index</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="index.html" title="libsoup Reference Manual"> +<link rel="prev" href="SoupSocket.html" title="SoupSocket"> +<link rel="next" href="annotation-glossary.html" title="Annotation Glossary"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><img src="up-insensitive.png" width="16" height="16" border="0"></td> +<td><a accesskey="p" href="SoupSocket.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="annotation-glossary.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="index"> +<div class="titlepage"><div><div><h1 class="title"> +<a name="id-1.7"></a>Index</h1></div></div></div> +<div class="index"><div class="indexdiv"> +<h3>S</h3> +<dl> +<dt>SoupAddress, <a class="indexterm" href="SoupAddress.html#SoupAddress-struct">SoupAddress</a> +</dt> +<dt>SoupAddress:family, <a class="indexterm" href="SoupAddress.html#SoupAddress--family">The “family” property</a> +</dt> +<dt>SoupAddress:name, <a class="indexterm" href="SoupAddress.html#SoupAddress--name">The “name” property</a> +</dt> +<dt>SoupAddress:physical, <a class="indexterm" href="SoupAddress.html#SoupAddress--physical">The “physical” property</a> +</dt> +<dt>SoupAddress:port, <a class="indexterm" href="SoupAddress.html#SoupAddress--port">The “port” property</a> +</dt> +<dt>SoupAddress:protocol, <a class="indexterm" href="SoupAddress.html#SoupAddress--protocol">The “protocol” property</a> +</dt> +<dt>SoupAddress:sockaddr, <a class="indexterm" href="SoupAddress.html#SoupAddress--sockaddr">The “sockaddr” property</a> +</dt> +<dt>SoupAddressCallback, <a class="indexterm" href="SoupAddress.html#SoupAddressCallback">SoupAddressCallback ()</a> +</dt> +<dt>SoupAddressFamily, <a class="indexterm" href="SoupAddress.html#SoupAddressFamily">enum SoupAddressFamily</a> +</dt> +<dt>SoupAuth, <a class="indexterm" href="SoupAuth.html#SoupAuth-struct">SoupAuth</a> +</dt> +<dt>SoupAuth:host, <a class="indexterm" href="SoupAuth.html#SoupAuth--host">The “host” property</a> +</dt> +<dt>SoupAuth:is-authenticated, <a class="indexterm" href="SoupAuth.html#SoupAuth--is-authenticated">The “is-authenticated” property</a> +</dt> +<dt>SoupAuth:is-for-proxy, <a class="indexterm" href="SoupAuth.html#SoupAuth--is-for-proxy">The “is-for-proxy” property</a> +</dt> +<dt>SoupAuth:realm, <a class="indexterm" href="SoupAuth.html#SoupAuth--realm">The “realm” property</a> +</dt> +<dt>SoupAuth:scheme-name, <a class="indexterm" href="SoupAuth.html#SoupAuth--scheme-name">The “scheme-name” property</a> +</dt> +<dt>SoupAuthDomain, <a class="indexterm" href="SoupAuthDomain.html#SoupAuthDomain-struct">SoupAuthDomain</a> +</dt> +<dt>SoupAuthDomain:add-path, <a class="indexterm" href="SoupAuthDomain.html#SoupAuthDomain--add-path">The “add-path” property</a> +</dt> +<dt>SoupAuthDomain:filter, <a class="indexterm" href="SoupAuthDomain.html#SoupAuthDomain--filter">The “filter” property</a> +</dt> +<dt>SoupAuthDomain:filter-data, <a class="indexterm" href="SoupAuthDomain.html#SoupAuthDomain--filter-data">The “filter-data” property</a> +</dt> +<dt>SoupAuthDomain:generic-auth-callback, <a class="indexterm" href="SoupAuthDomain.html#SoupAuthDomain--generic-auth-callback">The “generic-auth-callback” property</a> +</dt> +<dt>SoupAuthDomain:generic-auth-data, <a class="indexterm" href="SoupAuthDomain.html#SoupAuthDomain--generic-auth-data">The “generic-auth-data” property</a> +</dt> +<dt>SoupAuthDomain:proxy, <a class="indexterm" href="SoupAuthDomain.html#SoupAuthDomain--proxy">The “proxy” property</a> +</dt> +<dt>SoupAuthDomain:realm, <a class="indexterm" href="SoupAuthDomain.html#SoupAuthDomain--realm">The “realm” property</a> +</dt> +<dt>SoupAuthDomain:remove-path, <a class="indexterm" href="SoupAuthDomain.html#SoupAuthDomain--remove-path">The “remove-path” property</a> +</dt> +<dt>SoupAuthDomainBasic, <a class="indexterm" href="SoupAuthDomainBasic.html#SoupAuthDomainBasic-struct">SoupAuthDomainBasic</a> +</dt> +<dt>SoupAuthDomainBasic:auth-callback, <a class="indexterm" href="SoupAuthDomainBasic.html#SoupAuthDomainBasic--auth-callback">The “auth-callback” property</a> +</dt> +<dt>SoupAuthDomainBasic:auth-data, <a class="indexterm" href="SoupAuthDomainBasic.html#SoupAuthDomainBasic--auth-data">The “auth-data” property</a> +</dt> +<dt>SoupAuthDomainBasicAuthCallback, <a class="indexterm" href="SoupAuthDomainBasic.html#SoupAuthDomainBasicAuthCallback">SoupAuthDomainBasicAuthCallback ()</a> +</dt> +<dt>SoupAuthDomainDigest, <a class="indexterm" href="SoupAuthDomainDigest.html#SoupAuthDomainDigest-struct">SoupAuthDomainDigest</a> +</dt> +<dt>SoupAuthDomainDigest:auth-callback, <a class="indexterm" href="SoupAuthDomainDigest.html#SoupAuthDomainDigest--auth-callback">The “auth-callback” property</a> +</dt> +<dt>SoupAuthDomainDigest:auth-data, <a class="indexterm" href="SoupAuthDomainDigest.html#SoupAuthDomainDigest--auth-data">The “auth-data” property</a> +</dt> +<dt>SoupAuthDomainDigestAuthCallback, <a class="indexterm" href="SoupAuthDomainDigest.html#SoupAuthDomainDigestAuthCallback">SoupAuthDomainDigestAuthCallback ()</a> +</dt> +<dt>SoupAuthDomainFilter, <a class="indexterm" href="SoupAuthDomain.html#SoupAuthDomainFilter">SoupAuthDomainFilter ()</a> +</dt> +<dt>SoupAuthDomainGenericAuthCallback, <a class="indexterm" href="SoupAuthDomain.html#SoupAuthDomainGenericAuthCallback">SoupAuthDomainGenericAuthCallback ()</a> +</dt> +<dt>SoupAuthManager, <a class="indexterm" href="SoupAuthManager.html#SoupAuthManager-struct">SoupAuthManager</a> +</dt> +<dt>SoupAuthManager::authenticate, <a class="indexterm" href="SoupAuthManager.html#SoupAuthManager-authenticate">The “authenticate” signal</a> +</dt> +<dt>SoupBuffer, <a class="indexterm" href="SoupMessageBody.html#SoupBuffer-struct">SoupBuffer</a> +</dt> +<dt>SoupCache, <a class="indexterm" href="SoupCache.html#SoupCache-struct">struct SoupCache</a> +</dt> +<dt>SoupCache:cache-dir, <a class="indexterm" href="SoupCache.html#SoupCache--cache-dir">The “cache-dir” property</a> +</dt> +<dt>SoupCache:cache-type, <a class="indexterm" href="SoupCache.html#SoupCache--cache-type">The “cache-type” property</a> +</dt> +<dt>SoupCacheType, <a class="indexterm" href="SoupCache.html#SoupCacheType">enum SoupCacheType</a> +</dt> +<dt>SoupChunkAllocator, <a class="indexterm" href="SoupMessage.html#SoupChunkAllocator">SoupChunkAllocator ()</a> +</dt> +<dt>SoupClientContext, <a class="indexterm" href="SoupServer.html#SoupClientContext">SoupServer</a> +</dt> +<dt>SoupContentDecoder, <a class="indexterm" href="SoupContentDecoder.html#SoupContentDecoder-struct">SoupContentDecoder</a> +</dt> +<dt>SoupContentSniffer, <a class="indexterm" href="SoupContentSniffer.html#SoupContentSniffer-struct">SoupContentSniffer</a> +</dt> +<dt>SoupCookie, <a class="indexterm" href="SoupCookie.html#SoupCookie-struct">SoupCookie</a> +</dt> +<dt>SoupCookieJar, <a class="indexterm" href="SoupCookieJar.html#SoupCookieJar-struct">SoupCookieJar</a> +</dt> +<dt>SoupCookieJar::changed, <a class="indexterm" href="SoupCookieJar.html#SoupCookieJar-changed">The “changed” signal</a> +</dt> +<dt>SoupCookieJar:accept-policy, <a class="indexterm" href="SoupCookieJar.html#SoupCookieJar--accept-policy">The “accept-policy” property</a> +</dt> +<dt>SoupCookieJar:read-only, <a class="indexterm" href="SoupCookieJar.html#SoupCookieJar--read-only">The “read-only” property</a> +</dt> +<dt>SoupCookieJarAcceptPolicy, <a class="indexterm" href="SoupCookieJar.html#SoupCookieJarAcceptPolicy">enum SoupCookieJarAcceptPolicy</a> +</dt> +<dt>SoupCookieJarDB, <a class="indexterm" href="SoupCookieJarDB.html#SoupCookieJarDB-struct">SoupCookieJarDB</a> +</dt> +<dt>SoupCookieJarDB:filename, <a class="indexterm" href="SoupCookieJarDB.html#SoupCookieJarDB--filename">The “filename” property</a> +</dt> +<dt>SoupCookieJarText, <a class="indexterm" href="SoupCookieJarText.html#SoupCookieJarText-struct">SoupCookieJarText</a> +</dt> +<dt>SoupCookieJarText:filename, <a class="indexterm" href="SoupCookieJarText.html#SoupCookieJarText--filename">The “filename” property</a> +</dt> +<dt>SoupDate, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate-struct">SoupDate</a> +</dt> +<dt>SoupDateFormat, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDateFormat">enum SoupDateFormat</a> +</dt> +<dt>SoupEncoding, <a class="indexterm" href="SoupMessageHeaders.html#SoupEncoding">enum SoupEncoding</a> +</dt> +<dt>SoupExpectation, <a class="indexterm" href="SoupMessageHeaders.html#SoupExpectation">enum SoupExpectation</a> +</dt> +<dt>SoupHTTPVersion, <a class="indexterm" href="SoupMessage.html#SoupHTTPVersion">enum SoupHTTPVersion</a> +</dt> +<dt>SoupLogger, <a class="indexterm" href="SoupLogger.html#SoupLogger-struct">SoupLogger</a> +</dt> +<dt>SoupLoggerFilter, <a class="indexterm" href="SoupLogger.html#SoupLoggerFilter">SoupLoggerFilter ()</a> +</dt> +<dt>SoupLoggerLogLevel, <a class="indexterm" href="SoupLogger.html#SoupLoggerLogLevel">enum SoupLoggerLogLevel</a> +</dt> +<dt>SoupLoggerPrinter, <a class="indexterm" href="SoupLogger.html#SoupLoggerPrinter">SoupLoggerPrinter ()</a> +</dt> +<dt>SoupMemoryUse, <a class="indexterm" href="SoupMessageBody.html#SoupMemoryUse">enum SoupMemoryUse</a> +</dt> +<dt>SoupMessage, <a class="indexterm" href="SoupMessage.html#SoupMessage-struct">SoupMessage</a> +</dt> +<dt>SoupMessage::content-sniffed, <a class="indexterm" href="SoupMessage.html#SoupMessage-content-sniffed">The “content-sniffed” signal</a> +</dt> +<dt>SoupMessage::finished, <a class="indexterm" href="SoupMessage.html#SoupMessage-finished">The “finished” signal</a> +</dt> +<dt>SoupMessage::got-body, <a class="indexterm" href="SoupMessage.html#SoupMessage-got-body">The “got-body” signal</a> +</dt> +<dt>SoupMessage::got-chunk, <a class="indexterm" href="SoupMessage.html#SoupMessage-got-chunk">The “got-chunk” signal</a> +</dt> +<dt>SoupMessage::got-headers, <a class="indexterm" href="SoupMessage.html#SoupMessage-got-headers">The “got-headers” signal</a> +</dt> +<dt>SoupMessage::got-informational, <a class="indexterm" href="SoupMessage.html#SoupMessage-got-informational">The “got-informational” signal</a> +</dt> +<dt>SoupMessage::network-event, <a class="indexterm" href="SoupMessage.html#SoupMessage-network-event">The “network-event” signal</a> +</dt> +<dt>SoupMessage::restarted, <a class="indexterm" href="SoupMessage.html#SoupMessage-restarted">The “restarted” signal</a> +</dt> +<dt>SoupMessage::wrote-body, <a class="indexterm" href="SoupMessage.html#SoupMessage-wrote-body">The “wrote-body” signal</a> +</dt> +<dt>SoupMessage::wrote-body-data, <a class="indexterm" href="SoupMessage.html#SoupMessage-wrote-body-data">The “wrote-body-data” signal</a> +</dt> +<dt>SoupMessage::wrote-chunk, <a class="indexterm" href="SoupMessage.html#SoupMessage-wrote-chunk">The “wrote-chunk” signal</a> +</dt> +<dt>SoupMessage::wrote-headers, <a class="indexterm" href="SoupMessage.html#SoupMessage-wrote-headers">The “wrote-headers” signal</a> +</dt> +<dt>SoupMessage::wrote-informational, <a class="indexterm" href="SoupMessage.html#SoupMessage-wrote-informational">The “wrote-informational” signal</a> +</dt> +<dt>SoupMessage:first-party, <a class="indexterm" href="SoupMessage.html#SoupMessage--first-party">The “first-party” property</a> +</dt> +<dt>SoupMessage:flags, <a class="indexterm" href="SoupMessage.html#SoupMessage--flags">The “flags” property</a> +</dt> +<dt>SoupMessage:http-version, <a class="indexterm" href="SoupMessage.html#SoupMessage--http-version">The “http-version” property</a> +</dt> +<dt>SoupMessage:method, <a class="indexterm" href="SoupMessage.html#SoupMessage--method">The “method” property</a> +</dt> +<dt>SoupMessage:priority, <a class="indexterm" href="SoupMessage.html#SoupMessage--priority">The “priority” property</a> +</dt> +<dt>SoupMessage:reason-phrase, <a class="indexterm" href="SoupMessage.html#SoupMessage--reason-phrase">The “reason-phrase” property</a> +</dt> +<dt>SoupMessage:request-body, <a class="indexterm" href="SoupMessage.html#SoupMessage--request-body">The “request-body” property</a> +</dt> +<dt>SoupMessage:request-body-data, <a class="indexterm" href="SoupMessage.html#SoupMessage--request-body-data">The “request-body-data” property</a> +</dt> +<dt>SoupMessage:request-headers, <a class="indexterm" href="SoupMessage.html#SoupMessage--request-headers">The “request-headers” property</a> +</dt> +<dt>SoupMessage:response-body, <a class="indexterm" href="SoupMessage.html#SoupMessage--response-body">The “response-body” property</a> +</dt> +<dt>SoupMessage:response-body-data, <a class="indexterm" href="SoupMessage.html#SoupMessage--response-body-data">The “response-body-data” property</a> +</dt> +<dt>SoupMessage:response-headers, <a class="indexterm" href="SoupMessage.html#SoupMessage--response-headers">The “response-headers” property</a> +</dt> +<dt>SoupMessage:server-side, <a class="indexterm" href="SoupMessage.html#SoupMessage--server-side">The “server-side” property</a> +</dt> +<dt>SoupMessage:status-code, <a class="indexterm" href="SoupMessage.html#SoupMessage--status-code">The “status-code” property</a> +</dt> +<dt>SoupMessage:tls-certificate, <a class="indexterm" href="SoupMessage.html#SoupMessage--tls-certificate">The “tls-certificate” property</a> +</dt> +<dt>SoupMessage:tls-errors, <a class="indexterm" href="SoupMessage.html#SoupMessage--tls-errors">The “tls-errors” property</a> +</dt> +<dt>SoupMessage:uri, <a class="indexterm" href="SoupMessage.html#SoupMessage--uri">The “uri” property</a> +</dt> +<dt>SoupMessageBody, <a class="indexterm" href="SoupMessageBody.html#SoupMessageBody-struct">SoupMessageBody</a> +</dt> +<dt>SoupMessageFlags, <a class="indexterm" href="SoupMessage.html#SoupMessageFlags">enum SoupMessageFlags</a> +</dt> +<dt>SoupMessageHeaders, <a class="indexterm" href="SoupMessageHeaders.html">SoupMessageHeaders</a> +</dt> +<dt>SoupMessageHeadersForeachFunc, <a class="indexterm" href="SoupMessageHeaders.html#SoupMessageHeadersForeachFunc">SoupMessageHeadersForeachFunc ()</a> +</dt> +<dt>SoupMessageHeadersIter, <a class="indexterm" href="SoupMessageHeaders.html#SoupMessageHeadersIter">SoupMessageHeadersIter</a> +</dt> +<dt>SoupMessageHeadersType, <a class="indexterm" href="SoupMessageHeaders.html#SoupMessageHeadersType">enum SoupMessageHeadersType</a> +</dt> +<dt>SoupMessagePriority, <a class="indexterm" href="SoupMessage.html#SoupMessagePriority">enum SoupMessagePriority</a> +</dt> +<dt>SoupMultipart, <a class="indexterm" href="SoupMultipart.html">SoupMultipart</a> +</dt> +<dt>SoupMultipartInputStream, <a class="indexterm" href="SoupMultipartInputStream.html#SoupMultipartInputStream-struct">struct SoupMultipartInputStream</a> +</dt> +<dt>SoupMultipartInputStream:message, <a class="indexterm" href="SoupMultipartInputStream.html#SoupMultipartInputStream--message">The “message” property</a> +</dt> +<dt>SoupProxyResolverDefault, <a class="indexterm" href="SoupProxyResolverDefault.html#SoupProxyResolverDefault-struct">SoupProxyResolverDefault</a> +</dt> +<dt>SoupProxyResolverDefault:gproxy-resolver, <a class="indexterm" href="SoupProxyResolverDefault.html#SoupProxyResolverDefault--gproxy-resolver">The “gproxy-resolver” property</a> +</dt> +<dt>SoupRange, <a class="indexterm" href="SoupMessageHeaders.html#SoupRange">SoupRange</a> +</dt> +<dt>SoupRequest, <a class="indexterm" href="SoupRequest.html#SoupRequest-struct">SoupRequest</a> +</dt> +<dt>SoupRequest:session, <a class="indexterm" href="SoupRequest.html#SoupRequest--session">The “session” property</a> +</dt> +<dt>SoupRequest:uri, <a class="indexterm" href="SoupRequest.html#SoupRequest--uri">The “uri” property</a> +</dt> +<dt>SoupRequestData, <a class="indexterm" href="SoupRequestData.html#SoupRequestData-struct">SoupRequestData</a> +</dt> +<dt>SoupRequestError, <a class="indexterm" href="SoupSession.html#SoupRequestError">enum SoupRequestError</a> +</dt> +<dt>SoupRequestFile, <a class="indexterm" href="SoupRequestFile.html#SoupRequestFile-struct">SoupRequestFile</a> +</dt> +<dt>SoupRequestHTTP, <a class="indexterm" href="SoupRequestHTTP.html#SoupRequestHTTP-struct">SoupRequestHTTP</a> +</dt> +<dt>SoupServer, <a class="indexterm" href="SoupServer.html#SoupServer-struct">SoupServer</a> +</dt> +<dt>SoupServer::request-aborted, <a class="indexterm" href="SoupServer.html#SoupServer-request-aborted">The “request-aborted” signal</a> +</dt> +<dt>SoupServer::request-finished, <a class="indexterm" href="SoupServer.html#SoupServer-request-finished">The “request-finished” signal</a> +</dt> +<dt>SoupServer::request-read, <a class="indexterm" href="SoupServer.html#SoupServer-request-read">The “request-read” signal</a> +</dt> +<dt>SoupServer::request-started, <a class="indexterm" href="SoupServer.html#SoupServer-request-started">The “request-started” signal</a> +</dt> +<dt>SoupServer:async-context, <a class="indexterm" href="SoupServer.html#SoupServer--async-context">The “async-context” property</a> +</dt> +<dt>SoupServer:http-aliases, <a class="indexterm" href="SoupServer.html#SoupServer--http-aliases">The “http-aliases” property</a> +</dt> +<dt>SoupServer:https-aliases, <a class="indexterm" href="SoupServer.html#SoupServer--https-aliases">The “https-aliases” property</a> +</dt> +<dt>SoupServer:interface, <a class="indexterm" href="SoupServer.html#SoupServer--interface">The “interface” property</a> +</dt> +<dt>SoupServer:port, <a class="indexterm" href="SoupServer.html#SoupServer--port">The “port” property</a> +</dt> +<dt>SoupServer:raw-paths, <a class="indexterm" href="SoupServer.html#SoupServer--raw-paths">The “raw-paths” property</a> +</dt> +<dt>SoupServer:server-header, <a class="indexterm" href="SoupServer.html#SoupServer--server-header">The “server-header” property</a> +</dt> +<dt>SoupServer:ssl-cert-file, <a class="indexterm" href="SoupServer.html#SoupServer--ssl-cert-file">The “ssl-cert-file” property</a> +</dt> +<dt>SoupServer:ssl-key-file, <a class="indexterm" href="SoupServer.html#SoupServer--ssl-key-file">The “ssl-key-file” property</a> +</dt> +<dt>SoupServer:tls-certificate, <a class="indexterm" href="SoupServer.html#SoupServer--tls-certificate">The “tls-certificate” property</a> +</dt> +<dt>SoupServerCallback, <a class="indexterm" href="SoupServer.html#SoupServerCallback">SoupServerCallback ()</a> +</dt> +<dt>SoupSession, <a class="indexterm" href="SoupSession.html#SoupSession-struct">SoupSession</a> +</dt> +<dt>SoupSession::authenticate, <a class="indexterm" href="SoupSession.html#SoupSession-authenticate">The “authenticate” signal</a> +</dt> +<dt>SoupSession::connection-created, <a class="indexterm" href="SoupSession.html#SoupSession-connection-created">The “connection-created” signal</a> +</dt> +<dt>SoupSession::request-queued, <a class="indexterm" href="SoupSession.html#SoupSession-request-queued">The “request-queued” signal</a> +</dt> +<dt>SoupSession::request-started, <a class="indexterm" href="SoupSession.html#SoupSession-request-started">The “request-started” signal</a> +</dt> +<dt>SoupSession::request-unqueued, <a class="indexterm" href="SoupSession.html#SoupSession-request-unqueued">The “request-unqueued” signal</a> +</dt> +<dt>SoupSession::tunneling, <a class="indexterm" href="SoupSession.html#SoupSession-tunneling">The “tunneling” signal</a> +</dt> +<dt>SoupSession:accept-language, <a class="indexterm" href="SoupSession.html#SoupSession--accept-language">The “accept-language” property</a> +</dt> +<dt>SoupSession:accept-language-auto, <a class="indexterm" href="SoupSession.html#SoupSession--accept-language-auto">The “accept-language-auto” property</a> +</dt> +<dt>SoupSession:add-feature, <a class="indexterm" href="SoupSession.html#SoupSession--add-feature">The “add-feature” property</a> +</dt> +<dt>SoupSession:add-feature-by-type, <a class="indexterm" href="SoupSession.html#SoupSession--add-feature-by-type">The “add-feature-by-type” property</a> +</dt> +<dt>SoupSession:async-context, <a class="indexterm" href="SoupSession.html#SoupSession--async-context">The “async-context” property</a> +</dt> +<dt>SoupSession:http-aliases, <a class="indexterm" href="SoupSession.html#SoupSession--http-aliases">The “http-aliases” property</a> +</dt> +<dt>SoupSession:https-aliases, <a class="indexterm" href="SoupSession.html#SoupSession--https-aliases">The “https-aliases” property</a> +</dt> +<dt>SoupSession:idle-timeout, <a class="indexterm" href="SoupSession.html#SoupSession--idle-timeout">The “idle-timeout” property</a> +</dt> +<dt>SoupSession:local-address, <a class="indexterm" href="SoupSession.html#SoupSession--local-address">The “local-address” property</a> +</dt> +<dt>SoupSession:max-conns, <a class="indexterm" href="SoupSession.html#SoupSession--max-conns">The “max-conns” property</a> +</dt> +<dt>SoupSession:max-conns-per-host, <a class="indexterm" href="SoupSession.html#SoupSession--max-conns-per-host">The “max-conns-per-host” property</a> +</dt> +<dt>SoupSession:proxy-resolver, <a class="indexterm" href="SoupSession.html#SoupSession--proxy-resolver">The “proxy-resolver” property</a> +</dt> +<dt>SoupSession:proxy-uri, <a class="indexterm" href="SoupSession.html#SoupSession--proxy-uri">The “proxy-uri” property</a> +</dt> +<dt>SoupSession:remove-feature-by-type, <a class="indexterm" href="SoupSession.html#SoupSession--remove-feature-by-type">The “remove-feature-by-type” property</a> +</dt> +<dt>SoupSession:ssl-ca-file, <a class="indexterm" href="SoupSession.html#SoupSession--ssl-ca-file">The “ssl-ca-file” property</a> +</dt> +<dt>SoupSession:ssl-strict, <a class="indexterm" href="SoupSession.html#SoupSession--ssl-strict">The “ssl-strict” property</a> +</dt> +<dt>SoupSession:ssl-use-system-ca-file, <a class="indexterm" href="SoupSession.html#SoupSession--ssl-use-system-ca-file">The “ssl-use-system-ca-file” property</a> +</dt> +<dt>SoupSession:timeout, <a class="indexterm" href="SoupSession.html#SoupSession--timeout">The “timeout” property</a> +</dt> +<dt>SoupSession:tls-database, <a class="indexterm" href="SoupSession.html#SoupSession--tls-database">The “tls-database” property</a> +</dt> +<dt>SoupSession:use-ntlm, <a class="indexterm" href="SoupSession.html#SoupSession--use-ntlm">The “use-ntlm” property</a> +</dt> +<dt>SoupSession:use-thread-context, <a class="indexterm" href="SoupSession.html#SoupSession--use-thread-context">The “use-thread-context” property</a> +</dt> +<dt>SoupSession:user-agent, <a class="indexterm" href="SoupSession.html#SoupSession--user-agent">The “user-agent” property</a> +</dt> +<dt>SoupSessionAsync, <a class="indexterm" href="SoupSessionAsync.html#SoupSessionAsync-struct">SoupSessionAsync</a> +</dt> +<dt>SoupSessionCallback, <a class="indexterm" href="SoupSession.html#SoupSessionCallback">SoupSessionCallback ()</a> +</dt> +<dt>SoupSessionFeature, <a class="indexterm" href="SoupSessionFeature.html#SoupSessionFeature-struct">SoupSessionFeature</a> +</dt> +<dt>SoupSessionFeatureInterface, <a class="indexterm" href="SoupSessionFeature.html#SoupSessionFeatureInterface">SoupSessionFeatureInterface</a> +</dt> +<dt>SoupSessionSync, <a class="indexterm" href="SoupSessionSync.html#SoupSessionSync-struct">SoupSessionSync</a> +</dt> +<dt>SoupSocket, <a class="indexterm" href="SoupSocket.html#SoupSocket-struct">SoupSocket</a> +</dt> +<dt>SoupSocket::disconnected, <a class="indexterm" href="SoupSocket.html#SoupSocket-disconnected">The “disconnected” signal</a> +</dt> +<dt>SoupSocket::event, <a class="indexterm" href="SoupSocket.html#SoupSocket-event">The “event” signal</a> +</dt> +<dt>SoupSocket::new-connection, <a class="indexterm" href="SoupSocket.html#SoupSocket-new-connection">The “new-connection” signal</a> +</dt> +<dt>SoupSocket::readable, <a class="indexterm" href="SoupSocket.html#SoupSocket-readable">The “readable” signal</a> +</dt> +<dt>SoupSocket::writable, <a class="indexterm" href="SoupSocket.html#SoupSocket-writable">The “writable” signal</a> +</dt> +<dt>SoupSocket:async-context, <a class="indexterm" href="SoupSocket.html#SoupSocket--async-context">The “async-context” property</a> +</dt> +<dt>SoupSocket:clean-dispose, <a class="indexterm" href="SoupSocket.html#SoupSocket--clean-dispose">The “clean-dispose” property</a> +</dt> +<dt>SoupSocket:is-server, <a class="indexterm" href="SoupSocket.html#SoupSocket--is-server">The “is-server” property</a> +</dt> +<dt>SoupSocket:local-address, <a class="indexterm" href="SoupSocket.html#SoupSocket--local-address">The “local-address” property</a> +</dt> +<dt>SoupSocket:non-blocking, <a class="indexterm" href="SoupSocket.html#SoupSocket--non-blocking">The “non-blocking” property</a> +</dt> +<dt>SoupSocket:proxy-resolver, <a class="indexterm" href="SoupSocket.html#SoupSocket--proxy-resolver">The “proxy-resolver” property</a> +</dt> +<dt>SoupSocket:remote-address, <a class="indexterm" href="SoupSocket.html#SoupSocket--remote-address">The “remote-address” property</a> +</dt> +<dt>SoupSocket:ssl-creds, <a class="indexterm" href="SoupSocket.html#SoupSocket--ssl-creds">The “ssl-creds” property</a> +</dt> +<dt>SoupSocket:ssl-fallback, <a class="indexterm" href="SoupSocket.html#SoupSocket--ssl-fallback">The “ssl-fallback” property</a> +</dt> +<dt>SoupSocket:ssl-strict, <a class="indexterm" href="SoupSocket.html#SoupSocket--ssl-strict">The “ssl-strict” property</a> +</dt> +<dt>SoupSocket:timeout, <a class="indexterm" href="SoupSocket.html#SoupSocket--timeout">The “timeout” property</a> +</dt> +<dt>SoupSocket:tls-certificate, <a class="indexterm" href="SoupSocket.html#SoupSocket--tls-certificate">The “tls-certificate” property</a> +</dt> +<dt>SoupSocket:tls-errors, <a class="indexterm" href="SoupSocket.html#SoupSocket--tls-errors">The “tls-errors” property</a> +</dt> +<dt>SoupSocket:trusted-certificate, <a class="indexterm" href="SoupSocket.html#SoupSocket--trusted-certificate">The “trusted-certificate” property</a> +</dt> +<dt>SoupSocket:use-thread-context, <a class="indexterm" href="SoupSocket.html#SoupSocket--use-thread-context">The “use-thread-context” property</a> +</dt> +<dt>SoupSocketCallback, <a class="indexterm" href="SoupSocket.html#SoupSocketCallback">SoupSocketCallback ()</a> +</dt> +<dt>SoupSocketIOStatus, <a class="indexterm" href="SoupSocket.html#SoupSocketIOStatus">enum SoupSocketIOStatus</a> +</dt> +<dt>SoupStatus, <a class="indexterm" href="libsoup-2.4-soup-status.html#SoupStatus">enum SoupStatus</a> +</dt> +<dt>SoupTLDError, <a class="indexterm" href="libsoup-2.4-Top-Level-Domain-utils.html#SoupTLDError">enum SoupTLDError</a> +</dt> +<dt>SoupURI, <a class="indexterm" href="SoupURI.html#SoupURI-struct">SoupURI</a> +</dt> +<dt>SoupXMLRPCFault, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#SoupXMLRPCFault">enum SoupXMLRPCFault</a> +</dt> +<dt>SOUP_ADDRESS_ANY_PORT, <a class="indexterm" href="SoupAddress.html#SOUP-ADDRESS-ANY-PORT:CAPS">SOUP_ADDRESS_ANY_PORT</a> +</dt> +<dt>soup_address_equal_by_ip, <a class="indexterm" href="SoupAddress.html#soup-address-equal-by-ip">soup_address_equal_by_ip ()</a> +</dt> +<dt>soup_address_equal_by_name, <a class="indexterm" href="SoupAddress.html#soup-address-equal-by-name">soup_address_equal_by_name ()</a> +</dt> +<dt>SOUP_ADDRESS_FAMILY, <a class="indexterm" href="SoupAddress.html#SOUP-ADDRESS-FAMILY:CAPS">SOUP_ADDRESS_FAMILY</a> +</dt> +<dt>soup_address_get_gsockaddr, <a class="indexterm" href="SoupAddress.html#soup-address-get-gsockaddr">soup_address_get_gsockaddr ()</a> +</dt> +<dt>soup_address_get_name, <a class="indexterm" href="SoupAddress.html#soup-address-get-name">soup_address_get_name ()</a> +</dt> +<dt>soup_address_get_physical, <a class="indexterm" href="SoupAddress.html#soup-address-get-physical">soup_address_get_physical ()</a> +</dt> +<dt>soup_address_get_port, <a class="indexterm" href="SoupAddress.html#soup-address-get-port">soup_address_get_port ()</a> +</dt> +<dt>soup_address_get_sockaddr, <a class="indexterm" href="SoupAddress.html#soup-address-get-sockaddr">soup_address_get_sockaddr ()</a> +</dt> +<dt>soup_address_hash_by_ip, <a class="indexterm" href="SoupAddress.html#soup-address-hash-by-ip">soup_address_hash_by_ip ()</a> +</dt> +<dt>soup_address_hash_by_name, <a class="indexterm" href="SoupAddress.html#soup-address-hash-by-name">soup_address_hash_by_name ()</a> +</dt> +<dt>soup_address_is_resolved, <a class="indexterm" href="SoupAddress.html#soup-address-is-resolved">soup_address_is_resolved ()</a> +</dt> +<dt>SOUP_ADDRESS_NAME, <a class="indexterm" href="SoupAddress.html#SOUP-ADDRESS-NAME:CAPS">SOUP_ADDRESS_NAME</a> +</dt> +<dt>soup_address_new, <a class="indexterm" href="SoupAddress.html#soup-address-new">soup_address_new ()</a> +</dt> +<dt>soup_address_new_any, <a class="indexterm" href="SoupAddress.html#soup-address-new-any">soup_address_new_any ()</a> +</dt> +<dt>soup_address_new_from_sockaddr, <a class="indexterm" href="SoupAddress.html#soup-address-new-from-sockaddr">soup_address_new_from_sockaddr ()</a> +</dt> +<dt>SOUP_ADDRESS_PHYSICAL, <a class="indexterm" href="SoupAddress.html#SOUP-ADDRESS-PHYSICAL:CAPS">SOUP_ADDRESS_PHYSICAL</a> +</dt> +<dt>SOUP_ADDRESS_PORT, <a class="indexterm" href="SoupAddress.html#SOUP-ADDRESS-PORT:CAPS">SOUP_ADDRESS_PORT</a> +</dt> +<dt>SOUP_ADDRESS_PROTOCOL, <a class="indexterm" href="SoupAddress.html#SOUP-ADDRESS-PROTOCOL:CAPS">SOUP_ADDRESS_PROTOCOL</a> +</dt> +<dt>soup_address_resolve_async, <a class="indexterm" href="SoupAddress.html#soup-address-resolve-async">soup_address_resolve_async ()</a> +</dt> +<dt>soup_address_resolve_sync, <a class="indexterm" href="SoupAddress.html#soup-address-resolve-sync">soup_address_resolve_sync ()</a> +</dt> +<dt>SOUP_ADDRESS_SOCKADDR, <a class="indexterm" href="SoupAddress.html#SOUP-ADDRESS-SOCKADDR:CAPS">SOUP_ADDRESS_SOCKADDR</a> +</dt> +<dt>soup_add_completion, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-completion">soup_add_completion ()</a> +</dt> +<dt>soup_add_idle, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-idle">soup_add_idle ()</a> +</dt> +<dt>soup_add_io_watch, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-io-watch">soup_add_io_watch ()</a> +</dt> +<dt>soup_add_timeout, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-timeout">soup_add_timeout ()</a> +</dt> +<dt>soup_auth_authenticate, <a class="indexterm" href="SoupAuth.html#soup-auth-authenticate">soup_auth_authenticate ()</a> +</dt> +<dt>soup_auth_domain_accepts, <a class="indexterm" href="SoupAuthDomain.html#soup-auth-domain-accepts">soup_auth_domain_accepts ()</a> +</dt> +<dt>soup_auth_domain_add_path, <a class="indexterm" href="SoupAuthDomain.html#soup-auth-domain-add-path">soup_auth_domain_add_path ()</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_ADD_PATH, <a class="indexterm" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-ADD-PATH:CAPS">SOUP_AUTH_DOMAIN_ADD_PATH</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK, <a class="indexterm" href="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-CALLBACK:CAPS">SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA, <a class="indexterm" href="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-DATA:CAPS">SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA</a> +</dt> +<dt>soup_auth_domain_basic_new, <a class="indexterm" href="SoupAuthDomainBasic.html#soup-auth-domain-basic-new">soup_auth_domain_basic_new ()</a> +</dt> +<dt>soup_auth_domain_basic_set_auth_callback, <a class="indexterm" href="SoupAuthDomainBasic.html#soup-auth-domain-basic-set-auth-callback">soup_auth_domain_basic_set_auth_callback ()</a> +</dt> +<dt>soup_auth_domain_challenge, <a class="indexterm" href="SoupAuthDomain.html#soup-auth-domain-challenge">soup_auth_domain_challenge ()</a> +</dt> +<dt>soup_auth_domain_check_password, <a class="indexterm" href="SoupAuthDomain.html#soup-auth-domain-check-password">soup_auth_domain_check_password ()</a> +</dt> +<dt>soup_auth_domain_covers, <a class="indexterm" href="SoupAuthDomain.html#soup-auth-domain-covers">soup_auth_domain_covers ()</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK, <a class="indexterm" href="SoupAuthDomainDigest.html#SOUP-AUTH-DOMAIN-DIGEST-AUTH-CALLBACK:CAPS">SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA, <a class="indexterm" href="SoupAuthDomainDigest.html#SOUP-AUTH-DOMAIN-DIGEST-AUTH-DATA:CAPS">SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA</a> +</dt> +<dt>soup_auth_domain_digest_encode_password, <a class="indexterm" href="SoupAuthDomainDigest.html#soup-auth-domain-digest-encode-password">soup_auth_domain_digest_encode_password ()</a> +</dt> +<dt>soup_auth_domain_digest_new, <a class="indexterm" href="SoupAuthDomainDigest.html#soup-auth-domain-digest-new">soup_auth_domain_digest_new ()</a> +</dt> +<dt>soup_auth_domain_digest_set_auth_callback, <a class="indexterm" href="SoupAuthDomainDigest.html#soup-auth-domain-digest-set-auth-callback">soup_auth_domain_digest_set_auth_callback ()</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_FILTER, <a class="indexterm" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-FILTER:CAPS">SOUP_AUTH_DOMAIN_FILTER</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_FILTER_DATA, <a class="indexterm" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-FILTER-DATA:CAPS">SOUP_AUTH_DOMAIN_FILTER_DATA</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK, <a class="indexterm" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-GENERIC-AUTH-CALLBACK:CAPS">SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA, <a class="indexterm" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-GENERIC-AUTH-DATA:CAPS">SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA</a> +</dt> +<dt>soup_auth_domain_get_realm, <a class="indexterm" href="SoupAuthDomain.html#soup-auth-domain-get-realm">soup_auth_domain_get_realm ()</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_PROXY, <a class="indexterm" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-PROXY:CAPS">SOUP_AUTH_DOMAIN_PROXY</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_REALM, <a class="indexterm" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REALM:CAPS">SOUP_AUTH_DOMAIN_REALM</a> +</dt> +<dt>soup_auth_domain_remove_path, <a class="indexterm" href="SoupAuthDomain.html#soup-auth-domain-remove-path">soup_auth_domain_remove_path ()</a> +</dt> +<dt>SOUP_AUTH_DOMAIN_REMOVE_PATH, <a class="indexterm" href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REMOVE-PATH:CAPS">SOUP_AUTH_DOMAIN_REMOVE_PATH</a> +</dt> +<dt>soup_auth_domain_set_filter, <a class="indexterm" href="SoupAuthDomain.html#soup-auth-domain-set-filter">soup_auth_domain_set_filter ()</a> +</dt> +<dt>soup_auth_domain_set_generic_auth_callback, <a class="indexterm" href="SoupAuthDomain.html#soup-auth-domain-set-generic-auth-callback">soup_auth_domain_set_generic_auth_callback ()</a> +</dt> +<dt>soup_auth_free_protection_space, <a class="indexterm" href="SoupAuth.html#soup-auth-free-protection-space">soup_auth_free_protection_space ()</a> +</dt> +<dt>soup_auth_get_authorization, <a class="indexterm" href="SoupAuth.html#soup-auth-get-authorization">soup_auth_get_authorization ()</a> +</dt> +<dt>soup_auth_get_host, <a class="indexterm" href="SoupAuth.html#soup-auth-get-host">soup_auth_get_host ()</a> +</dt> +<dt>soup_auth_get_info, <a class="indexterm" href="SoupAuth.html#soup-auth-get-info">soup_auth_get_info ()</a> +</dt> +<dt>soup_auth_get_protection_space, <a class="indexterm" href="SoupAuth.html#soup-auth-get-protection-space">soup_auth_get_protection_space ()</a> +</dt> +<dt>soup_auth_get_realm, <a class="indexterm" href="SoupAuth.html#soup-auth-get-realm">soup_auth_get_realm ()</a> +</dt> +<dt>soup_auth_get_scheme_name, <a class="indexterm" href="SoupAuth.html#soup-auth-get-scheme-name">soup_auth_get_scheme_name ()</a> +</dt> +<dt>SOUP_AUTH_HOST, <a class="indexterm" href="SoupAuth.html#SOUP-AUTH-HOST:CAPS">SOUP_AUTH_HOST</a> +</dt> +<dt>soup_auth_is_authenticated, <a class="indexterm" href="SoupAuth.html#soup-auth-is-authenticated">soup_auth_is_authenticated ()</a> +</dt> +<dt>SOUP_AUTH_IS_AUTHENTICATED, <a class="indexterm" href="SoupAuth.html#SOUP-AUTH-IS-AUTHENTICATED:CAPS">SOUP_AUTH_IS_AUTHENTICATED</a> +</dt> +<dt>soup_auth_is_for_proxy, <a class="indexterm" href="SoupAuth.html#soup-auth-is-for-proxy">soup_auth_is_for_proxy ()</a> +</dt> +<dt>SOUP_AUTH_IS_FOR_PROXY, <a class="indexterm" href="SoupAuth.html#SOUP-AUTH-IS-FOR-PROXY:CAPS">SOUP_AUTH_IS_FOR_PROXY</a> +</dt> +<dt>soup_auth_is_ready, <a class="indexterm" href="SoupAuth.html#soup-auth-is-ready">soup_auth_is_ready ()</a> +</dt> +<dt>soup_auth_manager_use_auth, <a class="indexterm" href="SoupAuthManager.html#soup-auth-manager-use-auth">soup_auth_manager_use_auth ()</a> +</dt> +<dt>soup_auth_new, <a class="indexterm" href="SoupAuth.html#soup-auth-new">soup_auth_new ()</a> +</dt> +<dt>SOUP_AUTH_REALM, <a class="indexterm" href="SoupAuth.html#SOUP-AUTH-REALM:CAPS">SOUP_AUTH_REALM</a> +</dt> +<dt>SOUP_AUTH_SCHEME_NAME, <a class="indexterm" href="SoupAuth.html#SOUP-AUTH-SCHEME-NAME:CAPS">SOUP_AUTH_SCHEME_NAME</a> +</dt> +<dt>soup_auth_update, <a class="indexterm" href="SoupAuth.html#soup-auth-update">soup_auth_update ()</a> +</dt> +<dt>soup_buffer_copy, <a class="indexterm" href="SoupMessageBody.html#soup-buffer-copy">soup_buffer_copy ()</a> +</dt> +<dt>soup_buffer_free, <a class="indexterm" href="SoupMessageBody.html#soup-buffer-free">soup_buffer_free ()</a> +</dt> +<dt>soup_buffer_get_as_bytes, <a class="indexterm" href="SoupMessageBody.html#soup-buffer-get-as-bytes">soup_buffer_get_as_bytes ()</a> +</dt> +<dt>soup_buffer_get_data, <a class="indexterm" href="SoupMessageBody.html#soup-buffer-get-data">soup_buffer_get_data ()</a> +</dt> +<dt>soup_buffer_get_owner, <a class="indexterm" href="SoupMessageBody.html#soup-buffer-get-owner">soup_buffer_get_owner ()</a> +</dt> +<dt>soup_buffer_new, <a class="indexterm" href="SoupMessageBody.html#soup-buffer-new">soup_buffer_new ()</a> +</dt> +<dt>soup_buffer_new_subbuffer, <a class="indexterm" href="SoupMessageBody.html#soup-buffer-new-subbuffer">soup_buffer_new_subbuffer ()</a> +</dt> +<dt>soup_buffer_new_take, <a class="indexterm" href="SoupMessageBody.html#soup-buffer-new-take">soup_buffer_new_take ()</a> +</dt> +<dt>soup_buffer_new_with_owner, <a class="indexterm" href="SoupMessageBody.html#soup-buffer-new-with-owner">soup_buffer_new_with_owner ()</a> +</dt> +<dt>soup_cache_clear, <a class="indexterm" href="SoupCache.html#soup-cache-clear">soup_cache_clear ()</a> +</dt> +<dt>soup_cache_dump, <a class="indexterm" href="SoupCache.html#soup-cache-dump">soup_cache_dump ()</a> +</dt> +<dt>soup_cache_flush, <a class="indexterm" href="SoupCache.html#soup-cache-flush">soup_cache_flush ()</a> +</dt> +<dt>soup_cache_get_max_size, <a class="indexterm" href="SoupCache.html#soup-cache-get-max-size">soup_cache_get_max_size ()</a> +</dt> +<dt>soup_cache_load, <a class="indexterm" href="SoupCache.html#soup-cache-load">soup_cache_load ()</a> +</dt> +<dt>soup_cache_new, <a class="indexterm" href="SoupCache.html#soup-cache-new">soup_cache_new ()</a> +</dt> +<dt>soup_cache_set_max_size, <a class="indexterm" href="SoupCache.html#soup-cache-set-max-size">soup_cache_set_max_size ()</a> +</dt> +<dt>soup_check_version, <a class="indexterm" href="libsoup-2.4-Version-Information.html#soup-check-version">soup_check_version ()</a> +</dt> +<dt>SOUP_CHECK_VERSION, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-CHECK-VERSION:CAPS">SOUP_CHECK_VERSION()</a> +</dt> +<dt>soup_client_context_get_address, <a class="indexterm" href="SoupServer.html#soup-client-context-get-address">soup_client_context_get_address ()</a> +</dt> +<dt>soup_client_context_get_auth_domain, <a class="indexterm" href="SoupServer.html#soup-client-context-get-auth-domain">soup_client_context_get_auth_domain ()</a> +</dt> +<dt>soup_client_context_get_auth_user, <a class="indexterm" href="SoupServer.html#soup-client-context-get-auth-user">soup_client_context_get_auth_user ()</a> +</dt> +<dt>soup_client_context_get_host, <a class="indexterm" href="SoupServer.html#soup-client-context-get-host">soup_client_context_get_host ()</a> +</dt> +<dt>soup_client_context_get_socket, <a class="indexterm" href="SoupServer.html#soup-client-context-get-socket">soup_client_context_get_socket ()</a> +</dt> +<dt>soup_content_sniffer_get_buffer_size, <a class="indexterm" href="SoupContentSniffer.html#soup-content-sniffer-get-buffer-size">soup_content_sniffer_get_buffer_size ()</a> +</dt> +<dt>soup_content_sniffer_new, <a class="indexterm" href="SoupContentSniffer.html#soup-content-sniffer-new">soup_content_sniffer_new ()</a> +</dt> +<dt>soup_content_sniffer_sniff, <a class="indexterm" href="SoupContentSniffer.html#soup-content-sniffer-sniff">soup_content_sniffer_sniff ()</a> +</dt> +<dt>soup_cookies_free, <a class="indexterm" href="SoupCookie.html#soup-cookies-free">soup_cookies_free ()</a> +</dt> +<dt>soup_cookies_from_request, <a class="indexterm" href="SoupCookie.html#soup-cookies-from-request">soup_cookies_from_request ()</a> +</dt> +<dt>soup_cookies_from_response, <a class="indexterm" href="SoupCookie.html#soup-cookies-from-response">soup_cookies_from_response ()</a> +</dt> +<dt>soup_cookies_to_cookie_header, <a class="indexterm" href="SoupCookie.html#soup-cookies-to-cookie-header">soup_cookies_to_cookie_header ()</a> +</dt> +<dt>soup_cookies_to_request, <a class="indexterm" href="SoupCookie.html#soup-cookies-to-request">soup_cookies_to_request ()</a> +</dt> +<dt>soup_cookies_to_response, <a class="indexterm" href="SoupCookie.html#soup-cookies-to-response">soup_cookies_to_response ()</a> +</dt> +<dt>soup_cookie_applies_to_uri, <a class="indexterm" href="SoupCookie.html#soup-cookie-applies-to-uri">soup_cookie_applies_to_uri ()</a> +</dt> +<dt>soup_cookie_copy, <a class="indexterm" href="SoupCookie.html#soup-cookie-copy">soup_cookie_copy ()</a> +</dt> +<dt>soup_cookie_domain_matches, <a class="indexterm" href="SoupCookie.html#soup-cookie-domain-matches">soup_cookie_domain_matches ()</a> +</dt> +<dt>soup_cookie_free, <a class="indexterm" href="SoupCookie.html#soup-cookie-free">soup_cookie_free ()</a> +</dt> +<dt>soup_cookie_get_domain, <a class="indexterm" href="SoupCookie.html#soup-cookie-get-domain">soup_cookie_get_domain ()</a> +</dt> +<dt>soup_cookie_get_expires, <a class="indexterm" href="SoupCookie.html#soup-cookie-get-expires">soup_cookie_get_expires ()</a> +</dt> +<dt>soup_cookie_get_http_only, <a class="indexterm" href="SoupCookie.html#soup-cookie-get-http-only">soup_cookie_get_http_only ()</a> +</dt> +<dt>soup_cookie_get_name, <a class="indexterm" href="SoupCookie.html#soup-cookie-get-name">soup_cookie_get_name ()</a> +</dt> +<dt>soup_cookie_get_path, <a class="indexterm" href="SoupCookie.html#soup-cookie-get-path">soup_cookie_get_path ()</a> +</dt> +<dt>soup_cookie_get_secure, <a class="indexterm" href="SoupCookie.html#soup-cookie-get-secure">soup_cookie_get_secure ()</a> +</dt> +<dt>soup_cookie_get_value, <a class="indexterm" href="SoupCookie.html#soup-cookie-get-value">soup_cookie_get_value ()</a> +</dt> +<dt>SOUP_COOKIE_JAR_ACCEPT_POLICY, <a class="indexterm" href="SoupCookieJar.html#SOUP-COOKIE-JAR-ACCEPT-POLICY:CAPS">SOUP_COOKIE_JAR_ACCEPT_POLICY</a> +</dt> +<dt>soup_cookie_jar_add_cookie, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-add-cookie">soup_cookie_jar_add_cookie ()</a> +</dt> +<dt>soup_cookie_jar_add_cookie_with_first_party, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-add-cookie-with-first-party">soup_cookie_jar_add_cookie_with_first_party ()</a> +</dt> +<dt>soup_cookie_jar_all_cookies, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-all-cookies">soup_cookie_jar_all_cookies ()</a> +</dt> +<dt>SOUP_COOKIE_JAR_DB_FILENAME, <a class="indexterm" href="SoupCookieJarDB.html#SOUP-COOKIE-JAR-DB-FILENAME:CAPS">SOUP_COOKIE_JAR_DB_FILENAME</a> +</dt> +<dt>soup_cookie_jar_db_new, <a class="indexterm" href="SoupCookieJarDB.html#soup-cookie-jar-db-new">soup_cookie_jar_db_new ()</a> +</dt> +<dt>soup_cookie_jar_delete_cookie, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-delete-cookie">soup_cookie_jar_delete_cookie ()</a> +</dt> +<dt>soup_cookie_jar_get_accept_policy, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-get-accept-policy">soup_cookie_jar_get_accept_policy ()</a> +</dt> +<dt>soup_cookie_jar_get_cookies, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-get-cookies">soup_cookie_jar_get_cookies ()</a> +</dt> +<dt>soup_cookie_jar_get_cookie_list, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-get-cookie-list">soup_cookie_jar_get_cookie_list ()</a> +</dt> +<dt>soup_cookie_jar_is_persistent, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-is-persistent">soup_cookie_jar_is_persistent ()</a> +</dt> +<dt>soup_cookie_jar_new, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-new">soup_cookie_jar_new ()</a> +</dt> +<dt>SOUP_COOKIE_JAR_READ_ONLY, <a class="indexterm" href="SoupCookieJar.html#SOUP-COOKIE-JAR-READ-ONLY:CAPS">SOUP_COOKIE_JAR_READ_ONLY</a> +</dt> +<dt>soup_cookie_jar_set_accept_policy, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-set-accept-policy">soup_cookie_jar_set_accept_policy ()</a> +</dt> +<dt>soup_cookie_jar_set_cookie, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-set-cookie">soup_cookie_jar_set_cookie ()</a> +</dt> +<dt>soup_cookie_jar_set_cookie_with_first_party, <a class="indexterm" href="SoupCookieJar.html#soup-cookie-jar-set-cookie-with-first-party">soup_cookie_jar_set_cookie_with_first_party ()</a> +</dt> +<dt>SOUP_COOKIE_JAR_TEXT_FILENAME, <a class="indexterm" href="SoupCookieJarText.html#SOUP-COOKIE-JAR-TEXT-FILENAME:CAPS">SOUP_COOKIE_JAR_TEXT_FILENAME</a> +</dt> +<dt>soup_cookie_jar_text_new, <a class="indexterm" href="SoupCookieJarText.html#soup-cookie-jar-text-new">soup_cookie_jar_text_new ()</a> +</dt> +<dt>SOUP_COOKIE_MAX_AGE_ONE_DAY, <a class="indexterm" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-DAY:CAPS">SOUP_COOKIE_MAX_AGE_ONE_DAY</a> +</dt> +<dt>SOUP_COOKIE_MAX_AGE_ONE_HOUR, <a class="indexterm" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-HOUR:CAPS">SOUP_COOKIE_MAX_AGE_ONE_HOUR</a> +</dt> +<dt>SOUP_COOKIE_MAX_AGE_ONE_WEEK, <a class="indexterm" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-WEEK:CAPS">SOUP_COOKIE_MAX_AGE_ONE_WEEK</a> +</dt> +<dt>SOUP_COOKIE_MAX_AGE_ONE_YEAR, <a class="indexterm" href="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-YEAR:CAPS">SOUP_COOKIE_MAX_AGE_ONE_YEAR</a> +</dt> +<dt>soup_cookie_new, <a class="indexterm" href="SoupCookie.html#soup-cookie-new">soup_cookie_new ()</a> +</dt> +<dt>soup_cookie_parse, <a class="indexterm" href="SoupCookie.html#soup-cookie-parse">soup_cookie_parse ()</a> +</dt> +<dt>soup_cookie_set_domain, <a class="indexterm" href="SoupCookie.html#soup-cookie-set-domain">soup_cookie_set_domain ()</a> +</dt> +<dt>soup_cookie_set_expires, <a class="indexterm" href="SoupCookie.html#soup-cookie-set-expires">soup_cookie_set_expires ()</a> +</dt> +<dt>soup_cookie_set_http_only, <a class="indexterm" href="SoupCookie.html#soup-cookie-set-http-only">soup_cookie_set_http_only ()</a> +</dt> +<dt>soup_cookie_set_max_age, <a class="indexterm" href="SoupCookie.html#soup-cookie-set-max-age">soup_cookie_set_max_age ()</a> +</dt> +<dt>soup_cookie_set_name, <a class="indexterm" href="SoupCookie.html#soup-cookie-set-name">soup_cookie_set_name ()</a> +</dt> +<dt>soup_cookie_set_path, <a class="indexterm" href="SoupCookie.html#soup-cookie-set-path">soup_cookie_set_path ()</a> +</dt> +<dt>soup_cookie_set_secure, <a class="indexterm" href="SoupCookie.html#soup-cookie-set-secure">soup_cookie_set_secure ()</a> +</dt> +<dt>soup_cookie_set_value, <a class="indexterm" href="SoupCookie.html#soup-cookie-set-value">soup_cookie_set_value ()</a> +</dt> +<dt>soup_cookie_to_cookie_header, <a class="indexterm" href="SoupCookie.html#soup-cookie-to-cookie-header">soup_cookie_to_cookie_header ()</a> +</dt> +<dt>soup_cookie_to_set_cookie_header, <a class="indexterm" href="SoupCookie.html#soup-cookie-to-set-cookie-header">soup_cookie_to_set_cookie_header ()</a> +</dt> +<dt>soup_date_free, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-free">soup_date_free ()</a> +</dt> +<dt>soup_date_get_day, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-day">soup_date_get_day ()</a> +</dt> +<dt>soup_date_get_hour, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-hour">soup_date_get_hour ()</a> +</dt> +<dt>soup_date_get_minute, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-minute">soup_date_get_minute ()</a> +</dt> +<dt>soup_date_get_month, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-month">soup_date_get_month ()</a> +</dt> +<dt>soup_date_get_offset, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-offset">soup_date_get_offset ()</a> +</dt> +<dt>soup_date_get_second, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-second">soup_date_get_second ()</a> +</dt> +<dt>soup_date_get_utc, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-utc">soup_date_get_utc ()</a> +</dt> +<dt>soup_date_get_year, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-year">soup_date_get_year ()</a> +</dt> +<dt>soup_date_is_past, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-is-past">soup_date_is_past ()</a> +</dt> +<dt>soup_date_new, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new">soup_date_new ()</a> +</dt> +<dt>soup_date_new_from_now, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-now">soup_date_new_from_now ()</a> +</dt> +<dt>soup_date_new_from_string, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-string">soup_date_new_from_string ()</a> +</dt> +<dt>soup_date_new_from_time_t, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-time-t">soup_date_new_from_time_t ()</a> +</dt> +<dt>soup_date_to_string, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-string">soup_date_to_string ()</a> +</dt> +<dt>soup_date_to_timeval, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-timeval">soup_date_to_timeval ()</a> +</dt> +<dt>soup_date_to_time_t, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-time-t">soup_date_to_time_t ()</a> +</dt> +<dt>soup_form_decode, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#soup-form-decode">soup_form_decode ()</a> +</dt> +<dt>soup_form_decode_multipart, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#soup-form-decode-multipart">soup_form_decode_multipart ()</a> +</dt> +<dt>soup_form_encode, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode">soup_form_encode ()</a> +</dt> +<dt>soup_form_encode_datalist, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-datalist">soup_form_encode_datalist ()</a> +</dt> +<dt>soup_form_encode_hash, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-hash">soup_form_encode_hash ()</a> +</dt> +<dt>soup_form_encode_valist, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-valist">soup_form_encode_valist ()</a> +</dt> +<dt>SOUP_FORM_MIME_TYPE_MULTIPART, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#SOUP-FORM-MIME-TYPE-MULTIPART:CAPS">SOUP_FORM_MIME_TYPE_MULTIPART</a> +</dt> +<dt>SOUP_FORM_MIME_TYPE_URLENCODED, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#SOUP-FORM-MIME-TYPE-URLENCODED:CAPS">SOUP_FORM_MIME_TYPE_URLENCODED</a> +</dt> +<dt>soup_form_request_new, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new">soup_form_request_new ()</a> +</dt> +<dt>soup_form_request_new_from_datalist, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-datalist">soup_form_request_new_from_datalist ()</a> +</dt> +<dt>soup_form_request_new_from_hash, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-hash">soup_form_request_new_from_hash ()</a> +</dt> +<dt>soup_form_request_new_from_multipart, <a class="indexterm" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-multipart">soup_form_request_new_from_multipart ()</a> +</dt> +<dt>soup_get_major_version, <a class="indexterm" href="libsoup-2.4-Version-Information.html#soup-get-major-version">soup_get_major_version ()</a> +</dt> +<dt>soup_get_micro_version, <a class="indexterm" href="libsoup-2.4-Version-Information.html#soup-get-micro-version">soup_get_micro_version ()</a> +</dt> +<dt>soup_get_minor_version, <a class="indexterm" href="libsoup-2.4-Version-Information.html#soup-get-minor-version">soup_get_minor_version ()</a> +</dt> +<dt>soup_headers_parse, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse">soup_headers_parse ()</a> +</dt> +<dt>soup_headers_parse_request, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-request">soup_headers_parse_request ()</a> +</dt> +<dt>soup_headers_parse_response, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-response">soup_headers_parse_response ()</a> +</dt> +<dt>soup_headers_parse_status_line, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-status-line">soup_headers_parse_status_line ()</a> +</dt> +<dt>soup_header_contains, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-contains">soup_header_contains ()</a> +</dt> +<dt>soup_header_free_list, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-free-list">soup_header_free_list ()</a> +</dt> +<dt>soup_header_free_param_list, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-free-param-list">soup_header_free_param_list ()</a> +</dt> +<dt>soup_header_g_string_append_param, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-g-string-append-param">soup_header_g_string_append_param ()</a> +</dt> +<dt>soup_header_g_string_append_param_quoted, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-g-string-append-param-quoted">soup_header_g_string_append_param_quoted ()</a> +</dt> +<dt>soup_header_parse_list, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-list">soup_header_parse_list ()</a> +</dt> +<dt>soup_header_parse_param_list, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-param-list">soup_header_parse_param_list ()</a> +</dt> +<dt>soup_header_parse_quality_list, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-quality-list">soup_header_parse_quality_list ()</a> +</dt> +<dt>soup_header_parse_semi_param_list, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-semi-param-list">soup_header_parse_semi_param_list ()</a> +</dt> +<dt>SOUP_HTTP_ERROR, <a class="indexterm" href="libsoup-2.4-soup-status.html#SOUP-HTTP-ERROR:CAPS">SOUP_HTTP_ERROR</a> +</dt> +<dt>soup_logger_attach, <a class="indexterm" href="SoupLogger.html#soup-logger-attach">soup_logger_attach ()</a> +</dt> +<dt>soup_logger_detach, <a class="indexterm" href="SoupLogger.html#soup-logger-detach">soup_logger_detach ()</a> +</dt> +<dt>soup_logger_new, <a class="indexterm" href="SoupLogger.html#soup-logger-new">soup_logger_new ()</a> +</dt> +<dt>soup_logger_set_printer, <a class="indexterm" href="SoupLogger.html#soup-logger-set-printer">soup_logger_set_printer ()</a> +</dt> +<dt>soup_logger_set_request_filter, <a class="indexterm" href="SoupLogger.html#soup-logger-set-request-filter">soup_logger_set_request_filter ()</a> +</dt> +<dt>soup_logger_set_response_filter, <a class="indexterm" href="SoupLogger.html#soup-logger-set-response-filter">soup_logger_set_response_filter ()</a> +</dt> +<dt>SOUP_MAJOR_VERSION, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-MAJOR-VERSION:CAPS">SOUP_MAJOR_VERSION</a> +</dt> +<dt>soup_message_add_header_handler, <a class="indexterm" href="SoupMessage.html#soup-message-add-header-handler">soup_message_add_header_handler ()</a> +</dt> +<dt>soup_message_add_status_code_handler, <a class="indexterm" href="SoupMessage.html#soup-message-add-status-code-handler">soup_message_add_status_code_handler ()</a> +</dt> +<dt>soup_message_body_append, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-append">soup_message_body_append ()</a> +</dt> +<dt>soup_message_body_append_buffer, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-append-buffer">soup_message_body_append_buffer ()</a> +</dt> +<dt>soup_message_body_append_take, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-append-take">soup_message_body_append_take ()</a> +</dt> +<dt>soup_message_body_complete, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-complete">soup_message_body_complete ()</a> +</dt> +<dt>soup_message_body_flatten, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-flatten">soup_message_body_flatten ()</a> +</dt> +<dt>soup_message_body_free, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-free">soup_message_body_free ()</a> +</dt> +<dt>soup_message_body_get_accumulate, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-get-accumulate">soup_message_body_get_accumulate ()</a> +</dt> +<dt>soup_message_body_get_chunk, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-get-chunk">soup_message_body_get_chunk ()</a> +</dt> +<dt>soup_message_body_got_chunk, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-got-chunk">soup_message_body_got_chunk ()</a> +</dt> +<dt>soup_message_body_new, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-new">soup_message_body_new ()</a> +</dt> +<dt>soup_message_body_set_accumulate, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-set-accumulate">soup_message_body_set_accumulate ()</a> +</dt> +<dt>soup_message_body_truncate, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-truncate">soup_message_body_truncate ()</a> +</dt> +<dt>soup_message_body_wrote_chunk, <a class="indexterm" href="SoupMessageBody.html#soup-message-body-wrote-chunk">soup_message_body_wrote_chunk ()</a> +</dt> +<dt>soup_message_disable_feature, <a class="indexterm" href="SoupMessage.html#soup-message-disable-feature">soup_message_disable_feature ()</a> +</dt> +<dt>SOUP_MESSAGE_FIRST_PARTY, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-FIRST-PARTY:CAPS">SOUP_MESSAGE_FIRST_PARTY</a> +</dt> +<dt>SOUP_MESSAGE_FLAGS, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-FLAGS:CAPS">SOUP_MESSAGE_FLAGS</a> +</dt> +<dt>soup_message_get_address, <a class="indexterm" href="SoupMessage.html#soup-message-get-address">soup_message_get_address ()</a> +</dt> +<dt>soup_message_get_first_party, <a class="indexterm" href="SoupMessage.html#soup-message-get-first-party">soup_message_get_first_party ()</a> +</dt> +<dt>soup_message_get_flags, <a class="indexterm" href="SoupMessage.html#soup-message-get-flags">soup_message_get_flags ()</a> +</dt> +<dt>soup_message_get_https_status, <a class="indexterm" href="SoupMessage.html#soup-message-get-https-status">soup_message_get_https_status ()</a> +</dt> +<dt>soup_message_get_http_version, <a class="indexterm" href="SoupMessage.html#soup-message-get-http-version">soup_message_get_http_version ()</a> +</dt> +<dt>soup_message_get_priority, <a class="indexterm" href="SoupMessage.html#soup-message-get-priority">soup_message_get_priority ()</a> +</dt> +<dt>soup_message_get_soup_request, <a class="indexterm" href="SoupMessage.html#soup-message-get-soup-request">soup_message_get_soup_request ()</a> +</dt> +<dt>soup_message_get_uri, <a class="indexterm" href="SoupMessage.html#soup-message-get-uri">soup_message_get_uri ()</a> +</dt> +<dt>soup_message_headers_append, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-append">soup_message_headers_append ()</a> +</dt> +<dt>soup_message_headers_clean_connection_headers, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-clean-connection-headers">soup_message_headers_clean_connection_headers ()</a> +</dt> +<dt>soup_message_headers_clear, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-clear">soup_message_headers_clear ()</a> +</dt> +<dt>soup_message_headers_foreach, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-foreach">soup_message_headers_foreach ()</a> +</dt> +<dt>soup_message_headers_free, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-free">soup_message_headers_free ()</a> +</dt> +<dt>soup_message_headers_free_ranges, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-free-ranges">soup_message_headers_free_ranges ()</a> +</dt> +<dt>soup_message_headers_get, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-get">soup_message_headers_get ()</a> +</dt> +<dt>soup_message_headers_get_content_disposition, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-get-content-disposition">soup_message_headers_get_content_disposition ()</a> +</dt> +<dt>soup_message_headers_get_content_length, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-get-content-length">soup_message_headers_get_content_length ()</a> +</dt> +<dt>soup_message_headers_get_content_range, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-get-content-range">soup_message_headers_get_content_range ()</a> +</dt> +<dt>soup_message_headers_get_content_type, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-get-content-type">soup_message_headers_get_content_type ()</a> +</dt> +<dt>soup_message_headers_get_encoding, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-get-encoding">soup_message_headers_get_encoding ()</a> +</dt> +<dt>soup_message_headers_get_expectations, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-get-expectations">soup_message_headers_get_expectations ()</a> +</dt> +<dt>soup_message_headers_get_list, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-get-list">soup_message_headers_get_list ()</a> +</dt> +<dt>soup_message_headers_get_one, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-get-one">soup_message_headers_get_one ()</a> +</dt> +<dt>soup_message_headers_get_ranges, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-get-ranges">soup_message_headers_get_ranges ()</a> +</dt> +<dt>soup_message_headers_iter_init, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-iter-init">soup_message_headers_iter_init ()</a> +</dt> +<dt>soup_message_headers_iter_next, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-iter-next">soup_message_headers_iter_next ()</a> +</dt> +<dt>soup_message_headers_new, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-new">soup_message_headers_new ()</a> +</dt> +<dt>soup_message_headers_remove, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-remove">soup_message_headers_remove ()</a> +</dt> +<dt>soup_message_headers_replace, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-replace">soup_message_headers_replace ()</a> +</dt> +<dt>soup_message_headers_set_content_disposition, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-set-content-disposition">soup_message_headers_set_content_disposition ()</a> +</dt> +<dt>soup_message_headers_set_content_length, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-set-content-length">soup_message_headers_set_content_length ()</a> +</dt> +<dt>soup_message_headers_set_content_range, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-set-content-range">soup_message_headers_set_content_range ()</a> +</dt> +<dt>soup_message_headers_set_content_type, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-set-content-type">soup_message_headers_set_content_type ()</a> +</dt> +<dt>soup_message_headers_set_encoding, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-set-encoding">soup_message_headers_set_encoding ()</a> +</dt> +<dt>soup_message_headers_set_expectations, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-set-expectations">soup_message_headers_set_expectations ()</a> +</dt> +<dt>soup_message_headers_set_range, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-set-range">soup_message_headers_set_range ()</a> +</dt> +<dt>soup_message_headers_set_ranges, <a class="indexterm" href="SoupMessageHeaders.html#soup-message-headers-set-ranges">soup_message_headers_set_ranges ()</a> +</dt> +<dt>SOUP_MESSAGE_HTTP_VERSION, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-HTTP-VERSION:CAPS">SOUP_MESSAGE_HTTP_VERSION</a> +</dt> +<dt>soup_message_is_keepalive, <a class="indexterm" href="SoupMessage.html#soup-message-is-keepalive">soup_message_is_keepalive ()</a> +</dt> +<dt>SOUP_MESSAGE_METHOD, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-METHOD:CAPS">SOUP_MESSAGE_METHOD</a> +</dt> +<dt>soup_message_new, <a class="indexterm" href="SoupMessage.html#soup-message-new">soup_message_new ()</a> +</dt> +<dt>soup_message_new_from_uri, <a class="indexterm" href="SoupMessage.html#soup-message-new-from-uri">soup_message_new_from_uri ()</a> +</dt> +<dt>SOUP_MESSAGE_PRIORITY, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-PRIORITY:CAPS">SOUP_MESSAGE_PRIORITY</a> +</dt> +<dt>SOUP_MESSAGE_REASON_PHRASE, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-REASON-PHRASE:CAPS">SOUP_MESSAGE_REASON_PHRASE</a> +</dt> +<dt>SOUP_MESSAGE_REQUEST_BODY, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-REQUEST-BODY:CAPS">SOUP_MESSAGE_REQUEST_BODY</a> +</dt> +<dt>SOUP_MESSAGE_REQUEST_BODY_DATA, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-REQUEST-BODY-DATA:CAPS">SOUP_MESSAGE_REQUEST_BODY_DATA</a> +</dt> +<dt>SOUP_MESSAGE_REQUEST_HEADERS, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-REQUEST-HEADERS:CAPS">SOUP_MESSAGE_REQUEST_HEADERS</a> +</dt> +<dt>SOUP_MESSAGE_RESPONSE_BODY, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-RESPONSE-BODY:CAPS">SOUP_MESSAGE_RESPONSE_BODY</a> +</dt> +<dt>SOUP_MESSAGE_RESPONSE_BODY_DATA, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-RESPONSE-BODY-DATA:CAPS">SOUP_MESSAGE_RESPONSE_BODY_DATA</a> +</dt> +<dt>SOUP_MESSAGE_RESPONSE_HEADERS, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-RESPONSE-HEADERS:CAPS">SOUP_MESSAGE_RESPONSE_HEADERS</a> +</dt> +<dt>SOUP_MESSAGE_SERVER_SIDE, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-SERVER-SIDE:CAPS">SOUP_MESSAGE_SERVER_SIDE</a> +</dt> +<dt>soup_message_set_chunk_allocator, <a class="indexterm" href="SoupMessage.html#soup-message-set-chunk-allocator">soup_message_set_chunk_allocator ()</a> +</dt> +<dt>soup_message_set_first_party, <a class="indexterm" href="SoupMessage.html#soup-message-set-first-party">soup_message_set_first_party ()</a> +</dt> +<dt>soup_message_set_flags, <a class="indexterm" href="SoupMessage.html#soup-message-set-flags">soup_message_set_flags ()</a> +</dt> +<dt>soup_message_set_http_version, <a class="indexterm" href="SoupMessage.html#soup-message-set-http-version">soup_message_set_http_version ()</a> +</dt> +<dt>soup_message_set_priority, <a class="indexterm" href="SoupMessage.html#soup-message-set-priority">soup_message_set_priority ()</a> +</dt> +<dt>soup_message_set_redirect, <a class="indexterm" href="SoupMessage.html#soup-message-set-redirect">soup_message_set_redirect ()</a> +</dt> +<dt>soup_message_set_request, <a class="indexterm" href="SoupMessage.html#soup-message-set-request">soup_message_set_request ()</a> +</dt> +<dt>soup_message_set_response, <a class="indexterm" href="SoupMessage.html#soup-message-set-response">soup_message_set_response ()</a> +</dt> +<dt>soup_message_set_status, <a class="indexterm" href="SoupMessage.html#soup-message-set-status">soup_message_set_status ()</a> +</dt> +<dt>soup_message_set_status_full, <a class="indexterm" href="SoupMessage.html#soup-message-set-status-full">soup_message_set_status_full ()</a> +</dt> +<dt>soup_message_set_uri, <a class="indexterm" href="SoupMessage.html#soup-message-set-uri">soup_message_set_uri ()</a> +</dt> +<dt>SOUP_MESSAGE_STATUS_CODE, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-STATUS-CODE:CAPS">SOUP_MESSAGE_STATUS_CODE</a> +</dt> +<dt>SOUP_MESSAGE_TLS_CERTIFICATE, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-TLS-CERTIFICATE:CAPS">SOUP_MESSAGE_TLS_CERTIFICATE</a> +</dt> +<dt>SOUP_MESSAGE_TLS_ERRORS, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-TLS-ERRORS:CAPS">SOUP_MESSAGE_TLS_ERRORS</a> +</dt> +<dt>SOUP_MESSAGE_URI, <a class="indexterm" href="SoupMessage.html#SOUP-MESSAGE-URI:CAPS">SOUP_MESSAGE_URI</a> +</dt> +<dt>SOUP_METHOD_CONNECT, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-CONNECT:CAPS">SOUP_METHOD_CONNECT</a> +</dt> +<dt>SOUP_METHOD_COPY, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-COPY:CAPS">SOUP_METHOD_COPY</a> +</dt> +<dt>SOUP_METHOD_DELETE, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-DELETE:CAPS">SOUP_METHOD_DELETE</a> +</dt> +<dt>SOUP_METHOD_GET, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-GET:CAPS">SOUP_METHOD_GET</a> +</dt> +<dt>SOUP_METHOD_HEAD, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-HEAD:CAPS">SOUP_METHOD_HEAD</a> +</dt> +<dt>SOUP_METHOD_LOCK, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-LOCK:CAPS">SOUP_METHOD_LOCK</a> +</dt> +<dt>SOUP_METHOD_MKCOL, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-MKCOL:CAPS">SOUP_METHOD_MKCOL</a> +</dt> +<dt>SOUP_METHOD_MOVE, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-MOVE:CAPS">SOUP_METHOD_MOVE</a> +</dt> +<dt>SOUP_METHOD_OPTIONS, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-OPTIONS:CAPS">SOUP_METHOD_OPTIONS</a> +</dt> +<dt>SOUP_METHOD_POST, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-POST:CAPS">SOUP_METHOD_POST</a> +</dt> +<dt>SOUP_METHOD_PROPFIND, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-PROPFIND:CAPS">SOUP_METHOD_PROPFIND</a> +</dt> +<dt>SOUP_METHOD_PROPPATCH, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-PROPPATCH:CAPS">SOUP_METHOD_PROPPATCH</a> +</dt> +<dt>SOUP_METHOD_PUT, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-PUT:CAPS">SOUP_METHOD_PUT</a> +</dt> +<dt>SOUP_METHOD_TRACE, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-TRACE:CAPS">SOUP_METHOD_TRACE</a> +</dt> +<dt>SOUP_METHOD_UNLOCK, <a class="indexterm" href="libsoup-2.4-soup-method.html#SOUP-METHOD-UNLOCK:CAPS">SOUP_METHOD_UNLOCK</a> +</dt> +<dt>SOUP_MICRO_VERSION, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-MICRO-VERSION:CAPS">SOUP_MICRO_VERSION</a> +</dt> +<dt>SOUP_MINOR_VERSION, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-MINOR-VERSION:CAPS">SOUP_MINOR_VERSION</a> +</dt> +<dt>soup_multipart_append_form_file, <a class="indexterm" href="SoupMultipart.html#soup-multipart-append-form-file">soup_multipart_append_form_file ()</a> +</dt> +<dt>soup_multipart_append_form_string, <a class="indexterm" href="SoupMultipart.html#soup-multipart-append-form-string">soup_multipart_append_form_string ()</a> +</dt> +<dt>soup_multipart_append_part, <a class="indexterm" href="SoupMultipart.html#soup-multipart-append-part">soup_multipart_append_part ()</a> +</dt> +<dt>soup_multipart_free, <a class="indexterm" href="SoupMultipart.html#soup-multipart-free">soup_multipart_free ()</a> +</dt> +<dt>soup_multipart_get_length, <a class="indexterm" href="SoupMultipart.html#soup-multipart-get-length">soup_multipart_get_length ()</a> +</dt> +<dt>soup_multipart_get_part, <a class="indexterm" href="SoupMultipart.html#soup-multipart-get-part">soup_multipart_get_part ()</a> +</dt> +<dt>soup_multipart_input_stream_get_headers, <a class="indexterm" href="SoupMultipartInputStream.html#soup-multipart-input-stream-get-headers">soup_multipart_input_stream_get_headers ()</a> +</dt> +<dt>soup_multipart_input_stream_new, <a class="indexterm" href="SoupMultipartInputStream.html#soup-multipart-input-stream-new">soup_multipart_input_stream_new ()</a> +</dt> +<dt>soup_multipart_input_stream_next_part, <a class="indexterm" href="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part">soup_multipart_input_stream_next_part ()</a> +</dt> +<dt>soup_multipart_input_stream_next_part_async, <a class="indexterm" href="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part-async">soup_multipart_input_stream_next_part_async ()</a> +</dt> +<dt>soup_multipart_input_stream_next_part_finish, <a class="indexterm" href="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part-finish">soup_multipart_input_stream_next_part_finish ()</a> +</dt> +<dt>soup_multipart_new, <a class="indexterm" href="SoupMultipart.html#soup-multipart-new">soup_multipart_new ()</a> +</dt> +<dt>soup_multipart_new_from_message, <a class="indexterm" href="SoupMultipart.html#soup-multipart-new-from-message">soup_multipart_new_from_message ()</a> +</dt> +<dt>soup_multipart_to_message, <a class="indexterm" href="SoupMultipart.html#soup-multipart-to-message">soup_multipart_to_message ()</a> +</dt> +<dt>SOUP_REQUEST_ERROR, <a class="indexterm" href="SoupSession.html#SOUP-REQUEST-ERROR:CAPS">SOUP_REQUEST_ERROR</a> +</dt> +<dt>soup_request_file_get_file, <a class="indexterm" href="SoupRequestFile.html#soup-request-file-get-file">soup_request_file_get_file ()</a> +</dt> +<dt>soup_request_get_content_length, <a class="indexterm" href="SoupRequest.html#soup-request-get-content-length">soup_request_get_content_length ()</a> +</dt> +<dt>soup_request_get_content_type, <a class="indexterm" href="SoupRequest.html#soup-request-get-content-type">soup_request_get_content_type ()</a> +</dt> +<dt>soup_request_get_session, <a class="indexterm" href="SoupRequest.html#soup-request-get-session">soup_request_get_session ()</a> +</dt> +<dt>soup_request_get_uri, <a class="indexterm" href="SoupRequest.html#soup-request-get-uri">soup_request_get_uri ()</a> +</dt> +<dt>soup_request_http_get_message, <a class="indexterm" href="SoupRequestHTTP.html#soup-request-http-get-message">soup_request_http_get_message ()</a> +</dt> +<dt>soup_request_send, <a class="indexterm" href="SoupRequest.html#soup-request-send">soup_request_send ()</a> +</dt> +<dt>soup_request_send_async, <a class="indexterm" href="SoupRequest.html#soup-request-send-async">soup_request_send_async ()</a> +</dt> +<dt>soup_request_send_finish, <a class="indexterm" href="SoupRequest.html#soup-request-send-finish">soup_request_send_finish ()</a> +</dt> +<dt>SOUP_REQUEST_SESSION, <a class="indexterm" href="SoupRequest.html#SOUP-REQUEST-SESSION:CAPS">SOUP_REQUEST_SESSION</a> +</dt> +<dt>SOUP_REQUEST_URI, <a class="indexterm" href="SoupRequest.html#SOUP-REQUEST-URI:CAPS">SOUP_REQUEST_URI</a> +</dt> +<dt>soup_server_add_auth_domain, <a class="indexterm" href="SoupServer.html#soup-server-add-auth-domain">soup_server_add_auth_domain ()</a> +</dt> +<dt>soup_server_add_handler, <a class="indexterm" href="SoupServer.html#soup-server-add-handler">soup_server_add_handler ()</a> +</dt> +<dt>SOUP_SERVER_ASYNC_CONTEXT, <a class="indexterm" href="SoupServer.html#SOUP-SERVER-ASYNC-CONTEXT:CAPS">SOUP_SERVER_ASYNC_CONTEXT</a> +</dt> +<dt>soup_server_disconnect, <a class="indexterm" href="SoupServer.html#soup-server-disconnect">soup_server_disconnect ()</a> +</dt> +<dt>soup_server_get_async_context, <a class="indexterm" href="SoupServer.html#soup-server-get-async-context">soup_server_get_async_context ()</a> +</dt> +<dt>soup_server_get_listener, <a class="indexterm" href="SoupServer.html#soup-server-get-listener">soup_server_get_listener ()</a> +</dt> +<dt>soup_server_get_port, <a class="indexterm" href="SoupServer.html#soup-server-get-port">soup_server_get_port ()</a> +</dt> +<dt>SOUP_SERVER_HTTPS_ALIASES, <a class="indexterm" href="SoupServer.html#SOUP-SERVER-HTTPS-ALIASES:CAPS">SOUP_SERVER_HTTPS_ALIASES</a> +</dt> +<dt>SOUP_SERVER_HTTP_ALIASES, <a class="indexterm" href="SoupServer.html#SOUP-SERVER-HTTP-ALIASES:CAPS">SOUP_SERVER_HTTP_ALIASES</a> +</dt> +<dt>SOUP_SERVER_INTERFACE, <a class="indexterm" href="SoupServer.html#SOUP-SERVER-INTERFACE:CAPS">SOUP_SERVER_INTERFACE</a> +</dt> +<dt>soup_server_is_https, <a class="indexterm" href="SoupServer.html#soup-server-is-https">soup_server_is_https ()</a> +</dt> +<dt>soup_server_new, <a class="indexterm" href="SoupServer.html#soup-server-new">soup_server_new ()</a> +</dt> +<dt>soup_server_pause_message, <a class="indexterm" href="SoupServer.html#soup-server-pause-message">soup_server_pause_message ()</a> +</dt> +<dt>SOUP_SERVER_PORT, <a class="indexterm" href="SoupServer.html#SOUP-SERVER-PORT:CAPS">SOUP_SERVER_PORT</a> +</dt> +<dt>soup_server_quit, <a class="indexterm" href="SoupServer.html#soup-server-quit">soup_server_quit ()</a> +</dt> +<dt>SOUP_SERVER_RAW_PATHS, <a class="indexterm" href="SoupServer.html#SOUP-SERVER-RAW-PATHS:CAPS">SOUP_SERVER_RAW_PATHS</a> +</dt> +<dt>soup_server_remove_auth_domain, <a class="indexterm" href="SoupServer.html#soup-server-remove-auth-domain">soup_server_remove_auth_domain ()</a> +</dt> +<dt>soup_server_remove_handler, <a class="indexterm" href="SoupServer.html#soup-server-remove-handler">soup_server_remove_handler ()</a> +</dt> +<dt>soup_server_run, <a class="indexterm" href="SoupServer.html#soup-server-run">soup_server_run ()</a> +</dt> +<dt>soup_server_run_async, <a class="indexterm" href="SoupServer.html#soup-server-run-async">soup_server_run_async ()</a> +</dt> +<dt>SOUP_SERVER_SERVER_HEADER, <a class="indexterm" href="SoupServer.html#SOUP-SERVER-SERVER-HEADER:CAPS">SOUP_SERVER_SERVER_HEADER</a> +</dt> +<dt>SOUP_SERVER_SSL_CERT_FILE, <a class="indexterm" href="SoupServer.html#SOUP-SERVER-SSL-CERT-FILE:CAPS">SOUP_SERVER_SSL_CERT_FILE</a> +</dt> +<dt>SOUP_SERVER_SSL_KEY_FILE, <a class="indexterm" href="SoupServer.html#SOUP-SERVER-SSL-KEY-FILE:CAPS">SOUP_SERVER_SSL_KEY_FILE</a> +</dt> +<dt>SOUP_SERVER_TLS_CERTIFICATE, <a class="indexterm" href="SoupServer.html#SOUP-SERVER-TLS-CERTIFICATE:CAPS">SOUP_SERVER_TLS_CERTIFICATE</a> +</dt> +<dt>soup_server_unpause_message, <a class="indexterm" href="SoupServer.html#soup-server-unpause-message">soup_server_unpause_message ()</a> +</dt> +<dt>soup_session_abort, <a class="indexterm" href="SoupSession.html#soup-session-abort">soup_session_abort ()</a> +</dt> +<dt>SOUP_SESSION_ACCEPT_LANGUAGE, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-ACCEPT-LANGUAGE:CAPS">SOUP_SESSION_ACCEPT_LANGUAGE</a> +</dt> +<dt>SOUP_SESSION_ACCEPT_LANGUAGE_AUTO, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-ACCEPT-LANGUAGE-AUTO:CAPS">SOUP_SESSION_ACCEPT_LANGUAGE_AUTO</a> +</dt> +<dt>soup_session_add_feature, <a class="indexterm" href="SoupSession.html#soup-session-add-feature">soup_session_add_feature ()</a> +</dt> +<dt>SOUP_SESSION_ADD_FEATURE, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-ADD-FEATURE:CAPS">SOUP_SESSION_ADD_FEATURE</a> +</dt> +<dt>soup_session_add_feature_by_type, <a class="indexterm" href="SoupSession.html#soup-session-add-feature-by-type">soup_session_add_feature_by_type ()</a> +</dt> +<dt>SOUP_SESSION_ADD_FEATURE_BY_TYPE, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS">SOUP_SESSION_ADD_FEATURE_BY_TYPE</a> +</dt> +<dt>SOUP_SESSION_ASYNC_CONTEXT, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-ASYNC-CONTEXT:CAPS">SOUP_SESSION_ASYNC_CONTEXT</a> +</dt> +<dt>soup_session_async_new, <a class="indexterm" href="SoupSessionAsync.html#soup-session-async-new">soup_session_async_new ()</a> +</dt> +<dt>soup_session_async_new_with_options, <a class="indexterm" href="SoupSessionAsync.html#soup-session-async-new-with-options">soup_session_async_new_with_options ()</a> +</dt> +<dt>soup_session_cancel_message, <a class="indexterm" href="SoupSession.html#soup-session-cancel-message">soup_session_cancel_message ()</a> +</dt> +<dt>soup_session_get_async_context, <a class="indexterm" href="SoupSession.html#soup-session-get-async-context">soup_session_get_async_context ()</a> +</dt> +<dt>soup_session_get_feature, <a class="indexterm" href="SoupSession.html#soup-session-get-feature">soup_session_get_feature ()</a> +</dt> +<dt>soup_session_get_features, <a class="indexterm" href="SoupSession.html#soup-session-get-features">soup_session_get_features ()</a> +</dt> +<dt>soup_session_get_feature_for_message, <a class="indexterm" href="SoupSession.html#soup-session-get-feature-for-message">soup_session_get_feature_for_message ()</a> +</dt> +<dt>soup_session_has_feature, <a class="indexterm" href="SoupSession.html#soup-session-has-feature">soup_session_has_feature ()</a> +</dt> +<dt>SOUP_SESSION_HTTPS_ALIASES, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-HTTPS-ALIASES:CAPS">SOUP_SESSION_HTTPS_ALIASES</a> +</dt> +<dt>SOUP_SESSION_HTTP_ALIASES, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-HTTP-ALIASES:CAPS">SOUP_SESSION_HTTP_ALIASES</a> +</dt> +<dt>SOUP_SESSION_IDLE_TIMEOUT, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-IDLE-TIMEOUT:CAPS">SOUP_SESSION_IDLE_TIMEOUT</a> +</dt> +<dt>SOUP_SESSION_LOCAL_ADDRESS, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-LOCAL-ADDRESS:CAPS">SOUP_SESSION_LOCAL_ADDRESS</a> +</dt> +<dt>SOUP_SESSION_MAX_CONNS, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-MAX-CONNS:CAPS">SOUP_SESSION_MAX_CONNS</a> +</dt> +<dt>SOUP_SESSION_MAX_CONNS_PER_HOST, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-MAX-CONNS-PER-HOST:CAPS">SOUP_SESSION_MAX_CONNS_PER_HOST</a> +</dt> +<dt>soup_session_new, <a class="indexterm" href="SoupSession.html#soup-session-new">soup_session_new ()</a> +</dt> +<dt>soup_session_new_with_options, <a class="indexterm" href="SoupSession.html#soup-session-new-with-options">soup_session_new_with_options ()</a> +</dt> +<dt>soup_session_pause_message, <a class="indexterm" href="SoupSession.html#soup-session-pause-message">soup_session_pause_message ()</a> +</dt> +<dt>soup_session_prefetch_dns, <a class="indexterm" href="SoupSession.html#soup-session-prefetch-dns">soup_session_prefetch_dns ()</a> +</dt> +<dt>soup_session_prepare_for_uri, <a class="indexterm" href="SoupSession.html#soup-session-prepare-for-uri">soup_session_prepare_for_uri ()</a>, <a class="indexterm" href="SoupSession.html#soup-session-prepare-for-uri">soup_session_prepare_for_uri ()</a> +</dt> +<dt>SOUP_SESSION_PROXY_RESOLVER, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-PROXY-RESOLVER:CAPS">SOUP_SESSION_PROXY_RESOLVER</a> +</dt> +<dt>SOUP_SESSION_PROXY_URI, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-PROXY-URI:CAPS">SOUP_SESSION_PROXY_URI</a> +</dt> +<dt>soup_session_queue_message, <a class="indexterm" href="SoupSession.html#soup-session-queue-message">soup_session_queue_message ()</a> +</dt> +<dt>soup_session_redirect_message, <a class="indexterm" href="SoupSession.html#soup-session-redirect-message">soup_session_redirect_message ()</a> +</dt> +<dt>soup_session_remove_feature, <a class="indexterm" href="SoupSession.html#soup-session-remove-feature">soup_session_remove_feature ()</a> +</dt> +<dt>soup_session_remove_feature_by_type, <a class="indexterm" href="SoupSession.html#soup-session-remove-feature-by-type">soup_session_remove_feature_by_type ()</a> +</dt> +<dt>SOUP_SESSION_REMOVE_FEATURE_BY_TYPE, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-REMOVE-FEATURE-BY-TYPE:CAPS">SOUP_SESSION_REMOVE_FEATURE_BY_TYPE</a> +</dt> +<dt>soup_session_request, <a class="indexterm" href="SoupSession.html#soup-session-request">soup_session_request ()</a> +</dt> +<dt>soup_session_request_http, <a class="indexterm" href="SoupSession.html#soup-session-request-http">soup_session_request_http ()</a> +</dt> +<dt>soup_session_request_http_uri, <a class="indexterm" href="SoupSession.html#soup-session-request-http-uri">soup_session_request_http_uri ()</a> +</dt> +<dt>soup_session_request_uri, <a class="indexterm" href="SoupSession.html#soup-session-request-uri">soup_session_request_uri ()</a> +</dt> +<dt>soup_session_requeue_message, <a class="indexterm" href="SoupSession.html#soup-session-requeue-message">soup_session_requeue_message ()</a> +</dt> +<dt>soup_session_send, <a class="indexterm" href="SoupSession.html#soup-session-send">soup_session_send ()</a> +</dt> +<dt>soup_session_send_async, <a class="indexterm" href="SoupSession.html#soup-session-send-async">soup_session_send_async ()</a> +</dt> +<dt>soup_session_send_finish, <a class="indexterm" href="SoupSession.html#soup-session-send-finish">soup_session_send_finish ()</a> +</dt> +<dt>soup_session_send_message, <a class="indexterm" href="SoupSession.html#soup-session-send-message">soup_session_send_message ()</a> +</dt> +<dt>SOUP_SESSION_SSL_CA_FILE, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-SSL-CA-FILE:CAPS">SOUP_SESSION_SSL_CA_FILE</a> +</dt> +<dt>SOUP_SESSION_SSL_STRICT, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-SSL-STRICT:CAPS">SOUP_SESSION_SSL_STRICT</a> +</dt> +<dt>SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-SSL-USE-SYSTEM-CA-FILE:CAPS">SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE</a> +</dt> +<dt>soup_session_sync_new, <a class="indexterm" href="SoupSessionSync.html#soup-session-sync-new">soup_session_sync_new ()</a> +</dt> +<dt>soup_session_sync_new_with_options, <a class="indexterm" href="SoupSessionSync.html#soup-session-sync-new-with-options">soup_session_sync_new_with_options ()</a> +</dt> +<dt>SOUP_SESSION_TIMEOUT, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-TIMEOUT:CAPS">SOUP_SESSION_TIMEOUT</a> +</dt> +<dt>SOUP_SESSION_TLS_DATABASE, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-TLS-DATABASE:CAPS">SOUP_SESSION_TLS_DATABASE</a> +</dt> +<dt>soup_session_unpause_message, <a class="indexterm" href="SoupSession.html#soup-session-unpause-message">soup_session_unpause_message ()</a> +</dt> +<dt>SOUP_SESSION_USER_AGENT, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-USER-AGENT:CAPS">SOUP_SESSION_USER_AGENT</a> +</dt> +<dt>SOUP_SESSION_USE_THREAD_CONTEXT, <a class="indexterm" href="SoupSession.html#SOUP-SESSION-USE-THREAD-CONTEXT:CAPS">SOUP_SESSION_USE_THREAD_CONTEXT</a> +</dt> +<dt>soup_session_would_redirect, <a class="indexterm" href="SoupSession.html#soup-session-would-redirect">soup_session_would_redirect ()</a> +</dt> +<dt>SOUP_SOCKET_ASYNC_CONTEXT, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-ASYNC-CONTEXT:CAPS">SOUP_SOCKET_ASYNC_CONTEXT</a> +</dt> +<dt>soup_socket_connect_async, <a class="indexterm" href="SoupSocket.html#soup-socket-connect-async">soup_socket_connect_async ()</a> +</dt> +<dt>soup_socket_connect_sync, <a class="indexterm" href="SoupSocket.html#soup-socket-connect-sync">soup_socket_connect_sync ()</a> +</dt> +<dt>soup_socket_disconnect, <a class="indexterm" href="SoupSocket.html#soup-socket-disconnect">soup_socket_disconnect ()</a> +</dt> +<dt>SOUP_SOCKET_FLAG_NONBLOCKING, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-FLAG-NONBLOCKING:CAPS">SOUP_SOCKET_FLAG_NONBLOCKING</a> +</dt> +<dt>soup_socket_get_fd, <a class="indexterm" href="SoupSocket.html#soup-socket-get-fd">soup_socket_get_fd ()</a> +</dt> +<dt>soup_socket_get_local_address, <a class="indexterm" href="SoupSocket.html#soup-socket-get-local-address">soup_socket_get_local_address ()</a> +</dt> +<dt>soup_socket_get_remote_address, <a class="indexterm" href="SoupSocket.html#soup-socket-get-remote-address">soup_socket_get_remote_address ()</a> +</dt> +<dt>soup_socket_is_connected, <a class="indexterm" href="SoupSocket.html#soup-socket-is-connected">soup_socket_is_connected ()</a> +</dt> +<dt>SOUP_SOCKET_IS_SERVER, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-IS-SERVER:CAPS">SOUP_SOCKET_IS_SERVER</a> +</dt> +<dt>soup_socket_is_ssl, <a class="indexterm" href="SoupSocket.html#soup-socket-is-ssl">soup_socket_is_ssl ()</a> +</dt> +<dt>soup_socket_listen, <a class="indexterm" href="SoupSocket.html#soup-socket-listen">soup_socket_listen ()</a> +</dt> +<dt>SOUP_SOCKET_LOCAL_ADDRESS, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-LOCAL-ADDRESS:CAPS">SOUP_SOCKET_LOCAL_ADDRESS</a> +</dt> +<dt>soup_socket_new, <a class="indexterm" href="SoupSocket.html#soup-socket-new">soup_socket_new ()</a> +</dt> +<dt>soup_socket_read, <a class="indexterm" href="SoupSocket.html#soup-socket-read">soup_socket_read ()</a> +</dt> +<dt>soup_socket_read_until, <a class="indexterm" href="SoupSocket.html#soup-socket-read-until">soup_socket_read_until ()</a> +</dt> +<dt>SOUP_SOCKET_REMOTE_ADDRESS, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-REMOTE-ADDRESS:CAPS">SOUP_SOCKET_REMOTE_ADDRESS</a> +</dt> +<dt>SOUP_SOCKET_SSL_CREDENTIALS, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-SSL-CREDENTIALS:CAPS">SOUP_SOCKET_SSL_CREDENTIALS</a> +</dt> +<dt>SOUP_SOCKET_SSL_FALLBACK, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-SSL-FALLBACK:CAPS">SOUP_SOCKET_SSL_FALLBACK</a> +</dt> +<dt>SOUP_SOCKET_SSL_STRICT, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-SSL-STRICT:CAPS">SOUP_SOCKET_SSL_STRICT</a> +</dt> +<dt>soup_socket_start_proxy_ssl, <a class="indexterm" href="SoupSocket.html#soup-socket-start-proxy-ssl">soup_socket_start_proxy_ssl ()</a> +</dt> +<dt>soup_socket_start_ssl, <a class="indexterm" href="SoupSocket.html#soup-socket-start-ssl">soup_socket_start_ssl ()</a> +</dt> +<dt>SOUP_SOCKET_TIMEOUT, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-TIMEOUT:CAPS">SOUP_SOCKET_TIMEOUT</a> +</dt> +<dt>SOUP_SOCKET_TLS_CERTIFICATE, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-TLS-CERTIFICATE:CAPS">SOUP_SOCKET_TLS_CERTIFICATE</a> +</dt> +<dt>SOUP_SOCKET_TLS_ERRORS, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-TLS-ERRORS:CAPS">SOUP_SOCKET_TLS_ERRORS</a> +</dt> +<dt>SOUP_SOCKET_TRUSTED_CERTIFICATE, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-TRUSTED-CERTIFICATE:CAPS">SOUP_SOCKET_TRUSTED_CERTIFICATE</a> +</dt> +<dt>SOUP_SOCKET_USE_THREAD_CONTEXT, <a class="indexterm" href="SoupSocket.html#SOUP-SOCKET-USE-THREAD-CONTEXT:CAPS">SOUP_SOCKET_USE_THREAD_CONTEXT</a> +</dt> +<dt>soup_socket_write, <a class="indexterm" href="SoupSocket.html#soup-socket-write">soup_socket_write ()</a> +</dt> +<dt>soup_status_get_phrase, <a class="indexterm" href="libsoup-2.4-soup-status.html#soup-status-get-phrase">soup_status_get_phrase ()</a> +</dt> +<dt>SOUP_STATUS_IS_CLIENT_ERROR, <a class="indexterm" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-CLIENT-ERROR:CAPS">SOUP_STATUS_IS_CLIENT_ERROR()</a> +</dt> +<dt>SOUP_STATUS_IS_INFORMATIONAL, <a class="indexterm" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-INFORMATIONAL:CAPS">SOUP_STATUS_IS_INFORMATIONAL()</a> +</dt> +<dt>SOUP_STATUS_IS_REDIRECTION, <a class="indexterm" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-REDIRECTION:CAPS">SOUP_STATUS_IS_REDIRECTION()</a> +</dt> +<dt>SOUP_STATUS_IS_SERVER_ERROR, <a class="indexterm" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-SERVER-ERROR:CAPS">SOUP_STATUS_IS_SERVER_ERROR()</a> +</dt> +<dt>SOUP_STATUS_IS_SUCCESSFUL, <a class="indexterm" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-SUCCESSFUL:CAPS">SOUP_STATUS_IS_SUCCESSFUL()</a> +</dt> +<dt>SOUP_STATUS_IS_TRANSPORT_ERROR, <a class="indexterm" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-TRANSPORT-ERROR:CAPS">SOUP_STATUS_IS_TRANSPORT_ERROR()</a> +</dt> +<dt>soup_status_proxify, <a class="indexterm" href="libsoup-2.4-soup-status.html#soup-status-proxify">soup_status_proxify ()</a> +</dt> +<dt>soup_str_case_equal, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-str-case-equal">soup_str_case_equal ()</a> +</dt> +<dt>soup_str_case_hash, <a class="indexterm" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-str-case-hash">soup_str_case_hash ()</a> +</dt> +<dt>soup_tld_domain_is_public_suffix, <a class="indexterm" href="libsoup-2.4-Top-Level-Domain-utils.html#soup-tld-domain-is-public-suffix">soup_tld_domain_is_public_suffix ()</a> +</dt> +<dt>SOUP_TLD_ERROR, <a class="indexterm" href="libsoup-2.4-Top-Level-Domain-utils.html#SOUP-TLD-ERROR:CAPS">SOUP_TLD_ERROR</a> +</dt> +<dt>soup_tld_get_base_domain, <a class="indexterm" href="libsoup-2.4-Top-Level-Domain-utils.html#soup-tld-get-base-domain">soup_tld_get_base_domain ()</a> +</dt> +<dt>SOUP_TYPE_AUTH_BASIC, <a class="indexterm" href="SoupAuth.html#SOUP-TYPE-AUTH-BASIC:CAPS">SOUP_TYPE_AUTH_BASIC</a> +</dt> +<dt>SOUP_TYPE_AUTH_DIGEST, <a class="indexterm" href="SoupAuth.html#SOUP-TYPE-AUTH-DIGEST:CAPS">SOUP_TYPE_AUTH_DIGEST</a> +</dt> +<dt>SOUP_TYPE_AUTH_MANAGER, <a class="indexterm" href="SoupAuthManager.html#SOUP-TYPE-AUTH-MANAGER:CAPS">SOUP_TYPE_AUTH_MANAGER</a> +</dt> +<dt>SOUP_TYPE_AUTH_NTLM, <a class="indexterm" href="SoupAuth.html#SOUP-TYPE-AUTH-NTLM:CAPS">SOUP_TYPE_AUTH_NTLM</a> +</dt> +<dt>SOUP_TYPE_BYTE_ARRAY, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#SOUP-TYPE-BYTE-ARRAY:CAPS">SOUP_TYPE_BYTE_ARRAY</a> +</dt> +<dt>soup_uri_copy, <a class="indexterm" href="SoupURI.html#soup-uri-copy">soup_uri_copy ()</a> +</dt> +<dt>soup_uri_copy_host, <a class="indexterm" href="SoupURI.html#soup-uri-copy-host">soup_uri_copy_host ()</a> +</dt> +<dt>soup_uri_decode, <a class="indexterm" href="SoupURI.html#soup-uri-decode">soup_uri_decode ()</a> +</dt> +<dt>soup_uri_encode, <a class="indexterm" href="SoupURI.html#soup-uri-encode">soup_uri_encode ()</a> +</dt> +<dt>soup_uri_equal, <a class="indexterm" href="SoupURI.html#soup-uri-equal">soup_uri_equal ()</a> +</dt> +<dt>soup_uri_free, <a class="indexterm" href="SoupURI.html#soup-uri-free">soup_uri_free ()</a> +</dt> +<dt>soup_uri_get_fragment, <a class="indexterm" href="SoupURI.html#soup-uri-get-fragment">soup_uri_get_fragment ()</a> +</dt> +<dt>soup_uri_get_host, <a class="indexterm" href="SoupURI.html#soup-uri-get-host">soup_uri_get_host ()</a> +</dt> +<dt>soup_uri_get_password, <a class="indexterm" href="SoupURI.html#soup-uri-get-password">soup_uri_get_password ()</a> +</dt> +<dt>soup_uri_get_path, <a class="indexterm" href="SoupURI.html#soup-uri-get-path">soup_uri_get_path ()</a> +</dt> +<dt>soup_uri_get_port, <a class="indexterm" href="SoupURI.html#soup-uri-get-port">soup_uri_get_port ()</a> +</dt> +<dt>soup_uri_get_query, <a class="indexterm" href="SoupURI.html#soup-uri-get-query">soup_uri_get_query ()</a> +</dt> +<dt>soup_uri_get_scheme, <a class="indexterm" href="SoupURI.html#soup-uri-get-scheme">soup_uri_get_scheme ()</a> +</dt> +<dt>soup_uri_get_user, <a class="indexterm" href="SoupURI.html#soup-uri-get-user">soup_uri_get_user ()</a> +</dt> +<dt>soup_uri_host_equal, <a class="indexterm" href="SoupURI.html#soup-uri-host-equal">soup_uri_host_equal ()</a> +</dt> +<dt>soup_uri_host_hash, <a class="indexterm" href="SoupURI.html#soup-uri-host-hash">soup_uri_host_hash ()</a> +</dt> +<dt>SOUP_URI_IS_VALID, <a class="indexterm" href="SoupURI.html#SOUP-URI-IS-VALID:CAPS">SOUP_URI_IS_VALID()</a> +</dt> +<dt>soup_uri_new, <a class="indexterm" href="SoupURI.html#soup-uri-new">soup_uri_new ()</a> +</dt> +<dt>soup_uri_new_with_base, <a class="indexterm" href="SoupURI.html#soup-uri-new-with-base">soup_uri_new_with_base ()</a> +</dt> +<dt>soup_uri_normalize, <a class="indexterm" href="SoupURI.html#soup-uri-normalize">soup_uri_normalize ()</a> +</dt> +<dt>SOUP_URI_SCHEME_DATA, <a class="indexterm" href="SoupURI.html#SOUP-URI-SCHEME-DATA:CAPS">SOUP_URI_SCHEME_DATA</a> +</dt> +<dt>SOUP_URI_SCHEME_FILE, <a class="indexterm" href="SoupURI.html#SOUP-URI-SCHEME-FILE:CAPS">SOUP_URI_SCHEME_FILE</a> +</dt> +<dt>SOUP_URI_SCHEME_FTP, <a class="indexterm" href="SoupURI.html#SOUP-URI-SCHEME-FTP:CAPS">SOUP_URI_SCHEME_FTP</a> +</dt> +<dt>SOUP_URI_SCHEME_HTTP, <a class="indexterm" href="SoupURI.html#SOUP-URI-SCHEME-HTTP:CAPS">SOUP_URI_SCHEME_HTTP</a> +</dt> +<dt>SOUP_URI_SCHEME_HTTPS, <a class="indexterm" href="SoupURI.html#SOUP-URI-SCHEME-HTTPS:CAPS">SOUP_URI_SCHEME_HTTPS</a> +</dt> +<dt>SOUP_URI_SCHEME_RESOURCE, <a class="indexterm" href="SoupURI.html#SOUP-URI-SCHEME-RESOURCE:CAPS">SOUP_URI_SCHEME_RESOURCE</a> +</dt> +<dt>soup_uri_set_fragment, <a class="indexterm" href="SoupURI.html#soup-uri-set-fragment">soup_uri_set_fragment ()</a> +</dt> +<dt>soup_uri_set_host, <a class="indexterm" href="SoupURI.html#soup-uri-set-host">soup_uri_set_host ()</a> +</dt> +<dt>soup_uri_set_password, <a class="indexterm" href="SoupURI.html#soup-uri-set-password">soup_uri_set_password ()</a> +</dt> +<dt>soup_uri_set_path, <a class="indexterm" href="SoupURI.html#soup-uri-set-path">soup_uri_set_path ()</a> +</dt> +<dt>soup_uri_set_port, <a class="indexterm" href="SoupURI.html#soup-uri-set-port">soup_uri_set_port ()</a> +</dt> +<dt>soup_uri_set_query, <a class="indexterm" href="SoupURI.html#soup-uri-set-query">soup_uri_set_query ()</a> +</dt> +<dt>soup_uri_set_query_from_fields, <a class="indexterm" href="SoupURI.html#soup-uri-set-query-from-fields">soup_uri_set_query_from_fields ()</a> +</dt> +<dt>soup_uri_set_query_from_form, <a class="indexterm" href="SoupURI.html#soup-uri-set-query-from-form">soup_uri_set_query_from_form ()</a> +</dt> +<dt>soup_uri_set_scheme, <a class="indexterm" href="SoupURI.html#soup-uri-set-scheme">soup_uri_set_scheme ()</a> +</dt> +<dt>soup_uri_set_user, <a class="indexterm" href="SoupURI.html#soup-uri-set-user">soup_uri_set_user ()</a> +</dt> +<dt>soup_uri_to_string, <a class="indexterm" href="SoupURI.html#soup-uri-to-string">soup_uri_to_string ()</a> +</dt> +<dt>soup_uri_uses_default_port, <a class="indexterm" href="SoupURI.html#soup-uri-uses-default-port">soup_uri_uses_default_port ()</a> +</dt> +<dt>SOUP_URI_VALID_FOR_HTTP, <a class="indexterm" href="SoupURI.html#SOUP-URI-VALID-FOR-HTTP:CAPS">SOUP_URI_VALID_FOR_HTTP()</a> +</dt> +<dt>soup_value_array_append, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-array-append">soup_value_array_append ()</a> +</dt> +<dt>soup_value_array_append_vals, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-array-append-vals">soup_value_array_append_vals ()</a> +</dt> +<dt>soup_value_array_from_args, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-array-from-args">soup_value_array_from_args ()</a> +</dt> +<dt>soup_value_array_get_nth, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-array-get-nth">soup_value_array_get_nth ()</a> +</dt> +<dt>soup_value_array_insert, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-array-insert">soup_value_array_insert ()</a> +</dt> +<dt>soup_value_array_new, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-array-new">soup_value_array_new ()</a> +</dt> +<dt>soup_value_array_new_with_vals, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-array-new-with-vals">soup_value_array_new_with_vals ()</a> +</dt> +<dt>soup_value_array_to_args, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-array-to-args">soup_value_array_to_args ()</a> +</dt> +<dt>SOUP_VALUE_GETV, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#SOUP-VALUE-GETV:CAPS">SOUP_VALUE_GETV()</a> +</dt> +<dt>soup_value_hash_insert, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-hash-insert">soup_value_hash_insert ()</a> +</dt> +<dt>soup_value_hash_insert_vals, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-hash-insert-vals">soup_value_hash_insert_vals ()</a> +</dt> +<dt>soup_value_hash_insert_value, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-hash-insert-value">soup_value_hash_insert_value ()</a> +</dt> +<dt>soup_value_hash_lookup, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-hash-lookup">soup_value_hash_lookup ()</a> +</dt> +<dt>soup_value_hash_lookup_vals, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-hash-lookup-vals">soup_value_hash_lookup_vals ()</a> +</dt> +<dt>soup_value_hash_new, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-hash-new">soup_value_hash_new ()</a> +</dt> +<dt>soup_value_hash_new_with_vals, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#soup-value-hash-new-with-vals">soup_value_hash_new_with_vals ()</a> +</dt> +<dt>SOUP_VALUE_SETV, <a class="indexterm" href="libsoup-2.4-GValue-Support.html#SOUP-VALUE-SETV:CAPS">SOUP_VALUE_SETV()</a> +</dt> +<dt>SOUP_VERSION_2_24, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-24:CAPS">SOUP_VERSION_2_24</a> +</dt> +<dt>SOUP_VERSION_2_26, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-26:CAPS">SOUP_VERSION_2_26</a> +</dt> +<dt>SOUP_VERSION_2_28, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-28:CAPS">SOUP_VERSION_2_28</a> +</dt> +<dt>SOUP_VERSION_2_30, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-30:CAPS">SOUP_VERSION_2_30</a> +</dt> +<dt>SOUP_VERSION_2_32, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-32:CAPS">SOUP_VERSION_2_32</a> +</dt> +<dt>SOUP_VERSION_2_34, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-34:CAPS">SOUP_VERSION_2_34</a> +</dt> +<dt>SOUP_VERSION_2_36, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-36:CAPS">SOUP_VERSION_2_36</a> +</dt> +<dt>SOUP_VERSION_2_38, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-38:CAPS">SOUP_VERSION_2_38</a> +</dt> +<dt>SOUP_VERSION_2_40, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-40:CAPS">SOUP_VERSION_2_40</a> +</dt> +<dt>SOUP_VERSION_2_42, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-42:CAPS">SOUP_VERSION_2_42</a> +</dt> +<dt>SOUP_VERSION_2_44, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-44:CAPS">SOUP_VERSION_2_44</a> +</dt> +<dt>SOUP_VERSION_2_46, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-46:CAPS">SOUP_VERSION_2_46</a> +</dt> +<dt>SOUP_VERSION_MAX_ALLOWED, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS">SOUP_VERSION_MAX_ALLOWED</a> +</dt> +<dt>SOUP_VERSION_MIN_REQUIRED, <a class="indexterm" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS">SOUP_VERSION_MIN_REQUIRED</a> +</dt> +<dt>soup_xmlrpc_build_fault, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-fault">soup_xmlrpc_build_fault ()</a> +</dt> +<dt>soup_xmlrpc_build_method_call, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-method-call">soup_xmlrpc_build_method_call ()</a> +</dt> +<dt>soup_xmlrpc_build_method_response, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-method-response">soup_xmlrpc_build_method_response ()</a> +</dt> +<dt>soup_xmlrpc_extract_method_call, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-extract-method-call">soup_xmlrpc_extract_method_call ()</a> +</dt> +<dt>soup_xmlrpc_extract_method_response, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-extract-method-response">soup_xmlrpc_extract_method_response ()</a> +</dt> +<dt>SOUP_XMLRPC_FAULT, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#SOUP-XMLRPC-FAULT:CAPS">SOUP_XMLRPC_FAULT</a> +</dt> +<dt>soup_xmlrpc_parse_method_call, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-parse-method-call">soup_xmlrpc_parse_method_call ()</a> +</dt> +<dt>soup_xmlrpc_parse_method_response, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-parse-method-response">soup_xmlrpc_parse_method_response ()</a> +</dt> +<dt>soup_xmlrpc_request_new, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-request-new">soup_xmlrpc_request_new ()</a> +</dt> +<dt>soup_xmlrpc_set_fault, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-set-fault">soup_xmlrpc_set_fault ()</a> +</dt> +<dt>soup_xmlrpc_set_response, <a class="indexterm" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-set-response">soup_xmlrpc_set_response ()</a> +</dt> +</dl> +</div></div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/left-insensitive.png b/docs/reference/html/left-insensitive.png Binary files differnew file mode 100644 index 00000000..3269393a --- /dev/null +++ b/docs/reference/html/left-insensitive.png diff --git a/docs/reference/html/left.png b/docs/reference/html/left.png Binary files differnew file mode 100644 index 00000000..2abde032 --- /dev/null +++ b/docs/reference/html/left.png diff --git a/docs/reference/html/libsoup-2.4-GValue-Support.html b/docs/reference/html/libsoup-2.4-GValue-Support.html new file mode 100644 index 00000000..1ca50412 --- /dev/null +++ b/docs/reference/html/libsoup-2.4-GValue-Support.html @@ -0,0 +1,885 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: GValue Support</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch04.html" title="Web Services APIs"> +<link rel="prev" href="libsoup-2.4-XMLRPC-Support.html" title="XMLRPC Support"> +<link rel="next" href="ch05.html" title="Low-level Networking API"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#libsoup-2.4-GValue-Support.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#libsoup-2.4-GValue-Support.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch04.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="libsoup-2.4-XMLRPC-Support.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="ch05.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-2.4-GValue-Support"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="libsoup-2.4-GValue-Support.top_of_page"></a>GValue Support</span></h2> +<p>GValue Support — GValue utilities</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="libsoup-2.4-GValue-Support.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-hash-new" title="soup_value_hash_new ()">soup_value_hash_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-hash-new-with-vals" title="soup_value_hash_new_with_vals ()">soup_value_hash_new_with_vals</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-hash-insert-value" title="soup_value_hash_insert_value ()">soup_value_hash_insert_value</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-hash-insert" title="soup_value_hash_insert ()">soup_value_hash_insert</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-hash-insert-vals" title="soup_value_hash_insert_vals ()">soup_value_hash_insert_vals</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-hash-lookup" title="soup_value_hash_lookup ()">soup_value_hash_lookup</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-hash-lookup-vals" title="soup_value_hash_lookup_vals ()">soup_value_hash_lookup_vals</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="returnvalue">GValueArray</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-array-from-args" title="soup_value_array_from_args ()">soup_value_array_from_args</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-array-to-args" title="soup_value_array_to_args ()">soup_value_array_to_args</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="returnvalue">GValueArray</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-array-new" title="soup_value_array_new ()">soup_value_array_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="returnvalue">GValueArray</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-array-new-with-vals" title="soup_value_array_new_with_vals ()">soup_value_array_new_with_vals</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-array-insert" title="soup_value_array_insert ()">soup_value_array_insert</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-array-append" title="soup_value_array_append ()">soup_value_array_append</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-array-append-vals" title="soup_value_array_append_vals ()">soup_value_array_append_vals</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-array-get-nth" title="soup_value_array_get_nth ()">soup_value_array_get_nth</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#SOUP-VALUE-SETV:CAPS" title="SOUP_VALUE_SETV()">SOUP_VALUE_SETV</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-GValue-Support.html#SOUP-VALUE-GETV:CAPS" title="SOUP_VALUE_GETV()">SOUP_VALUE_GETV</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-GValue-Support.html#SOUP-TYPE-BYTE-ARRAY:CAPS" title="SOUP_TYPE_BYTE_ARRAY">SOUP_TYPE_BYTE_ARRAY</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-GValue-Support.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-GValue-Support.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-GValue-Support.description"></a><h2>Description</h2> +<p>These methods are useful for manipulating <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a>s, and in +particular, arrays and hash tables of <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a>s, in a +slightly nicer way than the standard <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> API.</p> +<p>They are written for use with soup-xmlrpc, but they also work with +types not used by XML-RPC.</p> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-GValue-Support.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-value-hash-new"></a><h3>soup_value_hash_new ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +soup_value_hash_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<p>Creates a <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> whose keys are strings and whose values +are <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a>.</p> +<div class="refsect3"> +<a name="id-1.5.4.7.2.5"></a><h4>Returns</h4> +<p> a new +empty <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>. </p> +<p><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 GValue][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-hash-new-with-vals"></a><h3>soup_value_hash_new_with_vals ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +soup_value_hash_new_with_vals (<em class="parameter"><code>const <span class="type">char</span> *first_key</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Creates a <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> whose keys are strings and whose values +are <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a>, and initializes it with the provided data. As +with <a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-hash-insert" title="soup_value_hash_insert ()"><code class="function">soup_value_hash_insert()</code></a>, the keys and values are copied +rather than being inserted directly.</p> +<div class="refsect3"> +<a name="id-1.5.4.7.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>first_key</p></td> +<td class="parameter_description"><p>the key for the first value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>the type of <em class="parameter"><code>first_key</code></em> +, followed by the value, followed +by additional key/type/value triplets, terminated by <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.4.7.3.6"></a><h4>Returns</h4> +<p> a new +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>, initialized with the given values. </p> +<p><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 GValue][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-hash-insert-value"></a><h3>soup_value_hash_insert_value ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_value_hash_insert_value (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *hash</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *key</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> *value</code></em>);</pre> +<p>Inserts <em class="parameter"><code>value</code></em> + into <em class="parameter"><code>hash</code></em> +. (Unlike with <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#g-hash-table-insert"><code class="function">g_hash_table_insert()</code></a>, both +the key and the value are copied).</p> +<div class="refsect3"> +<a name="id-1.5.4.7.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hash</p></td> +<td class="parameter_description"><p> a value hash. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 GValue]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>key</p></td> +<td class="parameter_description"><p>the key</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>value</p></td> +<td class="parameter_description"><p>a value</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-hash-insert"></a><h3>soup_value_hash_insert ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_value_hash_insert (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *hash</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *key</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Inserts the provided value of type <em class="parameter"><code>type</code></em> + into <em class="parameter"><code>hash</code></em> +. (Unlike with +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#g-hash-table-insert"><code class="function">g_hash_table_insert()</code></a>, both the key and the value are copied).</p> +<div class="refsect3"> +<a name="id-1.5.4.7.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hash</p></td> +<td class="parameter_description"><p> a value hash. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 GValue]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>key</p></td> +<td class="parameter_description"><p>the key</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>a value of type <em class="parameter"><code>type</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-hash-insert-vals"></a><h3>soup_value_hash_insert_vals ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_value_hash_insert_vals (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *hash</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *first_key</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Inserts the given data into <em class="parameter"><code>hash</code></em> +. As with +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-hash-insert" title="soup_value_hash_insert ()"><code class="function">soup_value_hash_insert()</code></a>, the keys and values are copied rather +than being inserted directly.</p> +<div class="refsect3"> +<a name="id-1.5.4.7.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hash</p></td> +<td class="parameter_description"><p> a value hash. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 GValue]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>first_key</p></td> +<td class="parameter_description"><p>the key for the first value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>the type of <em class="parameter"><code>first_key</code></em> +, followed by the value, followed +by additional key/type/value triplets, terminated by <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-hash-lookup"></a><h3>soup_value_hash_lookup ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_value_hash_lookup (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *hash</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *key</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Looks up <em class="parameter"><code>key</code></em> + in <em class="parameter"><code>hash</code></em> + and stores its value into the provided +location.</p> +<div class="refsect3"> +<a name="id-1.5.4.7.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hash</p></td> +<td class="parameter_description"><p> a value hash. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 GValue]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>key</p></td> +<td class="parameter_description"><p>the key to look up</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>a value of type pointer-to-<em class="parameter"><code>type</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.4.7.7.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>hash</code></em> +contained a value with key <em class="parameter"><code>key</code></em> +and +type <em class="parameter"><code>type</code></em> +, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if not.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-hash-lookup-vals"></a><h3>soup_value_hash_lookup_vals ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_value_hash_lookup_vals (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *hash</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *first_key</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Looks up a number of keys in <em class="parameter"><code>hash</code></em> + and returns their values.</p> +<div class="refsect3"> +<a name="id-1.5.4.7.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hash</p></td> +<td class="parameter_description"><p> a value hash. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 GValue]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>first_key</p></td> +<td class="parameter_description"><p>the first key to look up</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>the type of <em class="parameter"><code>first_key</code></em> +, a pointer to that type, and +then additional key/type/pointer triplets, terminated +by <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.4.7.8.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if all of the keys were found, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> +if any were missing; note that you will generally need to +initialize each destination variable to a reasonable default +value, since there is no way to tell which keys were found +and which were not.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-array-from-args"></a><h3>soup_value_array_from_args ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="returnvalue">GValueArray</span></a> * +soup_value_array_from_args (<em class="parameter"><code><span class="type">va_list</span> args</code></em>);</pre> +<p>Creates a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> from the provided arguments, which must +consist of pairs of a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> and a value of that type, terminated +by <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-INVALID:CAPS"><code class="literal">G_TYPE_INVALID</code></a>. (The array will contain copies of the provided +data rather than pointing to the passed-in data directly.)</p> +<div class="refsect3"> +<a name="id-1.5.4.7.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>args</p></td> +<td class="parameter_description"><p>arguments to create a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> from</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.4.7.9.6"></a><h4>Returns</h4> +<p> a new <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if an error occurred.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-array-to-args"></a><h3>soup_value_array_to_args ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_value_array_to_args (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> *array</code></em>, + <em class="parameter"><code><span class="type">va_list</span> args</code></em>);</pre> +<p>Extracts a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> into the provided arguments, which must +consist of pairs of a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> and a value of pointer-to-that-type, +terminated by <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-INVALID:CAPS"><code class="literal">G_TYPE_INVALID</code></a>. The returned values will point to the +same memory as the values in the array.</p> +<div class="refsect3"> +<a name="id-1.5.4.7.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>array</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>args</p></td> +<td class="parameter_description"><p>arguments to extract <em class="parameter"><code>array</code></em> +into</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.4.7.10.6"></a><h4>Returns</h4> +<p> success or failure</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-array-new"></a><h3>soup_value_array_new ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="returnvalue">GValueArray</span></a> * +soup_value_array_new (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<p>Creates a new <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><code class="literal">GValueArray</code></a>. (This is just a wrapper around +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#g-value-array-new"><code class="function">g_value_array_new()</code></a>, for naming consistency purposes.)</p> +<div class="refsect3"> +<a name="id-1.5.4.7.11.5"></a><h4>Returns</h4> +<p> a new <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><code class="literal">GValueArray</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-array-new-with-vals"></a><h3>soup_value_array_new_with_vals ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="returnvalue">GValueArray</span></a> * +soup_value_array_new_with_vals (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> first_type</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Creates a new <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><code class="literal">GValueArray</code></a> and copies the provided values +into it.</p> +<div class="refsect3"> +<a name="id-1.5.4.7.12.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>first_type</p></td> +<td class="parameter_description"><p>the type of the first value to add</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>the first value to add, followed by other type/value +pairs, terminated by <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-INVALID:CAPS"><code class="literal">G_TYPE_INVALID</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.4.7.12.6"></a><h4>Returns</h4> +<p> a new <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><code class="literal">GValueArray</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-array-insert"></a><h3>soup_value_array_insert ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_value_array_insert (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> *array</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> index_</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Inserts the provided value of type <em class="parameter"><code>type</code></em> + into <em class="parameter"><code>array</code></em> + as with +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#g-value-array-insert"><code class="function">g_value_array_insert()</code></a>. (The provided data is copied rather than +being inserted directly.)</p> +<div class="refsect3"> +<a name="id-1.5.4.7.13.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>array</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>index_</p></td> +<td class="parameter_description"><p>the index to insert at</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>a value of type <em class="parameter"><code>type</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-array-append"></a><h3>soup_value_array_append ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_value_array_append (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> *array</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Appends the provided value of type <em class="parameter"><code>type</code></em> + to <em class="parameter"><code>array</code></em> + as with +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#g-value-array-append"><code class="function">g_value_array_append()</code></a>. (The provided data is copied rather than +being inserted directly.)</p> +<div class="refsect3"> +<a name="id-1.5.4.7.14.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>array</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>a value of type <em class="parameter"><code>type</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-array-append-vals"></a><h3>soup_value_array_append_vals ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_value_array_append_vals (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> *array</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> first_type</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Appends the provided values into <em class="parameter"><code>array</code></em> + as with +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#g-value-array-append"><code class="function">g_value_array_append()</code></a>. (The provided data is copied rather than +being inserted directly.)</p> +<div class="refsect3"> +<a name="id-1.5.4.7.15.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>array</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>first_type</p></td> +<td class="parameter_description"><p>the type of the first value to add</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>the first value to add, followed by other type/value +pairs, terminated by <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-INVALID:CAPS"><code class="literal">G_TYPE_INVALID</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-value-array-get-nth"></a><h3>soup_value_array_get_nth ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_value_array_get_nth (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> *array</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> index_</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Gets the <em class="parameter"><code>index_</code></em> + element of <em class="parameter"><code>array</code></em> + and stores its value into the +provided location.</p> +<div class="refsect3"> +<a name="id-1.5.4.7.16.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>array</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>index_</p></td> +<td class="parameter_description"><p>the index to look up</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>a value of type pointer-to-<em class="parameter"><code>type</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.4.7.16.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>array</code></em> +contained a value with index <em class="parameter"><code>index_</code></em> +and type <em class="parameter"><code>type</code></em> +, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if not.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VALUE-SETV:CAPS"></a><h3>SOUP_VALUE_SETV()</h3> +<pre class="programlisting">#define SOUP_VALUE_SETV(val, type, args)</pre> +<p>Copies an argument of type <em class="parameter"><code>type</code></em> + from <em class="parameter"><code>args</code></em> + into <em class="parameter"><code>val</code></em> +. <em class="parameter"><code>val</code></em> + will +point directly to the value in <em class="parameter"><code>args</code></em> + rather than copying it, so you +must <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#g-value-copy"><code class="function">g_value_copy()</code></a> it if you want it to remain valid.</p> +<div class="refsect3"> +<a name="id-1.5.4.7.17.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>val</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>args</p></td> +<td class="parameter_description"><p><span class="type">va_list</span> pointing to a value of type <em class="parameter"><code>type</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VALUE-GETV:CAPS"></a><h3>SOUP_VALUE_GETV()</h3> +<pre class="programlisting">#define SOUP_VALUE_GETV(val, type, args)</pre> +<p>Extracts a value of type <em class="parameter"><code>type</code></em> + from <em class="parameter"><code>val</code></em> + into <em class="parameter"><code>args</code></em> +. The return +value will point to the same data as <em class="parameter"><code>val</code></em> + rather than being a copy +of it.</p> +<div class="refsect3"> +<a name="id-1.5.4.7.18.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>val</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>args</p></td> +<td class="parameter_description"><p><span class="type">va_list</span> pointing to a value of type pointer-to-<em class="parameter"><code>type</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-TYPE-BYTE-ARRAY:CAPS"></a><h3>SOUP_TYPE_BYTE_ARRAY</h3> +<pre class="programlisting">#define SOUP_TYPE_BYTE_ARRAY (soup_byte_array_get_type ()) +</pre> +<p>glib did not used to define a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> for <a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GByteArray"><span class="type">GByteArray</span></a>, so libsoup +defines this one itself.</p> +</div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-GValue-Support.other_details"></a><h2>Types and Values</h2> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-2.4-HTML-Form-Support.html b/docs/reference/html/libsoup-2.4-HTML-Form-Support.html new file mode 100644 index 00000000..1574d1fb --- /dev/null +++ b/docs/reference/html/libsoup-2.4-HTML-Form-Support.html @@ -0,0 +1,652 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: HTML Form Support</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch04.html" title="Web Services APIs"> +<link rel="prev" href="ch04.html" title="Web Services APIs"> +<link rel="next" href="libsoup-2.4-XMLRPC-Support.html" title="XMLRPC Support"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#libsoup-2.4-HTML-Form-Support.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#libsoup-2.4-HTML-Form-Support.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch04.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="ch04.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-2.4-XMLRPC-Support.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-2.4-HTML-Form-Support"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="libsoup-2.4-HTML-Form-Support.top_of_page"></a>HTML Form Support</span></h2> +<p>HTML Form Support — HTML form handling</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="libsoup-2.4-HTML-Form-Support.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-decode" title="soup_form_decode ()">soup_form_decode</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-decode-multipart" title="soup_form_decode_multipart ()">soup_form_decode_multipart</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode" title="soup_form_encode ()">soup_form_encode</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-datalist" title="soup_form_encode_datalist ()">soup_form_encode_datalist</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-hash" title="soup_form_encode_hash ()">soup_form_encode_hash</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-valist" title="soup_form_encode_valist ()">soup_form_encode_valist</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new" title="soup_form_request_new ()">soup_form_request_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-datalist" title="soup_form_request_new_from_datalist ()">soup_form_request_new_from_datalist</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-hash" title="soup_form_request_new_from_hash ()">soup_form_request_new_from_hash</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-multipart" title="soup_form_request_new_from_multipart ()">soup_form_request_new_from_multipart</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-HTML-Form-Support.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-HTML-Form-Support.html#SOUP-FORM-MIME-TYPE-MULTIPART:CAPS" title="SOUP_FORM_MIME_TYPE_MULTIPART">SOUP_FORM_MIME_TYPE_MULTIPART</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-HTML-Form-Support.html#SOUP-FORM-MIME-TYPE-URLENCODED:CAPS" title="SOUP_FORM_MIME_TYPE_URLENCODED">SOUP_FORM_MIME_TYPE_URLENCODED</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-HTML-Form-Support.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-HTML-Form-Support.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-HTML-Form-Support.description"></a><h2>Description</h2> +<p>libsoup contains several help methods for processing HTML forms as +defined by <a class="ulink" href="http://www.w3.org/TR/html401/interact/forms.html#h-17.13" target="_top">the +HTML 4.01 specification</a>.</p> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-HTML-Form-Support.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-form-decode"></a><h3>soup_form_decode ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +soup_form_decode (<em class="parameter"><code>const <span class="type">char</span> *encoded_form</code></em>);</pre> +<p>Decodes <em class="parameter"><code>form</code></em> +, which is an urlencoded dataset as defined in the +HTML 4.01 spec.</p> +<div class="refsect3"> +<a name="id-1.5.2.8.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>encoded_form</p></td> +<td class="parameter_description"><p>data of type "application/x-www-form-urlencoded"</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.2.8.2.6"></a><h4>Returns</h4> +<p> a hash +table containing the name/value pairs from <em class="parameter"><code>encoded_form</code></em> +, which you +can free with <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#g-hash-table-destroy"><code class="function">g_hash_table_destroy()</code></a>. </p> +<p><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-form-decode-multipart"></a><h3>soup_form_decode_multipart ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +soup_form_decode_multipart (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *file_control_name</code></em>, + <em class="parameter"><code><span class="type">char</span> **filename</code></em>, + <em class="parameter"><code><span class="type">char</span> **content_type</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageBody.html#SoupBuffer"><span class="type">SoupBuffer</span></a> **file</code></em>);</pre> +<p>Decodes the "multipart/form-data" request in <em class="parameter"><code>msg</code></em> +; this is a +convenience method for the case when you have a single file upload +control in a form. (Or when you don't have any file upload +controls, but are still using "multipart/form-data" anyway.) Pass +the name of the file upload control in <em class="parameter"><code>file_control_name</code></em> +, and +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-decode-multipart" title="soup_form_decode_multipart ()"><code class="function">soup_form_decode_multipart()</code></a> will extract the uploaded file data +into <em class="parameter"><code>filename</code></em> +, <em class="parameter"><code>content_type</code></em> +, and <em class="parameter"><code>file</code></em> +. All of the other form +control data will be returned (as strings, as with +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-decode" title="soup_form_decode ()"><code class="function">soup_form_decode()</code></a>) in the returned <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>.</p> +<p>You may pass <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> for <em class="parameter"><code>filename</code></em> +, <em class="parameter"><code>content_type</code></em> + and/or <em class="parameter"><code>file</code></em> + if you do not +care about those fields. <a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-decode-multipart" title="soup_form_decode_multipart ()"><code class="function">soup_form_decode_multipart()</code></a> may also +return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> in those fields if the client did not provide that +information. You must free the returned filename and content-type +with <a href="http://library.gnome.org/devel/glib/unstable/glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a>, and the returned file data with <a class="link" href="SoupMessageBody.html#soup-buffer-free" title="soup_buffer_free ()"><code class="function">soup_buffer_free()</code></a>.</p> +<p>If you have a form with more than one file upload control, you will +need to decode it manually, using <a class="link" href="SoupMultipart.html#soup-multipart-new-from-message" title="soup_multipart_new_from_message ()"><code class="function">soup_multipart_new_from_message()</code></a> +and <a class="link" href="SoupMultipart.html#soup-multipart-get-part" title="soup_multipart_get_part ()"><code class="function">soup_multipart_get_part()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.5.2.8.3.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> containing a "multipart/form-data" request body</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>file_control_name</p></td> +<td class="parameter_description"><p> the name of the HTML file upload control, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>filename</p></td> +<td class="parameter_description"><p> return location for the name of the uploaded file, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>content_type</p></td> +<td class="parameter_description"><p> return location for the MIME type of the uploaded file, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>file</p></td> +<td class="parameter_description"><p> return location for the uploaded file data, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.2.8.3.8"></a><h4>Returns</h4> +<p> a hash +table containing the name/value pairs (other than +<em class="parameter"><code>file_control_name</code></em> +) from <em class="parameter"><code>msg</code></em> +, which you can free with +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#g-hash-table-destroy"><code class="function">g_hash_table_destroy()</code></a>. On error, it will return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. </p> +<p><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-form-encode"></a><h3>soup_form_encode ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_form_encode (<em class="parameter"><code>const <span class="type">char</span> *first_field</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Encodes the given field names and values into a value of type +"application/x-www-form-urlencoded", as defined in the HTML 4.01 +spec.</p> +<p>This method requires you to know the names of the form fields (or +at the very least, the total number of fields) at compile time; for +working with dynamic forms, use <a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-hash" title="soup_form_encode_hash ()"><code class="function">soup_form_encode_hash()</code></a> or +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-datalist" title="soup_form_encode_datalist ()"><code class="function">soup_form_encode_datalist()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.5.2.8.4.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>first_field</p></td> +<td class="parameter_description"><p>name of the first form field</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>value of <em class="parameter"><code>first_field</code></em> +, followed by additional field names +and values, terminated by <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.2.8.4.7"></a><h4>Returns</h4> +<p> the encoded form</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-form-encode-datalist"></a><h3>soup_form_encode_datalist ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_form_encode_datalist (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Keyed-Data-Lists.html#GData"><span class="type">GData</span></a> **form_data_set</code></em>);</pre> +<p>Encodes <em class="parameter"><code>form_data_set</code></em> + into a value of type +"application/x-www-form-urlencoded", as defined in the HTML 4.01 +spec. Unlike <a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-hash" title="soup_form_encode_hash ()"><code class="function">soup_form_encode_hash()</code></a>, this preserves the ordering +of the form elements, which may be required in some situations.</p> +<div class="refsect3"> +<a name="id-1.5.2.8.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>form_data_set</p></td> +<td class="parameter_description"><p>a datalist containing name/value pairs</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.2.8.5.6"></a><h4>Returns</h4> +<p> the encoded form</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-form-encode-hash"></a><h3>soup_form_encode_hash ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_form_encode_hash (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *form_data_set</code></em>);</pre> +<p>Encodes <em class="parameter"><code>form_data_set</code></em> + into a value of type +"application/x-www-form-urlencoded", as defined in the HTML 4.01 +spec.</p> +<p>Note that the HTML spec states that "The control names/values are +listed in the order they appear in the document." Since this method +takes a hash table, it cannot enforce that; if you care about the +ordering of the form fields, use <a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-datalist" title="soup_form_encode_datalist ()"><code class="function">soup_form_encode_datalist()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.5.2.8.6.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>form_data_set</p></td> +<td class="parameter_description"><p> a hash table containing +name/value pairs (as strings). </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8]</span></td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.2.8.6.7"></a><h4>Returns</h4> +<p> the encoded form</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-form-encode-valist"></a><h3>soup_form_encode_valist ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_form_encode_valist (<em class="parameter"><code>const <span class="type">char</span> *first_field</code></em>, + <em class="parameter"><code><span class="type">va_list</span> args</code></em>);</pre> +<p>See <a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode" title="soup_form_encode ()"><code class="function">soup_form_encode()</code></a>. This is mostly an internal method, used by +various other methods such as <a class="link" href="SoupURI.html#soup-uri-set-query-from-fields" title="soup_uri_set_query_from_fields ()"><code class="function">soup_uri_set_query_from_fields()</code></a> and +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new" title="soup_form_request_new ()"><code class="function">soup_form_request_new()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.5.2.8.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>first_field</p></td> +<td class="parameter_description"><p>name of the first form field</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>args</p></td> +<td class="parameter_description"><p>pointer to additional values, as in <a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-encode" title="soup_form_encode ()"><code class="function">soup_form_encode()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.2.8.7.6"></a><h4>Returns</h4> +<p> the encoded form</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-form-request-new"></a><h3>soup_form_request_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +soup_form_request_new (<em class="parameter"><code>const <span class="type">char</span> *method</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *uri</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *first_field</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupMessage.html" title="SoupMessage"><code class="literal">SoupMessage</code></a> and sets it up to send the given data +to <em class="parameter"><code>uri</code></em> + via <em class="parameter"><code>method</code></em> +. (That is, if <em class="parameter"><code>method</code></em> + is "GET", it will encode +the form data into <em class="parameter"><code>uri</code></em> +'s query field, and if <em class="parameter"><code>method</code></em> + is "POST", it +will encode it into the <a class="link" href="SoupMessage.html" title="SoupMessage"><code class="literal">SoupMessage</code></a>'s request_body.)</p> +<div class="refsect3"> +<a name="id-1.5.2.8.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>method</p></td> +<td class="parameter_description"><p>the HTTP method, either "GET" or "POST"</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>the URI to send the form data to</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>first_field</p></td> +<td class="parameter_description"><p>name of the first form field</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>value of <em class="parameter"><code>first_field</code></em> +, followed by additional field names +and values, terminated by <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.2.8.8.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupMessage.html" title="SoupMessage"><code class="literal">SoupMessage</code></a>. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-form-request-new-from-datalist"></a><h3>soup_form_request_new_from_datalist ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +soup_form_request_new_from_datalist (<em class="parameter"><code>const <span class="type">char</span> *method</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *uri</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Keyed-Data-Lists.html#GData"><span class="type">GData</span></a> **form_data_set</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupMessage.html" title="SoupMessage"><code class="literal">SoupMessage</code></a> and sets it up to send <em class="parameter"><code>form_data_set</code></em> + to +<em class="parameter"><code>uri</code></em> + via <em class="parameter"><code>method</code></em> +, as with <a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new" title="soup_form_request_new ()"><code class="function">soup_form_request_new()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.5.2.8.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>method</p></td> +<td class="parameter_description"><p>the HTTP method, either "GET" or "POST"</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>the URI to send the form data to</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>form_data_set</p></td> +<td class="parameter_description"><p>the data to send to <em class="parameter"><code>uri</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.2.8.9.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupMessage.html" title="SoupMessage"><code class="literal">SoupMessage</code></a>. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-form-request-new-from-hash"></a><h3>soup_form_request_new_from_hash ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +soup_form_request_new_from_hash (<em class="parameter"><code>const <span class="type">char</span> *method</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *uri</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *form_data_set</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupMessage.html" title="SoupMessage"><code class="literal">SoupMessage</code></a> and sets it up to send <em class="parameter"><code>form_data_set</code></em> + to +<em class="parameter"><code>uri</code></em> + via <em class="parameter"><code>method</code></em> +, as with <a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new" title="soup_form_request_new ()"><code class="function">soup_form_request_new()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.5.2.8.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>method</p></td> +<td class="parameter_description"><p>the HTTP method, either "GET" or "POST"</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>the URI to send the form data to</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>form_data_set</p></td> +<td class="parameter_description"><p> the data to send to <em class="parameter"><code>uri</code></em> +. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.2.8.10.6"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupMessage.html" title="SoupMessage"><code class="literal">SoupMessage</code></a>. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-form-request-new-from-multipart"></a><h3>soup_form_request_new_from_multipart ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +soup_form_request_new_from_multipart (<em class="parameter"><code>const <span class="type">char</span> *uri</code></em>, + <em class="parameter"><code><a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a> *multipart</code></em>);</pre> +<p>Creates a new <a class="link" href="SoupMessage.html" title="SoupMessage"><code class="literal">SoupMessage</code></a> and sets it up to send <em class="parameter"><code>multipart</code></em> + to +<em class="parameter"><code>uri</code></em> + via POST.</p> +<p>To send a <code class="literal">"multipart/form-data"</code> POST, first +create a <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a>, using <a class="link" href="libsoup-2.4-HTML-Form-Support.html#SOUP-FORM-MIME-TYPE-MULTIPART:CAPS" title="SOUP_FORM_MIME_TYPE_MULTIPART"><code class="literal">SOUP_FORM_MIME_TYPE_MULTIPART</code></a> as +the MIME type. Then use <a class="link" href="SoupMultipart.html#soup-multipart-append-form-string" title="soup_multipart_append_form_string ()"><code class="function">soup_multipart_append_form_string()</code></a> and +<a class="link" href="SoupMultipart.html#soup-multipart-append-form-file" title="soup_multipart_append_form_file ()"><code class="function">soup_multipart_append_form_file()</code></a> to add the value of each form +control to the multipart. (These are just convenience methods, and +you can use <a class="link" href="SoupMultipart.html#soup-multipart-append-part" title="soup_multipart_append_part ()"><code class="function">soup_multipart_append_part()</code></a> if you need greater +control over the part headers.) Finally, call +<a class="link" href="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-multipart" title="soup_form_request_new_from_multipart ()"><code class="function">soup_form_request_new_from_multipart()</code></a> to serialize the multipart +structure and create a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>.</p> +<div class="refsect3"> +<a name="id-1.5.2.8.11.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>the URI to send the form data to</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>multipart</p></td> +<td class="parameter_description"><p>a "multipart/form-data" <a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.2.8.11.7"></a><h4>Returns</h4> +<p> the new <a class="link" href="SoupMessage.html" title="SoupMessage"><code class="literal">SoupMessage</code></a>. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.26</p> +</div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-HTML-Form-Support.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SOUP-FORM-MIME-TYPE-MULTIPART:CAPS"></a><h3>SOUP_FORM_MIME_TYPE_MULTIPART</h3> +<pre class="programlisting">#define SOUP_FORM_MIME_TYPE_MULTIPART "multipart/form-data" +</pre> +<p>A macro containing the value +<code class="literal">"multipart/form-data"</code>; the MIME type used for +posting form data that contains files to be uploaded.</p> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-FORM-MIME-TYPE-URLENCODED:CAPS"></a><h3>SOUP_FORM_MIME_TYPE_URLENCODED</h3> +<pre class="programlisting">#define SOUP_FORM_MIME_TYPE_URLENCODED "application/x-www-form-urlencoded" +</pre> +<p>A macro containing the value +<code class="literal">"application/x-www-form-urlencoded"</code>; the default +MIME type for POSTing HTML form data.</p> +<p class="since">Since 2.26</p> +</div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-HTML-Form-Support.see-also"></a><h2>See Also</h2> +<p><a class="link" href="SoupMultipart.html" title="SoupMultipart"><span class="type">SoupMultipart</span></a></p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-2.4-Soup-Miscellaneous-Utilities.html b/docs/reference/html/libsoup-2.4-Soup-Miscellaneous-Utilities.html new file mode 100644 index 00000000..2693a60a --- /dev/null +++ b/docs/reference/html/libsoup-2.4-Soup-Miscellaneous-Utilities.html @@ -0,0 +1,1956 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Soup Miscellaneous Utilities</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="libsoup-2.4-soup-method.html" title="soup-method"> +<link rel="next" href="SoupMultipart.html" title="SoupMultipart"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#libsoup-2.4-Soup-Miscellaneous-Utilities.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#libsoup-2.4-Soup-Miscellaneous-Utilities.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="libsoup-2.4-soup-method.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupMultipart.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-2.4-Soup-Miscellaneous-Utilities"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="libsoup-2.4-Soup-Miscellaneous-Utilities.top_of_page"></a>Soup Miscellaneous Utilities</span></h2> +<p>Soup Miscellaneous Utilities — Miscellaneous functions</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="libsoup-2.4-Soup-Miscellaneous-Utilities.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="returnvalue">SoupDate</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new" title="soup_date_new ()">soup_date_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="returnvalue">SoupDate</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-string" title="soup_date_new_from_string ()">soup_date_new_from_string</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="returnvalue">SoupDate</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-time-t" title="soup_date_new_from_time_t ()">soup_date_new_from_time_t</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="returnvalue">SoupDate</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-now" title="soup_date_new_from_now ()">soup_date_new_from_now</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-string" title="soup_date_to_string ()">soup_date_to_string</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">time_t</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-time-t" title="soup_date_to_time_t ()">soup_date_to_time_t</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-timeval" title="soup_date_to_timeval ()">soup_date_to_timeval</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-is-past" title="soup_date_is_past ()">soup_date_is_past</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">int</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-day" title="soup_date_get_day ()">soup_date_get_day</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">int</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-hour" title="soup_date_get_hour ()">soup_date_get_hour</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">int</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-minute" title="soup_date_get_minute ()">soup_date_get_minute</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">int</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-month" title="soup_date_get_month ()">soup_date_get_month</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">int</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-offset" title="soup_date_get_offset ()">soup_date_get_offset</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">int</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-second" title="soup_date_get_second ()">soup_date_get_second</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">int</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-utc" title="soup_date_get_utc ()">soup_date_get_utc</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">int</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-year" title="soup_date_get_year ()">soup_date_get_year</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-free" title="soup_date_free ()">soup_date_free</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-request" title="soup_headers_parse_request ()">soup_headers_parse_request</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-response" title="soup_headers_parse_response ()">soup_headers_parse_response</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-status-line" title="soup_headers_parse_status_line ()">soup_headers_parse_status_line</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse" title="soup_headers_parse ()">soup_headers_parse</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-list" title="soup_header_parse_list ()">soup_header_parse_list</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-quality-list" title="soup_header_parse_quality_list ()">soup_header_parse_quality_list</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-free-list" title="soup_header_free_list ()">soup_header_free_list</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-contains" title="soup_header_contains ()">soup_header_contains</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-param-list" title="soup_header_parse_param_list ()">soup_header_parse_param_list</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-semi-param-list" title="soup_header_parse_semi_param_list ()">soup_header_parse_semi_param_list</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-free-param-list" title="soup_header_free_param_list ()">soup_header_free_param_list</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-g-string-append-param" title="soup_header_g_string_append_param ()">soup_header_g_string_append_param</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-g-string-append-param-quoted" title="soup_header_g_string_append_param_quoted ()">soup_header_g_string_append_param_quoted</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-str-case-equal" title="soup_str_case_equal ()">soup_str_case_equal</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-str-case-hash" title="soup_str_case_hash ()">soup_str_case_hash</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-completion" title="soup_add_completion ()">soup_add_completion</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-idle" title="soup_add_idle ()">soup_add_idle</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-io-watch" title="soup_add_io_watch ()">soup_add_io_watch</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-timeout" title="soup_add_timeout ()">soup_add_timeout</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<a name="SoupDate"></a><div class="refsect1"> +<a name="libsoup-2.4-Soup-Miscellaneous-Utilities.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword"> </td> +<td class="function_name"><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate-struct" title="SoupDate">SoupDate</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDateFormat" title="enum SoupDateFormat">SoupDateFormat</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Soup-Miscellaneous-Utilities.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> GBoxed + <span class="lineart">╰──</span> SoupDate +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Soup-Miscellaneous-Utilities.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Soup-Miscellaneous-Utilities.description"></a><h2>Description</h2> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Soup-Miscellaneous-Utilities.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-date-new"></a><h3>soup_date_new ()</h3> +<pre class="programlisting"><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="returnvalue">SoupDate</span></a> * +soup_date_new (<em class="parameter"><code><span class="type">int</span> year</code></em>, + <em class="parameter"><code><span class="type">int</span> month</code></em>, + <em class="parameter"><code><span class="type">int</span> day</code></em>, + <em class="parameter"><code><span class="type">int</span> hour</code></em>, + <em class="parameter"><code><span class="type">int</span> minute</code></em>, + <em class="parameter"><code><span class="type">int</span> second</code></em>);</pre> +<p>Creates a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> representing the indicated time, UTC.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>year</p></td> +<td class="parameter_description"><p>the year (1-9999)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>month</p></td> +<td class="parameter_description"><p>the month (1-12)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>day</p></td> +<td class="parameter_description"><p>the day of the month (1-31, as appropriate for <em class="parameter"><code>month</code></em> +)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>hour</p></td> +<td class="parameter_description"><p>the hour (0-23)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>minute</p></td> +<td class="parameter_description"><p>the minute (0-59)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>second</p></td> +<td class="parameter_description"><p>the second (0-59, or up to 61 for leap seconds)</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.2.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-new-from-string"></a><h3>soup_date_new_from_string ()</h3> +<pre class="programlisting"><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="returnvalue">SoupDate</span></a> * +soup_date_new_from_string (<em class="parameter"><code>const <span class="type">char</span> *date_string</code></em>);</pre> +<p>Parses <em class="parameter"><code>date_string</code></em> + and tries to extract a date from it. This +recognizes all of the "HTTP-date" formats from RFC 2616, all ISO +8601 formats containing both a time and a date, RFC 2822 dates, +and reasonable approximations thereof. (Eg, it is lenient about +whitespace, leading "0"s, etc.)</p> +<div class="refsect3"> +<a name="id-1.3.12.9.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date_string</p></td> +<td class="parameter_description"><p>the date in some plausible format</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.3.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if <em class="parameter"><code>date_string</code></em> +could not +be parsed.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-new-from-time-t"></a><h3>soup_date_new_from_time_t ()</h3> +<pre class="programlisting"><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="returnvalue">SoupDate</span></a> * +soup_date_new_from_time_t (<em class="parameter"><code><span class="type">time_t</span> when</code></em>);</pre> +<p>Creates a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> corresponding to <em class="parameter"><code>when</code></em> +</p> +<div class="refsect3"> +<a name="id-1.3.12.9.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>when</p></td> +<td class="parameter_description"><p>a <span class="type">time_t</span></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.4.6"></a><h4>Returns</h4> +<p> a new <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-new-from-now"></a><h3>soup_date_new_from_now ()</h3> +<pre class="programlisting"><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="returnvalue">SoupDate</span></a> * +soup_date_new_from_now (<em class="parameter"><code><span class="type">int</span> offset_seconds</code></em>);</pre> +<p>Creates a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> representing a time <em class="parameter"><code>offset_seconds</code></em> + after the +current time (or before it, if <em class="parameter"><code>offset_seconds</code></em> + is negative). If +offset_seconds is 0, returns the current time.</p> +<p>If <em class="parameter"><code>offset_seconds</code></em> + would indicate a time not expressible as a</p> +<span class="type">time_t</span>, the return value will be clamped into range. +<div class="refsect3"> +<a name="id-1.3.12.9.5.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>offset_seconds</p></td> +<td class="parameter_description"><p>offset from current time</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.5.8"></a><h4>Returns</h4> +<p> a new <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-to-string"></a><h3>soup_date_to_string ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_date_to_string (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>, + <em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDateFormat" title="enum SoupDateFormat"><span class="type">SoupDateFormat</span></a> format</code></em>);</pre> +<p>Converts <em class="parameter"><code>date</code></em> + to a string in the format described by <em class="parameter"><code>format</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>format</p></td> +<td class="parameter_description"><p>the format to generate the date in</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.6.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>date</code></em> +as a string</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-to-time-t"></a><h3>soup_date_to_time_t ()</h3> +<pre class="programlisting"><span class="returnvalue">time_t</span> +soup_date_to_time_t (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>);</pre> +<p>Converts <em class="parameter"><code>date</code></em> + to a <span class="type">time_t</span>.</p> +<p>If <em class="parameter"><code>date</code></em> + is not representable as a <span class="type">time_t</span>, it will be +clamped into range. (In particular, some HTTP cookies have +expiration dates after "Y2.038k" (2038-01-19T03:14:07Z).)</p> +<div class="refsect3"> +<a name="id-1.3.12.9.7.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.7.7"></a><h4>Returns</h4> +<p> <em class="parameter"><code>date</code></em> +as a <span class="type">time_t</span></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-to-timeval"></a><h3>soup_date_to_timeval ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_date_to_timeval (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Date-and-Time-Functions.html#GTimeVal"><span class="type">GTimeVal</span></a> *time</code></em>);</pre> +<p>Converts <em class="parameter"><code>date</code></em> + to a <a href="http://library.gnome.org/devel/glib/unstable/glib-Date-and-Time-Functions.html#GTimeVal"><span class="type">GTimeVal</span></a>.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.8.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>time</p></td> +<td class="parameter_description"><p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Date-and-Time-Functions.html#GTimeVal"><span class="type">GTimeVal</span></a> structure in which to store the converted time. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-is-past"></a><h3>soup_date_is_past ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_date_is_past (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>);</pre> +<p>Determines if <em class="parameter"><code>date</code></em> + is in the past.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.9.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>date</code></em> +is in the past</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-get-day"></a><h3>soup_date_get_day ()</h3> +<pre class="programlisting"><span class="returnvalue">int</span> +soup_date_get_day (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>);</pre> +<p>Gets <em class="parameter"><code>date</code></em> +'s day.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.10.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>date</code></em> +'s day</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-get-hour"></a><h3>soup_date_get_hour ()</h3> +<pre class="programlisting"><span class="returnvalue">int</span> +soup_date_get_hour (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>);</pre> +<p>Gets <em class="parameter"><code>date</code></em> +'s hour.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.11.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.11.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>date</code></em> +'s hour</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-get-minute"></a><h3>soup_date_get_minute ()</h3> +<pre class="programlisting"><span class="returnvalue">int</span> +soup_date_get_minute (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>);</pre> +<p>Gets <em class="parameter"><code>date</code></em> +'s minute.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.12.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.12.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>date</code></em> +'s minute</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-get-month"></a><h3>soup_date_get_month ()</h3> +<pre class="programlisting"><span class="returnvalue">int</span> +soup_date_get_month (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>);</pre> +<p>Gets <em class="parameter"><code>date</code></em> +'s month.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.13.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.13.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>date</code></em> +'s month</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-get-offset"></a><h3>soup_date_get_offset ()</h3> +<pre class="programlisting"><span class="returnvalue">int</span> +soup_date_get_offset (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>);</pre> +<p>Gets <em class="parameter"><code>date</code></em> +'s offset from UTC.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.14.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.14.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>date</code></em> +'s offset from UTC. If <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-utc" title="soup_date_get_utc ()"><code class="function">soup_date_get_utc()</code></a> +returns <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> but <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-offset" title="soup_date_get_offset ()"><code class="function">soup_date_get_offset()</code></a> returns 0, that means the +date is a "floating" time with no associated offset information.</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-get-second"></a><h3>soup_date_get_second ()</h3> +<pre class="programlisting"><span class="returnvalue">int</span> +soup_date_get_second (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>);</pre> +<p>Gets <em class="parameter"><code>date</code></em> +'s second.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.15.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.15.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>date</code></em> +'s second</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-get-utc"></a><h3>soup_date_get_utc ()</h3> +<pre class="programlisting"><span class="returnvalue">int</span> +soup_date_get_utc (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>);</pre> +<p>Gets <em class="parameter"><code>date</code></em> +'s UTC flag</p> +<div class="refsect3"> +<a name="id-1.3.12.9.16.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.16.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>date</code></em> +is UTC.</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-get-year"></a><h3>soup_date_get_year ()</h3> +<pre class="programlisting"><span class="returnvalue">int</span> +soup_date_get_year (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>);</pre> +<p>Gets <em class="parameter"><code>date</code></em> +'s year.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.17.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.17.6"></a><h4>Returns</h4> +<p> <em class="parameter"><code>date</code></em> +'s year</p> +<p></p> +</div> +<p class="since">Since 2.32</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-date-free"></a><h3>soup_date_free ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_date_free (<em class="parameter"><code><a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> *date</code></em>);</pre> +<p>Frees <em class="parameter"><code>date</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.18.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>date</p></td> +<td class="parameter_description"><p>a <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-headers-parse-request"></a><h3>soup_headers_parse_request ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_headers_parse_request (<em class="parameter"><code>const <span class="type">char</span> *str</code></em>, + <em class="parameter"><code><span class="type">int</span> len</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *req_headers</code></em>, + <em class="parameter"><code><span class="type">char</span> **req_method</code></em>, + <em class="parameter"><code><span class="type">char</span> **req_path</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html#SoupHTTPVersion" title="enum SoupHTTPVersion"><span class="type">SoupHTTPVersion</span></a> *ver</code></em>);</pre> +<p>Parses the headers of an HTTP request in <em class="parameter"><code>str</code></em> + and stores the +results in <em class="parameter"><code>req_method</code></em> +, <em class="parameter"><code>req_path</code></em> +, <em class="parameter"><code>ver</code></em> +, and <em class="parameter"><code>req_headers</code></em> +.</p> +<p>Beware that <em class="parameter"><code>req_headers</code></em> + may be modified even on failure.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.19.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>str</p></td> +<td class="parameter_description"><p>the headers (up to, but not including, the trailing blank line)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>len</p></td> +<td class="parameter_description"><p>length of <em class="parameter"><code>str</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>req_headers</p></td> +<td class="parameter_description"><p><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> to store the header values in</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>req_method</p></td> +<td class="parameter_description"><p> if non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, will be filled in with the +request method. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>req_path</p></td> +<td class="parameter_description"><p> if non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, will be filled in with the +request path. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>ver</p></td> +<td class="parameter_description"><p> if non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, will be filled in with the HTTP +version. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.19.7"></a><h4>Returns</h4> +<p> <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-OK:CAPS"><code class="literal">SOUP_STATUS_OK</code></a> if the headers could be parsed, or an +HTTP error to be returned to the client if they could not be.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-headers-parse-response"></a><h3>soup_headers_parse_response ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_headers_parse_response (<em class="parameter"><code>const <span class="type">char</span> *str</code></em>, + <em class="parameter"><code><span class="type">int</span> len</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *headers</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html#SoupHTTPVersion" title="enum SoupHTTPVersion"><span class="type">SoupHTTPVersion</span></a> *ver</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> *status_code</code></em>, + <em class="parameter"><code><span class="type">char</span> **reason_phrase</code></em>);</pre> +<p>Parses the headers of an HTTP response in <em class="parameter"><code>str</code></em> + and stores the +results in <em class="parameter"><code>ver</code></em> +, <em class="parameter"><code>status_code</code></em> +, <em class="parameter"><code>reason_phrase</code></em> +, and <em class="parameter"><code>headers</code></em> +.</p> +<p>Beware that <em class="parameter"><code>headers</code></em> + may be modified even on failure.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.20.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>str</p></td> +<td class="parameter_description"><p>the headers (up to, but not including, the trailing blank line)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>len</p></td> +<td class="parameter_description"><p>length of <em class="parameter"><code>str</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>headers</p></td> +<td class="parameter_description"><p><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> to store the header values in</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>ver</p></td> +<td class="parameter_description"><p> if non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, will be filled in with the HTTP +version. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>status_code</p></td> +<td class="parameter_description"><p> if non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, will be filled in with +the status code. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>reason_phrase</p></td> +<td class="parameter_description"><p> if non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, will be filled in with +the reason phrase. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.20.7"></a><h4>Returns</h4> +<p> success or failure.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-headers-parse-status-line"></a><h3>soup_headers_parse_status_line ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_headers_parse_status_line (<em class="parameter"><code>const <span class="type">char</span> *status_line</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessage.html#SoupHTTPVersion" title="enum SoupHTTPVersion"><span class="type">SoupHTTPVersion</span></a> *ver</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> *status_code</code></em>, + <em class="parameter"><code><span class="type">char</span> **reason_phrase</code></em>);</pre> +<p>Parses the HTTP Status-Line string in <em class="parameter"><code>status_line</code></em> + into <em class="parameter"><code>ver</code></em> +, +<em class="parameter"><code>status_code</code></em> +, and <em class="parameter"><code>reason_phrase</code></em> +. <em class="parameter"><code>status_line</code></em> + must be terminated by +either "\0" or "\r\n".</p> +<div class="refsect3"> +<a name="id-1.3.12.9.21.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>status_line</p></td> +<td class="parameter_description"><p>an HTTP Status-Line</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>ver</p></td> +<td class="parameter_description"><p> if non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, will be filled in with the HTTP +version. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>status_code</p></td> +<td class="parameter_description"><p> if non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, will be filled in with +the status code. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>reason_phrase</p></td> +<td class="parameter_description"><p> if non-<a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, will be filled in with +the reason phrase. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.21.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if <em class="parameter"><code>status_line</code></em> +was parsed successfully.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-headers-parse"></a><h3>soup_headers_parse ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_headers_parse (<em class="parameter"><code>const <span class="type">char</span> *str</code></em>, + <em class="parameter"><code><span class="type">int</span> len</code></em>, + <em class="parameter"><code><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> *dest</code></em>);</pre> +<p>Parses the headers of an HTTP request or response in <em class="parameter"><code>str</code></em> + and +stores the results in <em class="parameter"><code>dest</code></em> +. Beware that <em class="parameter"><code>dest</code></em> + may be modified even +on failure.</p> +<p>This is a low-level method; normally you would use +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-request" title="soup_headers_parse_request ()"><code class="function">soup_headers_parse_request()</code></a> or <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-response" title="soup_headers_parse_response ()"><code class="function">soup_headers_parse_response()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.22.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>str</p></td> +<td class="parameter_description"><p>the header string (including the Request-Line or Status-Line, +but not the trailing blank line)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>len</p></td> +<td class="parameter_description"><p>length of <em class="parameter"><code>str</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>dest</p></td> +<td class="parameter_description"><p><a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> to store the header values in</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.22.7"></a><h4>Returns</h4> +<p> success or failure</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-header-parse-list"></a><h3>soup_header_parse_list ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +soup_header_parse_list (<em class="parameter"><code>const <span class="type">char</span> *header</code></em>);</pre> +<p>Parses a header whose content is described by RFC2616 as +"<span class="type">something</span>", where "something" does not itself contain commas, +except as part of quoted-strings.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.23.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>header</p></td> +<td class="parameter_description"><p>a header value</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.23.6"></a><h4>Returns</h4> +<p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> of +list elements, as allocated strings. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-header-parse-quality-list"></a><h3>soup_header_parse_quality_list ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="returnvalue">GSList</span></a> * +soup_header_parse_quality_list (<em class="parameter"><code>const <span class="type">char</span> *header</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> **unacceptable</code></em>);</pre> +<p>Parses a header whose content is a list of items with optional +"qvalue"s (eg, Accept, Accept-Charset, Accept-Encoding, +Accept-Language, TE).</p> +<p>If <em class="parameter"><code>unacceptable</code></em> + is not <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, then on return, it will contain the +items with qvalue 0. Either way, those items will be removed from +the main list.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.24.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>header</p></td> +<td class="parameter_description"><p>a header value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>unacceptable</p></td> +<td class="parameter_description"><p> on +return, will contain a list of unacceptable values. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.24.7"></a><h4>Returns</h4> +<p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> of +acceptable values (as allocated strings), highest-qvalue first. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-header-free-list"></a><h3>soup_header_free_list ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_header_free_list (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> *list</code></em>);</pre> +<p>Frees <em class="parameter"><code>list</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.25.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>list</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/glib/unstable/glib-Singly-Linked-Lists.html#GSList"><span class="type">GSList</span></a> returned from <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-list" title="soup_header_parse_list ()"><code class="function">soup_header_parse_list()</code></a> or +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-quality-list" title="soup_header_parse_quality_list ()"><code class="function">soup_header_parse_quality_list()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-header-contains"></a><h3>soup_header_contains ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_header_contains (<em class="parameter"><code>const <span class="type">char</span> *header</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *token</code></em>);</pre> +<p>Parses <em class="parameter"><code>header</code></em> + to see if it contains the token <em class="parameter"><code>token</code></em> + (matched +case-insensitively). Note that this can't be used with lists +that have qvalues.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.26.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>header</p></td> +<td class="parameter_description"><p>An HTTP header suitable for parsing with +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-list" title="soup_header_parse_list ()"><code class="function">soup_header_parse_list()</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>token</p></td> +<td class="parameter_description"><p>a token</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.26.6"></a><h4>Returns</h4> +<p> whether or not <em class="parameter"><code>header</code></em> +contains <em class="parameter"><code>token</code></em> +</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-header-parse-param-list"></a><h3>soup_header_parse_param_list ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +soup_header_parse_param_list (<em class="parameter"><code>const <span class="type">char</span> *header</code></em>);</pre> +<p>Parses a header which is a comma-delimited list of something like: +<code class="literal">token [ "=" ( token | quoted-string ) ]</code>.</p> +<p>Tokens that don't have an associated value will still be added to +the resulting hash table, but with a <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> value.</p> +<p>This also handles RFC5987 encoding (which in HTTP is mostly used +for giving UTF8-encoded filenames in the Content-Disposition +header).</p> +<div class="refsect3"> +<a name="id-1.3.12.9.27.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>header</p></td> +<td class="parameter_description"><p>a header value</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.27.8"></a><h4>Returns</h4> +<p> a +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> of list elements, which can be freed with +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-free-param-list" title="soup_header_free_param_list ()"><code class="function">soup_header_free_param_list()</code></a>. </p> +<p><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-header-parse-semi-param-list"></a><h3>soup_header_parse_semi_param_list ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="returnvalue">GHashTable</span></a> * +soup_header_parse_semi_param_list (<em class="parameter"><code>const <span class="type">char</span> *header</code></em>);</pre> +<p>Parses a header which is a semicolon-delimited list of something +like: <code class="literal">token [ "=" ( token | quoted-string ) ]</code>.</p> +<p>Tokens that don't have an associated value will still be added to +the resulting hash table, but with a <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> value.</p> +<p>This also handles RFC5987 encoding (which in HTTP is mostly used +for giving UTF8-encoded filenames in the Content-Disposition +header).</p> +<div class="refsect3"> +<a name="id-1.3.12.9.28.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>header</p></td> +<td class="parameter_description"><p>a header value</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.28.8"></a><h4>Returns</h4> +<p> a +<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> of list elements, which can be freed with +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-free-param-list" title="soup_header_free_param_list ()"><code class="function">soup_header_free_param_list()</code></a>. </p> +<p><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8][<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-header-free-param-list"></a><h3>soup_header_free_param_list ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_header_free_param_list (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> *param_list</code></em>);</pre> +<p>Frees <em class="parameter"><code>param_list</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.29.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>param_list</p></td> +<td class="parameter_description"><p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> returned from <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-param-list" title="soup_header_parse_param_list ()"><code class="function">soup_header_parse_param_list()</code></a> +or <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-semi-param-list" title="soup_header_parse_semi_param_list ()"><code class="function">soup_header_parse_semi_param_list()</code></a>. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 utf8]</span></td> +</tr></tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-header-g-string-append-param"></a><h3>soup_header_g_string_append_param ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_header_g_string_append_param (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Strings.html#GString"><span class="type">GString</span></a> *string</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *name</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *value</code></em>);</pre> +<p>Appends something like <code class="literal"><em class="parameter"><code>name</code></em> +=<em class="parameter"><code>value</code></em> +</code> to <em class="parameter"><code>string</code></em> +, +taking care to quote <em class="parameter"><code>value</code></em> + if needed, and if so, to escape any +quotes or backslashes in <em class="parameter"><code>value</code></em> +.</p> +<p>Alternatively, if <em class="parameter"><code>value</code></em> + is a non-ASCII UTF-8 string, it will be +appended using RFC5987 syntax. Although in theory this is supposed +to work anywhere in HTTP that uses this style of parameter, in +reality, it can only be used portably with the Content-Disposition +"filename" parameter.</p> +<p>If <em class="parameter"><code>value</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, this will just append <em class="parameter"><code>name</code></em> + to <em class="parameter"><code>string</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.30.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>string</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/glib/unstable/glib-Strings.html#GString"><span class="type">GString</span></a> being used to construct an HTTP header value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>a parameter name</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>value</p></td> +<td class="parameter_description"><p>a parameter value, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a></p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.26</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-header-g-string-append-param-quoted"></a><h3>soup_header_g_string_append_param_quoted ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_header_g_string_append_param_quoted + (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Strings.html#GString"><span class="type">GString</span></a> *string</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *name</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *value</code></em>);</pre> +<p>Appends something like <code class="literal"><em class="parameter"><code>name</code></em> +="<em class="parameter"><code>value</code></em> +"</code> to +<em class="parameter"><code>string</code></em> +, taking care to escape any quotes or backslashes in <em class="parameter"><code>value</code></em> +.</p> +<p>If <em class="parameter"><code>value</code></em> + is (non-ASCII) UTF-8, this will instead use RFC 5987 +encoding, just like <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-g-string-append-param" title="soup_header_g_string_append_param ()"><code class="function">soup_header_g_string_append_param()</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.31.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>string</p></td> +<td class="parameter_description"><p>a <a href="http://library.gnome.org/devel/glib/unstable/glib-Strings.html#GString"><span class="type">GString</span></a> being used to construct an HTTP header value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>name</p></td> +<td class="parameter_description"><p>a parameter name</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>value</p></td> +<td class="parameter_description"><p>a parameter value</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.30</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-str-case-equal"></a><h3>soup_str_case_equal ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_str_case_equal (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> v1</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> v2</code></em>);</pre> +<p>Compares <em class="parameter"><code>v1</code></em> + and <em class="parameter"><code>v2</code></em> + in a case-insensitive manner</p> +<div class="refsect3"> +<a name="id-1.3.12.9.32.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>v1</p></td> +<td class="parameter_description"><p>an ASCII string</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>v2</p></td> +<td class="parameter_description"><p>another ASCII string</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.32.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if they are equal (modulo case)</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-str-case-hash"></a><h3>soup_str_case_hash ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_str_case_hash (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gconstpointer"><span class="type">gconstpointer</span></a> key</code></em>);</pre> +<p>Hashes <em class="parameter"><code>key</code></em> + in a case-insensitive manner.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.33.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>key</p></td> +<td class="parameter_description"><p>ASCII string to hash</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.33.6"></a><h4>Returns</h4> +<p> the hash code.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-add-completion"></a><h3>soup_add_completion ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> * +soup_add_completion (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> *async_context</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> function</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre> +<p>Adds <em class="parameter"><code>function</code></em> + to be executed from inside <em class="parameter"><code>async_context</code></em> + with the +default priority. Use this when you want to complete an action in +<em class="parameter"><code>async_context</code></em> +'s main loop, as soon as possible.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.34.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>async_context</p></td> +<td class="parameter_description"><p> the <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> to dispatch the I/O +watch in, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> for the default context. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>function</p></td> +<td class="parameter_description"><p>the callback to invoke</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p>user data to pass to <em class="parameter"><code>function</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.34.6"></a><h4>Returns</h4> +<p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a>, which can be removed from <em class="parameter"><code>async_context</code></em> +with <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-source-destroy"><code class="function">g_source_destroy()</code></a>.</p> +<p></p> +</div> +<p class="since">Since 2.24</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-add-idle"></a><h3>soup_add_idle ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> * +soup_add_idle (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> *async_context</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> function</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre> +<p>Adds an idle event as with <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-idle-add"><code class="function">g_idle_add()</code></a>, but using the given +<em class="parameter"><code>async_context</code></em> +.</p> +<p>If you want <em class="parameter"><code>function</code></em> + to run "right away", use +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-completion" title="soup_add_completion ()"><code class="function">soup_add_completion()</code></a>, since that sets a higher priority on the +<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a> than <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-idle" title="soup_add_idle ()"><code class="function">soup_add_idle()</code></a> does.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.35.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>async_context</p></td> +<td class="parameter_description"><p> the <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> to dispatch the I/O +watch in, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> for the default context. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>function</p></td> +<td class="parameter_description"><p>the callback to invoke at idle time</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p>user data to pass to <em class="parameter"><code>function</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.35.7"></a><h4>Returns</h4> +<p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a>, which can be removed from <em class="parameter"><code>async_context</code></em> +with <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-source-destroy"><code class="function">g_source_destroy()</code></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-add-io-watch"></a><h3>soup_add_io_watch ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> * +soup_add_io_watch (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> *async_context</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-IO-Channels.html#GIOChannel"><span class="type">GIOChannel</span></a> *chan</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-IO-Channels.html#GIOCondition"><span class="type">GIOCondition</span></a> condition</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-IO-Channels.html#GIOFunc"><span class="type">GIOFunc</span></a> function</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre> +<p>Adds an I/O watch as with <a href="http://library.gnome.org/devel/glib/unstable/glib-IO-Channels.html#g-io-add-watch"><code class="function">g_io_add_watch()</code></a>, but using the given +<em class="parameter"><code>async_context</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.36.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>async_context</p></td> +<td class="parameter_description"><p> the <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> to dispatch the I/O +watch in, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> for the default context. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>chan</p></td> +<td class="parameter_description"><p>the <a href="http://library.gnome.org/devel/glib/unstable/glib-IO-Channels.html#GIOChannel"><span class="type">GIOChannel</span></a> to watch</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>condition</p></td> +<td class="parameter_description"><p>the condition to watch for</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>function</p></td> +<td class="parameter_description"><p>the callback to invoke when <em class="parameter"><code>condition</code></em> +occurs</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p>user data to pass to <em class="parameter"><code>function</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.36.6"></a><h4>Returns</h4> +<p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a>, which can be removed from <em class="parameter"><code>async_context</code></em> +with <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-source-destroy"><code class="function">g_source_destroy()</code></a>.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-add-timeout"></a><h3>soup_add_timeout ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="returnvalue">GSource</span></a> * +soup_add_timeout (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> *async_context</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> interval</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSourceFunc"><span class="type">GSourceFunc</span></a> function</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre> +<p>Adds a timeout as with <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-timeout-add"><code class="function">g_timeout_add()</code></a>, but using the given +<em class="parameter"><code>async_context</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.3.12.9.37.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>async_context</p></td> +<td class="parameter_description"><p> the <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> to dispatch the I/O +watch in, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> for the default context. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>interval</p></td> +<td class="parameter_description"><p>the timeout interval, in milliseconds</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>function</p></td> +<td class="parameter_description"><p>the callback to invoke at timeout time</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>data</p></td> +<td class="parameter_description"><p>user data to pass to <em class="parameter"><code>function</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.12.9.37.6"></a><h4>Returns</h4> +<p> a <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GSource"><span class="type">GSource</span></a>, which can be removed from <em class="parameter"><code>async_context</code></em> +with <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-source-destroy"><code class="function">g_source_destroy()</code></a>.</p> +<p></p> +</div> +</div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Soup-Miscellaneous-Utilities.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupDate-struct"></a><h3>SoupDate</h3> +<pre class="programlisting">typedef struct { + int year; + int month; + int day; + + int hour; + int minute; + int second; + + gboolean utc; + int offset; +} SoupDate; +</pre> +<p>A date and time. The date is assumed to be in the (proleptic) +Gregorian calendar. The time is in UTC if <em class="parameter"><code>utc</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>. Otherwise, +the time is a local time, and <em class="parameter"><code>offset</code></em> + gives the offset from UTC in +minutes (such that adding <em class="parameter"><code>offset</code></em> + to the time would give the +correct UTC time). If <em class="parameter"><code>utc</code></em> + is <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> and <em class="parameter"><code>offset</code></em> + is 0, then the +<a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><code class="literal">SoupDate</code></a> represents a "floating" time with no associated timezone +information.</p> +<div class="refsect3"> +<a name="id-1.3.12.10.2.5"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="struct_members_name"> +<col class="struct_members_description"> +<col width="200px" class="struct_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="struct_member_name"><p><span class="type">int</span> <em class="structfield"><code><a name="SoupDate-struct.year"></a>year</code></em>;</p></td> +<td class="struct_member_description"><p>the year, 1 to 9999</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">int</span> <em class="structfield"><code><a name="SoupDate-struct.month"></a>month</code></em>;</p></td> +<td class="struct_member_description"><p>the month, 1 to 12</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">int</span> <em class="structfield"><code><a name="SoupDate-struct.day"></a>day</code></em>;</p></td> +<td class="struct_member_description"><p>day of the month, 1 to 31</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">int</span> <em class="structfield"><code><a name="SoupDate-struct.hour"></a>hour</code></em>;</p></td> +<td class="struct_member_description"><p>hour of the day, 0 to 23</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">int</span> <em class="structfield"><code><a name="SoupDate-struct.minute"></a>minute</code></em>;</p></td> +<td class="struct_member_description"><p>minute, 0 to 59</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">int</span> <em class="structfield"><code><a name="SoupDate-struct.second"></a>second</code></em>;</p></td> +<td class="struct_member_description"><p>second, 0 to 59 (or up to 61 in the case of leap seconds)</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> <em class="structfield"><code><a name="SoupDate-struct.utc"></a>utc</code></em>;</p></td> +<td class="struct_member_description"><p><a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the date is in UTC</p></td> +<td class="struct_member_annotations"> </td> +</tr> +<tr> +<td class="struct_member_name"><p><span class="type">int</span> <em class="structfield"><code><a name="SoupDate-struct.offset"></a>offset</code></em>;</p></td> +<td class="struct_member_description"><p>offset from UTC</p></td> +<td class="struct_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SoupDateFormat"></a><h3>enum SoupDateFormat</h3> +<p>Date formats that <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-string" title="soup_date_to_string ()"><code class="function">soup_date_to_string()</code></a> can use.</p> +<p><em class="parameter"><code>SOUP_DATE_HTTP</code></em> + and <em class="parameter"><code>SOUP_DATE_COOKIE</code></em> + always coerce the time to +UTC. <em class="parameter"><code>SOUP_DATE_ISO8601_XMLRPC</code></em> + uses the time as given, ignoring the +offset completely. <em class="parameter"><code>SOUP_DATE_RFC2822</code></em> + and the other ISO 8601 +variants use the local time, appending the offset information if +available.</p> +<p>This enum may be extended with more values in future releases.</p> +<div class="refsect3"> +<a name="id-1.3.12.10.3.6"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-DATE-HTTP:CAPS"></a>SOUP_DATE_HTTP</p></td> +<td class="enum_member_description"> +<p>RFC 1123 format, used by the HTTP "Date" header. Eg +"Sun, 06 Nov 1994 08:49:37 GMT"</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-DATE-COOKIE:CAPS"></a>SOUP_DATE_COOKIE</p></td> +<td class="enum_member_description"> +<p>The format for the "Expires" timestamp in the +Netscape cookie specification. Eg, "Sun, 06-Nov-1994 08:49:37 GMT".</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-DATE-RFC2822:CAPS"></a>SOUP_DATE_RFC2822</p></td> +<td class="enum_member_description"> +<p>RFC 2822 format, eg "Sun, 6 Nov 1994 09:49:37 -0100"</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-DATE-ISO8601-COMPACT:CAPS"></a>SOUP_DATE_ISO8601_COMPACT</p></td> +<td class="enum_member_description"> +<p>ISO 8601 date/time with no optional +punctuation. Eg, "19941106T094937-0100".</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-DATE-ISO8601-FULL:CAPS"></a>SOUP_DATE_ISO8601_FULL</p></td> +<td class="enum_member_description"> +<p>ISO 8601 date/time with all optional +punctuation. Eg, "1994-11-06T09:49:37-01:00".</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-DATE-ISO8601:CAPS"></a>SOUP_DATE_ISO8601</p></td> +<td class="enum_member_description"> +<p>An alias for <em class="parameter"><code>SOUP_DATE_ISO8601_FULL</code></em> +.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-DATE-ISO8601-XMLRPC:CAPS"></a>SOUP_DATE_ISO8601_XMLRPC</p></td> +<td class="enum_member_description"> +<p>ISO 8601 date/time as used by XML-RPC. +Eg, "19941106T09:49:37".</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-2.4-Top-Level-Domain-utils.html b/docs/reference/html/libsoup-2.4-Top-Level-Domain-utils.html new file mode 100644 index 00000000..2d9cc67d --- /dev/null +++ b/docs/reference/html/libsoup-2.4-Top-Level-Domain-utils.html @@ -0,0 +1,252 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Top Level Domain utils</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="libsoup-2.4-soup-status.html" title="soup-status"> +<link rel="next" href="SoupURI.html" title="SoupURI"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#libsoup-2.4-Top-Level-Domain-utils.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#libsoup-2.4-Top-Level-Domain-utils.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="libsoup-2.4-soup-status.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="SoupURI.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-2.4-Top-Level-Domain-utils"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="libsoup-2.4-Top-Level-Domain-utils.top_of_page"></a>Top Level Domain utils</span></h2> +<p>Top Level Domain utils — Top-Level Domain Utilities</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="libsoup-2.4-Top-Level-Domain-utils.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Top-Level-Domain-utils.html#soup-tld-get-base-domain" title="soup_tld_get_base_domain ()">soup_tld_get_base_domain</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Top-Level-Domain-utils.html#soup-tld-domain-is-public-suffix" title="soup_tld_domain_is_public_suffix ()">soup_tld_domain_is_public_suffix</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Top-Level-Domain-utils.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Top-Level-Domain-utils.html#SOUP-TLD-ERROR:CAPS" title="SOUP_TLD_ERROR">SOUP_TLD_ERROR</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Top-Level-Domain-utils.html#SoupTLDError" title="enum SoupTLDError">SoupTLDError</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Top-Level-Domain-utils.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Top-Level-Domain-utils.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Top-Level-Domain-utils.description"></a><h2>Description</h2> +<p>These functions can be used to parse hostnames to attempt to determine +what part of the name belongs to the domain owner, and what part is +simply a "public suffix" such as ".com".</p> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Top-Level-Domain-utils.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-tld-get-base-domain"></a><h3>soup_tld_get_base_domain ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_tld_get_base_domain (<em class="parameter"><code>const <span class="type">char</span> *hostname</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Finds the base domain for a given <em class="parameter"><code>hostname</code></em> +. The base domain is +composed by the top level domain (such as .org, .com, .co.uk, etc) +plus the second level domain, for example for myhost.mydomain.com +it will return mydomain.com.</p> +<p>Note that <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> will be returned for private URLs (those not ending +with any well known TLD) because choosing a base domain for them +would be totally arbitrary.</p> +<p>Prior to libsoup 2.46, this function required that <em class="parameter"><code>hostname</code></em> + be in +UTF-8 if it was an IDN. From 2.46 on, the name can be in either +UTF-8 or ASCII format (and the return value will be in the same +format).</p> +<div class="refsect3"> +<a name="id-1.3.24.8.2.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>hostname</p></td> +<td class="parameter_description"><p>a hostname</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>return location for a <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a>, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore +errors. See <a class="link" href="libsoup-2.4-Top-Level-Domain-utils.html#SoupTLDError" title="enum SoupTLDError"><span class="type">SoupTLDError</span></a> for the available error codes</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.24.8.2.8"></a><h4>Returns</h4> +<p> a pointer to the start of the base domain in <em class="parameter"><code>hostname</code></em> +. If +an error occurs, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> will be returned and <em class="parameter"><code>error</code></em> +set.</p> +<p></p> +</div> +<p class="since">Since 2.40</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-tld-domain-is-public-suffix"></a><h3>soup_tld_domain_is_public_suffix ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_tld_domain_is_public_suffix (<em class="parameter"><code>const <span class="type">char</span> *domain</code></em>);</pre> +<p>Looks whether the <em class="parameter"><code>domain</code></em> + passed as argument is a public domain +suffix (.org, .com, .co.uk, etc) or not.</p> +<p>Prior to libsoup 2.46, this function required that <em class="parameter"><code>domain</code></em> + be in +UTF-8 if it was an IDN. From 2.46 on, the name can be in either +UTF-8 or ASCII format (and the return value will be in the same +format).</p> +<div class="refsect3"> +<a name="id-1.3.24.8.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>domain</p></td> +<td class="parameter_description"><p>a domain name</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.24.8.3.7"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if it is a public domain, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> otherwise.</p> +<p></p> +</div> +<p class="since">Since 2.40</p> +</div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Top-Level-Domain-utils.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SOUP-TLD-ERROR:CAPS"></a><h3>SOUP_TLD_ERROR</h3> +<pre class="programlisting">#define SOUP_TLD_ERROR soup_tld_error_quark() +</pre> +<p>The <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> domain for soup-tld-related errors.</p> +<p class="since">Since 2.40</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupTLDError"></a><h3>enum SoupTLDError</h3> +<p>Error codes for <a class="link" href="libsoup-2.4-Top-Level-Domain-utils.html#SOUP-TLD-ERROR:CAPS" title="SOUP_TLD_ERROR"><code class="literal">SOUP_TLD_ERROR</code></a>.</p> +<div class="refsect3"> +<a name="id-1.3.24.9.3.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-TLD-ERROR-INVALID-HOSTNAME:CAPS"></a>SOUP_TLD_ERROR_INVALID_HOSTNAME</p></td> +<td class="enum_member_description"> +<p>A hostname was syntactically + invalid.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-TLD-ERROR-IS-IP-ADDRESS:CAPS"></a>SOUP_TLD_ERROR_IS_IP_ADDRESS</p></td> +<td class="enum_member_description"> +<p>The passed-in "hostname" was + actually an IP address (and thus has no base domain or + public suffix).</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-TLD-ERROR-NOT-ENOUGH-DOMAINS:CAPS"></a>SOUP_TLD_ERROR_NOT_ENOUGH_DOMAINS</p></td> +<td class="enum_member_description"> +<p>The passed-in hostname + did not have enough components. Eg, calling + <a class="link" href="libsoup-2.4-Top-Level-Domain-utils.html#soup-tld-get-base-domain" title="soup_tld_get_base_domain ()"><code class="function">soup_tld_get_base_domain()</code></a> on <code class="literal">"co.uk"</code>.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-TLD-ERROR-NO-BASE-DOMAIN:CAPS"></a>SOUP_TLD_ERROR_NO_BASE_DOMAIN</p></td> +<td class="enum_member_description"> +<p>The passed-in hostname has + no recognized public suffix.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<p class="since">Since 2.40</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-2.4-Version-Information.html b/docs/reference/html/libsoup-2.4-Version-Information.html new file mode 100644 index 00000000..bf917497 --- /dev/null +++ b/docs/reference/html/libsoup-2.4-Version-Information.html @@ -0,0 +1,499 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Version Information</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupURI.html" title="SoupURI"> +<link rel="next" href="ch03.html" title="Additional Features"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#libsoup-2.4-Version-Information.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#libsoup-2.4-Version-Information.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupURI.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="ch03.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-2.4-Version-Information"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="libsoup-2.4-Version-Information.top_of_page"></a>Version Information</span></h2> +<p>Version Information — Variables and functions to check the libsoup version</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="libsoup-2.4-Version-Information.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Version-Information.html#soup-get-major-version" title="soup_get_major_version ()">soup_get_major_version</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Version-Information.html#soup-get-minor-version" title="soup_get_minor_version ()">soup_get_minor_version</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Version-Information.html#soup-get-micro-version" title="soup_get_micro_version ()">soup_get_micro_version</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Version-Information.html#soup-check-version" title="soup_check_version ()">soup_check_version</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-MAJOR-VERSION:CAPS" title="SOUP_MAJOR_VERSION">SOUP_MAJOR_VERSION</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-MINOR-VERSION:CAPS" title="SOUP_MINOR_VERSION">SOUP_MINOR_VERSION</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-MICRO-VERSION:CAPS" title="SOUP_MICRO_VERSION">SOUP_MICRO_VERSION</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-CHECK-VERSION:CAPS" title="SOUP_CHECK_VERSION()">SOUP_CHECK_VERSION</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED">SOUP_VERSION_MIN_REQUIRED</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED">SOUP_VERSION_MAX_ALLOWED</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-24:CAPS" title="SOUP_VERSION_2_24">SOUP_VERSION_2_24</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-26:CAPS" title="SOUP_VERSION_2_26">SOUP_VERSION_2_26</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-28:CAPS" title="SOUP_VERSION_2_28">SOUP_VERSION_2_28</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-30:CAPS" title="SOUP_VERSION_2_30">SOUP_VERSION_2_30</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-32:CAPS" title="SOUP_VERSION_2_32">SOUP_VERSION_2_32</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-34:CAPS" title="SOUP_VERSION_2_34">SOUP_VERSION_2_34</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-36:CAPS" title="SOUP_VERSION_2_36">SOUP_VERSION_2_36</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-38:CAPS" title="SOUP_VERSION_2_38">SOUP_VERSION_2_38</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-40:CAPS" title="SOUP_VERSION_2_40">SOUP_VERSION_2_40</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-42:CAPS" title="SOUP_VERSION_2_42">SOUP_VERSION_2_42</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-44:CAPS" title="SOUP_VERSION_2_44">SOUP_VERSION_2_44</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-46:CAPS" title="SOUP_VERSION_2_46">SOUP_VERSION_2_46</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Version-Information.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Version-Information.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Version-Information.description"></a><h2>Description</h2> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Version-Information.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-get-major-version"></a><h3>soup_get_major_version ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_get_major_version (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<p>Returns the major version number of the libsoup library. +(e.g. in libsoup version 2.42.0 this is 2.)</p> +<p>This function is in the library, so it represents the libsoup library +your code is running against. Contrast with the <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-MAJOR-VERSION:CAPS" title="SOUP_MAJOR_VERSION"><span class="type">SOUP_MAJOR_VERSION</span></a> +macro, which represents the major version of the libsoup headers you +have included when compiling your code.</p> +<div class="refsect3"> +<a name="id-1.3.26.7.2.6"></a><h4>Returns</h4> +<p> the major version number of the libsoup library</p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-get-minor-version"></a><h3>soup_get_minor_version ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_get_minor_version (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<p>Returns the minor version number of the libsoup library. +(e.g. in libsoup version 2.42.0 this is 42.)</p> +<p>This function is in the library, so it represents the libsoup library +your code is running against. Contrast with the <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-MINOR-VERSION:CAPS" title="SOUP_MINOR_VERSION"><span class="type">SOUP_MINOR_VERSION</span></a> +macro, which represents the minor version of the libsoup headers you +have included when compiling your code.</p> +<div class="refsect3"> +<a name="id-1.3.26.7.3.6"></a><h4>Returns</h4> +<p> the minor version number of the libsoup library</p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-get-micro-version"></a><h3>soup_get_micro_version ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_get_micro_version (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<p>Returns the micro version number of the libsoup library. +(e.g. in libsoup version 2.42.0 this is 0.)</p> +<p>This function is in the library, so it represents the libsoup library +your code is running against. Contrast with the <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-MICRO-VERSION:CAPS" title="SOUP_MICRO_VERSION"><span class="type">SOUP_MICRO_VERSION</span></a> +macro, which represents the micro version of the libsoup headers you +have included when compiling your code.</p> +<div class="refsect3"> +<a name="id-1.3.26.7.4.6"></a><h4>Returns</h4> +<p> the micro version number of the libsoup library</p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="soup-check-version"></a><h3>soup_check_version ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_check_version (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> major</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> minor</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> micro</code></em>);</pre> +<p>Like SOUP_CHECK_VERSION, but the check for soup_check_version is +at runtime instead of compile time. This is useful for compiling +against older versions of libsoup, but using features from newer +versions.</p> +<div class="refsect3"> +<a name="id-1.3.26.7.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>major</p></td> +<td class="parameter_description"><p>the major version to check</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>minor</p></td> +<td class="parameter_description"><p>the minor version to check</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>micro</p></td> +<td class="parameter_description"><p>the micro version to check</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.26.7.5.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the version of the libsoup currently loaded +is the same as or newer than the passed-in version.</p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MAJOR-VERSION:CAPS"></a><h3>SOUP_MAJOR_VERSION</h3> +<pre class="programlisting">#define SOUP_MAJOR_VERSION (2) +</pre> +<p>Like <a class="link" href="libsoup-2.4-Version-Information.html#soup-get-major-version" title="soup_get_major_version ()"><code class="function">soup_get_major_version()</code></a>, but from the headers used at +application compile time, rather than from the library linked +against at application run time.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MINOR-VERSION:CAPS"></a><h3>SOUP_MINOR_VERSION</h3> +<pre class="programlisting">#define SOUP_MINOR_VERSION (45) +</pre> +<p>Like <a class="link" href="libsoup-2.4-Version-Information.html#soup-get-minor-version" title="soup_get_minor_version ()"><code class="function">soup_get_minor_version()</code></a>, but from the headers used at +application compile time, rather than from the library linked +against at application run time.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-MICRO-VERSION:CAPS"></a><h3>SOUP_MICRO_VERSION</h3> +<pre class="programlisting">#define SOUP_MICRO_VERSION (92) +</pre> +<p>Like <a class="link" href="libsoup-2.4-Version-Information.html#soup-get-micro-version" title="soup_get_micro_version ()"><code class="function">soup_get_micro_version()</code></a>, but from the headers used at +application compile time, rather than from the library linked +against at application run time.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-CHECK-VERSION:CAPS"></a><h3>SOUP_CHECK_VERSION()</h3> +<pre class="programlisting">#define SOUP_CHECK_VERSION(major, minor, micro)</pre> +<p>Macro to test the version of libsoup being compiled against.</p> +<div class="refsect3"> +<a name="id-1.3.26.7.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>major</p></td> +<td class="parameter_description"><p>major version (e.g. 2 for version 2.42.0)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>minor</p></td> +<td class="parameter_description"><p>minor version (e.g. 42 for version 2.42.0)</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>micro</p></td> +<td class="parameter_description"><p>micro version (e.g. 0 for version 2.42.0)</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.26.7.9.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if the version of the libsoup header files +is the same as or newer than the passed-in version.</p> +<p></p> +</div> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-MIN-REQUIRED:CAPS"></a><h3>SOUP_VERSION_MIN_REQUIRED</h3> +<pre class="programlisting"># define SOUP_VERSION_MIN_REQUIRED (SOUP_VERSION_CUR_STABLE) +</pre> +<p>A macro that should be defined by the user prior to including +libsoup.h. The definition should be one of the predefined libsoup +version macros: <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-24:CAPS" title="SOUP_VERSION_2_24"><code class="literal">SOUP_VERSION_2_24</code></a>, <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-26:CAPS" title="SOUP_VERSION_2_26"><code class="literal">SOUP_VERSION_2_26</code></a>, ...</p> +<p>This macro defines the earliest version of libsoup that the package +is required to be able to compile against.</p> +<p>If the compiler is configured to warn about the use of deprecated +functions, then using functions that were deprecated in version +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> or earlier will cause warnings (but +using functions deprecated in later releases will not).</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-MAX-ALLOWED:CAPS"></a><h3>SOUP_VERSION_MAX_ALLOWED</h3> +<pre class="programlisting"># define SOUP_VERSION_MAX_ALLOWED (SOUP_VERSION_CUR_STABLE) +</pre> +<p>A macro that should be defined by the user prior to including +libsoup.h. The definition should be one of the predefined libsoup +version macros: <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-24:CAPS" title="SOUP_VERSION_2_24"><code class="literal">SOUP_VERSION_2_24</code></a>, <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-26:CAPS" title="SOUP_VERSION_2_26"><code class="literal">SOUP_VERSION_2_26</code></a>, ...</p> +<p>This macro defines the latest version of the libsoup API that the +package is allowed to make use of.</p> +<p>If the compiler is configured to warn about the use of deprecated +functions, then using functions added after version +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a> will cause warnings.</p> +<p>Unless you are using <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-CHECK-VERSION:CAPS" title="SOUP_CHECK_VERSION()"><code class="function">SOUP_CHECK_VERSION()</code></a> or the like to compile +different code depending on the libsoup version, then this should be +set to the same value as <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-24:CAPS"></a><h3>SOUP_VERSION_2_24</h3> +<pre class="programlisting">#define SOUP_VERSION_2_24 (SOUP_ENCODE_VERSION (2, 24)) +</pre> +<p>A macro that evaluates to the 2.24 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-26:CAPS"></a><h3>SOUP_VERSION_2_26</h3> +<pre class="programlisting">#define SOUP_VERSION_2_26 (SOUP_ENCODE_VERSION (2, 26)) +</pre> +<p>A macro that evaluates to the 2.26 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-28:CAPS"></a><h3>SOUP_VERSION_2_28</h3> +<pre class="programlisting">#define SOUP_VERSION_2_28 (SOUP_ENCODE_VERSION (2, 28)) +</pre> +<p>A macro that evaluates to the 2.28 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-30:CAPS"></a><h3>SOUP_VERSION_2_30</h3> +<pre class="programlisting">#define SOUP_VERSION_2_30 (SOUP_ENCODE_VERSION (2, 30)) +</pre> +<p>A macro that evaluates to the 2.30 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-32:CAPS"></a><h3>SOUP_VERSION_2_32</h3> +<pre class="programlisting">#define SOUP_VERSION_2_32 (SOUP_ENCODE_VERSION (2, 32)) +</pre> +<p>A macro that evaluates to the 2.32 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-34:CAPS"></a><h3>SOUP_VERSION_2_34</h3> +<pre class="programlisting">#define SOUP_VERSION_2_34 (SOUP_ENCODE_VERSION (2, 34)) +</pre> +<p>A macro that evaluates to the 2.34 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-36:CAPS"></a><h3>SOUP_VERSION_2_36</h3> +<pre class="programlisting">#define SOUP_VERSION_2_36 (SOUP_ENCODE_VERSION (2, 36)) +</pre> +<p>A macro that evaluates to the 2.36 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-38:CAPS"></a><h3>SOUP_VERSION_2_38</h3> +<pre class="programlisting">#define SOUP_VERSION_2_38 (SOUP_ENCODE_VERSION (2, 38)) +</pre> +<p>A macro that evaluates to the 2.38 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-40:CAPS"></a><h3>SOUP_VERSION_2_40</h3> +<pre class="programlisting">#define SOUP_VERSION_2_40 (SOUP_ENCODE_VERSION (2, 40)) +</pre> +<p>A macro that evaluates to the 2.40 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-42:CAPS"></a><h3>SOUP_VERSION_2_42</h3> +<pre class="programlisting">#define SOUP_VERSION_2_42 (SOUP_ENCODE_VERSION (2, 42)) +</pre> +<p>A macro that evaluates to the 2.42 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.42</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-44:CAPS"></a><h3>SOUP_VERSION_2_44</h3> +<pre class="programlisting">#define SOUP_VERSION_2_44 (SOUP_ENCODE_VERSION (2, 44)) +</pre> +<p>A macro that evaluates to the 2.44 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.44</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-VERSION-2-46:CAPS"></a><h3>SOUP_VERSION_2_46</h3> +<pre class="programlisting">#define SOUP_VERSION_2_46 (SOUP_ENCODE_VERSION (2, 46)) +</pre> +<p>A macro that evaluates to the 2.46 version of libsoup, in a format +that can be used by <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> and +<a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>.</p> +<p class="since">Since 2.46</p> +</div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-Version-Information.other_details"></a><h2>Types and Values</h2> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-2.4-XMLRPC-Support.html b/docs/reference/html/libsoup-2.4-XMLRPC-Support.html new file mode 100644 index 00000000..b4265303 --- /dev/null +++ b/docs/reference/html/libsoup-2.4-XMLRPC-Support.html @@ -0,0 +1,790 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: XMLRPC Support</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch04.html" title="Web Services APIs"> +<link rel="prev" href="libsoup-2.4-HTML-Form-Support.html" title="HTML Form Support"> +<link rel="next" href="libsoup-2.4-GValue-Support.html" title="GValue Support"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#libsoup-2.4-XMLRPC-Support.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#libsoup-2.4-XMLRPC-Support.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch04.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="libsoup-2.4-HTML-Form-Support.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-2.4-GValue-Support.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-2.4-XMLRPC-Support"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="libsoup-2.4-XMLRPC-Support.top_of_page"></a>XMLRPC Support</span></h2> +<p>XMLRPC Support — XML-RPC support</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="libsoup-2.4-XMLRPC-Support.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-method-call" title="soup_xmlrpc_build_method_call ()">soup_xmlrpc_build_method_call</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-request-new" title="soup_xmlrpc_request_new ()">soup_xmlrpc_request_new</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-parse-method-response" title="soup_xmlrpc_parse_method_response ()">soup_xmlrpc_parse_method_response</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-extract-method-response" title="soup_xmlrpc_extract_method_response ()">soup_xmlrpc_extract_method_response</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-parse-method-call" title="soup_xmlrpc_parse_method_call ()">soup_xmlrpc_parse_method_call</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-extract-method-call" title="soup_xmlrpc_extract_method_call ()">soup_xmlrpc_extract_method_call</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-method-response" title="soup_xmlrpc_build_method_response ()">soup_xmlrpc_build_method_response</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-fault" title="soup_xmlrpc_build_fault ()">soup_xmlrpc_build_fault</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-set-response" title="soup_xmlrpc_set_response ()">soup_xmlrpc_set_response</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">void</span> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-set-fault" title="soup_xmlrpc_set_fault ()">soup_xmlrpc_set_fault</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-XMLRPC-Support.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-XMLRPC-Support.html#SOUP-XMLRPC-FAULT:CAPS" title="SOUP_XMLRPC_FAULT">SOUP_XMLRPC_FAULT</a></td> +</tr> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="libsoup-2.4-XMLRPC-Support.html#SoupXMLRPCFault" title="enum SoupXMLRPCFault">SoupXMLRPCFault</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-XMLRPC-Support.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-XMLRPC-Support.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-XMLRPC-Support.description"></a><h2>Description</h2> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-XMLRPC-Support.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="soup-xmlrpc-build-method-call"></a><h3>soup_xmlrpc_build_method_call ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_xmlrpc_build_method_call (<em class="parameter"><code>const <span class="type">char</span> *method_name</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> *params</code></em>, + <em class="parameter"><code><span class="type">int</span> n_params</code></em>);</pre> +<p>This creates an XML-RPC methodCall and returns it as a string. +This is the low-level method that <a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-request-new" title="soup_xmlrpc_request_new ()"><code class="function">soup_xmlrpc_request_new()</code></a> is +built on.</p> +<p><em class="parameter"><code>params</code></em> + is an array of <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> representing the parameters to +<em class="parameter"><code>method</code></em> +. (It is *not* a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a>, although if you have a +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a>, you can just pass its <code class="literal">values</code>f and +<code class="literal">n_values</code> fields.)</p> +<p>The correspondence between glib types and XML-RPC types is:</p> +<p> int: <span class="type">int</span> (<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-INT:CAPS"><code class="literal">G_TYPE_INT</code></a>) + boolean: <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> (<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-BOOLEAN:CAPS"><code class="literal">G_TYPE_BOOLEAN</code></a>) + string: <span class="type">char</span>* (<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-STRING:CAPS"><code class="literal">G_TYPE_STRING</code></a>) + double: <span class="type">double</span> (<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-DOUBLE:CAPS"><code class="literal">G_TYPE_DOUBLE</code></a>) + datetime.iso8601: <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate"><span class="type">SoupDate</span></a> (<code class="literal">SOUP_TYPE_DATE</code>) + base64: <a href="http://library.gnome.org/devel/glib/unstable/glib-Byte-Arrays.html#GByteArray"><span class="type">GByteArray</span></a> (<a class="link" href="libsoup-2.4-GValue-Support.html#SOUP-TYPE-BYTE-ARRAY:CAPS" title="SOUP_TYPE_BYTE_ARRAY"><code class="literal">SOUP_TYPE_BYTE_ARRAY</code></a>) + struct: <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> (<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Boxed-Types.html#G-TYPE-HASH-TABLE:CAPS"><code class="literal">G_TYPE_HASH_TABLE</code></a>) + array: <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> (<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#G-TYPE-VALUE-ARRAY:CAPS"><code class="literal">G_TYPE_VALUE_ARRAY</code></a>)</p> +<p>For structs, use a <a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> that maps strings to <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a>; +<a class="link" href="libsoup-2.4-GValue-Support.html#soup-value-hash-new" title="soup_value_hash_new ()"><code class="function">soup_value_hash_new()</code></a> and related methods can help with this.</p> +<div class="refsect3"> +<a name="id-1.5.3.8.2.9"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>method_name</p></td> +<td class="parameter_description"><p>the name of the XML-RPC method</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>params</p></td> +<td class="parameter_description"><p> arguments to <em class="parameter"><code>method</code></em> +. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=n_params]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>n_params</p></td> +<td class="parameter_description"><p>length of <em class="parameter"><code>params</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.3.8.2.10"></a><h4>Returns</h4> +<p> the text of the methodCall, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-xmlrpc-request-new"></a><h3>soup_xmlrpc_request_new ()</h3> +<pre class="programlisting"><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="returnvalue">SoupMessage</span></a> * +soup_xmlrpc_request_new (<em class="parameter"><code>const <span class="type">char</span> *uri</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *method_name</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Creates an XML-RPC methodCall and returns a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, ready +to send, for that method call.</p> +<p>The parameters are passed as type/value pairs; ie, first a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a>, +and then a value of the appropriate type, finally terminated by +<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-INVALID:CAPS"><code class="literal">G_TYPE_INVALID</code></a>.</p> +<div class="refsect3"> +<a name="id-1.5.3.8.3.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>uri</p></td> +<td class="parameter_description"><p>URI of the XML-RPC service</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>method_name</p></td> +<td class="parameter_description"><p>the name of the XML-RPC method to invoke at <em class="parameter"><code>uri</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>parameters for <em class="parameter"><code>method</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.3.8.3.7"></a><h4>Returns</h4> +<p> a <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> encoding the +indicated XML-RPC request. </p> +<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-xmlrpc-parse-method-response"></a><h3>soup_xmlrpc_parse_method_response ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_xmlrpc_parse_method_response (<em class="parameter"><code>const <span class="type">char</span> *method_response</code></em>, + <em class="parameter"><code><span class="type">int</span> length</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> *value</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> +<p>Parses <em class="parameter"><code>method_response</code></em> + and returns the return value in <em class="parameter"><code>value</code></em> +. If +<em class="parameter"><code>method_response</code></em> + is a fault, <em class="parameter"><code>value</code></em> + will be unchanged, and <em class="parameter"><code>error</code></em> + +will be set to an error of type <a class="link" href="libsoup-2.4-XMLRPC-Support.html#SOUP-XMLRPC-FAULT:CAPS" title="SOUP_XMLRPC_FAULT"><code class="literal">SOUP_XMLRPC_FAULT</code></a>, with the error +<span class="type">code</span> containing the fault code, and the error <span class="type">message</span> containing +the fault string. (If <em class="parameter"><code>method_response</code></em> + cannot be parsed at all, +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-parse-method-response" title="soup_xmlrpc_parse_method_response ()"><code class="function">soup_xmlrpc_parse_method_response()</code></a> will return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, but <em class="parameter"><code>error</code></em> + +will be unset.)</p> +<div class="refsect3"> +<a name="id-1.5.3.8.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>method_response</p></td> +<td class="parameter_description"><p>the XML-RPC methodResponse string</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>the length of <em class="parameter"><code>method_response</code></em> +, or -1 if it is NUL-terminated</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>value</p></td> +<td class="parameter_description"><p> on return, the return value from <em class="parameter"><code>method_call</code></em> +. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>error return value</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.3.8.4.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if a return value was parsed, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if the +response could not be parsed, or contained a fault.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-xmlrpc-extract-method-response"></a><h3>soup_xmlrpc_extract_method_response ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_xmlrpc_extract_method_response (<em class="parameter"><code>const <span class="type">char</span> *method_response</code></em>, + <em class="parameter"><code><span class="type">int</span> length</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Parses <em class="parameter"><code>method_response</code></em> + and extracts the return value into +a variable of the correct type.</p> +<p>If <em class="parameter"><code>method_response</code></em> + is a fault, the return value will be unset, +and <em class="parameter"><code>error</code></em> + will be set to an error of type <a class="link" href="libsoup-2.4-XMLRPC-Support.html#SOUP-XMLRPC-FAULT:CAPS" title="SOUP_XMLRPC_FAULT"><code class="literal">SOUP_XMLRPC_FAULT</code></a>, with +the error <span class="type">code</span> containing the fault code, and the error <span class="type">message</span> +containing the fault string. (If <em class="parameter"><code>method_response</code></em> + cannot be parsed +at all, <a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-extract-method-response" title="soup_xmlrpc_extract_method_response ()"><code class="function">soup_xmlrpc_extract_method_response()</code></a> will return <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, +but <em class="parameter"><code>error</code></em> + will be unset.)</p> +<div class="refsect3"> +<a name="id-1.5.3.8.5.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>method_response</p></td> +<td class="parameter_description"><p>the XML-RPC methodResponse string</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>the length of <em class="parameter"><code>method_response</code></em> +, or -1 if it is NUL-terminated</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>error</p></td> +<td class="parameter_description"><p>error return value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>the expected type of the return value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>location for return value</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.3.8.5.7"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> if a return value was parsed, <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a> if the +response was of the wrong type, or contained a fault.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-xmlrpc-parse-method-call"></a><h3>soup_xmlrpc_parse_method_call ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_xmlrpc_parse_method_call (<em class="parameter"><code>const <span class="type">char</span> *method_call</code></em>, + <em class="parameter"><code><span class="type">int</span> length</code></em>, + <em class="parameter"><code><span class="type">char</span> **method_name</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a> **params</code></em>);</pre> +<p>Parses <em class="parameter"><code>method_call</code></em> + to get the name and parameters, and returns the +parameter values in a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Value-arrays.html#GValueArray"><span class="type">GValueArray</span></a>; see also +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-extract-method-call" title="soup_xmlrpc_extract_method_call ()"><code class="function">soup_xmlrpc_extract_method_call()</code></a>, which is more convenient if you +know in advance what the types of the parameters will be.</p> +<div class="refsect3"> +<a name="id-1.5.3.8.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>method_call</p></td> +<td class="parameter_description"><p>the XML-RPC methodCall string</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>the length of <em class="parameter"><code>method_call</code></em> +, or -1 if it is NUL-terminated</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>method_name</p></td> +<td class="parameter_description"><p> on return, the methodName from <em class="parameter"><code>method_call</code></em> +. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>params</p></td> +<td class="parameter_description"><p> on return, the parameters from <em class="parameter"><code>method_call</code></em> +. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.3.8.6.6"></a><h4>Returns</h4> +<p> success or failure.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-xmlrpc-extract-method-call"></a><h3>soup_xmlrpc_extract_method_call ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="returnvalue">gboolean</span></a> +soup_xmlrpc_extract_method_call (<em class="parameter"><code>const <span class="type">char</span> *method_call</code></em>, + <em class="parameter"><code><span class="type">int</span> length</code></em>, + <em class="parameter"><code><span class="type">char</span> **method_name</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Parses <em class="parameter"><code>method_call</code></em> + to get the name and parameters, and puts +the parameters into variables of the appropriate types.</p> +<p>The parameters are handled similarly to +<em class="parameter"><code>soup_xmlrpc_build_method_call</code></em> +, with pairs of types and values, +terminated by <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#G-TYPE-INVALID:CAPS"><code class="literal">G_TYPE_INVALID</code></a>, except that values are pointers to +variables of the indicated type, rather than values of the type.</p> +<p>See also <a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-parse-method-call" title="soup_xmlrpc_parse_method_call ()"><code class="function">soup_xmlrpc_parse_method_call()</code></a>, which can be used if +you don't know the types of the parameters.</p> +<div class="refsect3"> +<a name="id-1.5.3.8.7.7"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>method_call</p></td> +<td class="parameter_description"><p>the XML-RPC methodCall string</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>length</p></td> +<td class="parameter_description"><p>the length of <em class="parameter"><code>method_call</code></em> +, or -1 if it is NUL-terminated</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>method_name</p></td> +<td class="parameter_description"><p> on return, the methodName from <em class="parameter"><code>method_call</code></em> +. </p></td> +<td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>return types and locations for parameters</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.3.8.7.8"></a><h4>Returns</h4> +<p> success or failure.</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-xmlrpc-build-method-response"></a><h3>soup_xmlrpc_build_method_response ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_xmlrpc_build_method_response (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a> *value</code></em>);</pre> +<p>This creates a (successful) XML-RPC methodResponse and returns it +as a string. To create a fault response, use +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-fault" title="soup_xmlrpc_build_fault ()"><code class="function">soup_xmlrpc_build_fault()</code></a>.</p> +<p>The glib type to XML-RPC type mapping is as with +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-method-call" title="soup_xmlrpc_build_method_call ()"><code class="function">soup_xmlrpc_build_method_call()</code></a>, qv.</p> +<div class="refsect3"> +<a name="id-1.5.3.8.8.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>value</p></td> +<td class="parameter_description"><p>the return value</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.3.8.8.7"></a><h4>Returns</h4> +<p> the text of the methodResponse, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-xmlrpc-build-fault"></a><h3>soup_xmlrpc_build_fault ()</h3> +<pre class="programlisting"><span class="returnvalue">char</span> * +soup_xmlrpc_build_fault (<em class="parameter"><code><span class="type">int</span> fault_code</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *fault_format</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>This creates an XML-RPC fault response and returns it as a string. +(To create a successful response, use +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-method-response" title="soup_xmlrpc_build_method_response ()"><code class="function">soup_xmlrpc_build_method_response()</code></a>.)</p> +<div class="refsect3"> +<a name="id-1.5.3.8.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>fault_code</p></td> +<td class="parameter_description"><p>the fault code</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>fault_format</p></td> +<td class="parameter_description"><p>a <code class="function">printf()</code>-style format string</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>the parameters to <em class="parameter"><code>fault_format</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.5.3.8.9.6"></a><h4>Returns</h4> +<p> the text of the fault</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-xmlrpc-set-response"></a><h3>soup_xmlrpc_set_response ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_xmlrpc_set_response (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> type</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Sets the status code and response body of <em class="parameter"><code>msg</code></em> + to indicate a +successful XML-RPC call, with a return value given by <em class="parameter"><code>type</code></em> + and the +following varargs argument, of the type indicated by <em class="parameter"><code>type</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.5.3.8.10.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>an XML-RPC request</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>type</p></td> +<td class="parameter_description"><p>the type of the response value</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>the response value</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-xmlrpc-set-fault"></a><h3>soup_xmlrpc_set_fault ()</h3> +<pre class="programlisting"><span class="returnvalue">void</span> +soup_xmlrpc_set_fault (<em class="parameter"><code><a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> *msg</code></em>, + <em class="parameter"><code><span class="type">int</span> fault_code</code></em>, + <em class="parameter"><code>const <span class="type">char</span> *fault_format</code></em>, + <em class="parameter"><code>...</code></em>);</pre> +<p>Sets the status code and response body of <em class="parameter"><code>msg</code></em> + to indicate an +unsuccessful XML-RPC call, with the error described by <em class="parameter"><code>fault_code</code></em> + +and <em class="parameter"><code>fault_format</code></em> +.</p> +<div class="refsect3"> +<a name="id-1.5.3.8.11.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>msg</p></td> +<td class="parameter_description"><p>an XML-RPC request</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>fault_code</p></td> +<td class="parameter_description"><p>the fault code</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>fault_format</p></td> +<td class="parameter_description"><p>a <code class="function">printf()</code>-style format string</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>...</p></td> +<td class="parameter_description"><p>the parameters to <em class="parameter"><code>fault_format</code></em> +</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-XMLRPC-Support.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SOUP-XMLRPC-FAULT:CAPS"></a><h3>SOUP_XMLRPC_FAULT</h3> +<pre class="programlisting">#define SOUP_XMLRPC_FAULT soup_xmlrpc_fault_quark() +</pre> +<p>A <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> domain representing an XML-RPC fault code. Used with +<a class="link" href="libsoup-2.4-XMLRPC-Support.html#SoupXMLRPCFault" title="enum SoupXMLRPCFault"><span class="type">SoupXMLRPCFault</span></a> (although servers may also return fault codes not +in that enumeration).</p> +</div> +<hr> +<div class="refsect2"> +<a name="SoupXMLRPCFault"></a><h3>enum SoupXMLRPCFault</h3> +<p>Pre-defined XML-RPC fault codes from <a class="ulink" href="http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php" target="_top">http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php</a>. +These are an extension, not part of the XML-RPC spec; you can't +assume servers will use them.</p> +<div class="refsect3"> +<a name="id-1.5.3.9.3.4"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-XMLRPC-FAULT-PARSE-ERROR-NOT-WELL-FORMED:CAPS"></a>SOUP_XMLRPC_FAULT_PARSE_ERROR_NOT_WELL_FORMED</p></td> +<td class="enum_member_description"> +<p>request was not + well-formed</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-XMLRPC-FAULT-PARSE-ERROR-UNSUPPORTED-ENCODING:CAPS"></a>SOUP_XMLRPC_FAULT_PARSE_ERROR_UNSUPPORTED_ENCODING</p></td> +<td class="enum_member_description"> +<p>request was in + an unsupported encoding</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-XMLRPC-FAULT-PARSE-ERROR-INVALID-CHARACTER-FOR-ENCODING:CAPS"></a>SOUP_XMLRPC_FAULT_PARSE_ERROR_INVALID_CHARACTER_FOR_ENCODING</p></td> +<td class="enum_member_description"> +<p> request contained an invalid character</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-XMLRPC-FAULT-SERVER-ERROR-INVALID-XML-RPC:CAPS"></a>SOUP_XMLRPC_FAULT_SERVER_ERROR_INVALID_XML_RPC</p></td> +<td class="enum_member_description"> +<p>request was not + valid XML-RPC</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-XMLRPC-FAULT-SERVER-ERROR-REQUESTED-METHOD-NOT-FOUND:CAPS"></a>SOUP_XMLRPC_FAULT_SERVER_ERROR_REQUESTED_METHOD_NOT_FOUND</p></td> +<td class="enum_member_description"> +<p>method + not found</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-XMLRPC-FAULT-SERVER-ERROR-INVALID-METHOD-PARAMETERS:CAPS"></a>SOUP_XMLRPC_FAULT_SERVER_ERROR_INVALID_METHOD_PARAMETERS</p></td> +<td class="enum_member_description"> +<p>invalid + parameters</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-XMLRPC-FAULT-SERVER-ERROR-INTERNAL-XML-RPC-ERROR:CAPS"></a>SOUP_XMLRPC_FAULT_SERVER_ERROR_INTERNAL_XML_RPC_ERROR</p></td> +<td class="enum_member_description"> +<p>internal + error</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-XMLRPC-FAULT-APPLICATION-ERROR:CAPS"></a>SOUP_XMLRPC_FAULT_APPLICATION_ERROR</p></td> +<td class="enum_member_description"> +<p>start of reserved range for + application error codes</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-XMLRPC-FAULT-SYSTEM-ERROR:CAPS"></a>SOUP_XMLRPC_FAULT_SYSTEM_ERROR</p></td> +<td class="enum_member_description"> +<p>start of reserved range for + system error codes</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-XMLRPC-FAULT-TRANSPORT-ERROR:CAPS"></a>SOUP_XMLRPC_FAULT_TRANSPORT_ERROR</p></td> +<td class="enum_member_description"> +<p>start of reserved range for + transport error codes</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-2.4-soup-method.html b/docs/reference/html/libsoup-2.4-soup-method.html new file mode 100644 index 00000000..c9ac31a8 --- /dev/null +++ b/docs/reference/html/libsoup-2.4-soup-method.html @@ -0,0 +1,260 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: soup-method</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupMessageBody.html" title="SoupMessageBody"> +<link rel="next" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html" title="Soup Miscellaneous Utilities"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#libsoup-2.4-soup-method.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#libsoup-2.4-soup-method.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupMessageBody.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-2.4-soup-method"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="libsoup-2.4-soup-method.top_of_page"></a>soup-method</span></h2> +<p>soup-method — HTTP method definitions</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-method.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-OPTIONS:CAPS" title="SOUP_METHOD_OPTIONS">SOUP_METHOD_OPTIONS</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-GET:CAPS" title="SOUP_METHOD_GET">SOUP_METHOD_GET</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-HEAD:CAPS" title="SOUP_METHOD_HEAD">SOUP_METHOD_HEAD</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-PUT:CAPS" title="SOUP_METHOD_PUT">SOUP_METHOD_PUT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-POST:CAPS" title="SOUP_METHOD_POST">SOUP_METHOD_POST</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-DELETE:CAPS" title="SOUP_METHOD_DELETE">SOUP_METHOD_DELETE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-TRACE:CAPS" title="SOUP_METHOD_TRACE">SOUP_METHOD_TRACE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-CONNECT:CAPS" title="SOUP_METHOD_CONNECT">SOUP_METHOD_CONNECT</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-PROPFIND:CAPS" title="SOUP_METHOD_PROPFIND">SOUP_METHOD_PROPFIND</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-PROPPATCH:CAPS" title="SOUP_METHOD_PROPPATCH">SOUP_METHOD_PROPPATCH</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-MKCOL:CAPS" title="SOUP_METHOD_MKCOL">SOUP_METHOD_MKCOL</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-COPY:CAPS" title="SOUP_METHOD_COPY">SOUP_METHOD_COPY</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-MOVE:CAPS" title="SOUP_METHOD_MOVE">SOUP_METHOD_MOVE</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-LOCK:CAPS" title="SOUP_METHOD_LOCK">SOUP_METHOD_LOCK</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-method.html#SOUP-METHOD-UNLOCK:CAPS" title="SOUP_METHOD_UNLOCK">SOUP_METHOD_UNLOCK</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-method.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-method.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-method.description"></a><h2>Description</h2> +<p>soup-method.h contains a number of defines for standard HTTP and +WebDAV headers. You do not need to use these defines; you can pass +arbitrary strings to <a class="link" href="SoupMessage.html#soup-message-new" title="soup_message_new ()"><code class="function">soup_message_new()</code></a> if you prefer.</p> +<p>The thing that these defines <span class="emphasis"><em>are</em></span> useful for is +performing quick comparisons against <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>'s <code class="literal">method</code> field; +because that field always contains an interned string, and these +macros return interned strings, you can compare <code class="literal">method</code> directly +against these macros rather than needing to use <code class="function">strcmp()</code>. This is +most useful in SoupServer handlers. Eg:</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">-></span><span class="normal">method </span><span class="symbol">!=</span><span class="normal"> <a href="libsoup-2.4-soup-method.html#SOUP-METHOD-GET:CAPS">SOUP_METHOD_GET</a> </span><span class="symbol">&&</span><span class="normal"> msg</span><span class="symbol">-></span><span class="normal">method </span><span class="symbol">!=</span><span class="normal"> <a href="libsoup-2.4-soup-method.html#SOUP-METHOD-HEAD:CAPS">SOUP_METHOD_HEAD</a></span><span class="symbol">)</span><span class="normal"> </span><span class="cbracket">{</span> +<span class="normal"> </span><span class="function"><a href="SoupMessage.html#soup-message-set-status">soup_message_set_status</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> SOUP_METHOD_NOT_IMPLEMENTED</span><span class="symbol">);</span> +<span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span> +<span class="cbracket">}</span></pre></td> + </tr> + </tbody> + </table> +</div> + +</div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-method.functions_details"></a><h2>Functions</h2> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-method.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SOUP-METHOD-OPTIONS:CAPS"></a><h3>SOUP_METHOD_OPTIONS</h3> +<pre class="programlisting">#define SOUP_METHOD_OPTIONS _SOUP_INTERN_METHOD (OPTIONS) +</pre> +<p>"OPTIONS" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-GET:CAPS"></a><h3>SOUP_METHOD_GET</h3> +<pre class="programlisting">#define SOUP_METHOD_GET _SOUP_INTERN_METHOD (GET) +</pre> +<p>"GET" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-HEAD:CAPS"></a><h3>SOUP_METHOD_HEAD</h3> +<pre class="programlisting">#define SOUP_METHOD_HEAD _SOUP_INTERN_METHOD (HEAD) +</pre> +<p>"HEAD" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-PUT:CAPS"></a><h3>SOUP_METHOD_PUT</h3> +<pre class="programlisting">#define SOUP_METHOD_PUT _SOUP_INTERN_METHOD (PUT) +</pre> +<p>"PUT" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-POST:CAPS"></a><h3>SOUP_METHOD_POST</h3> +<pre class="programlisting">#define SOUP_METHOD_POST _SOUP_INTERN_METHOD (POST) +</pre> +<p>"POST" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-DELETE:CAPS"></a><h3>SOUP_METHOD_DELETE</h3> +<pre class="programlisting">#define SOUP_METHOD_DELETE _SOUP_INTERN_METHOD (DELETE) +</pre> +<p>"DELETE" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-TRACE:CAPS"></a><h3>SOUP_METHOD_TRACE</h3> +<pre class="programlisting">#define SOUP_METHOD_TRACE _SOUP_INTERN_METHOD (TRACE) +</pre> +<p>"TRACE" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-CONNECT:CAPS"></a><h3>SOUP_METHOD_CONNECT</h3> +<pre class="programlisting">#define SOUP_METHOD_CONNECT _SOUP_INTERN_METHOD (CONNECT) +</pre> +<p>"CONNECT" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-PROPFIND:CAPS"></a><h3>SOUP_METHOD_PROPFIND</h3> +<pre class="programlisting">#define SOUP_METHOD_PROPFIND _SOUP_INTERN_METHOD (PROPFIND) +</pre> +<p>"PROPFIND" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-PROPPATCH:CAPS"></a><h3>SOUP_METHOD_PROPPATCH</h3> +<pre class="programlisting">#define SOUP_METHOD_PROPPATCH _SOUP_INTERN_METHOD (PROPPATCH) +</pre> +<p>"PROPPATCH" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-MKCOL:CAPS"></a><h3>SOUP_METHOD_MKCOL</h3> +<pre class="programlisting">#define SOUP_METHOD_MKCOL _SOUP_INTERN_METHOD (MKCOL) +</pre> +<p>"MKCOL" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-COPY:CAPS"></a><h3>SOUP_METHOD_COPY</h3> +<pre class="programlisting">#define SOUP_METHOD_COPY _SOUP_INTERN_METHOD (COPY) +</pre> +<p>"COPY" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-MOVE:CAPS"></a><h3>SOUP_METHOD_MOVE</h3> +<pre class="programlisting">#define SOUP_METHOD_MOVE _SOUP_INTERN_METHOD (MOVE) +</pre> +<p>"MOVE" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-LOCK:CAPS"></a><h3>SOUP_METHOD_LOCK</h3> +<pre class="programlisting">#define SOUP_METHOD_LOCK _SOUP_INTERN_METHOD (LOCK) +</pre> +<p>"LOCK" as an interned string.</p> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-METHOD-UNLOCK:CAPS"></a><h3>SOUP_METHOD_UNLOCK</h3> +<pre class="programlisting">#define SOUP_METHOD_UNLOCK _SOUP_INTERN_METHOD (UNLOCK) +</pre> +<p>"UNLOCK" as an interned string.</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-2.4-soup-status.html b/docs/reference/html/libsoup-2.4-soup-status.html new file mode 100644 index 00000000..ecd50a04 --- /dev/null +++ b/docs/reference/html/libsoup-2.4-soup-status.html @@ -0,0 +1,866 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: soup-status</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch02.html" title="Core API"> +<link rel="prev" href="SoupSessionSync.html" title="SoupSessionSync"> +<link rel="next" href="libsoup-2.4-Top-Level-Domain-utils.html" title="Top Level Domain utils"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#libsoup-2.4-soup-status.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span> + <a href="#libsoup-2.4-soup-status.object-hierarchy" class="shortcut">Object Hierarchy</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="SoupSessionSync.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-2.4-Top-Level-Domain-utils.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-2.4-soup-status"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="libsoup-2.4-soup-status.top_of_page"></a>soup-status</span></h2> +<p>soup-status — HTTP (and libsoup) status codes</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-status.functions"></a><h2>Functions</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-TRANSPORT-ERROR:CAPS" title="SOUP_STATUS_IS_TRANSPORT_ERROR()">SOUP_STATUS_IS_TRANSPORT_ERROR</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-INFORMATIONAL:CAPS" title="SOUP_STATUS_IS_INFORMATIONAL()">SOUP_STATUS_IS_INFORMATIONAL</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-SUCCESSFUL:CAPS" title="SOUP_STATUS_IS_SUCCESSFUL()">SOUP_STATUS_IS_SUCCESSFUL</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-REDIRECTION:CAPS" title="SOUP_STATUS_IS_REDIRECTION()">SOUP_STATUS_IS_REDIRECTION</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-CLIENT-ERROR:CAPS" title="SOUP_STATUS_IS_CLIENT_ERROR()">SOUP_STATUS_IS_CLIENT_ERROR</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-SERVER-ERROR:CAPS" title="SOUP_STATUS_IS_SERVER_ERROR()">SOUP_STATUS_IS_SERVER_ERROR</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-soup-status.html#soup-status-get-phrase" title="soup_status_get_phrase ()">soup_status_get_phrase</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +</td> +<td class="function_name"> +<a class="link" href="libsoup-2.4-soup-status.html#soup-status-proxify" title="soup_status_proxify ()">soup_status_proxify</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-status.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="datatype_keyword">enum</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-status.html#SoupStatus" title="enum SoupStatus">SoupStatus</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="libsoup-2.4-soup-status.html#SOUP-HTTP-ERROR:CAPS" title="SOUP_HTTP_ERROR">SOUP_HTTP_ERROR</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-status.object-hierarchy"></a><h2>Object Hierarchy</h2> +<pre class="screen"> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-status.includes"></a><h2>Includes</h2> +<pre class="synopsis">#include <libsoup/soup.h> +</pre> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-status.description"></a><h2>Description</h2> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-status.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="SOUP-STATUS-IS-TRANSPORT-ERROR:CAPS"></a><h3>SOUP_STATUS_IS_TRANSPORT_ERROR()</h3> +<pre class="programlisting">#define SOUP_STATUS_IS_TRANSPORT_ERROR(status) ((status) > 0 && (status) < 100) +</pre> +<p>Tests if <em class="parameter"><code>status</code></em> + is a libsoup transport error.</p> +<div class="refsect3"> +<a name="id-1.3.23.8.2.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>status</p></td> +<td class="parameter_description"><p>a status code</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.23.8.2.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-STATUS-IS-INFORMATIONAL:CAPS"></a><h3>SOUP_STATUS_IS_INFORMATIONAL()</h3> +<pre class="programlisting">#define SOUP_STATUS_IS_INFORMATIONAL(status) ((status) >= 100 && (status) < 200) +</pre> +<p>Tests if <em class="parameter"><code>status</code></em> + is an Informational (1xx) response.</p> +<div class="refsect3"> +<a name="id-1.3.23.8.3.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>status</p></td> +<td class="parameter_description"><p>an HTTP status code</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.23.8.3.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-STATUS-IS-SUCCESSFUL:CAPS"></a><h3>SOUP_STATUS_IS_SUCCESSFUL()</h3> +<pre class="programlisting">#define SOUP_STATUS_IS_SUCCESSFUL(status) ((status) >= 200 && (status) < 300) +</pre> +<p>Tests if <em class="parameter"><code>status</code></em> + is a Successful (2xx) response.</p> +<div class="refsect3"> +<a name="id-1.3.23.8.4.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>status</p></td> +<td class="parameter_description"><p>an HTTP status code</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.23.8.4.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-STATUS-IS-REDIRECTION:CAPS"></a><h3>SOUP_STATUS_IS_REDIRECTION()</h3> +<pre class="programlisting">#define SOUP_STATUS_IS_REDIRECTION(status) ((status) >= 300 && (status) < 400) +</pre> +<p>Tests if <em class="parameter"><code>status</code></em> + is a Redirection (3xx) response.</p> +<div class="refsect3"> +<a name="id-1.3.23.8.5.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>status</p></td> +<td class="parameter_description"><p>an HTTP status code</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.23.8.5.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-STATUS-IS-CLIENT-ERROR:CAPS"></a><h3>SOUP_STATUS_IS_CLIENT_ERROR()</h3> +<pre class="programlisting">#define SOUP_STATUS_IS_CLIENT_ERROR(status) ((status) >= 400 && (status) < 500) +</pre> +<p>Tests if <em class="parameter"><code>status</code></em> + is a Client Error (4xx) response.</p> +<div class="refsect3"> +<a name="id-1.3.23.8.6.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>status</p></td> +<td class="parameter_description"><p>an HTTP status code</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.23.8.6.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-STATUS-IS-SERVER-ERROR:CAPS"></a><h3>SOUP_STATUS_IS_SERVER_ERROR()</h3> +<pre class="programlisting">#define SOUP_STATUS_IS_SERVER_ERROR(status) ((status) >= 500 && (status) < 600) +</pre> +<p>Tests if <em class="parameter"><code>status</code></em> + is a Server Error (5xx) response.</p> +<div class="refsect3"> +<a name="id-1.3.23.8.7.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>status</p></td> +<td class="parameter_description"><p>an HTTP status code</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.23.8.7.6"></a><h4>Returns</h4> +<p> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a> or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a></p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-status-get-phrase"></a><h3>soup_status_get_phrase ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +soup_status_get_phrase (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> status_code</code></em>);</pre> +<p>Looks up the stock HTTP description of <em class="parameter"><code>status_code</code></em> +. This is used +by <a class="link" href="SoupMessage.html#soup-message-set-status" title="soup_message_set_status ()"><code class="function">soup_message_set_status()</code></a> to get the correct text to go with a +given status code.</p> +<p><span class="emphasis"><em>There is no reason for you to ever use this +function.</em></span> If you wanted the textual description for the +<a class="link" href="SoupMessage.html#SoupMessage--status-code" title="The “status-code” property"><span class="type">“status_code”</span></a> of a given <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, you should just +look at the message's <a class="link" href="SoupMessage.html#SoupMessage--reason-phrase" title="The “reason-phrase” property"><span class="type">“reason_phrase”</span></a>. However, you +should only do that for use in debugging messages; HTTP reason +phrases are not localized, and are not generally very descriptive +anyway, and so they should never be presented to the user directly. +Instead, you should create you own error messages based on the +status code, and on what you were trying to do.</p> +<div class="refsect3"> +<a name="id-1.3.23.8.8.6"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>status_code</p></td> +<td class="parameter_description"><p>an HTTP status code</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.23.8.8.7"></a><h4>Returns</h4> +<p> the (terse, English) description of <em class="parameter"><code>status_code</code></em> +</p> +<p></p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="soup-status-proxify"></a><h3>soup_status_proxify ()</h3> +<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="returnvalue">guint</span></a> +soup_status_proxify (<em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> status_code</code></em>);</pre> +<p>Turns <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANT-RESOLVE:CAPS"><code class="literal">SOUP_STATUS_CANT_RESOLVE</code></a> into +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANT-RESOLVE-PROXY:CAPS"><code class="literal">SOUP_STATUS_CANT_RESOLVE_PROXY</code></a> and <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANT-CONNECT:CAPS"><code class="literal">SOUP_STATUS_CANT_CONNECT</code></a> into +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANT-CONNECT-PROXY:CAPS"><code class="literal">SOUP_STATUS_CANT_CONNECT_PROXY</code></a>. Other status codes are passed +through unchanged.</p> +<div class="refsect3"> +<a name="id-1.3.23.8.9.5"></a><h4>Parameters</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody><tr> +<td class="parameter_name"><p>status_code</p></td> +<td class="parameter_description"><p>a status code</p></td> +<td class="parameter_annotations"> </td> +</tr></tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="id-1.3.23.8.9.6"></a><h4>Returns</h4> +<p> the "proxified" equivalent of <em class="parameter"><code>status_code</code></em> +.</p> +<p></p> +</div> +<p class="since">Since 2.26</p> +</div> +</div> +<div class="refsect1"> +<a name="libsoup-2.4-soup-status.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="SoupStatus"></a><h3>enum SoupStatus</h3> +<p>These represent the known HTTP status code values, plus various +network and internal errors.</p> +<p>Note that no libsoup functions take or return this type directly; +any function that works with status codes will accept unrecognized +status codes as well.</p> +<p>Prior to 2.44 this type was called +<code class="literal">SoupKnownStatusCode</code>, but the individual values +have always had the names they have now.</p> +<div class="refsect3"> +<a name="id-1.3.23.9.2.6"></a><h4>Members</h4> +<div class="informaltable"><table width="100%" border="0"> +<colgroup> +<col width="300px" class="enum_members_name"> +<col class="enum_members_description"> +<col width="200px" class="enum_members_annotations"> +</colgroup> +<tbody> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-NONE:CAPS"></a>SOUP_STATUS_NONE</p></td> +<td class="enum_member_description"> +<p>No status available. (Eg, the message has not +been sent yet)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-CANCELLED:CAPS"></a>SOUP_STATUS_CANCELLED</p></td> +<td class="enum_member_description"> +<p>Message was cancelled locally</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-CANT-RESOLVE:CAPS"></a>SOUP_STATUS_CANT_RESOLVE</p></td> +<td class="enum_member_description"> +<p>Unable to resolve destination host name</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-CANT-RESOLVE-PROXY:CAPS"></a>SOUP_STATUS_CANT_RESOLVE_PROXY</p></td> +<td class="enum_member_description"> +<p>Unable to resolve proxy host name</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-CANT-CONNECT:CAPS"></a>SOUP_STATUS_CANT_CONNECT</p></td> +<td class="enum_member_description"> +<p>Unable to connect to remote host</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-CANT-CONNECT-PROXY:CAPS"></a>SOUP_STATUS_CANT_CONNECT_PROXY</p></td> +<td class="enum_member_description"> +<p>Unable to connect to proxy</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-SSL-FAILED:CAPS"></a>SOUP_STATUS_SSL_FAILED</p></td> +<td class="enum_member_description"> +<p>SSL/TLS negotiation failed</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-IO-ERROR:CAPS"></a>SOUP_STATUS_IO_ERROR</p></td> +<td class="enum_member_description"> +<p>A network error occurred, or the other end +closed the connection unexpectedly</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-MALFORMED:CAPS"></a>SOUP_STATUS_MALFORMED</p></td> +<td class="enum_member_description"> +<p>Malformed data (usually a programmer error)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-TRY-AGAIN:CAPS"></a>SOUP_STATUS_TRY_AGAIN</p></td> +<td class="enum_member_description"> +<p>Used internally</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-TOO-MANY-REDIRECTS:CAPS"></a>SOUP_STATUS_TOO_MANY_REDIRECTS</p></td> +<td class="enum_member_description"> +<p>There were too many redirections</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-TLS-FAILED:CAPS"></a>SOUP_STATUS_TLS_FAILED</p></td> +<td class="enum_member_description"> +<p>Used internally</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-CONTINUE:CAPS"></a>SOUP_STATUS_CONTINUE</p></td> +<td class="enum_member_description"> +<p>100 Continue (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-SWITCHING-PROTOCOLS:CAPS"></a>SOUP_STATUS_SWITCHING_PROTOCOLS</p></td> +<td class="enum_member_description"> +<p>101 Switching Protocols (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-PROCESSING:CAPS"></a>SOUP_STATUS_PROCESSING</p></td> +<td class="enum_member_description"> +<p>102 Processing (WebDAV)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-OK:CAPS"></a>SOUP_STATUS_OK</p></td> +<td class="enum_member_description"> +<p>200 Success (HTTP). Also used by many lower-level +soup routines to indicate success.</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-CREATED:CAPS"></a>SOUP_STATUS_CREATED</p></td> +<td class="enum_member_description"> +<p>201 Created (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-ACCEPTED:CAPS"></a>SOUP_STATUS_ACCEPTED</p></td> +<td class="enum_member_description"> +<p>202 Accepted (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-NON-AUTHORITATIVE:CAPS"></a>SOUP_STATUS_NON_AUTHORITATIVE</p></td> +<td class="enum_member_description"> +<p>203 Non-Authoritative Information +(HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-NO-CONTENT:CAPS"></a>SOUP_STATUS_NO_CONTENT</p></td> +<td class="enum_member_description"> +<p>204 No Content (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-RESET-CONTENT:CAPS"></a>SOUP_STATUS_RESET_CONTENT</p></td> +<td class="enum_member_description"> +<p>205 Reset Content (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-PARTIAL-CONTENT:CAPS"></a>SOUP_STATUS_PARTIAL_CONTENT</p></td> +<td class="enum_member_description"> +<p>206 Partial Content (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-MULTI-STATUS:CAPS"></a>SOUP_STATUS_MULTI_STATUS</p></td> +<td class="enum_member_description"> +<p>207 Multi-Status (WebDAV)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-MULTIPLE-CHOICES:CAPS"></a>SOUP_STATUS_MULTIPLE_CHOICES</p></td> +<td class="enum_member_description"> +<p>300 Multiple Choices (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-MOVED-PERMANENTLY:CAPS"></a>SOUP_STATUS_MOVED_PERMANENTLY</p></td> +<td class="enum_member_description"> +<p>301 Moved Permanently (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-FOUND:CAPS"></a>SOUP_STATUS_FOUND</p></td> +<td class="enum_member_description"> +<p>302 Found (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-MOVED-TEMPORARILY:CAPS"></a>SOUP_STATUS_MOVED_TEMPORARILY</p></td> +<td class="enum_member_description"> +<p>302 Moved Temporarily (old name, +RFC 2068)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-SEE-OTHER:CAPS"></a>SOUP_STATUS_SEE_OTHER</p></td> +<td class="enum_member_description"> +<p>303 See Other (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-NOT-MODIFIED:CAPS"></a>SOUP_STATUS_NOT_MODIFIED</p></td> +<td class="enum_member_description"> +<p>304 Not Modified (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-USE-PROXY:CAPS"></a>SOUP_STATUS_USE_PROXY</p></td> +<td class="enum_member_description"> +<p>305 Use Proxy (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-NOT-APPEARING-IN-THIS-PROTOCOL:CAPS"></a>SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL</p></td> +<td class="enum_member_description"> +<p>306 [Unused] (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-TEMPORARY-REDIRECT:CAPS"></a>SOUP_STATUS_TEMPORARY_REDIRECT</p></td> +<td class="enum_member_description"> +<p>307 Temporary Redirect (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-BAD-REQUEST:CAPS"></a>SOUP_STATUS_BAD_REQUEST</p></td> +<td class="enum_member_description"> +<p>400 Bad Request (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-UNAUTHORIZED:CAPS"></a>SOUP_STATUS_UNAUTHORIZED</p></td> +<td class="enum_member_description"> +<p>401 Unauthorized (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-PAYMENT-REQUIRED:CAPS"></a>SOUP_STATUS_PAYMENT_REQUIRED</p></td> +<td class="enum_member_description"> +<p>402 Payment Required (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-FORBIDDEN:CAPS"></a>SOUP_STATUS_FORBIDDEN</p></td> +<td class="enum_member_description"> +<p>403 Forbidden (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-NOT-FOUND:CAPS"></a>SOUP_STATUS_NOT_FOUND</p></td> +<td class="enum_member_description"> +<p>404 Not Found (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-METHOD-NOT-ALLOWED:CAPS"></a>SOUP_STATUS_METHOD_NOT_ALLOWED</p></td> +<td class="enum_member_description"> +<p>405 Method Not Allowed (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-NOT-ACCEPTABLE:CAPS"></a>SOUP_STATUS_NOT_ACCEPTABLE</p></td> +<td class="enum_member_description"> +<p>406 Not Acceptable (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-PROXY-AUTHENTICATION-REQUIRED:CAPS"></a>SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED</p></td> +<td class="enum_member_description"> +<p>407 Proxy Authentication +Required (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-PROXY-UNAUTHORIZED:CAPS"></a>SOUP_STATUS_PROXY_UNAUTHORIZED</p></td> +<td class="enum_member_description"> +<p>shorter alias for +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-PROXY-AUTHENTICATION-REQUIRED:CAPS"><code class="literal">SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED</code></a></p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-REQUEST-TIMEOUT:CAPS"></a>SOUP_STATUS_REQUEST_TIMEOUT</p></td> +<td class="enum_member_description"> +<p>408 Request Timeout (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-CONFLICT:CAPS"></a>SOUP_STATUS_CONFLICT</p></td> +<td class="enum_member_description"> +<p>409 Conflict (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-GONE:CAPS"></a>SOUP_STATUS_GONE</p></td> +<td class="enum_member_description"> +<p>410 Gone (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-LENGTH-REQUIRED:CAPS"></a>SOUP_STATUS_LENGTH_REQUIRED</p></td> +<td class="enum_member_description"> +<p>411 Length Required (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-PRECONDITION-FAILED:CAPS"></a>SOUP_STATUS_PRECONDITION_FAILED</p></td> +<td class="enum_member_description"> +<p>412 Precondition Failed (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-REQUEST-ENTITY-TOO-LARGE:CAPS"></a>SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE</p></td> +<td class="enum_member_description"> +<p>413 Request Entity Too Large +(HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-REQUEST-URI-TOO-LONG:CAPS"></a>SOUP_STATUS_REQUEST_URI_TOO_LONG</p></td> +<td class="enum_member_description"> +<p>414 Request-URI Too Long (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-UNSUPPORTED-MEDIA-TYPE:CAPS"></a>SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE</p></td> +<td class="enum_member_description"> +<p>415 Unsupported Media Type +(HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-REQUESTED-RANGE-NOT-SATISFIABLE:CAPS"></a>SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE</p></td> +<td class="enum_member_description"> +<p>416 Requested Range +Not Satisfiable (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-INVALID-RANGE:CAPS"></a>SOUP_STATUS_INVALID_RANGE</p></td> +<td class="enum_member_description"> +<p>shorter alias for +<a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-REQUESTED-RANGE-NOT-SATISFIABLE:CAPS"><code class="literal">SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE</code></a></p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-EXPECTATION-FAILED:CAPS"></a>SOUP_STATUS_EXPECTATION_FAILED</p></td> +<td class="enum_member_description"> +<p>417 Expectation Failed (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-UNPROCESSABLE-ENTITY:CAPS"></a>SOUP_STATUS_UNPROCESSABLE_ENTITY</p></td> +<td class="enum_member_description"> +<p>422 Unprocessable Entity +(WebDAV)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-LOCKED:CAPS"></a>SOUP_STATUS_LOCKED</p></td> +<td class="enum_member_description"> +<p>423 Locked (WebDAV)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-FAILED-DEPENDENCY:CAPS"></a>SOUP_STATUS_FAILED_DEPENDENCY</p></td> +<td class="enum_member_description"> +<p>424 Failed Dependency (WebDAV)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-INTERNAL-SERVER-ERROR:CAPS"></a>SOUP_STATUS_INTERNAL_SERVER_ERROR</p></td> +<td class="enum_member_description"> +<p>500 Internal Server Error +(HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-NOT-IMPLEMENTED:CAPS"></a>SOUP_STATUS_NOT_IMPLEMENTED</p></td> +<td class="enum_member_description"> +<p>501 Not Implemented (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-BAD-GATEWAY:CAPS"></a>SOUP_STATUS_BAD_GATEWAY</p></td> +<td class="enum_member_description"> +<p>502 Bad Gateway (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-SERVICE-UNAVAILABLE:CAPS"></a>SOUP_STATUS_SERVICE_UNAVAILABLE</p></td> +<td class="enum_member_description"> +<p>503 Service Unavailable (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-GATEWAY-TIMEOUT:CAPS"></a>SOUP_STATUS_GATEWAY_TIMEOUT</p></td> +<td class="enum_member_description"> +<p>504 Gateway Timeout (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-HTTP-VERSION-NOT-SUPPORTED:CAPS"></a>SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED</p></td> +<td class="enum_member_description"> +<p>505 HTTP Version Not +Supported (HTTP)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-INSUFFICIENT-STORAGE:CAPS"></a>SOUP_STATUS_INSUFFICIENT_STORAGE</p></td> +<td class="enum_member_description"> +<p>507 Insufficient Storage +(WebDAV)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +<tr> +<td class="enum_member_name"><p><a name="SOUP-STATUS-NOT-EXTENDED:CAPS"></a>SOUP_STATUS_NOT_EXTENDED</p></td> +<td class="enum_member_description"> +<p>510 Not Extended (RFC 2774)</p> +</td> +<td class="enum_member_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="SOUP-HTTP-ERROR:CAPS"></a><h3>SOUP_HTTP_ERROR</h3> +<pre class="programlisting">#define SOUP_HTTP_ERROR soup_http_error_quark() +</pre> +<p>A <a href="http://library.gnome.org/devel/glib/unstable/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> domain representing an HTTP status. Use a <a class="link" href="libsoup-2.4-soup-status.html#SoupStatus" title="enum SoupStatus"><span class="type">SoupStatus</span></a> for +the <em class="structfield"><code>code</code></em> value.</p> +</div> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-2.4.devhelp2 b/docs/reference/html/libsoup-2.4.devhelp2 new file mode 100644 index 00000000..24b28dd6 --- /dev/null +++ b/docs/reference/html/libsoup-2.4.devhelp2 @@ -0,0 +1,815 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<!DOCTYPE book PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" ""> +<book xmlns="http://www.devhelp.net/book" title="libsoup Reference Manual" link="index.html" author="" name="libsoup-2.4" version="2" language="c"> + <chapters> + <sub name="Tutorial" link="ch01.html"> + <sub name="Compiling with libsoup" link="libsoup-build-howto.html"/> + <sub name="libsoup Client Basics" link="libsoup-client-howto.html"/> + <sub name="libsoup Client SoupRequest API" link="libsoup-request-howto.html"/> + <sub name="Soup Server Basics" link="libsoup-server-howto.html"/> + <sub name="Porting to the new SoupSession" link="libsoup-session-porting.html"/> + </sub> + <sub name="Core API" link="ch02.html"> + <sub name="SoupAuth" link="SoupAuth.html"/> + <sub name="SoupAuthDomain" link="SoupAuthDomain.html"/> + <sub name="SoupAuthDomainBasic" link="SoupAuthDomainBasic.html"/> + <sub name="SoupAuthDomainDigest" link="SoupAuthDomainDigest.html"/> + <sub name="SoupCache" link="SoupCache.html"/> + <sub name="SoupCookie" link="SoupCookie.html"/> + <sub name="SoupMessage" link="SoupMessage.html"/> + <sub name="SoupMessageHeaders" link="SoupMessageHeaders.html"/> + <sub name="SoupMessageBody" link="SoupMessageBody.html"/> + <sub name="soup-method" link="libsoup-2.4-soup-method.html"/> + <sub name="Soup Miscellaneous Utilities" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html"/> + <sub name="SoupMultipart" link="SoupMultipart.html"/> + <sub name="SoupMultipartInputStream" link="SoupMultipartInputStream.html"/> + <sub name="SoupRequest" link="SoupRequest.html"/> + <sub name="SoupRequestHTTP" link="SoupRequestHTTP.html"/> + <sub name="SoupRequestFile" link="SoupRequestFile.html"/> + <sub name="SoupRequestData" link="SoupRequestData.html"/> + <sub name="SoupServer" link="SoupServer.html"/> + <sub name="SoupSession" link="SoupSession.html"/> + <sub name="SoupSessionAsync" link="SoupSessionAsync.html"/> + <sub name="SoupSessionSync" link="SoupSessionSync.html"/> + <sub name="soup-status" link="libsoup-2.4-soup-status.html"/> + <sub name="Top Level Domain utils" link="libsoup-2.4-Top-Level-Domain-utils.html"/> + <sub name="SoupURI" link="SoupURI.html"/> + <sub name="Version Information" link="libsoup-2.4-Version-Information.html"/> + </sub> + <sub name="Additional Features" link="ch03.html"> + <sub name="SoupSessionFeature" link="SoupSessionFeature.html"/> + <sub name="SoupAuthManager" link="SoupAuthManager.html"/> + <sub name="SoupContentDecoder" link="SoupContentDecoder.html"/> + <sub name="SoupContentSniffer" link="SoupContentSniffer.html"/> + <sub name="SoupCookieJar" link="SoupCookieJar.html"/> + <sub name="SoupCookieJarText" link="SoupCookieJarText.html"/> + <sub name="SoupCookieJarDB" link="SoupCookieJarDB.html"/> + <sub name="SoupLogger" link="SoupLogger.html"/> + <sub name="SoupProxyResolverDefault" link="SoupProxyResolverDefault.html"/> + </sub> + <sub name="Web Services APIs" link="ch04.html"> + <sub name="HTML Form Support" link="libsoup-2.4-HTML-Form-Support.html"/> + <sub name="XMLRPC Support" link="libsoup-2.4-XMLRPC-Support.html"/> + <sub name="GValue Support" link="libsoup-2.4-GValue-Support.html"/> + </sub> + <sub name="Low-level Networking API" link="ch05.html"> + <sub name="SoupAddress" link="SoupAddress.html"/> + <sub name="SoupSocket" link="SoupSocket.html"/> + </sub> + <sub name="Index" link="ix01.html"/> + <sub name="Annotation Glossary" link="annotation-glossary.html"/> + </chapters> + <functions> + <keyword type="" name="Using pkg-config" link="libsoup-build-howto.html#id-1.2.2.3"/> + <keyword type="" name="API Availability and Deprecation Warnings" link="libsoup-build-howto.html#id-1.2.2.4"/> + <keyword type="" name="Headers" link="libsoup-build-howto.html#id-1.2.2.5"/> + <keyword type="" name="" link="libsoup-client-howto.html#id-1.2.3.3"/> + <keyword type="" name="Creating a SoupSession" link="libsoup-client-howto.html#id-1.2.3.4"/> + <keyword type="" name="Session features" link="libsoup-client-howto.html#session-features"/> + <keyword type="" name="Creating and Sending SoupMessages" link="libsoup-client-howto.html#id-1.2.3.6"/> + <keyword type="" name="Processing the Response" link="libsoup-client-howto.html#id-1.2.3.7"/> + <keyword type="" name="Handling Authentication" link="libsoup-client-howto.html#id-1.2.3.8"/> + <keyword type="" name="Multi-threaded usage" link="libsoup-client-howto.html#id-1.2.3.9"/> + <keyword type="" name="Sample Programs" link="libsoup-client-howto.html#id-1.2.3.10"/> + <keyword type="" name="SoupRequest" link="libsoup-request-howto.html#id-1.2.4.3"/> + <keyword type="" name="Creating a SoupRequest" link="libsoup-request-howto.html#id-1.2.4.4"/> + <keyword type="" name="Sending a SoupRequest" link="libsoup-request-howto.html#id-1.2.4.5"/> + <keyword type="" name="Supported URI types, and adding your own" link="libsoup-request-howto.html#id-1.2.4.6"/> + <keyword type="" name="Creating a SoupSession" link="libsoup-server-howto.html#id-1.2.5.3"/> + <keyword type="" name="Adding Handlers" link="libsoup-server-howto.html#id-1.2.5.4"/> + <keyword type="" name="Responding to Requests" link="libsoup-server-howto.html#id-1.2.5.5"/> + <keyword type="" name="Handling Authentication" link="libsoup-server-howto.html#id-1.2.5.6"/> + <keyword type="" name="Introduction" link="libsoup-session-porting.html#intro"/> + <keyword type="" name="Different defaults" link="libsoup-session-porting.html#defaults"/> + <keyword type="" name="Differences in feature behavior" link="libsoup-session-porting.html#behavior"/> + <keyword type="" name="Differences in SoupMessage-sending APIs" link="libsoup-session-porting.html#apis"/> + <keyword type="" name="Differences in Asynchronous I/O" link="libsoup-session-porting.html#async"/> + <keyword type="function" name="soup_auth_new ()" link="SoupAuth.html#soup-auth-new"/> + <keyword type="function" name="soup_auth_update ()" link="SoupAuth.html#soup-auth-update"/> + <keyword type="macro" name="SOUP_TYPE_AUTH_BASIC" link="SoupAuth.html#SOUP-TYPE-AUTH-BASIC:CAPS" since="2.34"/> + <keyword type="macro" name="SOUP_TYPE_AUTH_DIGEST" link="SoupAuth.html#SOUP-TYPE-AUTH-DIGEST:CAPS" since="2.34"/> + <keyword type="macro" name="SOUP_TYPE_AUTH_NTLM" link="SoupAuth.html#SOUP-TYPE-AUTH-NTLM:CAPS" since="2.34"/> + <keyword type="function" name="soup_auth_is_for_proxy ()" link="SoupAuth.html#soup-auth-is-for-proxy"/> + <keyword type="function" name="soup_auth_get_scheme_name ()" link="SoupAuth.html#soup-auth-get-scheme-name"/> + <keyword type="function" name="soup_auth_get_host ()" link="SoupAuth.html#soup-auth-get-host"/> + <keyword type="function" name="soup_auth_get_realm ()" link="SoupAuth.html#soup-auth-get-realm"/> + <keyword type="function" name="soup_auth_get_info ()" link="SoupAuth.html#soup-auth-get-info"/> + <keyword type="function" name="soup_auth_authenticate ()" link="SoupAuth.html#soup-auth-authenticate"/> + <keyword type="function" name="soup_auth_is_authenticated ()" link="SoupAuth.html#soup-auth-is-authenticated"/> + <keyword type="function" name="soup_auth_is_ready ()" link="SoupAuth.html#soup-auth-is-ready" since="2.42"/> + <keyword type="function" name="soup_auth_get_authorization ()" link="SoupAuth.html#soup-auth-get-authorization"/> + <keyword type="function" name="soup_auth_get_protection_space ()" link="SoupAuth.html#soup-auth-get-protection-space"/> + <keyword type="function" name="soup_auth_free_protection_space ()" link="SoupAuth.html#soup-auth-free-protection-space"/> + <keyword type="struct" name="SoupAuth" link="SoupAuth.html#SoupAuth-struct"/> + <keyword type="macro" name="SOUP_AUTH_SCHEME_NAME" link="SoupAuth.html#SOUP-AUTH-SCHEME-NAME:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_REALM" link="SoupAuth.html#SOUP-AUTH-REALM:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_HOST" link="SoupAuth.html#SOUP-AUTH-HOST:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_IS_FOR_PROXY" link="SoupAuth.html#SOUP-AUTH-IS-FOR-PROXY:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_IS_AUTHENTICATED" link="SoupAuth.html#SOUP-AUTH-IS-AUTHENTICATED:CAPS"/> + <keyword type="property" name="The “host” property" link="SoupAuth.html#SoupAuth--host"/> + <keyword type="property" name="The “is-authenticated” property" link="SoupAuth.html#SoupAuth--is-authenticated"/> + <keyword type="property" name="The “is-for-proxy” property" link="SoupAuth.html#SoupAuth--is-for-proxy"/> + <keyword type="property" name="The “realm” property" link="SoupAuth.html#SoupAuth--realm"/> + <keyword type="property" name="The “scheme-name” property" link="SoupAuth.html#SoupAuth--scheme-name"/> + <keyword type="function" name="soup_auth_domain_add_path ()" link="SoupAuthDomain.html#soup-auth-domain-add-path"/> + <keyword type="function" name="soup_auth_domain_remove_path ()" link="SoupAuthDomain.html#soup-auth-domain-remove-path"/> + <keyword type="function" name="SoupAuthDomainFilter ()" link="SoupAuthDomain.html#SoupAuthDomainFilter"/> + <keyword type="function" name="soup_auth_domain_set_filter ()" link="SoupAuthDomain.html#soup-auth-domain-set-filter"/> + <keyword type="function" name="soup_auth_domain_get_realm ()" link="SoupAuthDomain.html#soup-auth-domain-get-realm"/> + <keyword type="function" name="SoupAuthDomainGenericAuthCallback ()" link="SoupAuthDomain.html#SoupAuthDomainGenericAuthCallback"/> + <keyword type="function" name="soup_auth_domain_set_generic_auth_callback ()" link="SoupAuthDomain.html#soup-auth-domain-set-generic-auth-callback"/> + <keyword type="function" name="soup_auth_domain_check_password ()" link="SoupAuthDomain.html#soup-auth-domain-check-password"/> + <keyword type="function" name="soup_auth_domain_covers ()" link="SoupAuthDomain.html#soup-auth-domain-covers"/> + <keyword type="function" name="soup_auth_domain_accepts ()" link="SoupAuthDomain.html#soup-auth-domain-accepts"/> + <keyword type="function" name="soup_auth_domain_challenge ()" link="SoupAuthDomain.html#soup-auth-domain-challenge"/> + <keyword type="struct" name="SoupAuthDomain" link="SoupAuthDomain.html#SoupAuthDomain-struct"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_REALM" link="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REALM:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_PROXY" link="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-PROXY:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_ADD_PATH" link="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-ADD-PATH:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_REMOVE_PATH" link="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REMOVE-PATH:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_FILTER" link="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-FILTER:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_FILTER_DATA" link="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-FILTER-DATA:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK" link="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-GENERIC-AUTH-CALLBACK:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA" link="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-GENERIC-AUTH-DATA:CAPS"/> + <keyword type="property" name="The “add-path” property" link="SoupAuthDomain.html#SoupAuthDomain--add-path"/> + <keyword type="property" name="The “filter” property" link="SoupAuthDomain.html#SoupAuthDomain--filter"/> + <keyword type="property" name="The “filter-data” property" link="SoupAuthDomain.html#SoupAuthDomain--filter-data"/> + <keyword type="property" name="The “generic-auth-callback” property" link="SoupAuthDomain.html#SoupAuthDomain--generic-auth-callback"/> + <keyword type="property" name="The “generic-auth-data” property" link="SoupAuthDomain.html#SoupAuthDomain--generic-auth-data"/> + <keyword type="property" name="The “proxy” property" link="SoupAuthDomain.html#SoupAuthDomain--proxy"/> + <keyword type="property" name="The “realm” property" link="SoupAuthDomain.html#SoupAuthDomain--realm"/> + <keyword type="property" name="The “remove-path” property" link="SoupAuthDomain.html#SoupAuthDomain--remove-path"/> + <keyword type="function" name="soup_auth_domain_basic_new ()" link="SoupAuthDomainBasic.html#soup-auth-domain-basic-new"/> + <keyword type="function" name="SoupAuthDomainBasicAuthCallback ()" link="SoupAuthDomainBasic.html#SoupAuthDomainBasicAuthCallback"/> + <keyword type="function" name="soup_auth_domain_basic_set_auth_callback ()" link="SoupAuthDomainBasic.html#soup-auth-domain-basic-set-auth-callback"/> + <keyword type="struct" name="SoupAuthDomainBasic" link="SoupAuthDomainBasic.html#SoupAuthDomainBasic-struct"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK" link="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-CALLBACK:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA" link="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-DATA:CAPS"/> + <keyword type="property" name="The “auth-callback” property" link="SoupAuthDomainBasic.html#SoupAuthDomainBasic--auth-callback"/> + <keyword type="property" name="The “auth-data” property" link="SoupAuthDomainBasic.html#SoupAuthDomainBasic--auth-data"/> + <keyword type="function" name="soup_auth_domain_digest_new ()" link="SoupAuthDomainDigest.html#soup-auth-domain-digest-new"/> + <keyword type="function" name="SoupAuthDomainDigestAuthCallback ()" link="SoupAuthDomainDigest.html#SoupAuthDomainDigestAuthCallback"/> + <keyword type="function" name="soup_auth_domain_digest_set_auth_callback ()" link="SoupAuthDomainDigest.html#soup-auth-domain-digest-set-auth-callback"/> + <keyword type="function" name="soup_auth_domain_digest_encode_password ()" link="SoupAuthDomainDigest.html#soup-auth-domain-digest-encode-password"/> + <keyword type="struct" name="SoupAuthDomainDigest" link="SoupAuthDomainDigest.html#SoupAuthDomainDigest-struct"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK" link="SoupAuthDomainDigest.html#SOUP-AUTH-DOMAIN-DIGEST-AUTH-CALLBACK:CAPS"/> + <keyword type="macro" name="SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA" link="SoupAuthDomainDigest.html#SOUP-AUTH-DOMAIN-DIGEST-AUTH-DATA:CAPS"/> + <keyword type="property" name="The “auth-callback” property" link="SoupAuthDomainDigest.html#SoupAuthDomainDigest--auth-callback"/> + <keyword type="property" name="The “auth-data” property" link="SoupAuthDomainDigest.html#SoupAuthDomainDigest--auth-data"/> + <keyword type="function" name="soup_cache_new ()" link="SoupCache.html#soup-cache-new" since="2.34"/> + <keyword type="function" name="soup_cache_flush ()" link="SoupCache.html#soup-cache-flush" since="2.34"/> + <keyword type="function" name="soup_cache_clear ()" link="SoupCache.html#soup-cache-clear" since="2.34"/> + <keyword type="function" name="soup_cache_dump ()" link="SoupCache.html#soup-cache-dump" since="2.34."/> + <keyword type="function" name="soup_cache_load ()" link="SoupCache.html#soup-cache-load" since="2.34"/> + <keyword type="function" name="soup_cache_get_max_size ()" link="SoupCache.html#soup-cache-get-max-size" since="2.34"/> + <keyword type="function" name="soup_cache_set_max_size ()" link="SoupCache.html#soup-cache-set-max-size" since="2.34"/> + <keyword type="struct" name="struct SoupCache" link="SoupCache.html#SoupCache-struct"/> + <keyword type="enum" name="enum SoupCacheType" link="SoupCache.html#SoupCacheType" since="2.34"/> + <keyword type="property" name="The “cache-dir” property" link="SoupCache.html#SoupCache--cache-dir"/> + <keyword type="property" name="The “cache-type” property" link="SoupCache.html#SoupCache--cache-type"/> + <keyword type="function" name="soup_cookie_new ()" link="SoupCookie.html#soup-cookie-new" since="2.24"/> + <keyword type="function" name="soup_cookie_parse ()" link="SoupCookie.html#soup-cookie-parse" since="2.24"/> + <keyword type="function" name="soup_cookie_copy ()" link="SoupCookie.html#soup-cookie-copy" since="2.24"/> + <keyword type="function" name="soup_cookie_free ()" link="SoupCookie.html#soup-cookie-free" since="2.24"/> + <keyword type="function" name="soup_cookie_set_name ()" link="SoupCookie.html#soup-cookie-set-name" since="2.24"/> + <keyword type="function" name="soup_cookie_get_name ()" link="SoupCookie.html#soup-cookie-get-name" since="2.32"/> + <keyword type="function" name="soup_cookie_set_value ()" link="SoupCookie.html#soup-cookie-set-value" since="2.24"/> + <keyword type="function" name="soup_cookie_get_value ()" link="SoupCookie.html#soup-cookie-get-value" since="2.32"/> + <keyword type="function" name="soup_cookie_set_domain ()" link="SoupCookie.html#soup-cookie-set-domain" since="2.24"/> + <keyword type="function" name="soup_cookie_get_domain ()" link="SoupCookie.html#soup-cookie-get-domain" since="2.32"/> + <keyword type="function" name="soup_cookie_set_path ()" link="SoupCookie.html#soup-cookie-set-path" since="2.24"/> + <keyword type="function" name="soup_cookie_get_path ()" link="SoupCookie.html#soup-cookie-get-path" since="2.32"/> + <keyword type="function" name="soup_cookie_set_max_age ()" link="SoupCookie.html#soup-cookie-set-max-age" since="2.24"/> + <keyword type="macro" name="SOUP_COOKIE_MAX_AGE_ONE_HOUR" link="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-HOUR:CAPS" since="2.24"/> + <keyword type="macro" name="SOUP_COOKIE_MAX_AGE_ONE_DAY" link="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-DAY:CAPS" since="2.24"/> + <keyword type="macro" name="SOUP_COOKIE_MAX_AGE_ONE_WEEK" link="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-WEEK:CAPS" since="2.24"/> + <keyword type="macro" name="SOUP_COOKIE_MAX_AGE_ONE_YEAR" link="SoupCookie.html#SOUP-COOKIE-MAX-AGE-ONE-YEAR:CAPS" since="2.24"/> + <keyword type="function" name="soup_cookie_set_expires ()" link="SoupCookie.html#soup-cookie-set-expires" since="2.24"/> + <keyword type="function" name="soup_cookie_get_expires ()" link="SoupCookie.html#soup-cookie-get-expires" since="2.32"/> + <keyword type="function" name="soup_cookie_set_secure ()" link="SoupCookie.html#soup-cookie-set-secure" since="2.24"/> + <keyword type="function" name="soup_cookie_get_secure ()" link="SoupCookie.html#soup-cookie-get-secure" since="2.32"/> + <keyword type="function" name="soup_cookie_set_http_only ()" link="SoupCookie.html#soup-cookie-set-http-only" since="2.24"/> + <keyword type="function" name="soup_cookie_get_http_only ()" link="SoupCookie.html#soup-cookie-get-http-only" since="2.32"/> + <keyword type="function" name="soup_cookie_applies_to_uri ()" link="SoupCookie.html#soup-cookie-applies-to-uri" since="2.24"/> + <keyword type="function" name="soup_cookie_domain_matches ()" link="SoupCookie.html#soup-cookie-domain-matches" since="2.30"/> + <keyword type="function" name="soup_cookie_to_cookie_header ()" link="SoupCookie.html#soup-cookie-to-cookie-header" since="2.24"/> + <keyword type="function" name="soup_cookie_to_set_cookie_header ()" link="SoupCookie.html#soup-cookie-to-set-cookie-header" since="2.24"/> + <keyword type="function" name="soup_cookies_from_request ()" link="SoupCookie.html#soup-cookies-from-request" since="2.24"/> + <keyword type="function" name="soup_cookies_from_response ()" link="SoupCookie.html#soup-cookies-from-response" since="2.24"/> + <keyword type="function" name="soup_cookies_to_request ()" link="SoupCookie.html#soup-cookies-to-request" since="2.24"/> + <keyword type="function" name="soup_cookies_to_response ()" link="SoupCookie.html#soup-cookies-to-response" since="2.24"/> + <keyword type="function" name="soup_cookies_to_cookie_header ()" link="SoupCookie.html#soup-cookies-to-cookie-header" since="2.24"/> + <keyword type="function" name="soup_cookies_free ()" link="SoupCookie.html#soup-cookies-free" since="2.24"/> + <keyword type="struct" name="SoupCookie" link="SoupCookie.html#SoupCookie-struct"/> + <keyword type="function" name="soup_message_new ()" link="SoupMessage.html#soup-message-new"/> + <keyword type="function" name="soup_message_new_from_uri ()" link="SoupMessage.html#soup-message-new-from-uri"/> + <keyword type="function" name="soup_message_set_request ()" link="SoupMessage.html#soup-message-set-request"/> + <keyword type="function" name="soup_message_set_response ()" link="SoupMessage.html#soup-message-set-response"/> + <keyword type="function" name="soup_message_set_http_version ()" link="SoupMessage.html#soup-message-set-http-version"/> + <keyword type="function" name="soup_message_get_http_version ()" link="SoupMessage.html#soup-message-get-http-version"/> + <keyword type="function" name="soup_message_get_uri ()" link="SoupMessage.html#soup-message-get-uri"/> + <keyword type="function" name="soup_message_set_uri ()" link="SoupMessage.html#soup-message-set-uri"/> + <keyword type="function" name="soup_message_get_address ()" link="SoupMessage.html#soup-message-get-address" since="2.26"/> + <keyword type="function" name="soup_message_set_status ()" link="SoupMessage.html#soup-message-set-status"/> + <keyword type="function" name="soup_message_set_status_full ()" link="SoupMessage.html#soup-message-set-status-full"/> + <keyword type="function" name="soup_message_set_redirect ()" link="SoupMessage.html#soup-message-set-redirect" since="2.38"/> + <keyword type="function" name="soup_message_is_keepalive ()" link="SoupMessage.html#soup-message-is-keepalive"/> + <keyword type="function" name="soup_message_get_https_status ()" link="SoupMessage.html#soup-message-get-https-status" since="2.34"/> + <keyword type="function" name="soup_message_set_first_party ()" link="SoupMessage.html#soup-message-set-first-party" since="2.30"/> + <keyword type="function" name="soup_message_get_first_party ()" link="SoupMessage.html#soup-message-get-first-party" since="2.30"/> + <keyword type="function" name="soup_message_add_header_handler ()" link="SoupMessage.html#soup-message-add-header-handler"/> + <keyword type="function" name="soup_message_add_status_code_handler ()" link="SoupMessage.html#soup-message-add-status-code-handler"/> + <keyword type="function" name="soup_message_set_flags ()" link="SoupMessage.html#soup-message-set-flags"/> + <keyword type="function" name="soup_message_get_flags ()" link="SoupMessage.html#soup-message-get-flags"/> + <keyword type="function" name="SoupChunkAllocator ()" link="SoupMessage.html#SoupChunkAllocator" deprecated=""/> + <keyword type="function" name="soup_message_set_chunk_allocator ()" link="SoupMessage.html#soup-message-set-chunk-allocator" deprecated=""/> + <keyword type="function" name="soup_message_disable_feature ()" link="SoupMessage.html#soup-message-disable-feature" since="2.28"/> + <keyword type="function" name="soup_message_get_soup_request ()" link="SoupMessage.html#soup-message-get-soup-request" since="2.42"/> + <keyword type="function" name="soup_message_get_priority ()" link="SoupMessage.html#soup-message-get-priority" since="2.44"/> + <keyword type="function" name="soup_message_set_priority ()" link="SoupMessage.html#soup-message-set-priority" since="2.44"/> + <keyword type="struct" name="SoupMessage" link="SoupMessage.html#SoupMessage-struct"/> + <keyword type="enum" name="enum SoupHTTPVersion" link="SoupMessage.html#SoupHTTPVersion"/> + <keyword type="enum" name="enum SoupMessageFlags" link="SoupMessage.html#SoupMessageFlags"/> + <keyword type="enum" name="enum SoupMessagePriority" link="SoupMessage.html#SoupMessagePriority"/> + <keyword type="macro" name="SOUP_MESSAGE_METHOD" link="SoupMessage.html#SOUP-MESSAGE-METHOD:CAPS"/> + <keyword type="macro" name="SOUP_MESSAGE_URI" link="SoupMessage.html#SOUP-MESSAGE-URI:CAPS"/> + <keyword type="macro" name="SOUP_MESSAGE_HTTP_VERSION" link="SoupMessage.html#SOUP-MESSAGE-HTTP-VERSION:CAPS"/> + <keyword type="macro" name="SOUP_MESSAGE_FLAGS" link="SoupMessage.html#SOUP-MESSAGE-FLAGS:CAPS"/> + <keyword type="macro" name="SOUP_MESSAGE_STATUS_CODE" link="SoupMessage.html#SOUP-MESSAGE-STATUS-CODE:CAPS"/> + <keyword type="macro" name="SOUP_MESSAGE_REASON_PHRASE" link="SoupMessage.html#SOUP-MESSAGE-REASON-PHRASE:CAPS"/> + <keyword type="macro" name="SOUP_MESSAGE_SERVER_SIDE" link="SoupMessage.html#SOUP-MESSAGE-SERVER-SIDE:CAPS"/> + <keyword type="macro" name="SOUP_MESSAGE_FIRST_PARTY" link="SoupMessage.html#SOUP-MESSAGE-FIRST-PARTY:CAPS" since="2.30"/> + <keyword type="macro" name="SOUP_MESSAGE_PRIORITY" link="SoupMessage.html#SOUP-MESSAGE-PRIORITY:CAPS" since="2.44"/> + <keyword type="macro" name="SOUP_MESSAGE_REQUEST_BODY" link="SoupMessage.html#SOUP-MESSAGE-REQUEST-BODY:CAPS"/> + <keyword type="macro" name="SOUP_MESSAGE_REQUEST_BODY_DATA" link="SoupMessage.html#SOUP-MESSAGE-REQUEST-BODY-DATA:CAPS" since="2.46"/> + <keyword type="macro" name="SOUP_MESSAGE_REQUEST_HEADERS" link="SoupMessage.html#SOUP-MESSAGE-REQUEST-HEADERS:CAPS"/> + <keyword type="macro" name="SOUP_MESSAGE_RESPONSE_BODY" link="SoupMessage.html#SOUP-MESSAGE-RESPONSE-BODY:CAPS"/> + <keyword type="macro" name="SOUP_MESSAGE_RESPONSE_BODY_DATA" link="SoupMessage.html#SOUP-MESSAGE-RESPONSE-BODY-DATA:CAPS" since="2.46"/> + <keyword type="macro" name="SOUP_MESSAGE_RESPONSE_HEADERS" link="SoupMessage.html#SOUP-MESSAGE-RESPONSE-HEADERS:CAPS"/> + <keyword type="macro" name="SOUP_MESSAGE_TLS_CERTIFICATE" link="SoupMessage.html#SOUP-MESSAGE-TLS-CERTIFICATE:CAPS" since="2.34"/> + <keyword type="macro" name="SOUP_MESSAGE_TLS_ERRORS" link="SoupMessage.html#SOUP-MESSAGE-TLS-ERRORS:CAPS" since="2.34"/> + <keyword type="property" name="The “first-party” property" link="SoupMessage.html#SoupMessage--first-party"/> + <keyword type="property" name="The “flags” property" link="SoupMessage.html#SoupMessage--flags"/> + <keyword type="property" name="The “http-version” property" link="SoupMessage.html#SoupMessage--http-version"/> + <keyword type="property" name="The “method” property" link="SoupMessage.html#SoupMessage--method"/> + <keyword type="property" name="The “priority” property" link="SoupMessage.html#SoupMessage--priority"/> + <keyword type="property" name="The “reason-phrase” property" link="SoupMessage.html#SoupMessage--reason-phrase"/> + <keyword type="property" name="The “request-body” property" link="SoupMessage.html#SoupMessage--request-body"/> + <keyword type="property" name="The “request-body-data” property" link="SoupMessage.html#SoupMessage--request-body-data"/> + <keyword type="property" name="The “request-headers” property" link="SoupMessage.html#SoupMessage--request-headers"/> + <keyword type="property" name="The “response-body” property" link="SoupMessage.html#SoupMessage--response-body"/> + <keyword type="property" name="The “response-body-data” property" link="SoupMessage.html#SoupMessage--response-body-data"/> + <keyword type="property" name="The “response-headers” property" link="SoupMessage.html#SoupMessage--response-headers"/> + <keyword type="property" name="The “server-side” property" link="SoupMessage.html#SoupMessage--server-side"/> + <keyword type="property" name="The “status-code” property" link="SoupMessage.html#SoupMessage--status-code"/> + <keyword type="property" name="The “tls-certificate” property" link="SoupMessage.html#SoupMessage--tls-certificate"/> + <keyword type="property" name="The “tls-errors” property" link="SoupMessage.html#SoupMessage--tls-errors"/> + <keyword type="property" name="The “uri” property" link="SoupMessage.html#SoupMessage--uri"/> + <keyword type="signal" name="The “content-sniffed” signal" link="SoupMessage.html#SoupMessage-content-sniffed"/> + <keyword type="signal" name="The “finished” signal" link="SoupMessage.html#SoupMessage-finished"/> + <keyword type="signal" name="The “got-body” signal" link="SoupMessage.html#SoupMessage-got-body"/> + <keyword type="signal" name="The “got-chunk” signal" link="SoupMessage.html#SoupMessage-got-chunk"/> + <keyword type="signal" name="The “got-headers” signal" link="SoupMessage.html#SoupMessage-got-headers"/> + <keyword type="signal" name="The “got-informational” signal" link="SoupMessage.html#SoupMessage-got-informational"/> + <keyword type="signal" name="The “network-event” signal" link="SoupMessage.html#SoupMessage-network-event"/> + <keyword type="signal" name="The “restarted” signal" link="SoupMessage.html#SoupMessage-restarted"/> + <keyword type="signal" name="The “wrote-body” signal" link="SoupMessage.html#SoupMessage-wrote-body"/> + <keyword type="signal" name="The “wrote-body-data” signal" link="SoupMessage.html#SoupMessage-wrote-body-data"/> + <keyword type="signal" name="The “wrote-chunk” signal" link="SoupMessage.html#SoupMessage-wrote-chunk"/> + <keyword type="signal" name="The “wrote-headers” signal" link="SoupMessage.html#SoupMessage-wrote-headers"/> + <keyword type="signal" name="The “wrote-informational” signal" link="SoupMessage.html#SoupMessage-wrote-informational"/> + <keyword type="function" name="soup_message_headers_new ()" link="SoupMessageHeaders.html#soup-message-headers-new"/> + <keyword type="function" name="soup_message_headers_free ()" link="SoupMessageHeaders.html#soup-message-headers-free"/> + <keyword type="function" name="soup_message_headers_append ()" link="SoupMessageHeaders.html#soup-message-headers-append"/> + <keyword type="function" name="soup_message_headers_replace ()" link="SoupMessageHeaders.html#soup-message-headers-replace"/> + <keyword type="function" name="soup_message_headers_remove ()" link="SoupMessageHeaders.html#soup-message-headers-remove"/> + <keyword type="function" name="soup_message_headers_clear ()" link="SoupMessageHeaders.html#soup-message-headers-clear"/> + <keyword type="function" name="soup_message_headers_clean_connection_headers ()" link="SoupMessageHeaders.html#soup-message-headers-clean-connection-headers" since="2.36"/> + <keyword type="function" name="soup_message_headers_get_one ()" link="SoupMessageHeaders.html#soup-message-headers-get-one" since="2.28"/> + <keyword type="function" name="soup_message_headers_get_list ()" link="SoupMessageHeaders.html#soup-message-headers-get-list" since="2.28"/> + <keyword type="function" name="soup_message_headers_get ()" link="SoupMessageHeaders.html#soup-message-headers-get" deprecated=""/> + <keyword type="function" name="SoupMessageHeadersForeachFunc ()" link="SoupMessageHeaders.html#SoupMessageHeadersForeachFunc"/> + <keyword type="function" name="soup_message_headers_foreach ()" link="SoupMessageHeaders.html#soup-message-headers-foreach"/> + <keyword type="function" name="soup_message_headers_iter_init ()" link="SoupMessageHeaders.html#soup-message-headers-iter-init"/> + <keyword type="function" name="soup_message_headers_iter_next ()" link="SoupMessageHeaders.html#soup-message-headers-iter-next"/> + <keyword type="function" name="soup_message_headers_get_encoding ()" link="SoupMessageHeaders.html#soup-message-headers-get-encoding"/> + <keyword type="function" name="soup_message_headers_set_encoding ()" link="SoupMessageHeaders.html#soup-message-headers-set-encoding"/> + <keyword type="function" name="soup_message_headers_get_content_length ()" link="SoupMessageHeaders.html#soup-message-headers-get-content-length"/> + <keyword type="function" name="soup_message_headers_set_content_length ()" link="SoupMessageHeaders.html#soup-message-headers-set-content-length"/> + <keyword type="function" name="soup_message_headers_get_expectations ()" link="SoupMessageHeaders.html#soup-message-headers-get-expectations"/> + <keyword type="function" name="soup_message_headers_set_expectations ()" link="SoupMessageHeaders.html#soup-message-headers-set-expectations"/> + <keyword type="function" name="soup_message_headers_get_content_type ()" link="SoupMessageHeaders.html#soup-message-headers-get-content-type" since="2.26"/> + <keyword type="function" name="soup_message_headers_set_content_type ()" link="SoupMessageHeaders.html#soup-message-headers-set-content-type" since="2.26"/> + <keyword type="function" name="soup_message_headers_get_content_disposition ()" link="SoupMessageHeaders.html#soup-message-headers-get-content-disposition" since="2.26"/> + <keyword type="function" name="soup_message_headers_set_content_disposition ()" link="SoupMessageHeaders.html#soup-message-headers-set-content-disposition" since="2.26"/> + <keyword type="function" name="soup_message_headers_get_ranges ()" link="SoupMessageHeaders.html#soup-message-headers-get-ranges" since="2.26"/> + <keyword type="function" name="soup_message_headers_set_ranges ()" link="SoupMessageHeaders.html#soup-message-headers-set-ranges" since="2.26"/> + <keyword type="function" name="soup_message_headers_set_range ()" link="SoupMessageHeaders.html#soup-message-headers-set-range" since="2.26"/> + <keyword type="function" name="soup_message_headers_free_ranges ()" link="SoupMessageHeaders.html#soup-message-headers-free-ranges" since="2.26"/> + <keyword type="function" name="soup_message_headers_get_content_range ()" link="SoupMessageHeaders.html#soup-message-headers-get-content-range" since="2.26"/> + <keyword type="function" name="soup_message_headers_set_content_range ()" link="SoupMessageHeaders.html#soup-message-headers-set-content-range" since="2.26"/> + <keyword type="typedef" name="SoupMessageHeaders" link="SoupMessageHeaders.html#SoupMessageHeaders"/> + <keyword type="enum" name="enum SoupMessageHeadersType" link="SoupMessageHeaders.html#SoupMessageHeadersType"/> + <keyword type="struct" name="SoupMessageHeadersIter" link="SoupMessageHeaders.html#SoupMessageHeadersIter"/> + <keyword type="enum" name="enum SoupEncoding" link="SoupMessageHeaders.html#SoupEncoding"/> + <keyword type="enum" name="enum SoupExpectation" link="SoupMessageHeaders.html#SoupExpectation"/> + <keyword type="struct" name="SoupRange" link="SoupMessageHeaders.html#SoupRange" since="2.26"/> + <keyword type="function" name="soup_buffer_new ()" link="SoupMessageBody.html#soup-buffer-new"/> + <keyword type="function" name="soup_buffer_new_subbuffer ()" link="SoupMessageBody.html#soup-buffer-new-subbuffer"/> + <keyword type="function" name="soup_buffer_new_with_owner ()" link="SoupMessageBody.html#soup-buffer-new-with-owner"/> + <keyword type="function" name="soup_buffer_new_take ()" link="SoupMessageBody.html#soup-buffer-new-take" since="2.32"/> + <keyword type="function" name="soup_buffer_get_owner ()" link="SoupMessageBody.html#soup-buffer-get-owner"/> + <keyword type="function" name="soup_buffer_get_data ()" link="SoupMessageBody.html#soup-buffer-get-data" since="2.32"/> + <keyword type="function" name="soup_buffer_copy ()" link="SoupMessageBody.html#soup-buffer-copy"/> + <keyword type="function" name="soup_buffer_free ()" link="SoupMessageBody.html#soup-buffer-free"/> + <keyword type="function" name="soup_buffer_get_as_bytes ()" link="SoupMessageBody.html#soup-buffer-get-as-bytes" since="2.40"/> + <keyword type="function" name="soup_message_body_new ()" link="SoupMessageBody.html#soup-message-body-new"/> + <keyword type="function" name="soup_message_body_free ()" link="SoupMessageBody.html#soup-message-body-free"/> + <keyword type="function" name="soup_message_body_set_accumulate ()" link="SoupMessageBody.html#soup-message-body-set-accumulate" since="2.24"/> + <keyword type="function" name="soup_message_body_get_accumulate ()" link="SoupMessageBody.html#soup-message-body-get-accumulate" since="2.24"/> + <keyword type="function" name="soup_message_body_append ()" link="SoupMessageBody.html#soup-message-body-append"/> + <keyword type="function" name="soup_message_body_append_buffer ()" link="SoupMessageBody.html#soup-message-body-append-buffer"/> + <keyword type="function" name="soup_message_body_append_take ()" link="SoupMessageBody.html#soup-message-body-append-take" since="2.32"/> + <keyword type="function" name="soup_message_body_truncate ()" link="SoupMessageBody.html#soup-message-body-truncate"/> + <keyword type="function" name="soup_message_body_complete ()" link="SoupMessageBody.html#soup-message-body-complete"/> + <keyword type="function" name="soup_message_body_flatten ()" link="SoupMessageBody.html#soup-message-body-flatten"/> + <keyword type="function" name="soup_message_body_get_chunk ()" link="SoupMessageBody.html#soup-message-body-get-chunk"/> + <keyword type="function" name="soup_message_body_got_chunk ()" link="SoupMessageBody.html#soup-message-body-got-chunk" since="2.24"/> + <keyword type="function" name="soup_message_body_wrote_chunk ()" link="SoupMessageBody.html#soup-message-body-wrote-chunk" since="2.24"/> + <keyword type="struct" name="SoupBuffer" link="SoupMessageBody.html#SoupBuffer-struct"/> + <keyword type="enum" name="enum SoupMemoryUse" link="SoupMessageBody.html#SoupMemoryUse"/> + <keyword type="struct" name="SoupMessageBody" link="SoupMessageBody.html#SoupMessageBody-struct"/> + <keyword type="macro" name="SOUP_METHOD_OPTIONS" link="libsoup-2.4-soup-method.html#SOUP-METHOD-OPTIONS:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_GET" link="libsoup-2.4-soup-method.html#SOUP-METHOD-GET:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_HEAD" link="libsoup-2.4-soup-method.html#SOUP-METHOD-HEAD:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_PUT" link="libsoup-2.4-soup-method.html#SOUP-METHOD-PUT:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_POST" link="libsoup-2.4-soup-method.html#SOUP-METHOD-POST:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_DELETE" link="libsoup-2.4-soup-method.html#SOUP-METHOD-DELETE:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_TRACE" link="libsoup-2.4-soup-method.html#SOUP-METHOD-TRACE:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_CONNECT" link="libsoup-2.4-soup-method.html#SOUP-METHOD-CONNECT:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_PROPFIND" link="libsoup-2.4-soup-method.html#SOUP-METHOD-PROPFIND:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_PROPPATCH" link="libsoup-2.4-soup-method.html#SOUP-METHOD-PROPPATCH:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_MKCOL" link="libsoup-2.4-soup-method.html#SOUP-METHOD-MKCOL:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_COPY" link="libsoup-2.4-soup-method.html#SOUP-METHOD-COPY:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_MOVE" link="libsoup-2.4-soup-method.html#SOUP-METHOD-MOVE:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_LOCK" link="libsoup-2.4-soup-method.html#SOUP-METHOD-LOCK:CAPS"/> + <keyword type="macro" name="SOUP_METHOD_UNLOCK" link="libsoup-2.4-soup-method.html#SOUP-METHOD-UNLOCK:CAPS"/> + <keyword type="function" name="soup_date_new ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new"/> + <keyword type="function" name="soup_date_new_from_string ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-string"/> + <keyword type="function" name="soup_date_new_from_time_t ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-time-t"/> + <keyword type="function" name="soup_date_new_from_now ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-new-from-now"/> + <keyword type="function" name="soup_date_to_string ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-string"/> + <keyword type="function" name="soup_date_to_time_t ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-time-t"/> + <keyword type="function" name="soup_date_to_timeval ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-to-timeval" since="2.24"/> + <keyword type="function" name="soup_date_is_past ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-is-past" since="2.24"/> + <keyword type="function" name="soup_date_get_day ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-day" since="2.32"/> + <keyword type="function" name="soup_date_get_hour ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-hour" since="2.32"/> + <keyword type="function" name="soup_date_get_minute ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-minute" since="2.32"/> + <keyword type="function" name="soup_date_get_month ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-month" since="2.32"/> + <keyword type="function" name="soup_date_get_offset ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-offset" since="2.32"/> + <keyword type="function" name="soup_date_get_second ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-second" since="2.32"/> + <keyword type="function" name="soup_date_get_utc ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-utc" since="2.32"/> + <keyword type="function" name="soup_date_get_year ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-get-year" since="2.32"/> + <keyword type="function" name="soup_date_free ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-date-free" since="2.24"/> + <keyword type="function" name="soup_headers_parse_request ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-request"/> + <keyword type="function" name="soup_headers_parse_response ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-response"/> + <keyword type="function" name="soup_headers_parse_status_line ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse-status-line"/> + <keyword type="function" name="soup_headers_parse ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-headers-parse" since="2.26"/> + <keyword type="function" name="soup_header_parse_list ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-list"/> + <keyword type="function" name="soup_header_parse_quality_list ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-quality-list"/> + <keyword type="function" name="soup_header_free_list ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-free-list"/> + <keyword type="function" name="soup_header_contains ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-contains"/> + <keyword type="function" name="soup_header_parse_param_list ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-param-list"/> + <keyword type="function" name="soup_header_parse_semi_param_list ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-semi-param-list" since="2.24"/> + <keyword type="function" name="soup_header_free_param_list ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-free-param-list"/> + <keyword type="function" name="soup_header_g_string_append_param ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-g-string-append-param" since="2.26"/> + <keyword type="function" name="soup_header_g_string_append_param_quoted ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-g-string-append-param-quoted" since="2.30"/> + <keyword type="function" name="soup_str_case_equal ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-str-case-equal"/> + <keyword type="function" name="soup_str_case_hash ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-str-case-hash"/> + <keyword type="function" name="soup_add_completion ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-completion" since="2.24"/> + <keyword type="function" name="soup_add_idle ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-idle"/> + <keyword type="function" name="soup_add_io_watch ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-io-watch"/> + <keyword type="function" name="soup_add_timeout ()" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-add-timeout"/> + <keyword type="struct" name="SoupDate" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDate-struct"/> + <keyword type="enum" name="enum SoupDateFormat" link="libsoup-2.4-Soup-Miscellaneous-Utilities.html#SoupDateFormat"/> + <keyword type="function" name="soup_multipart_new ()" link="SoupMultipart.html#soup-multipart-new" since="2.26"/> + <keyword type="function" name="soup_multipart_new_from_message ()" link="SoupMultipart.html#soup-multipart-new-from-message" since="2.26"/> + <keyword type="function" name="soup_multipart_free ()" link="SoupMultipart.html#soup-multipart-free" since="2.26"/> + <keyword type="function" name="soup_multipart_get_length ()" link="SoupMultipart.html#soup-multipart-get-length" since="2.26"/> + <keyword type="function" name="soup_multipart_get_part ()" link="SoupMultipart.html#soup-multipart-get-part" since="2.26"/> + <keyword type="function" name="soup_multipart_append_part ()" link="SoupMultipart.html#soup-multipart-append-part" since="2.26"/> + <keyword type="function" name="soup_multipart_append_form_string ()" link="SoupMultipart.html#soup-multipart-append-form-string" since="2.26"/> + <keyword type="function" name="soup_multipart_append_form_file ()" link="SoupMultipart.html#soup-multipart-append-form-file" since="2.26"/> + <keyword type="function" name="soup_multipart_to_message ()" link="SoupMultipart.html#soup-multipart-to-message" since="2.26"/> + <keyword type="typedef" name="SoupMultipart" link="SoupMultipart.html#SoupMultipart" since="2.26"/> + <keyword type="function" name="soup_multipart_input_stream_new ()" link="SoupMultipartInputStream.html#soup-multipart-input-stream-new" since="2.40"/> + <keyword type="function" name="soup_multipart_input_stream_get_headers ()" link="SoupMultipartInputStream.html#soup-multipart-input-stream-get-headers" since="2.40"/> + <keyword type="function" name="soup_multipart_input_stream_next_part ()" link="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part" since="2.40"/> + <keyword type="function" name="soup_multipart_input_stream_next_part_async ()" link="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part-async" since="2.40"/> + <keyword type="function" name="soup_multipart_input_stream_next_part_finish ()" link="SoupMultipartInputStream.html#soup-multipart-input-stream-next-part-finish" since="2.40"/> + <keyword type="struct" name="struct SoupMultipartInputStream" link="SoupMultipartInputStream.html#SoupMultipartInputStream-struct"/> + <keyword type="property" name="The “message” property" link="SoupMultipartInputStream.html#SoupMultipartInputStream--message"/> + <keyword type="function" name="soup_request_send ()" link="SoupRequest.html#soup-request-send" since="2.42"/> + <keyword type="function" name="soup_request_send_async ()" link="SoupRequest.html#soup-request-send-async" since="2.42"/> + <keyword type="function" name="soup_request_send_finish ()" link="SoupRequest.html#soup-request-send-finish" since="2.42"/> + <keyword type="function" name="soup_request_get_content_length ()" link="SoupRequest.html#soup-request-get-content-length" since="2.42"/> + <keyword type="function" name="soup_request_get_content_type ()" link="SoupRequest.html#soup-request-get-content-type" since="2.42"/> + <keyword type="function" name="soup_request_get_session ()" link="SoupRequest.html#soup-request-get-session" since="2.42"/> + <keyword type="function" name="soup_request_get_uri ()" link="SoupRequest.html#soup-request-get-uri" since="2.42"/> + <keyword type="struct" name="SoupRequest" link="SoupRequest.html#SoupRequest-struct"/> + <keyword type="macro" name="SOUP_REQUEST_SESSION" link="SoupRequest.html#SOUP-REQUEST-SESSION:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_REQUEST_URI" link="SoupRequest.html#SOUP-REQUEST-URI:CAPS" since="2.42"/> + <keyword type="property" name="The “session” property" link="SoupRequest.html#SoupRequest--session"/> + <keyword type="property" name="The “uri” property" link="SoupRequest.html#SoupRequest--uri"/> + <keyword type="function" name="soup_request_http_get_message ()" link="SoupRequestHTTP.html#soup-request-http-get-message" since="2.40"/> + <keyword type="struct" name="SoupRequestHTTP" link="SoupRequestHTTP.html#SoupRequestHTTP-struct"/> + <keyword type="function" name="soup_request_file_get_file ()" link="SoupRequestFile.html#soup-request-file-get-file" since="2.40"/> + <keyword type="struct" name="SoupRequestFile" link="SoupRequestFile.html#SoupRequestFile-struct"/> + <keyword type="struct" name="SoupRequestData" link="SoupRequestData.html#SoupRequestData-struct"/> + <keyword type="function" name="soup_server_new ()" link="SoupServer.html#soup-server-new"/> + <keyword type="function" name="soup_server_is_https ()" link="SoupServer.html#soup-server-is-https"/> + <keyword type="function" name="soup_server_get_port ()" link="SoupServer.html#soup-server-get-port"/> + <keyword type="function" name="soup_server_get_listener ()" link="SoupServer.html#soup-server-get-listener"/> + <keyword type="function" name="soup_server_run ()" link="SoupServer.html#soup-server-run"/> + <keyword type="function" name="soup_server_run_async ()" link="SoupServer.html#soup-server-run-async"/> + <keyword type="function" name="soup_server_quit ()" link="SoupServer.html#soup-server-quit"/> + <keyword type="function" name="soup_server_disconnect ()" link="SoupServer.html#soup-server-disconnect"/> + <keyword type="function" name="soup_server_get_async_context ()" link="SoupServer.html#soup-server-get-async-context"/> + <keyword type="function" name="SoupServerCallback ()" link="SoupServer.html#SoupServerCallback"/> + <keyword type="function" name="soup_server_add_handler ()" link="SoupServer.html#soup-server-add-handler"/> + <keyword type="function" name="soup_server_remove_handler ()" link="SoupServer.html#soup-server-remove-handler"/> + <keyword type="function" name="soup_client_context_get_socket ()" link="SoupServer.html#soup-client-context-get-socket"/> + <keyword type="function" name="soup_client_context_get_address ()" link="SoupServer.html#soup-client-context-get-address"/> + <keyword type="function" name="soup_client_context_get_host ()" link="SoupServer.html#soup-client-context-get-host"/> + <keyword type="function" name="soup_client_context_get_auth_domain ()" link="SoupServer.html#soup-client-context-get-auth-domain"/> + <keyword type="function" name="soup_client_context_get_auth_user ()" link="SoupServer.html#soup-client-context-get-auth-user"/> + <keyword type="function" name="soup_server_add_auth_domain ()" link="SoupServer.html#soup-server-add-auth-domain"/> + <keyword type="function" name="soup_server_remove_auth_domain ()" link="SoupServer.html#soup-server-remove-auth-domain"/> + <keyword type="function" name="soup_server_pause_message ()" link="SoupServer.html#soup-server-pause-message"/> + <keyword type="function" name="soup_server_unpause_message ()" link="SoupServer.html#soup-server-unpause-message"/> + <keyword type="struct" name="SoupServer" link="SoupServer.html#SoupServer-struct"/> + <keyword type="typedef" name="SoupClientContext" link="SoupServer.html#SoupClientContext"/> + <keyword type="macro" name="SOUP_SERVER_PORT" link="SoupServer.html#SOUP-SERVER-PORT:CAPS"/> + <keyword type="macro" name="SOUP_SERVER_INTERFACE" link="SoupServer.html#SOUP-SERVER-INTERFACE:CAPS"/> + <keyword type="macro" name="SOUP_SERVER_SSL_CERT_FILE" link="SoupServer.html#SOUP-SERVER-SSL-CERT-FILE:CAPS"/> + <keyword type="macro" name="SOUP_SERVER_SSL_KEY_FILE" link="SoupServer.html#SOUP-SERVER-SSL-KEY-FILE:CAPS"/> + <keyword type="macro" name="SOUP_SERVER_TLS_CERTIFICATE" link="SoupServer.html#SOUP-SERVER-TLS-CERTIFICATE:CAPS"/> + <keyword type="macro" name="SOUP_SERVER_ASYNC_CONTEXT" link="SoupServer.html#SOUP-SERVER-ASYNC-CONTEXT:CAPS"/> + <keyword type="macro" name="SOUP_SERVER_RAW_PATHS" link="SoupServer.html#SOUP-SERVER-RAW-PATHS:CAPS"/> + <keyword type="macro" name="SOUP_SERVER_SERVER_HEADER" link="SoupServer.html#SOUP-SERVER-SERVER-HEADER:CAPS"/> + <keyword type="macro" name="SOUP_SERVER_HTTP_ALIASES" link="SoupServer.html#SOUP-SERVER-HTTP-ALIASES:CAPS"/> + <keyword type="macro" name="SOUP_SERVER_HTTPS_ALIASES" link="SoupServer.html#SOUP-SERVER-HTTPS-ALIASES:CAPS" since="2.44"/> + <keyword type="property" name="The “async-context” property" link="SoupServer.html#SoupServer--async-context"/> + <keyword type="property" name="The “http-aliases” property" link="SoupServer.html#SoupServer--http-aliases"/> + <keyword type="property" name="The “https-aliases” property" link="SoupServer.html#SoupServer--https-aliases"/> + <keyword type="property" name="The “interface” property" link="SoupServer.html#SoupServer--interface"/> + <keyword type="property" name="The “port” property" link="SoupServer.html#SoupServer--port"/> + <keyword type="property" name="The “raw-paths” property" link="SoupServer.html#SoupServer--raw-paths"/> + <keyword type="property" name="The “server-header” property" link="SoupServer.html#SoupServer--server-header"/> + <keyword type="property" name="The “ssl-cert-file” property" link="SoupServer.html#SoupServer--ssl-cert-file"/> + <keyword type="property" name="The “ssl-key-file” property" link="SoupServer.html#SoupServer--ssl-key-file"/> + <keyword type="property" name="The “tls-certificate” property" link="SoupServer.html#SoupServer--tls-certificate"/> + <keyword type="signal" name="The “request-aborted” signal" link="SoupServer.html#SoupServer-request-aborted"/> + <keyword type="signal" name="The “request-finished” signal" link="SoupServer.html#SoupServer-request-finished"/> + <keyword type="signal" name="The “request-read” signal" link="SoupServer.html#SoupServer-request-read"/> + <keyword type="signal" name="The “request-started” signal" link="SoupServer.html#SoupServer-request-started"/> + <keyword type="function" name="soup_session_new ()" link="SoupSession.html#soup-session-new" since="2.42"/> + <keyword type="function" name="soup_session_new_with_options ()" link="SoupSession.html#soup-session-new-with-options" since="2.42"/> + <keyword type="function" name="soup_session_request ()" link="SoupSession.html#soup-session-request" since="2.42"/> + <keyword type="function" name="soup_session_request_uri ()" link="SoupSession.html#soup-session-request-uri" since="2.42"/> + <keyword type="function" name="soup_session_request_http ()" link="SoupSession.html#soup-session-request-http" since="2.42"/> + <keyword type="function" name="soup_session_request_http_uri ()" link="SoupSession.html#soup-session-request-http-uri" since="2.42"/> + <keyword type="function" name="SoupSessionCallback ()" link="SoupSession.html#SoupSessionCallback"/> + <keyword type="function" name="soup_session_queue_message ()" link="SoupSession.html#soup-session-queue-message"/> + <keyword type="function" name="soup_session_requeue_message ()" link="SoupSession.html#soup-session-requeue-message"/> + <keyword type="function" name="soup_session_send_message ()" link="SoupSession.html#soup-session-send-message"/> + <keyword type="function" name="soup_session_cancel_message ()" link="SoupSession.html#soup-session-cancel-message"/> + <keyword type="function" name="soup_session_send ()" link="SoupSession.html#soup-session-send" since="2.42"/> + <keyword type="function" name="soup_session_send_async ()" link="SoupSession.html#soup-session-send-async" since="2.42"/> + <keyword type="function" name="soup_session_send_finish ()" link="SoupSession.html#soup-session-send-finish" since="2.42"/> + <keyword type="function" name="soup_session_prefetch_dns ()" link="SoupSession.html#soup-session-prefetch-dns" since="2.38"/> + <keyword type="function" name="soup_session_prepare_for_uri ()" link="SoupSession.html#soup-session-prepare-for-uri" deprecated="2.38: use soup_session_prefetch_dns() instead" since="2.30"/> + <keyword type="function" name="soup_session_abort ()" link="SoupSession.html#soup-session-abort"/> + <keyword type="function" name="soup_session_would_redirect ()" link="SoupSession.html#soup-session-would-redirect" since="2.38"/> + <keyword type="function" name="soup_session_redirect_message ()" link="SoupSession.html#soup-session-redirect-message" since="2.38"/> + <keyword type="function" name="soup_session_pause_message ()" link="SoupSession.html#soup-session-pause-message"/> + <keyword type="function" name="soup_session_unpause_message ()" link="SoupSession.html#soup-session-unpause-message"/> + <keyword type="function" name="soup_session_get_async_context ()" link="SoupSession.html#soup-session-get-async-context"/> + <keyword type="function" name="soup_session_add_feature ()" link="SoupSession.html#soup-session-add-feature" since="2.24"/> + <keyword type="function" name="soup_session_add_feature_by_type ()" link="SoupSession.html#soup-session-add-feature-by-type" since="2.24"/> + <keyword type="function" name="soup_session_remove_feature ()" link="SoupSession.html#soup-session-remove-feature" since="2.24"/> + <keyword type="function" name="soup_session_remove_feature_by_type ()" link="SoupSession.html#soup-session-remove-feature-by-type" since="2.24"/> + <keyword type="function" name="soup_session_get_features ()" link="SoupSession.html#soup-session-get-features" since="2.26"/> + <keyword type="function" name="soup_session_get_feature ()" link="SoupSession.html#soup-session-get-feature" since="2.26"/> + <keyword type="function" name="soup_session_get_feature_for_message ()" link="SoupSession.html#soup-session-get-feature-for-message" since="2.28"/> + <keyword type="function" name="soup_session_has_feature ()" link="SoupSession.html#soup-session-has-feature" since="2.42"/> + <keyword type="struct" name="SoupSession" link="SoupSession.html#SoupSession-struct"/> + <keyword type="enum" name="enum SoupRequestError" link="SoupSession.html#SoupRequestError" since="2.42"/> + <keyword type="macro" name="SOUP_REQUEST_ERROR" link="SoupSession.html#SOUP-REQUEST-ERROR:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_SESSION_PROXY_URI" link="SoupSession.html#SOUP-SESSION-PROXY-URI:CAPS"/> + <keyword type="macro" name="SOUP_SESSION_PROXY_RESOLVER" link="SoupSession.html#SOUP-SESSION-PROXY-RESOLVER:CAPS"/> + <keyword type="macro" name="SOUP_SESSION_MAX_CONNS" link="SoupSession.html#SOUP-SESSION-MAX-CONNS:CAPS"/> + <keyword type="macro" name="SOUP_SESSION_MAX_CONNS_PER_HOST" link="SoupSession.html#SOUP-SESSION-MAX-CONNS-PER-HOST:CAPS"/> + <keyword type="macro" name="SOUP_SESSION_TLS_DATABASE" link="SoupSession.html#SOUP-SESSION-TLS-DATABASE:CAPS" since="2.38"/> + <keyword type="macro" name="SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE" link="SoupSession.html#SOUP-SESSION-SSL-USE-SYSTEM-CA-FILE:CAPS" since="2.38"/> + <keyword type="macro" name="SOUP_SESSION_SSL_CA_FILE" link="SoupSession.html#SOUP-SESSION-SSL-CA-FILE:CAPS"/> + <keyword type="macro" name="SOUP_SESSION_SSL_STRICT" link="SoupSession.html#SOUP-SESSION-SSL-STRICT:CAPS" since="2.30"/> + <keyword type="macro" name="SOUP_SESSION_ASYNC_CONTEXT" link="SoupSession.html#SOUP-SESSION-ASYNC-CONTEXT:CAPS"/> + <keyword type="macro" name="SOUP_SESSION_USE_THREAD_CONTEXT" link="SoupSession.html#SOUP-SESSION-USE-THREAD-CONTEXT:CAPS" since="2.38"/> + <keyword type="macro" name="SOUP_SESSION_TIMEOUT" link="SoupSession.html#SOUP-SESSION-TIMEOUT:CAPS"/> + <keyword type="macro" name="SOUP_SESSION_IDLE_TIMEOUT" link="SoupSession.html#SOUP-SESSION-IDLE-TIMEOUT:CAPS" since="2.24"/> + <keyword type="macro" name="SOUP_SESSION_USER_AGENT" link="SoupSession.html#SOUP-SESSION-USER-AGENT:CAPS"/> + <keyword type="macro" name="SOUP_SESSION_ADD_FEATURE" link="SoupSession.html#SOUP-SESSION-ADD-FEATURE:CAPS" since="2.24"/> + <keyword type="macro" name="SOUP_SESSION_ADD_FEATURE_BY_TYPE" link="SoupSession.html#SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS" since="2.24"/> + <keyword type="macro" name="SOUP_SESSION_REMOVE_FEATURE_BY_TYPE" link="SoupSession.html#SOUP-SESSION-REMOVE-FEATURE-BY-TYPE:CAPS" since="2.24"/> + <keyword type="macro" name="SOUP_SESSION_ACCEPT_LANGUAGE" link="SoupSession.html#SOUP-SESSION-ACCEPT-LANGUAGE:CAPS" since="2.30"/> + <keyword type="macro" name="SOUP_SESSION_ACCEPT_LANGUAGE_AUTO" link="SoupSession.html#SOUP-SESSION-ACCEPT-LANGUAGE-AUTO:CAPS" since="2.30"/> + <keyword type="macro" name="SOUP_SESSION_HTTP_ALIASES" link="SoupSession.html#SOUP-SESSION-HTTP-ALIASES:CAPS" since="2.38"/> + <keyword type="macro" name="SOUP_SESSION_HTTPS_ALIASES" link="SoupSession.html#SOUP-SESSION-HTTPS-ALIASES:CAPS" since="2.38"/> + <keyword type="macro" name="SOUP_SESSION_LOCAL_ADDRESS" link="SoupSession.html#SOUP-SESSION-LOCAL-ADDRESS:CAPS" since="2.42"/> + <keyword type="property" name="The “accept-language” property" link="SoupSession.html#SoupSession--accept-language"/> + <keyword type="property" name="The “accept-language-auto” property" link="SoupSession.html#SoupSession--accept-language-auto"/> + <keyword type="property" name="The “add-feature” property" link="SoupSession.html#SoupSession--add-feature"/> + <keyword type="property" name="The “add-feature-by-type” property" link="SoupSession.html#SoupSession--add-feature-by-type"/> + <keyword type="property" name="The “async-context” property" link="SoupSession.html#SoupSession--async-context"/> + <keyword type="property" name="The “http-aliases” property" link="SoupSession.html#SoupSession--http-aliases"/> + <keyword type="property" name="The “https-aliases” property" link="SoupSession.html#SoupSession--https-aliases"/> + <keyword type="property" name="The “idle-timeout” property" link="SoupSession.html#SoupSession--idle-timeout"/> + <keyword type="property" name="The “local-address” property" link="SoupSession.html#SoupSession--local-address"/> + <keyword type="property" name="The “max-conns” property" link="SoupSession.html#SoupSession--max-conns"/> + <keyword type="property" name="The “max-conns-per-host” property" link="SoupSession.html#SoupSession--max-conns-per-host"/> + <keyword type="property" name="The “proxy-resolver” property" link="SoupSession.html#SoupSession--proxy-resolver"/> + <keyword type="property" name="The “proxy-uri” property" link="SoupSession.html#SoupSession--proxy-uri"/> + <keyword type="property" name="The “remove-feature-by-type” property" link="SoupSession.html#SoupSession--remove-feature-by-type"/> + <keyword type="property" name="The “ssl-ca-file” property" link="SoupSession.html#SoupSession--ssl-ca-file"/> + <keyword type="property" name="The “ssl-strict” property" link="SoupSession.html#SoupSession--ssl-strict"/> + <keyword type="property" name="The “ssl-use-system-ca-file” property" link="SoupSession.html#SoupSession--ssl-use-system-ca-file"/> + <keyword type="property" name="The “timeout” property" link="SoupSession.html#SoupSession--timeout"/> + <keyword type="property" name="The “tls-database” property" link="SoupSession.html#SoupSession--tls-database"/> + <keyword type="property" name="The “use-ntlm” property" link="SoupSession.html#SoupSession--use-ntlm"/> + <keyword type="property" name="The “use-thread-context” property" link="SoupSession.html#SoupSession--use-thread-context"/> + <keyword type="property" name="The “user-agent” property" link="SoupSession.html#SoupSession--user-agent"/> + <keyword type="signal" name="The “authenticate” signal" link="SoupSession.html#SoupSession-authenticate"/> + <keyword type="signal" name="The “connection-created” signal" link="SoupSession.html#SoupSession-connection-created"/> + <keyword type="signal" name="The “request-queued” signal" link="SoupSession.html#SoupSession-request-queued"/> + <keyword type="signal" name="The “request-started” signal" link="SoupSession.html#SoupSession-request-started"/> + <keyword type="signal" name="The “request-unqueued” signal" link="SoupSession.html#SoupSession-request-unqueued"/> + <keyword type="signal" name="The “tunneling” signal" link="SoupSession.html#SoupSession-tunneling"/> + <keyword type="function" name="soup_session_async_new ()" link="SoupSessionAsync.html#soup-session-async-new" deprecated=""/> + <keyword type="function" name="soup_session_async_new_with_options ()" link="SoupSessionAsync.html#soup-session-async-new-with-options" deprecated=""/> + <keyword type="struct" name="SoupSessionAsync" link="SoupSessionAsync.html#SoupSessionAsync-struct"/> + <keyword type="function" name="soup_session_sync_new ()" link="SoupSessionSync.html#soup-session-sync-new" deprecated=""/> + <keyword type="function" name="soup_session_sync_new_with_options ()" link="SoupSessionSync.html#soup-session-sync-new-with-options" deprecated=""/> + <keyword type="struct" name="SoupSessionSync" link="SoupSessionSync.html#SoupSessionSync-struct"/> + <keyword type="macro" name="SOUP_STATUS_IS_TRANSPORT_ERROR()" link="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-TRANSPORT-ERROR:CAPS"/> + <keyword type="macro" name="SOUP_STATUS_IS_INFORMATIONAL()" link="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-INFORMATIONAL:CAPS"/> + <keyword type="macro" name="SOUP_STATUS_IS_SUCCESSFUL()" link="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-SUCCESSFUL:CAPS"/> + <keyword type="macro" name="SOUP_STATUS_IS_REDIRECTION()" link="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-REDIRECTION:CAPS"/> + <keyword type="macro" name="SOUP_STATUS_IS_CLIENT_ERROR()" link="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-CLIENT-ERROR:CAPS"/> + <keyword type="macro" name="SOUP_STATUS_IS_SERVER_ERROR()" link="libsoup-2.4-soup-status.html#SOUP-STATUS-IS-SERVER-ERROR:CAPS"/> + <keyword type="function" name="soup_status_get_phrase ()" link="libsoup-2.4-soup-status.html#soup-status-get-phrase"/> + <keyword type="function" name="soup_status_proxify ()" link="libsoup-2.4-soup-status.html#soup-status-proxify" since="2.26"/> + <keyword type="enum" name="enum SoupStatus" link="libsoup-2.4-soup-status.html#SoupStatus"/> + <keyword type="macro" name="SOUP_HTTP_ERROR" link="libsoup-2.4-soup-status.html#SOUP-HTTP-ERROR:CAPS"/> + <keyword type="function" name="soup_tld_get_base_domain ()" link="libsoup-2.4-Top-Level-Domain-utils.html#soup-tld-get-base-domain" since="2.40"/> + <keyword type="function" name="soup_tld_domain_is_public_suffix ()" link="libsoup-2.4-Top-Level-Domain-utils.html#soup-tld-domain-is-public-suffix" since="2.40"/> + <keyword type="macro" name="SOUP_TLD_ERROR" link="libsoup-2.4-Top-Level-Domain-utils.html#SOUP-TLD-ERROR:CAPS" since="2.40"/> + <keyword type="enum" name="enum SoupTLDError" link="libsoup-2.4-Top-Level-Domain-utils.html#SoupTLDError" since="2.40"/> + <keyword type="function" name="soup_uri_new_with_base ()" link="SoupURI.html#soup-uri-new-with-base"/> + <keyword type="function" name="soup_uri_new ()" link="SoupURI.html#soup-uri-new"/> + <keyword type="function" name="soup_uri_to_string ()" link="SoupURI.html#soup-uri-to-string"/> + <keyword type="function" name="soup_uri_copy ()" link="SoupURI.html#soup-uri-copy"/> + <keyword type="function" name="soup_uri_copy_host ()" link="SoupURI.html#soup-uri-copy-host" since="2.28"/> + <keyword type="function" name="soup_uri_equal ()" link="SoupURI.html#soup-uri-equal"/> + <keyword type="function" name="soup_uri_host_equal ()" link="SoupURI.html#soup-uri-host-equal" since="2.28"/> + <keyword type="function" name="soup_uri_host_hash ()" link="SoupURI.html#soup-uri-host-hash" since="2.28"/> + <keyword type="function" name="soup_uri_free ()" link="SoupURI.html#soup-uri-free"/> + <keyword type="function" name="soup_uri_encode ()" link="SoupURI.html#soup-uri-encode"/> + <keyword type="function" name="soup_uri_decode ()" link="SoupURI.html#soup-uri-decode"/> + <keyword type="function" name="soup_uri_normalize ()" link="SoupURI.html#soup-uri-normalize"/> + <keyword type="function" name="soup_uri_uses_default_port ()" link="SoupURI.html#soup-uri-uses-default-port"/> + <keyword type="macro" name="SOUP_URI_IS_VALID()" link="SoupURI.html#SOUP-URI-IS-VALID:CAPS" since="2.38"/> + <keyword type="macro" name="SOUP_URI_VALID_FOR_HTTP()" link="SoupURI.html#SOUP-URI-VALID-FOR-HTTP:CAPS" since="2.24"/> + <keyword type="function" name="soup_uri_set_scheme ()" link="SoupURI.html#soup-uri-set-scheme"/> + <keyword type="function" name="soup_uri_get_scheme ()" link="SoupURI.html#soup-uri-get-scheme" since="2.32"/> + <keyword type="function" name="soup_uri_set_user ()" link="SoupURI.html#soup-uri-set-user"/> + <keyword type="function" name="soup_uri_get_user ()" link="SoupURI.html#soup-uri-get-user" since="2.32"/> + <keyword type="function" name="soup_uri_set_password ()" link="SoupURI.html#soup-uri-set-password"/> + <keyword type="function" name="soup_uri_get_password ()" link="SoupURI.html#soup-uri-get-password" since="2.32"/> + <keyword type="function" name="soup_uri_set_host ()" link="SoupURI.html#soup-uri-set-host"/> + <keyword type="function" name="soup_uri_get_host ()" link="SoupURI.html#soup-uri-get-host" since="2.32"/> + <keyword type="function" name="soup_uri_set_port ()" link="SoupURI.html#soup-uri-set-port"/> + <keyword type="function" name="soup_uri_get_port ()" link="SoupURI.html#soup-uri-get-port" since="2.32"/> + <keyword type="function" name="soup_uri_set_path ()" link="SoupURI.html#soup-uri-set-path"/> + <keyword type="function" name="soup_uri_get_path ()" link="SoupURI.html#soup-uri-get-path" since="2.32"/> + <keyword type="function" name="soup_uri_set_query ()" link="SoupURI.html#soup-uri-set-query"/> + <keyword type="function" name="soup_uri_set_query_from_form ()" link="SoupURI.html#soup-uri-set-query-from-form"/> + <keyword type="function" name="soup_uri_set_query_from_fields ()" link="SoupURI.html#soup-uri-set-query-from-fields"/> + <keyword type="function" name="soup_uri_get_query ()" link="SoupURI.html#soup-uri-get-query" since="2.32"/> + <keyword type="function" name="soup_uri_set_fragment ()" link="SoupURI.html#soup-uri-set-fragment"/> + <keyword type="function" name="soup_uri_get_fragment ()" link="SoupURI.html#soup-uri-get-fragment" since="2.32"/> + <keyword type="struct" name="SoupURI" link="SoupURI.html#SoupURI-struct"/> + <keyword type="macro" name="SOUP_URI_SCHEME_HTTP" link="SoupURI.html#SOUP-URI-SCHEME-HTTP:CAPS"/> + <keyword type="macro" name="SOUP_URI_SCHEME_HTTPS" link="SoupURI.html#SOUP-URI-SCHEME-HTTPS:CAPS"/> + <keyword type="macro" name="SOUP_URI_SCHEME_DATA" link="SoupURI.html#SOUP-URI-SCHEME-DATA:CAPS" since="2.30"/> + <keyword type="macro" name="SOUP_URI_SCHEME_FILE" link="SoupURI.html#SOUP-URI-SCHEME-FILE:CAPS" since="2.30"/> + <keyword type="macro" name="SOUP_URI_SCHEME_FTP" link="SoupURI.html#SOUP-URI-SCHEME-FTP:CAPS" since="2.30"/> + <keyword type="macro" name="SOUP_URI_SCHEME_RESOURCE" link="SoupURI.html#SOUP-URI-SCHEME-RESOURCE:CAPS" since="2.42"/> + <keyword type="function" name="soup_get_major_version ()" link="libsoup-2.4-Version-Information.html#soup-get-major-version" since="2.42"/> + <keyword type="function" name="soup_get_minor_version ()" link="libsoup-2.4-Version-Information.html#soup-get-minor-version" since="2.42"/> + <keyword type="function" name="soup_get_micro_version ()" link="libsoup-2.4-Version-Information.html#soup-get-micro-version" since="2.42"/> + <keyword type="function" name="soup_check_version ()" link="libsoup-2.4-Version-Information.html#soup-check-version" since="2.42"/> + <keyword type="macro" name="SOUP_MAJOR_VERSION" link="libsoup-2.4-Version-Information.html#SOUP-MAJOR-VERSION:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_MINOR_VERSION" link="libsoup-2.4-Version-Information.html#SOUP-MINOR-VERSION:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_MICRO_VERSION" link="libsoup-2.4-Version-Information.html#SOUP-MICRO-VERSION:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_CHECK_VERSION()" link="libsoup-2.4-Version-Information.html#SOUP-CHECK-VERSION:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_MIN_REQUIRED" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_MAX_ALLOWED" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_2_24" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-24:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_2_26" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-26:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_2_28" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-28:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_2_30" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-30:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_2_32" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-32:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_2_34" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-34:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_2_36" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-36:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_2_38" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-38:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_2_40" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-40:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_2_42" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-42:CAPS" since="2.42"/> + <keyword type="macro" name="SOUP_VERSION_2_44" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-44:CAPS" since="2.44"/> + <keyword type="macro" name="SOUP_VERSION_2_46" link="libsoup-2.4-Version-Information.html#SOUP-VERSION-2-46:CAPS" since="2.46"/> + <keyword type="struct" name="SoupSessionFeature" link="SoupSessionFeature.html#SoupSessionFeature-struct"/> + <keyword type="struct" name="SoupSessionFeatureInterface" link="SoupSessionFeature.html#SoupSessionFeatureInterface" since="2.24"/> + <keyword type="macro" name="SOUP_TYPE_AUTH_MANAGER" link="SoupAuthManager.html#SOUP-TYPE-AUTH-MANAGER:CAPS" since="2.42"/> + <keyword type="function" name="soup_auth_manager_use_auth ()" link="SoupAuthManager.html#soup-auth-manager-use-auth" since="2.42"/> + <keyword type="struct" name="SoupAuthManager" link="SoupAuthManager.html#SoupAuthManager-struct"/> + <keyword type="signal" name="The “authenticate” signal" link="SoupAuthManager.html#SoupAuthManager-authenticate"/> + <keyword type="struct" name="SoupContentDecoder" link="SoupContentDecoder.html#SoupContentDecoder-struct"/> + <keyword type="function" name="soup_content_sniffer_new ()" link="SoupContentSniffer.html#soup-content-sniffer-new" since="2.28"/> + <keyword type="function" name="soup_content_sniffer_sniff ()" link="SoupContentSniffer.html#soup-content-sniffer-sniff" since="2.28"/> + <keyword type="function" name="soup_content_sniffer_get_buffer_size ()" link="SoupContentSniffer.html#soup-content-sniffer-get-buffer-size" since="2.28"/> + <keyword type="struct" name="SoupContentSniffer" link="SoupContentSniffer.html#SoupContentSniffer-struct"/> + <keyword type="function" name="soup_cookie_jar_new ()" link="SoupCookieJar.html#soup-cookie-jar-new" since="2.24"/> + <keyword type="function" name="soup_cookie_jar_get_cookies ()" link="SoupCookieJar.html#soup-cookie-jar-get-cookies" since="2.24"/> + <keyword type="function" name="soup_cookie_jar_get_cookie_list ()" link="SoupCookieJar.html#soup-cookie-jar-get-cookie-list" since="2.40"/> + <keyword type="function" name="soup_cookie_jar_set_cookie ()" link="SoupCookieJar.html#soup-cookie-jar-set-cookie" since="2.24"/> + <keyword type="function" name="soup_cookie_jar_set_cookie_with_first_party ()" link="SoupCookieJar.html#soup-cookie-jar-set-cookie-with-first-party" since="2.30"/> + <keyword type="function" name="soup_cookie_jar_add_cookie ()" link="SoupCookieJar.html#soup-cookie-jar-add-cookie" since="2.26"/> + <keyword type="function" name="soup_cookie_jar_add_cookie_with_first_party ()" link="SoupCookieJar.html#soup-cookie-jar-add-cookie-with-first-party" since="2.40"/> + <keyword type="function" name="soup_cookie_jar_delete_cookie ()" link="SoupCookieJar.html#soup-cookie-jar-delete-cookie" since="2.26"/> + <keyword type="function" name="soup_cookie_jar_all_cookies ()" link="SoupCookieJar.html#soup-cookie-jar-all-cookies" since="2.26"/> + <keyword type="function" name="soup_cookie_jar_get_accept_policy ()" link="SoupCookieJar.html#soup-cookie-jar-get-accept-policy" since="2.30"/> + <keyword type="function" name="soup_cookie_jar_set_accept_policy ()" link="SoupCookieJar.html#soup-cookie-jar-set-accept-policy" since="2.30"/> + <keyword type="function" name="soup_cookie_jar_is_persistent ()" link="SoupCookieJar.html#soup-cookie-jar-is-persistent" since="2.40"/> + <keyword type="struct" name="SoupCookieJar" link="SoupCookieJar.html#SoupCookieJar-struct"/> + <keyword type="enum" name="enum SoupCookieJarAcceptPolicy" link="SoupCookieJar.html#SoupCookieJarAcceptPolicy" since="2.30"/> + <keyword type="macro" name="SOUP_COOKIE_JAR_READ_ONLY" link="SoupCookieJar.html#SOUP-COOKIE-JAR-READ-ONLY:CAPS"/> + <keyword type="macro" name="SOUP_COOKIE_JAR_ACCEPT_POLICY" link="SoupCookieJar.html#SOUP-COOKIE-JAR-ACCEPT-POLICY:CAPS" since="2.30"/> + <keyword type="property" name="The “accept-policy” property" link="SoupCookieJar.html#SoupCookieJar--accept-policy"/> + <keyword type="property" name="The “read-only” property" link="SoupCookieJar.html#SoupCookieJar--read-only"/> + <keyword type="signal" name="The “changed” signal" link="SoupCookieJar.html#SoupCookieJar-changed"/> + <keyword type="function" name="soup_cookie_jar_text_new ()" link="SoupCookieJarText.html#soup-cookie-jar-text-new" since="2.26"/> + <keyword type="struct" name="SoupCookieJarText" link="SoupCookieJarText.html#SoupCookieJarText-struct"/> + <keyword type="macro" name="SOUP_COOKIE_JAR_TEXT_FILENAME" link="SoupCookieJarText.html#SOUP-COOKIE-JAR-TEXT-FILENAME:CAPS"/> + <keyword type="property" name="The “filename” property" link="SoupCookieJarText.html#SoupCookieJarText--filename"/> + <keyword type="function" name="soup_cookie_jar_db_new ()" link="SoupCookieJarDB.html#soup-cookie-jar-db-new" since="2.42"/> + <keyword type="struct" name="SoupCookieJarDB" link="SoupCookieJarDB.html#SoupCookieJarDB-struct"/> + <keyword type="macro" name="SOUP_COOKIE_JAR_DB_FILENAME" link="SoupCookieJarDB.html#SOUP-COOKIE-JAR-DB-FILENAME:CAPS"/> + <keyword type="property" name="The “filename” property" link="SoupCookieJarDB.html#SoupCookieJarDB--filename"/> + <keyword type="function" name="soup_logger_new ()" link="SoupLogger.html#soup-logger-new"/> + <keyword type="function" name="soup_logger_attach ()" link="SoupLogger.html#soup-logger-attach" deprecated="Use soup_session_add_feature() instead."/> + <keyword type="function" name="soup_logger_detach ()" link="SoupLogger.html#soup-logger-detach" deprecated="Use soup_session_remove_feature() instead."/> + <keyword type="function" name="SoupLoggerFilter ()" link="SoupLogger.html#SoupLoggerFilter"/> + <keyword type="function" name="soup_logger_set_request_filter ()" link="SoupLogger.html#soup-logger-set-request-filter"/> + <keyword type="function" name="soup_logger_set_response_filter ()" link="SoupLogger.html#soup-logger-set-response-filter"/> + <keyword type="function" name="SoupLoggerPrinter ()" link="SoupLogger.html#SoupLoggerPrinter"/> + <keyword type="function" name="soup_logger_set_printer ()" link="SoupLogger.html#soup-logger-set-printer"/> + <keyword type="struct" name="SoupLogger" link="SoupLogger.html#SoupLogger-struct"/> + <keyword type="enum" name="enum SoupLoggerLogLevel" link="SoupLogger.html#SoupLoggerLogLevel"/> + <keyword type="struct" name="SoupProxyResolverDefault" link="SoupProxyResolverDefault.html#SoupProxyResolverDefault-struct"/> + <keyword type="property" name="The “gproxy-resolver” property" link="SoupProxyResolverDefault.html#SoupProxyResolverDefault--gproxy-resolver"/> + <keyword type="function" name="soup_form_decode ()" link="libsoup-2.4-HTML-Form-Support.html#soup-form-decode"/> + <keyword type="function" name="soup_form_decode_multipart ()" link="libsoup-2.4-HTML-Form-Support.html#soup-form-decode-multipart" since="2.26"/> + <keyword type="function" name="soup_form_encode ()" link="libsoup-2.4-HTML-Form-Support.html#soup-form-encode"/> + <keyword type="function" name="soup_form_encode_datalist ()" link="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-datalist"/> + <keyword type="function" name="soup_form_encode_hash ()" link="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-hash"/> + <keyword type="function" name="soup_form_encode_valist ()" link="libsoup-2.4-HTML-Form-Support.html#soup-form-encode-valist"/> + <keyword type="function" name="soup_form_request_new ()" link="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new"/> + <keyword type="function" name="soup_form_request_new_from_datalist ()" link="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-datalist"/> + <keyword type="function" name="soup_form_request_new_from_hash ()" link="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-hash"/> + <keyword type="function" name="soup_form_request_new_from_multipart ()" link="libsoup-2.4-HTML-Form-Support.html#soup-form-request-new-from-multipart" since="2.26"/> + <keyword type="macro" name="SOUP_FORM_MIME_TYPE_MULTIPART" link="libsoup-2.4-HTML-Form-Support.html#SOUP-FORM-MIME-TYPE-MULTIPART:CAPS" since="2.26"/> + <keyword type="macro" name="SOUP_FORM_MIME_TYPE_URLENCODED" link="libsoup-2.4-HTML-Form-Support.html#SOUP-FORM-MIME-TYPE-URLENCODED:CAPS" since="2.26"/> + <keyword type="function" name="soup_xmlrpc_build_method_call ()" link="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-method-call"/> + <keyword type="function" name="soup_xmlrpc_request_new ()" link="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-request-new"/> + <keyword type="function" name="soup_xmlrpc_parse_method_response ()" link="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-parse-method-response"/> + <keyword type="function" name="soup_xmlrpc_extract_method_response ()" link="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-extract-method-response"/> + <keyword type="function" name="soup_xmlrpc_parse_method_call ()" link="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-parse-method-call"/> + <keyword type="function" name="soup_xmlrpc_extract_method_call ()" link="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-extract-method-call"/> + <keyword type="function" name="soup_xmlrpc_build_method_response ()" link="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-method-response"/> + <keyword type="function" name="soup_xmlrpc_build_fault ()" link="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-build-fault"/> + <keyword type="function" name="soup_xmlrpc_set_response ()" link="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-set-response"/> + <keyword type="function" name="soup_xmlrpc_set_fault ()" link="libsoup-2.4-XMLRPC-Support.html#soup-xmlrpc-set-fault"/> + <keyword type="macro" name="SOUP_XMLRPC_FAULT" link="libsoup-2.4-XMLRPC-Support.html#SOUP-XMLRPC-FAULT:CAPS"/> + <keyword type="enum" name="enum SoupXMLRPCFault" link="libsoup-2.4-XMLRPC-Support.html#SoupXMLRPCFault"/> + <keyword type="function" name="soup_value_hash_new ()" link="libsoup-2.4-GValue-Support.html#soup-value-hash-new"/> + <keyword type="function" name="soup_value_hash_new_with_vals ()" link="libsoup-2.4-GValue-Support.html#soup-value-hash-new-with-vals"/> + <keyword type="function" name="soup_value_hash_insert_value ()" link="libsoup-2.4-GValue-Support.html#soup-value-hash-insert-value"/> + <keyword type="function" name="soup_value_hash_insert ()" link="libsoup-2.4-GValue-Support.html#soup-value-hash-insert"/> + <keyword type="function" name="soup_value_hash_insert_vals ()" link="libsoup-2.4-GValue-Support.html#soup-value-hash-insert-vals"/> + <keyword type="function" name="soup_value_hash_lookup ()" link="libsoup-2.4-GValue-Support.html#soup-value-hash-lookup"/> + <keyword type="function" name="soup_value_hash_lookup_vals ()" link="libsoup-2.4-GValue-Support.html#soup-value-hash-lookup-vals"/> + <keyword type="function" name="soup_value_array_from_args ()" link="libsoup-2.4-GValue-Support.html#soup-value-array-from-args"/> + <keyword type="function" name="soup_value_array_to_args ()" link="libsoup-2.4-GValue-Support.html#soup-value-array-to-args"/> + <keyword type="function" name="soup_value_array_new ()" link="libsoup-2.4-GValue-Support.html#soup-value-array-new"/> + <keyword type="function" name="soup_value_array_new_with_vals ()" link="libsoup-2.4-GValue-Support.html#soup-value-array-new-with-vals"/> + <keyword type="function" name="soup_value_array_insert ()" link="libsoup-2.4-GValue-Support.html#soup-value-array-insert"/> + <keyword type="function" name="soup_value_array_append ()" link="libsoup-2.4-GValue-Support.html#soup-value-array-append"/> + <keyword type="function" name="soup_value_array_append_vals ()" link="libsoup-2.4-GValue-Support.html#soup-value-array-append-vals"/> + <keyword type="function" name="soup_value_array_get_nth ()" link="libsoup-2.4-GValue-Support.html#soup-value-array-get-nth"/> + <keyword type="macro" name="SOUP_VALUE_SETV()" link="libsoup-2.4-GValue-Support.html#SOUP-VALUE-SETV:CAPS"/> + <keyword type="macro" name="SOUP_VALUE_GETV()" link="libsoup-2.4-GValue-Support.html#SOUP-VALUE-GETV:CAPS"/> + <keyword type="macro" name="SOUP_TYPE_BYTE_ARRAY" link="libsoup-2.4-GValue-Support.html#SOUP-TYPE-BYTE-ARRAY:CAPS"/> + <keyword type="function" name="soup_address_new ()" link="SoupAddress.html#soup-address-new"/> + <keyword type="function" name="soup_address_new_from_sockaddr ()" link="SoupAddress.html#soup-address-new-from-sockaddr"/> + <keyword type="function" name="soup_address_new_any ()" link="SoupAddress.html#soup-address-new-any"/> + <keyword type="function" name="SoupAddressCallback ()" link="SoupAddress.html#SoupAddressCallback"/> + <keyword type="function" name="soup_address_resolve_async ()" link="SoupAddress.html#soup-address-resolve-async"/> + <keyword type="function" name="soup_address_resolve_sync ()" link="SoupAddress.html#soup-address-resolve-sync"/> + <keyword type="function" name="soup_address_is_resolved ()" link="SoupAddress.html#soup-address-is-resolved"/> + <keyword type="function" name="soup_address_get_name ()" link="SoupAddress.html#soup-address-get-name"/> + <keyword type="function" name="soup_address_get_sockaddr ()" link="SoupAddress.html#soup-address-get-sockaddr"/> + <keyword type="function" name="soup_address_get_gsockaddr ()" link="SoupAddress.html#soup-address-get-gsockaddr" since="2.32"/> + <keyword type="function" name="soup_address_get_physical ()" link="SoupAddress.html#soup-address-get-physical"/> + <keyword type="function" name="soup_address_get_port ()" link="SoupAddress.html#soup-address-get-port"/> + <keyword type="function" name="soup_address_equal_by_name ()" link="SoupAddress.html#soup-address-equal-by-name" since="2.26"/> + <keyword type="function" name="soup_address_hash_by_name ()" link="SoupAddress.html#soup-address-hash-by-name" since="2.26"/> + <keyword type="function" name="soup_address_equal_by_ip ()" link="SoupAddress.html#soup-address-equal-by-ip" since="2.26"/> + <keyword type="function" name="soup_address_hash_by_ip ()" link="SoupAddress.html#soup-address-hash-by-ip" since="2.26"/> + <keyword type="struct" name="SoupAddress" link="SoupAddress.html#SoupAddress-struct"/> + <keyword type="enum" name="enum SoupAddressFamily" link="SoupAddress.html#SoupAddressFamily"/> + <keyword type="macro" name="SOUP_ADDRESS_ANY_PORT" link="SoupAddress.html#SOUP-ADDRESS-ANY-PORT:CAPS"/> + <keyword type="macro" name="SOUP_ADDRESS_FAMILY" link="SoupAddress.html#SOUP-ADDRESS-FAMILY:CAPS"/> + <keyword type="macro" name="SOUP_ADDRESS_NAME" link="SoupAddress.html#SOUP-ADDRESS-NAME:CAPS"/> + <keyword type="macro" name="SOUP_ADDRESS_PHYSICAL" link="SoupAddress.html#SOUP-ADDRESS-PHYSICAL:CAPS"/> + <keyword type="macro" name="SOUP_ADDRESS_PORT" link="SoupAddress.html#SOUP-ADDRESS-PORT:CAPS"/> + <keyword type="macro" name="SOUP_ADDRESS_SOCKADDR" link="SoupAddress.html#SOUP-ADDRESS-SOCKADDR:CAPS"/> + <keyword type="macro" name="SOUP_ADDRESS_PROTOCOL" link="SoupAddress.html#SOUP-ADDRESS-PROTOCOL:CAPS"/> + <keyword type="property" name="The “family” property" link="SoupAddress.html#SoupAddress--family"/> + <keyword type="property" name="The “name” property" link="SoupAddress.html#SoupAddress--name"/> + <keyword type="property" name="The “physical” property" link="SoupAddress.html#SoupAddress--physical"/> + <keyword type="property" name="The “port” property" link="SoupAddress.html#SoupAddress--port"/> + <keyword type="property" name="The “protocol” property" link="SoupAddress.html#SoupAddress--protocol"/> + <keyword type="property" name="The “sockaddr” property" link="SoupAddress.html#SoupAddress--sockaddr"/> + <keyword type="function" name="soup_socket_new ()" link="SoupSocket.html#soup-socket-new"/> + <keyword type="function" name="SoupSocketCallback ()" link="SoupSocket.html#SoupSocketCallback"/> + <keyword type="function" name="soup_socket_connect_async ()" link="SoupSocket.html#soup-socket-connect-async"/> + <keyword type="function" name="soup_socket_connect_sync ()" link="SoupSocket.html#soup-socket-connect-sync"/> + <keyword type="function" name="soup_socket_listen ()" link="SoupSocket.html#soup-socket-listen"/> + <keyword type="function" name="soup_socket_start_ssl ()" link="SoupSocket.html#soup-socket-start-ssl"/> + <keyword type="function" name="soup_socket_start_proxy_ssl ()" link="SoupSocket.html#soup-socket-start-proxy-ssl"/> + <keyword type="function" name="soup_socket_is_ssl ()" link="SoupSocket.html#soup-socket-is-ssl"/> + <keyword type="function" name="soup_socket_disconnect ()" link="SoupSocket.html#soup-socket-disconnect"/> + <keyword type="function" name="soup_socket_is_connected ()" link="SoupSocket.html#soup-socket-is-connected"/> + <keyword type="function" name="soup_socket_get_local_address ()" link="SoupSocket.html#soup-socket-get-local-address"/> + <keyword type="function" name="soup_socket_get_remote_address ()" link="SoupSocket.html#soup-socket-get-remote-address"/> + <keyword type="function" name="soup_socket_get_fd ()" link="SoupSocket.html#soup-socket-get-fd"/> + <keyword type="function" name="soup_socket_read ()" link="SoupSocket.html#soup-socket-read"/> + <keyword type="function" name="soup_socket_read_until ()" link="SoupSocket.html#soup-socket-read-until"/> + <keyword type="function" name="soup_socket_write ()" link="SoupSocket.html#soup-socket-write"/> + <keyword type="struct" name="SoupSocket" link="SoupSocket.html#SoupSocket-struct"/> + <keyword type="enum" name="enum SoupSocketIOStatus" link="SoupSocket.html#SoupSocketIOStatus"/> + <keyword type="macro" name="SOUP_SOCKET_LOCAL_ADDRESS" link="SoupSocket.html#SOUP-SOCKET-LOCAL-ADDRESS:CAPS"/> + <keyword type="macro" name="SOUP_SOCKET_REMOTE_ADDRESS" link="SoupSocket.html#SOUP-SOCKET-REMOTE-ADDRESS:CAPS"/> + <keyword type="macro" name="SOUP_SOCKET_FLAG_NONBLOCKING" link="SoupSocket.html#SOUP-SOCKET-FLAG-NONBLOCKING:CAPS"/> + <keyword type="macro" name="SOUP_SOCKET_IS_SERVER" link="SoupSocket.html#SOUP-SOCKET-IS-SERVER:CAPS"/> + <keyword type="macro" name="SOUP_SOCKET_SSL_CREDENTIALS" link="SoupSocket.html#SOUP-SOCKET-SSL-CREDENTIALS:CAPS"/> + <keyword type="macro" name="SOUP_SOCKET_ASYNC_CONTEXT" link="SoupSocket.html#SOUP-SOCKET-ASYNC-CONTEXT:CAPS"/> + <keyword type="macro" name="SOUP_SOCKET_TIMEOUT" link="SoupSocket.html#SOUP-SOCKET-TIMEOUT:CAPS"/> + <keyword type="macro" name="SOUP_SOCKET_SSL_FALLBACK" link="SoupSocket.html#SOUP-SOCKET-SSL-FALLBACK:CAPS"/> + <keyword type="macro" name="SOUP_SOCKET_SSL_STRICT" link="SoupSocket.html#SOUP-SOCKET-SSL-STRICT:CAPS"/> + <keyword type="macro" name="SOUP_SOCKET_TLS_CERTIFICATE" link="SoupSocket.html#SOUP-SOCKET-TLS-CERTIFICATE:CAPS" since="2.34"/> + <keyword type="macro" name="SOUP_SOCKET_TLS_ERRORS" link="SoupSocket.html#SOUP-SOCKET-TLS-ERRORS:CAPS" since="2.34"/> + <keyword type="macro" name="SOUP_SOCKET_TRUSTED_CERTIFICATE" link="SoupSocket.html#SOUP-SOCKET-TRUSTED-CERTIFICATE:CAPS"/> + <keyword type="macro" name="SOUP_SOCKET_USE_THREAD_CONTEXT" link="SoupSocket.html#SOUP-SOCKET-USE-THREAD-CONTEXT:CAPS" since="2.38"/> + <keyword type="property" name="The “async-context” property" link="SoupSocket.html#SoupSocket--async-context"/> + <keyword type="property" name="The “clean-dispose” property" link="SoupSocket.html#SoupSocket--clean-dispose"/> + <keyword type="property" name="The “is-server” property" link="SoupSocket.html#SoupSocket--is-server"/> + <keyword type="property" name="The “local-address” property" link="SoupSocket.html#SoupSocket--local-address"/> + <keyword type="property" name="The “non-blocking” property" link="SoupSocket.html#SoupSocket--non-blocking"/> + <keyword type="property" name="The “proxy-resolver” property" link="SoupSocket.html#SoupSocket--proxy-resolver"/> + <keyword type="property" name="The “remote-address” property" link="SoupSocket.html#SoupSocket--remote-address"/> + <keyword type="property" name="The “ssl-creds” property" link="SoupSocket.html#SoupSocket--ssl-creds"/> + <keyword type="property" name="The “ssl-fallback” property" link="SoupSocket.html#SoupSocket--ssl-fallback"/> + <keyword type="property" name="The “ssl-strict” property" link="SoupSocket.html#SoupSocket--ssl-strict"/> + <keyword type="property" name="The “timeout” property" link="SoupSocket.html#SoupSocket--timeout"/> + <keyword type="property" name="The “tls-certificate” property" link="SoupSocket.html#SoupSocket--tls-certificate"/> + <keyword type="property" name="The “tls-errors” property" link="SoupSocket.html#SoupSocket--tls-errors"/> + <keyword type="property" name="The “trusted-certificate” property" link="SoupSocket.html#SoupSocket--trusted-certificate"/> + <keyword type="property" name="The “use-thread-context” property" link="SoupSocket.html#SoupSocket--use-thread-context"/> + <keyword type="signal" name="The “disconnected” signal" link="SoupSocket.html#SoupSocket-disconnected"/> + <keyword type="signal" name="The “event” signal" link="SoupSocket.html#SoupSocket-event"/> + <keyword type="signal" name="The “new-connection” signal" link="SoupSocket.html#SoupSocket-new-connection"/> + <keyword type="signal" name="The “readable” signal" link="SoupSocket.html#SoupSocket-readable"/> + <keyword type="signal" name="The “writable” signal" link="SoupSocket.html#SoupSocket-writable"/> + </functions> +</book> diff --git a/docs/reference/html/libsoup-build-howto.html b/docs/reference/html/libsoup-build-howto.html new file mode 100644 index 00000000..bfeab1c8 --- /dev/null +++ b/docs/reference/html/libsoup-build-howto.html @@ -0,0 +1,136 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Compiling with libsoup</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch01.html" title="Tutorial"> +<link rel="prev" href="ch01.html" title="Tutorial"> +<link rel="next" href="libsoup-client-howto.html" title="libsoup Client Basics"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="ch01.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-client-howto.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-build-howto"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle">Compiling with libsoup</span></h2> +<p>Compiling with libsoup — Notes on compiling</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect2"> +<a name="id-1.2.2.3"></a><h3>Using pkg-config</h3> +<p> +Like other GNOME libraries, <span class="application">libsoup</span> uses +<span class="application">pkg-config</span> to provide compiler options. The +package name is "<code class="literal">libsoup-2.4</code>". So in your +<code class="literal">configure</code> script, you might specify something like: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="function">PKG_CHECK_MODULES</span><span class="symbol">(</span><span class="normal">LIBSOUP</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">[</span><span class="normal">libsoup</span><span class="symbol">-</span><span class="number">2.4</span><span class="normal"> </span><span class="symbol">>=</span><span class="normal"> </span><span class="number">2.26</span><span class="symbol">])</span> +<span class="function">AC_SUBST</span><span class="symbol">(</span><span class="normal">LIBSOUP_CFLAGS</span><span class="symbol">)</span> +<span class="function">AC_SUBST</span><span class="symbol">(</span><span class="normal">LIBSOUP_LIBS</span><span class="symbol">)</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +The "<code class="literal">2.4</code>" in the package name is the "API version" +(indicating "the version of the <span class="application">libsoup</span> API +that first appeared in version 2.4") and is essentially just part of +the package name. +</p> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.2.4"></a><h3>API Availability and Deprecation Warnings</h3> +<p> +If you want to restrict your program to a particular +<span class="application">libsoup</span> version or range of versions, you +can define <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MIN-REQUIRED:CAPS" title="SOUP_VERSION_MIN_REQUIRED"><code class="literal">SOUP_VERSION_MIN_REQUIRED</code></a> +and/or <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-VERSION-MAX-ALLOWED:CAPS" title="SOUP_VERSION_MAX_ALLOWED"><code class="literal">SOUP_VERSION_MAX_ALLOWED</code></a>. +Eg: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="normal">LIBSOUP_CFLAGS</span><span class="symbol">=</span><span class="string">"$LIBSOUP_CFLAGS -DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_2_36"</span> +<span class="normal">LIBSOUP_CFLAGS</span><span class="symbol">=</span><span class="string">"$LIBSOUP_CFLAGS -DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_2_40"</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +The <code class="literal">SOUP_VERSION_MIN_REQUIRED</code> declaration states +that the code is not expected to compile on versions of +<span class="application">libsoup</span> older than the indicated version +(here, 2.36), and so the compiler should print warnings if the code +uses functions that were deprecated as of that release. +</p> +<p> +The <code class="literal">SOUP_VERSION_MAX_ALLOWED</code> declaration states +that the code <span class="emphasis"><em>is</em></span> expected to compile on versions +of <span class="application">libsoup</span> up to the indicated version +(here, 2.40), and so, when compiling the program against a newer +version than that, the compiler should print warnings if the code uses +functions that did not yet exist in the max-allowed release. +</p> +<p> +You can use <a class="link" href="libsoup-2.4-Version-Information.html#SOUP-CHECK-VERSION:CAPS" title="SOUP_CHECK_VERSION()"><code class="literal">SOUP_CHECK_VERSION</code></a> +to check the version of libsoup at compile time, to compile different +code for different <span class="application">libsoup</span> versions. (If +you are setting <code class="literal">SOUP_VERSION_MIN_REQUIRED</code> and +<code class="literal">SOUP_VERSION_MAX_ALLOWED</code> to different versions, as +in the example above, then you almost certainly need to be doing +this.) +</p> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.2.5"></a><h3>Headers</h3> +<p> +Code using <span class="application">libsoup</span> should do: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="preproc">#include</span><span class="normal"> </span><span class="string"><libsoup/soup.h></span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +Including individual headers rather than <code class="literal">soup.h</code> is not +recommended. +</p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-client-howto.html b/docs/reference/html/libsoup-client-howto.html new file mode 100644 index 00000000..7e87d641 --- /dev/null +++ b/docs/reference/html/libsoup-client-howto.html @@ -0,0 +1,604 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: libsoup Client Basics</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch01.html" title="Tutorial"> +<link rel="prev" href="libsoup-build-howto.html" title="Compiling with libsoup"> +<link rel="next" href="libsoup-request-howto.html" title="libsoup Client SoupRequest API"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="libsoup-build-howto.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-request-howto.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-client-howto"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle">libsoup Client Basics</span></h2> +<p>libsoup Client Basics — Client-side tutorial</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect2"> +<a name="id-1.2.3.3"></a><p> +This section explains how to use <span class="application">libsoup</span> as +an HTTP client using several new APIs introduced in version 2.42. If +you want to be compatible with older versions of +<span class="application">libsoup</span>, consult the documentation for that +version. +</p> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.3.4"></a><h3>Creating a <span class="type">SoupSession</span> +</h3> +<p> +The first step in using the client API is to create a <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a>. The session object +encapsulates all of the state that <span class="application">libsoup</span> +is keeping on behalf of your program; cached HTTP connections, +authentication information, etc. +</p> +<p> +When you create the session with <a class="link" href="SoupSession.html#soup-session-new-with-options" title="soup_session_new_with_options ()"><code class="function">soup_session_new_with_options</code></a>, +you can specify various additional options: +</p> +<div class="variablelist"><table border="0" class="variablelist"> +<colgroup> +<col align="left" valign="top"> +<col> +</colgroup> +<tbody> +<tr> +<td><p><span class="term"><a class="link" href="SoupSession.html#SOUP-SESSION-MAX-CONNS:CAPS" title="SOUP_SESSION_MAX_CONNS"><code class="literal">SOUP_SESSION_MAX_CONNS</code></a></span></p></td> +<td><p> + Allows you to set the maximum total number of connections + the session will have open at one time. (Once it reaches + this limit, it will either close idle connections, or + wait for existing connections to free up before starting + new requests.) The default value is 10. + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupSession.html#SOUP-SESSION-MAX-CONNS-PER-HOST:CAPS" title="SOUP_SESSION_MAX_CONNS_PER_HOST"><code class="literal">SOUP_SESSION_MAX_CONNS_PER_HOST</code></a></span></p></td> +<td><p> + Allows you to set the maximum total number of connections + the session will have open <span class="emphasis"><em>to a single + host</em></span> at one time. The default value is 2. + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupSession.html#SOUP-SESSION-USER-AGENT:CAPS" title="SOUP_SESSION_USER_AGENT"><code class="literal">SOUP_SESSION_USER_AGENT</code></a></span></p></td> +<td><p> + Allows you to set a User-Agent string that will be sent + on all outgoing requests. + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupSession.html#SOUP-SESSION-ACCEPT-LANGUAGE:CAPS" title="SOUP_SESSION_ACCEPT_LANGUAGE"><code class="literal">SOUP_SESSION_ACCEPT_LANGUAGE</code></a> + and <a class="link" href="SoupSession.html#SOUP-SESSION-ACCEPT-LANGUAGE-AUTO:CAPS" title="SOUP_SESSION_ACCEPT_LANGUAGE_AUTO"><code class="literal">SOUP_SESSION_ACCEPT_LANGUAGE_AUTO</code></a></span></p></td> +<td><p> + Allow you to set an Accept-Language header on all outgoing + requests. <code class="literal">SOUP_SESSION_ACCEPT_LANGUAGE</code> + takes a list of language tags to use, while + <code class="literal">SOUP_SESSION_ACCEPT_LANGUAGE_AUTO</code> + automatically generates the list from the user's locale + settings. + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupSession.html#SOUP-SESSION-HTTP-ALIASES:CAPS" title="SOUP_SESSION_HTTP_ALIASES"><code class="literal">SOUP_SESSION_HTTP_ALIASES</code></a> + and <a class="link" href="SoupSession.html#SOUP-SESSION-HTTPS-ALIASES:CAPS" title="SOUP_SESSION_HTTPS_ALIASES"><code class="literal">SOUP_SESSION_HTTPS_ALIASES</code></a></span></p></td> +<td><p> + Allow you to tell the session to recognize additional URI + schemes as aliases for "<code class="literal">http</code>" or + <code class="literal">https</code>. You can set this if you are + using URIs with schemes like "<code class="literal">dav</code>" or + "<code class="literal">webcal</code>" (and in particular, you need + to set this if the server you are talking to might return + redirects with such a scheme). + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupSession.html#SOUP-SESSION-PROXY-RESOLVER:CAPS" title="SOUP_SESSION_PROXY_RESOLVER"><code class="literal">SOUP_SESSION_PROXY_RESOLVER</code></a> and <a class="link" href="SoupSession.html#SOUP-SESSION-PROXY-URI:CAPS" title="SOUP_SESSION_PROXY_URI"><code class="literal">SOUP_SESSION_PROXY_URI</code></a></span></p></td> +<td> +<p> + <a class="link" href="SoupSession.html#SOUP-SESSION-PROXY-RESOLVER:CAPS" title="SOUP_SESSION_PROXY_RESOLVER"><code class="literal">SOUP_SESSION_PROXY_RESOLVER</code></a> + specifies a <span class="type">GProxyResolver</span> + to use to determine the HTTP proxies to use. By default, + this is set to the resolver returned by <code class="function">g_proxy_resolver_get_default</code>, + so you do not need to set it yourself. + </p> +<p> + Alternatively, if you want all requests to go through a + single proxy, you can set <a class="link" href="SoupSession.html#SOUP-SESSION-PROXY-URI:CAPS" title="SOUP_SESSION_PROXY_URI"><code class="literal">SOUP_SESSION_PROXY_URI</code></a>. + </p> +</td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupSession.html#SOUP-SESSION-ADD-FEATURE:CAPS" title="SOUP_SESSION_ADD_FEATURE"><code class="literal">SOUP_SESSION_ADD_FEATURE</code></a> and <a class="link" href="SoupSession.html#SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS" title="SOUP_SESSION_ADD_FEATURE_BY_TYPE"><code class="literal">SOUP_SESSION_ADD_FEATURE_BY_TYPE</code></a></span></p></td> +<td><p> + These allow you to specify <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a>s + (discussed <a class="link" href="libsoup-client-howto.html#session-features" title="Session features">below</a>) + to add at construct-time. + </p></td> +</tr> +</tbody> +</table></div> +<p> +Other properties are also available; see the <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> documentation for +more details. +</p> +<p> +If you don't need to specify any options, you can just use <a class="link" href="SoupSession.html#soup-session-new" title="soup_session_new ()"><code class="function">soup_session_new</code></a>, +which takes no arguments. +</p> +</div> +<hr> +<div class="refsect2"> +<a name="session-features"></a><h3>Session features</h3> +<p> +Additional session functionality is provided as <a class="link" href="SoupSessionFeature.html" title="SoupSessionFeature"><span class="type">SoupSessionFeature</span></a>s, +which can be added to a session, via the <a class="link" href="SoupSession.html#SOUP-SESSION-ADD-FEATURE:CAPS" title="SOUP_SESSION_ADD_FEATURE"><code class="literal">SOUP_SESSION_ADD_FEATURE</code></a> +and <a class="link" href="SoupSession.html#SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS" title="SOUP_SESSION_ADD_FEATURE_BY_TYPE"><code class="literal">SOUP_SESSION_ADD_FEATURE_BY_TYPE</code></a> +options at session-construction-time, or afterward via the <a class="link" href="SoupSession.html#soup-session-add-feature" title="soup_session_add_feature ()"><code class="function">soup_session_add_feature</code></a> +and <a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()"><code class="function">soup_session_add_feature_by_type</code></a> +functions. +</p> +<p> +A <a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder"><span class="type">SoupContentDecoder</span></a> is +added for you automatically. This advertises to servers that the +client supports compression, and automatically decompresses compressed +responses. +</p> +<p> +Some other available features that you can add include: +</p> +<div class="variablelist"><table border="0" class="variablelist"> +<colgroup> +<col align="left" valign="top"> +<col> +</colgroup> +<tbody> +<tr> +<td><p><span class="term"><a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a></span></p></td> +<td><p> + A debugging aid, which logs all of libsoup's HTTP traffic + to <code class="literal">stdout</code> (or another place you specify). + </p></td> +</tr> +<tr> +<td><p><span class="term"> + <a class="link" href="SoupCookieJar.html" title="SoupCookieJar"><span class="type">SoupCookieJar</span></a>, + <a class="link" href="SoupCookieJarText.html" title="SoupCookieJarText"><span class="type">SoupCookieJarText</span></a>, + and <a class="link" href="SoupCookieJarDB.html" title="SoupCookieJarDB"><span class="type">SoupCookieJarDB</span></a> + </span></p></td> +<td><p> + Support for HTTP cookies. <span class="type">SoupCookieJar</span> + provides non-persistent cookie storage, while + <span class="type">SoupCookieJarText</span> uses a text file to keep + track of cookies between sessions, and + <span class="type">SoupCookieJarDB</span> uses a + <span class="application">SQLite</span> database. + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="type">SoupContentSniffer</span></a></span></p></td> +<td><p> + Uses the HTML5 sniffing rules to attempt to + determine the Content-Type of a response when the + server does not identify the Content-Type, or appears to + have provided an incorrect one. + </p></td> +</tr> +</tbody> +</table></div> +<p> +Use the "add_feature_by_type" property/function to add features that +don't require any configuration (such as <a class="link" href="SoupContentSniffer.html" title="SoupContentSniffer"><span class="type">SoupContentSniffer</span></a>), +and the "add_feature" property/function to add features that must be +constructed first (such as <a class="link" href="SoupLogger.html" title="SoupLogger"><span class="type">SoupLogger</span></a>). For example, an +application might do something like the following: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="normal">session </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="SoupSession.html#soup-session-new-with-options">soup_session_new_with_options</a></span><span class="normal"> </span><span class="symbol">(</span> +<span class="normal"> <a href="SoupSession.html#SOUP-SESSION-ADD-FEATURE-BY-TYPE:CAPS">SOUP_SESSION_ADD_FEATURE_BY_TYPE</a></span><span class="symbol">,</span><span class="normal"> SOUP_TYPE_CONTENT_SNIFFER</span><span class="symbol">,</span> +<span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> + +<span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">debug_level</span><span class="symbol">)</span><span class="normal"> </span><span class="cbracket">{</span> +<span class="normal"> </span><span class="usertype">SoupLogger</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">logger</span><span class="symbol">;</span> + +<span class="normal"> logger </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="SoupLogger.html#soup-logger-new">soup_logger_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">debug_level</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">-</span><span class="number">1</span><span class="symbol">);</span> +<span class="normal"> </span><span class="function"><a href="SoupSession.html#soup-session-add-feature">soup_session_add_feature</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">session</span><span class="symbol">,</span><span class="normal"> </span><span class="function">SOUP_SESSION_FEATURE</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">logger</span><span class="symbol">));</span> +<span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">logger</span><span class="symbol">);</span> +<span class="cbracket">}</span></pre></td> + </tr> + </tbody> + </table> +</div> + +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.3.6"></a><h3>Creating and Sending SoupMessages</h3> +<p> +Once you have a session, you send HTTP requests using <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>. In the simplest +case, you only need to create the message and it's ready to send: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="usertype">SoupMessage</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">msg</span><span class="symbol">;</span> + +<span class="normal">msg </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="SoupMessage.html#soup-message-new">soup_message_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"GET"</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"http://example.com/"</span><span class="symbol">);</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +In more complicated cases, you can use various <a class="link" href="SoupMessage.html" title="SoupMessage">SoupMessage</a>, <a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders">SoupMessageHeaders</a>, and <a class="link" href="SoupMessageBody.html" title="SoupMessageBody">SoupMessageBody</a> methods to set the +request headers and body of the message: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4 +5 +6</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="usertype">SoupMessage</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">msg</span><span class="symbol">;</span> + +<span class="normal">msg </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="SoupMessage.html#soup-message-new">soup_message_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"POST"</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"http://example.com/form.cgi"</span><span class="symbol">);</span> +<span class="function"><a href="SoupMessage.html#soup-message-set-request">soup_message_set_request</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"application/x-www-form-urlencoded"</span><span class="symbol">,</span> +<span class="normal"> <a href="SoupMessageBody.html#SOUP-MEMORY-COPY:CAPS">SOUP_MEMORY_COPY</a></span><span class="symbol">,</span><span class="normal"> formdata</span><span class="symbol">,</span><span class="normal"> </span><span class="function">strlen</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">formdata</span><span class="symbol">));</span> +<span class="function"><a href="SoupMessageHeaders.html#soup-message-headers-append">soup_message_headers_append</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">-></span><span class="normal">request_headers</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"Referer"</span><span class="symbol">,</span><span class="normal"> referring_url</span><span class="symbol">);</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +(Although this is a bad example, because +<span class="application">libsoup</span> actually has convenience methods +for dealing with <a class="link" href="libsoup-2.4-HTML-Form-Support.html" title="HTML Form Support">HTML +forms</a>, as well as <a class="link" href="libsoup-2.4-XMLRPC-Support.html" title="XMLRPC Support">XML-RPC</a>.) +</p> +<p> +You can also use <a class="link" href="SoupMessage.html#soup-message-set-flags" title="soup_message_set_flags ()"><code class="function">soup_message_set_flags</code></a> +to change some default behaviors. For example, by default, +<span class="type">SoupSession</span> automatically handles responses from the +server that redirect to another URL. If you would like to handle these +yourself, you can set the <a class="link" href="SoupMessage.html#SOUP-MESSAGE-NO-REDIRECT:CAPS"><code class="literal">SOUP_MESSAGE_NO_REDIRECT</code></a> +flag. +</p> +<div class="refsect3"> +<a name="id-1.2.3.6.8"></a><h4>Sending a Message Synchronously</h4> +<p> +To send a message and wait for the response, use <a class="link" href="SoupSession.html#soup-session-send" title="soup_session_send ()"><code class="function">soup_session_send</code></a>: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="usertype">GInputStream</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">stream</span><span class="symbol">;</span> +<span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">error </span><span class="symbol">=</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span> + +<span class="normal">stream </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="SoupSession.html#soup-session-send">soup_session_send</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">session</span><span class="symbol">,</span><span class="normal"> msg</span><span class="symbol">,</span><span class="normal"> cancellable</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">error</span><span class="symbol">);</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +At the point when <code class="function">soup_session_send</code> returns, the +request will have been sent, and the response headers read back in; +you can examine the message's <em class="structfield"><code>status_code</code></em>, +<em class="structfield"><code>reason_phrase</code></em>, and +<em class="structfield"><code>response_headers</code></em> fields to see the response +metadata. To get the response body, read from the returned <span class="type">GInputStream</span>, and close it +when you are done. +</p> +<p> +Note that <code class="function">soup_session_send</code> only returns an error +if a transport-level problem occurs (eg, it could not connect to the +host, or the request was cancelled). Use the message's +<em class="structfield"><code>status_code</code></em> field to determine whether the +request was successful or not at the HTTP level (ie, "<code class="literal">200 +OK</code>" vs "<code class="literal">401 Bad Request</code>"). +</p> +<p> +If you would prefer to have <span class="application">libsoup</span> gather +the response body for you and then return it all at once, you can use +the older +<a class="link" href="SoupSession.html#soup-session-send-message" title="soup_session_send_message ()"><code class="function">soup_session_send_message</code></a> +API: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="usertype">guint</span><span class="normal"> status</span><span class="symbol">;</span> + +<span class="normal">status </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="SoupSession.html#soup-session-send-message">soup_session_send_message</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">session</span><span class="symbol">,</span><span class="normal"> msg</span><span class="symbol">);</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +In this case, the response body will be available in the message's +<em class="structfield"><code>response_body</code></em> field, and transport-level +errors will be indicated in the <em class="structfield"><code>status_code</code></em> +field via special pseudo-HTTP-status codes like <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-CANT-CONNECT:CAPS"><code class="literal">SOUP_STATUS_CANT_CONNECT</code></a>. +</p> +</div> +<div class="refsect3"> +<a name="id-1.2.3.6.9"></a><h4>Sending a Message Asynchronously</h4> +<p> +To send a message asynchronously, use <a class="link" href="SoupSession.html#soup-session-send-async" title="soup_session_send_async ()"><code class="function">soup_session_send_async</code></a>: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="cbracket">{</span> +<span class="normal"> </span><span class="symbol">...</span> +<span class="normal"> </span><span class="function"><a href="SoupSession.html#soup-session-send-async">soup_session_send_async</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">session</span><span class="symbol">,</span><span class="normal"> msg</span><span class="symbol">,</span><span class="normal"> cancellable</span><span class="symbol">,</span><span class="normal"> my_callback</span><span class="symbol">,</span><span class="normal"> my_callback_data</span><span class="symbol">);</span> +<span class="normal"> </span><span class="symbol">...</span> +<span class="cbracket">}</span> + +<span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> +<span class="function">my_callback</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GObject</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">object</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">GAsyncResult</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">result</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> +<span class="cbracket">{</span> +<span class="normal"> </span><span class="usertype">GInputStream</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">stream</span><span class="symbol">;</span> +<span class="normal"> </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">error </span><span class="symbol">=</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">;</span> + +<span class="normal"> stream </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="SoupSession.html#soup-session-send-finish">soup_session_send_finish</a></span><span class="normal"> </span><span class="symbol">(</span><span class="function">SOUP_SESSION</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">object</span><span class="symbol">),</span><span class="normal"> result</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">&</span><span class="normal">error</span><span class="symbol">);</span> +<span class="normal"> </span><span class="symbol">...</span> +<span class="cbracket">}</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +The message will be added to the session's queue, and eventually (when +control is returned back to the main loop), it will be sent and the +response be will be read. When the message has been sent, and its +headers received, the callback will be invoked, in the standard +<span class="type">GAsyncReadyCallback</span> +style. +</p> +<p> +As with synchronous sending, there is also an alternate API, <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message</code></a>, +in which your callback is not invoked until the response has been +completely read: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="cbracket">{</span> +<span class="normal"> </span><span class="symbol">...</span> +<span class="normal"> </span><span class="function"><a href="SoupSession.html#soup-session-queue-message">soup_session_queue_message</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">session</span><span class="symbol">,</span><span class="normal"> msg</span><span class="symbol">,</span><span class="normal"> my_callback</span><span class="symbol">,</span><span class="normal"> my_callback_data</span><span class="symbol">);</span> +<span class="normal"> </span><span class="symbol">...</span> +<span class="cbracket">}</span> + +<span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> +<span class="function">my_callback</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">SoupSession</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">session</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">SoupMessage</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> +<span class="cbracket">{</span> +<span class="normal"> </span><span class="comment">/* msg->response_body contains the response */</span> +<span class="cbracket">}</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +<a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message</code></a> +is slightly unusual in that it steals a reference to the message +object, and unrefs it after the last callback is invoked on it. So +when using this API, you should not unref the message yourself. +</p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.3.7"></a><h3>Processing the Response</h3> +<p> +Once you have received the initial response from the server, +synchronously or asynchronously, streaming or not, you can look at the +response fields in the <code class="literal">SoupMessage</code> to decide what +to do next. The <em class="structfield"><code>status_code</code></em> and +<em class="structfield"><code>reason_phrase</code></em> fields contain the numeric +status and textual status response from the server. +<em class="structfield"><code>response_headers</code></em> contains the response +headers, which you can investigate using <a class="link" href="SoupMessageHeaders.html#soup-message-headers-get" title="soup_message_headers_get ()"><code class="function">soup_message_headers_get</code></a> +and <a class="link" href="SoupMessageHeaders.html#soup-message-headers-foreach" title="soup_message_headers_foreach ()"><code class="function">soup_message_headers_foreach</code></a>. +</p> +<p> +<a class="link" href="SoupMessageHeaders.html" title="SoupMessageHeaders"><span class="type">SoupMessageHeaders</span></a> +automatically parses several important headers in +<em class="structfield"><code>response_headers</code></em> for you and provides +specialized accessors for them. Eg, <a class="link" href="SoupMessageHeaders.html#soup-message-headers-get-content-type" title="soup_message_headers_get_content_type ()"><code class="function">soup_message_headers_get_content_type</code></a>. +There are several generic methods such as <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-parse-param-list" title="soup_header_parse_param_list ()"><code class="function">soup_header_parse_param_list</code></a> +(for parsing an attribute-list-type header) and <a class="link" href="libsoup-2.4-Soup-Miscellaneous-Utilities.html#soup-header-contains" title="soup_header_contains ()"><code class="function">soup_header_contains</code></a> +(for quickly testing if a list-type header contains a particular +token). These handle the various syntactical oddities of parsing HTTP +headers much better than functions like +<code class="function">g_strsplit</code> or <code class="function">strstr</code>. +</p> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.3.8"></a><h3>Handling Authentication</h3> +<p> +<span class="type">SoupSession</span> handles most of the details of HTTP +authentication for you. If it receives a 401 ("Unauthorized") or 407 +("Proxy Authentication Required") response, the session will emit the +<a class="link" href="SoupSession.html#SoupSession-authenticate" title="The “authenticate” signal">authenticate</a> signal, +providing you with a <a class="link" href="SoupAuth.html" title="SoupAuth"><span class="type">SoupAuth</span></a> object indicating the +authentication type ("Basic", "Digest", or "NTLM") and the realm name +provided by the server. If you have a username and password available +(or can generate one), call <a class="link" href="SoupAuth.html#soup-auth-authenticate" title="soup_auth_authenticate ()"><code class="function">soup_auth_authenticate</code></a> +to give the information to libsoup. The session will automatically +requeue the message and try it again with that authentication +information. (If you don't call +<code class="function">soup_auth_authenticate</code>, the session will just +return the message to the application with its 401 or 407 status.) +</p> +<p> +If the server doesn't accept the username and password provided, the +session will emit <a class="link" href="SoupSession.html#SoupSession-authenticate" title="The “authenticate” signal">authenticate</a> again, with the +<code class="literal">retrying</code> parameter set to <code class="literal">TRUE</code>. This lets the +application know that the information it provided earlier was +incorrect, and gives it a chance to try again. If this +username/password pair also doesn't work, the session will contine to +emit <code class="literal">authenticate</code> again and again until the +provided username/password successfully authenticates, or until the +signal handler fails to call <a class="link" href="SoupAuth.html#soup-auth-authenticate" title="soup_auth_authenticate ()"><code class="function">soup_auth_authenticate</code></a>, +at which point <span class="application">libsoup</span> will allow the +message to fail (with status 401 or 407). +</p> +<p> +If you need to handle authentication asynchronously (eg, to pop up a +password dialog without recursively entering the main loop), you can +do that as well. Just call <a class="link" href="SoupSession.html#soup-session-pause-message" title="soup_session_pause_message ()"><code class="function">soup_session_pause_message</code></a> +on the message before returning from the signal handler, and +<code class="function">g_object_ref</code> the <span class="type">SoupAuth</span>. Then, +later on, after calling <code class="function">soup_auth_authenticate</code> +(or deciding not to), call <a class="link" href="SoupSession.html#soup-session-unpause-message" title="soup_session_unpause_message ()"><code class="function">soup_session_unpause_message</code></a> +to resume the paused message. +</p> +<p> +By default, NTLM authentication is not enabled. To add NTLM support to +a session, call: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="function"><a href="SoupSession.html#soup-session-add-feature-by-type">soup_session_add_feature_by_type</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">session</span><span class="symbol">,</span><span class="normal"> <a href="SoupAuth.html#SOUP-TYPE-AUTH-NTLM:CAPS">SOUP_TYPE_AUTH_NTLM</a></span><span class="symbol">);</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +(You can also disable Basic or Digest authentication by calling <a class="link" href="SoupSession.html#soup-session-remove-feature-by-type" title="soup_session_remove_feature_by_type ()"><code class="function">soup_session_remove_feature_by_type</code></a> +on <a class="link" href="SoupAuth.html#SOUP-TYPE-AUTH-BASIC:CAPS" title="SOUP_TYPE_AUTH_BASIC"><code class="literal">SOUP_TYPE_AUTH_BASIC</code></a> +or <a class="link" href="SoupAuth.html#SOUP-TYPE-AUTH-DIGEST:CAPS" title="SOUP_TYPE_AUTH_DIGEST"><code class="literal">SOUP_TYPE_AUTH_DIGEST</code></a>.) +</p> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.3.9"></a><h3>Multi-threaded usage</h3> +<p> +A <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> can be +used from multiple threads. However, if you are using the async APIs, +then each thread you use the session from must have its own +thread-default <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a>. +</p> +<p> +<a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a> is +<span class="emphasis"><em>not</em></span> thread-safe, so once you send a message on +the session, you must not interact with it from any thread other than +the one where it was sent. +</p> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.3.10"></a><h3>Sample Programs</h3> +<p> +A few sample programs are available in the +<span class="application">libsoup</span> sources, in the +<code class="literal">examples</code> directory: +</p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"><p> + <span class="bold"><strong><code class="literal">get</code></strong></span> is a simple command-line + HTTP GET utility using the asynchronous API. + </p></li> +<li class="listitem"><p> + <span class="bold"><strong><code class="literal">simple-proxy</code></strong></span> uses both the + client and server APIs to create a simple (and not very + RFC-compliant) proxy server. It shows how to use the <a class="link" href="SoupMessage.html#SoupMessageFlags" title="enum SoupMessageFlags"><code class="literal">SOUP_MESSAGE_OVERWRITE_CHUNKS</code></a> + flag when reading a message to save memory by processing each + chunk of the message as it is read, rather than accumulating + them all into a single buffer to process all at the end. + </p></li> +</ul></div> +<p> +More complicated examples are available in GNOME git. +</p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-request-howto.html b/docs/reference/html/libsoup-request-howto.html new file mode 100644 index 00000000..b0e44632 --- /dev/null +++ b/docs/reference/html/libsoup-request-howto.html @@ -0,0 +1,172 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: libsoup Client SoupRequest API</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch01.html" title="Tutorial"> +<link rel="prev" href="libsoup-client-howto.html" title="libsoup Client Basics"> +<link rel="next" href="libsoup-server-howto.html" title="Soup Server Basics"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="libsoup-client-howto.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-server-howto.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-request-howto"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle">libsoup Client SoupRequest API</span></h2> +<p>libsoup Client SoupRequest API — Using +libsoup with a mix of <code class="literal">http</code> and non-<code class="literal">http</code> URIs.</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect2"> +<a name="id-1.2.4.3"></a><h3><span class="type">SoupRequest</span></h3> +<p> +<a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a> is an +abstract type representing a request for a particular URI. The +<span class="type">SoupRequest</span> API is an alternative to the <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>-based <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> APIs which may be +useful to programs that want to deal with multiple kinds of URIs. +</p> +<p> +<span class="type">SoupRequest</span> officially became part of the +<span class="application">libsoup</span> API in 2.42 with the addition of +<a class="link" href="SoupSession.html#soup-session-request" title="soup_session_request ()"><code class="function">soup_session_request</code></a> +and the related functions. However, parts of it are also available as +far back as <span class="application">libsoup</span> 2.34 via the +(now-deprecated) <span class="type">SoupRequester</span> session feature, if you +define <code class="literal">LIBSOUP_USE_UNSTABLE_REQUEST_API</code> before +including the <span class="application">libsoup</span> headers. +</p> +<p> +Additionally, before <span class="application">libsoup</span> 2.42, the +<span class="type">SoupRequest</span> API was the only way to stream an HTTP +response body via <span class="type">GInputStream</span>. As of 2.42, +there are streaming APIs based on <span class="type">SoupMessage</span> (<a class="link" href="SoupSession.html#soup-session-send" title="soup_session_send ()"><code class="function">soup_session_send</code></a> +and <a class="link" href="SoupSession.html#soup-session-send-async" title="soup_session_send_async ()"><code class="function">soup_session_send_async</code></a>), +so applications that are using <span class="type">SoupRequest</span> with only +<code class="literal">http</code> and <code class="literal">https</code> URIs can be +ported to those APIs now. +</p> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.4.4"></a><h3>Creating a SoupRequest</h3> +<p> +There are four <span class="type">SoupSession</span> methods for creating +<span class="type">SoupRequest</span>s: +</p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"><p> + <a class="link" href="SoupSession.html#soup-session-request" title="soup_session_request ()"><code class="function">soup_session_request</code></a> + takes an arbitrary URI as a string, and returns a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>. + </p></li> +<li class="listitem"><p> + <a class="link" href="SoupSession.html#soup-session-request-uri" title="soup_session_request_uri ()"><code class="function">soup_session_request_uri</code></a> + takes an arbitrary URI as a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>, + and returns a <a class="link" href="SoupRequest.html" title="SoupRequest"><span class="type">SoupRequest</span></a>. + </p></li> +<li class="listitem"><p> + <a class="link" href="SoupSession.html#soup-session-request-http" title="soup_session_request_http ()"><code class="function">soup_session_request_http</code></a> + takes an HTTP method and an <code class="literal">http</code> or <code class="literal">https</code> URI as a string, and returns a <a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a>. + </p></li> +<li class="listitem"><p> + <a class="link" href="SoupSession.html#soup-session-request-http-uri" title="soup_session_request_http_uri ()"><code class="function">soup_session_request_http_uri</code></a> + takes an HTTP method and an <code class="literal">http</code> or <code class="literal">https</code> URI as a <a class="link" href="SoupURI.html" title="SoupURI"><span class="type">SoupURI</span></a>, + and returns a <a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a>. + </p></li> +</ul></div> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.4.5"></a><h3>Sending a SoupRequest</h3> +<p> +Once you have created a <span class="type">SoupRequest</span>, you can send it with +either <a class="link" href="SoupRequest.html#soup-request-send" title="soup_request_send ()"><code class="function">soup_request_send</code></a> +or <a class="link" href="SoupRequest.html#soup-request-send-async" title="soup_request_send_async ()"><code class="function">soup_request_send_async</code></a>. +This will provide you with a <span class="type">GInputStream</span> which you can +read to get the response body. +</p> +<p> +After sending, you can use <a class="link" href="SoupRequest.html#soup-request-get-content-length" title="soup_request_get_content_length ()"><code class="function">soup_request_get_content_length</code></a> +and <a class="link" href="SoupRequest.html#soup-request-get-content-type" title="soup_request_get_content_type ()"><code class="function">soup_request_get_content_type</code></a> +to get information about the response body. +</p> +<p> +As with the streaming <span class="type">SoupMessage</span>-based APIs, +<code class="function">soup_request_send</code> and +<code class="function">soup_request_send_async</code> only return errors if a +transport-level problem occurs (eg, it could not connect to the host, +or the request was cancelled). In the case of an HTTP request, use the +message's <em class="structfield"><code>status_code</code></em> field to determine +whether the request was successful or not at the HTTP level (ie, "<code class="literal">200 +OK</code>" vs "<code class="literal">401 Bad Request</code>"). (You can call <a class="link" href="SoupRequestHTTP.html#soup-request-http-get-message" title="soup_request_http_get_message ()"><code class="function">soup_request_http_get_message</code></a> +to get the request's corresponding <a class="link" href="SoupMessage.html" title="SoupMessage"><span class="type">SoupMessage</span></a>, to look at the +status code or other HTTP metadata.) +</p> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.4.6"></a><h3>Supported URI types, and adding your own</h3> +<p> +Different URI types are implemented by different subclasses of +<span class="type">SoupRequest</span>. <span class="application">libsoup</span> currently +implements three <span class="type">SoupRequest</span> classes: +</p> +<div class="variablelist"><table border="0" class="variablelist"> +<colgroup> +<col align="left" valign="top"> +<col> +</colgroup> +<tbody> +<tr> +<td><p><span class="term"><a class="link" href="SoupRequestHTTP.html" title="SoupRequestHTTP"><span class="type">SoupRequestHTTP</span></a></span></p></td> +<td><p> + Handles <code class="literal">http</code> and + <code class="literal">https</code> URI. + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupRequestData.html" title="SoupRequestData"><span class="type">SoupRequestData</span></a></span></p></td> +<td><p> + Handles <code class="literal">data</code> URIs containing inline data. + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupRequestFile.html" title="SoupRequestFile"><span class="type">SoupRequestFile</span></a></span></p></td> +<td><p> + Handles <code class="literal">file</code> and + <code class="literal">resource</code> URIs. + If you request a URI corresponding to a directory, this + will generate an HTML listing of the directory. + </p></td> +</tr> +</tbody> +</table></div> +<p> +You can add additional URI types by implementing your own +<span class="type">SoupRequest</span> subclass; set the +<span class="type">SoupRequestClass</span>'s <em class="structfield"><code>schemes</code></em> +field to point to a <code class="literal">NULL</code>-terminated array of scheme +names, implement the various <span class="type">SoupRequest</span> methods, and +then register the type with your <span class="type">SoupSession</span> by calling +<a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()"><code class="function">soup_session_add_feature_by_type</code></a> +and passing the <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType"><span class="type">GType</span></a> of +your request class. +</p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-server-howto.html b/docs/reference/html/libsoup-server-howto.html new file mode 100644 index 00000000..aaeba8b8 --- /dev/null +++ b/docs/reference/html/libsoup-server-howto.html @@ -0,0 +1,444 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Soup Server Basics</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch01.html" title="Tutorial"> +<link rel="prev" href="libsoup-request-howto.html" title="libsoup Client SoupRequest API"> +<link rel="next" href="libsoup-session-porting.html" title="Porting to the new SoupSession"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="libsoup-request-howto.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="libsoup-session-porting.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-server-howto"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle">Soup Server Basics</span></h2> +<p>Soup Server Basics — Server-side tutorial</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect2"> +<a name="id-1.2.5.3"></a><h3>Creating a SoupSession</h3> +<p> +As with the client API, there is a single object that will encapsulate +most of your interactions with libsoup. In this case, <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a>. +</p> +<p> +You create the server with <a class="link" href="SoupServer.html#soup-server-new" title="soup_server_new ()"><code class="function">soup_server_new</code></a>, +and as with the <span class="type">SoupSession</span> constructor, you can specify +various additional options: +</p> +<div class="variablelist"><table border="0" class="variablelist"> +<colgroup> +<col align="left" valign="top"> +<col> +</colgroup> +<tbody> +<tr> +<td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-PORT:CAPS" title="SOUP_SERVER_PORT"><code class="literal">SOUP_SERVER_PORT</code></a></span></p></td> +<td><p> + The TCP port to listen on. If <code class="literal">0</code> (or + left unspecified), some unused port will be selected for + you. (You can find out what port by calling <a class="link" href="SoupServer.html#soup-server-get-port" title="soup_server_get_port ()"><code class="function">soup_server_get_port</code></a>. + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-INTERFACE:CAPS" title="SOUP_SERVER_INTERFACE"><code class="literal">SOUP_SERVER_INTERFACE</code></a></span></p></td> +<td><p> + A <a class="link" href="SoupAddress.html" title="SoupAddress"><span class="type">SoupAddress</span></a>, + specifying the IP address of the network interface to run + the server on. If <code class="literal">NULL</code> (or left + unspecified), the server will listen on all interfaces. + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-SSL-CERT-FILE:CAPS" title="SOUP_SERVER_SSL_CERT_FILE"><code class="literal">SOUP_SERVER_SSL_CERT_FILE</code></a></span></p></td> +<td><p> + Points to a file containing an SSL certificate to use. If + this is set, then the server will speak HTTPS; otherwise + it will speak HTTP. + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-SSL-KEY-FILE:CAPS" title="SOUP_SERVER_SSL_KEY_FILE"><code class="literal">SOUP_SERVER_SSL_KEY_FILE</code></a></span></p></td> +<td><p> + Points to a file containing the private key for the + <code class="literal">SOUP_SERVER_SSL_CERT_FILE</code>. (It may + point to the same file.) + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-ASYNC-CONTEXT:CAPS" title="SOUP_SERVER_ASYNC_CONTEXT"><code class="literal">SOUP_SERVER_ASYNC_CONTEXT</code></a></span></p></td> +<td><p> + A <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> which + the server will use for asynchronous operations. This can + be set if you want to use a SoupServer in a thread + other than the main thread. + </p></td> +</tr> +<tr> +<td><p><span class="term"><a class="link" href="SoupServer.html#SOUP-SERVER-RAW-PATHS:CAPS" title="SOUP_SERVER_RAW_PATHS"><code class="literal">SOUP_SERVER_RAW_PATHS</code></a></span></p></td> +<td><p> + Set this to <code class="literal">TRUE</code> if you don't want + <span class="application">libsoup</span> to decode %-encoding + in the Request-URI. (Eg, because you need to treat + <code class="literal">"/foo/bar"</code> and + <code class="literal">"/foo%2Fbar"</code> as different paths. + </p></td> +</tr> +</tbody> +</table></div> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.5.4"></a><h3>Adding Handlers</h3> +<p> +By default, <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> +returns "404 Not Found" in response to all requests (except ones that +it can't parse, which get "400 Bad Request"). To override this +behavior, call <a class="link" href="SoupServer.html#soup-server-add-handler" title="soup_server_add_handler ()"><code class="function">soup_server_add_handler</code></a> +to set a callback to handle certain URI paths. +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="function"><a href="SoupServer.html#soup-server-add-handler">soup_server_add_handler</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">server</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"/foo"</span><span class="symbol">,</span><span class="normal"> server_callback</span><span class="symbol">,</span> +<span class="normal"> data</span><span class="symbol">,</span><span class="normal"> destroy_notify</span><span class="symbol">);</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +The <code class="literal">"/foo"</code> indicates the base path for this +handler. When a request comes in, if there is a handler registered for +exactly the path in the request's <code class="literal">Request-URI</code>, then +that handler will be called. Otherwise +<span class="application">libsoup</span> will strip path components one by +one until it finds a matching handler. So for example, a request of +the form +"<code class="literal">GET /foo/bar/baz.html?a=1&b=2 HTTP/1.1</code>" +would look for handlers for "<code class="literal">/foo/bar/baz.html</code>", +"<code class="literal">/foo/bar</code>", and "<code class="literal">/foo</code>". If a +handler has been registered with a <code class="literal">NULL</code> base path, +then it is used as the default handler for any request that doesn't +match any other handler. +</p> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.5.5"></a><h3>Responding to Requests</h3> +<p> +A handler callback looks something like this: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4 +5 +6 +7 +8 +9 +10</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> +<span class="function">server_callback</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">SoupServer</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">server</span><span class="symbol">,</span> +<span class="normal"> </span><span class="usertype">SoupMessage</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> </span> +<span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">path</span><span class="symbol">,</span> +<span class="normal"> </span><span class="usertype">GHashTable</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">query</span><span class="symbol">,</span> +<span class="normal"> </span><span class="usertype">SoupClientContext</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">client</span><span class="symbol">,</span> +<span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> +<span class="cbracket">{</span> +<span class="normal"> </span><span class="symbol">...</span> +<span class="cbracket">}</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +<code class="literal">msg</code> is the request that has been received and +<code class="literal">user_data</code> is the data that was passed to <a class="link" href="SoupServer.html#soup-server-add-handler" title="soup_server_add_handler ()"><code class="function">soup_server_add_handler</code></a>. +<code class="literal">path</code> is the path (from <code class="literal">msg</code>'s +URI), and <code class="literal">query</code> contains the result of parsing the +URI query field. (It is <code class="literal">NULL</code> if there was no +query.) <code class="literal">client</code> is a <a class="link" href="SoupServer.html#SoupClientContext"><span class="type">SoupClientContext</span></a>, +which contains additional information about the client (including its +IP address, and whether or not it used HTTP authentication). +</p> +<p> +By default, <span class="application">libsoup</span> assumes that you have +completely finished processing the message when you return from the +callback, and that it can therefore begin sending the response. If you +are not ready to send a response immediately (eg, you have to contact +another server, or wait for data from a database), you must call <a class="link" href="SoupServer.html#soup-server-pause-message" title="soup_server_pause_message ()"><code class="function">soup_server_pause_message</code></a> +on the message before returning from the callback. This will delay +sending a response until you call <a class="link" href="SoupServer.html#soup-server-unpause-message" title="soup_server_unpause_message ()"><code class="function">soup_server_unpause_message</code></a>. +(You must also connect to the <a class="link" href="SoupMessage.html#SoupMessage-finished" title="The “finished” signal">finished</a> signal on the message +in this case, so that you can break off processing if the client +unexpectedly disconnects before you start sending the data.) +</p> +<p> +To set the response status, call <a class="link" href="SoupMessage.html#soup-message-set-status" title="soup_message_set_status ()"><code class="function">soup_message_set_status</code></a> +or <a class="link" href="SoupMessage.html#soup-message-set-status-full" title="soup_message_set_status_full ()"><code class="function">soup_message_set_status_full</code></a>. +If the response requires a body, you must decide whether to use +<code class="literal">Content-Length</code> encoding (the default), or +<code class="literal">chunked</code> encoding. +</p> +<div class="refsect3"> +<a name="id-1.2.5.5.7"></a><h4>Responding with <code class="literal">Content-Length</code> +Encoding</h4> +<p> +This is the simpler way to set a response body, if you have all of the +data available at once. +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> </span><span class="type">void</span> +<span class="function">server_callback</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">SoupServer</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">server</span><span class="symbol">,</span> +<span class="normal"> </span><span class="usertype">SoupMessage</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> </span> +<span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">path</span><span class="symbol">,</span> +<span class="normal"> </span><span class="usertype">GHashTable</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">query</span><span class="symbol">,</span> +<span class="normal"> </span><span class="usertype">SoupClientContext</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">client</span><span class="symbol">,</span> +<span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> +<span class="cbracket">{</span> +<span class="normal"> </span><span class="usertype">MyServerData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">server_data </span><span class="symbol">=</span><span class="normal"> user_data</span><span class="symbol">;</span> +<span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">mime_type</span><span class="symbol">;</span> +<span class="normal"> </span><span class="usertype">GByteArray</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">body</span><span class="symbol">;</span> + +<span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">-></span><span class="normal">method </span><span class="symbol">!=</span><span class="normal"> <a href="libsoup-2.4-soup-method.html#SOUP-METHOD-GET:CAPS">SOUP_METHOD_GET</a></span><span class="symbol">)</span><span class="normal"> </span><span class="cbracket">{</span> +<span class="normal"> </span><span class="function"><a href="SoupMessage.html#soup-message-set-status">soup_message_set_status</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> <a href="libsoup-2.4-soup-status.html#SOUP-STATUS-NOT-IMPLEMENTED:CAPS">SOUP_STATUS_NOT_IMPLEMENTED</a></span><span class="symbol">);</span> +<span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span> +<span class="normal"> </span><span class="cbracket">}</span> + +<span class="normal"> </span><span class="comment">/* This is somewhat silly. Presumably your server will do</span> +<span class="comment"> * something more interesting.</span> +<span class="comment"> */</span> +<span class="normal"> body </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#g-hash-table-lookup">g_hash_table_lookup</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">server_data</span><span class="symbol">-></span><span class="normal">bodies</span><span class="symbol">,</span><span class="normal"> path</span><span class="symbol">);</span> +<span class="normal"> mime_type </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#g-hash-table-lookup">g_hash_table_lookup</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">server_data</span><span class="symbol">-></span><span class="normal">mime_types</span><span class="symbol">,</span><span class="normal"> path</span><span class="symbol">);</span> +<span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">body </span><span class="symbol">||</span><span class="normal"> </span><span class="symbol">!</span><span class="normal">mime_type</span><span class="symbol">)</span><span class="normal"> </span><span class="cbracket">{</span> +<span class="normal"> </span><span class="function"><a href="SoupMessage.html#soup-message-set-status">soup_message_set_status</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> <a href="libsoup-2.4-soup-status.html#SOUP-STATUS-NOT-FOUND:CAPS">SOUP_STATUS_NOT_FOUND</a></span><span class="symbol">);</span> +<span class="normal"> </span><span class="keyword">return</span><span class="symbol">;</span> +<span class="normal"> </span><span class="cbracket">}</span> + +<span class="normal"> </span><span class="function"><a href="SoupMessage.html#soup-message-set-status">soup_message_set_status</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> <a href="libsoup-2.4-soup-status.html#SOUP-STATUS-OK:CAPS">SOUP_STATUS_OK</a></span><span class="symbol">);</span> +<span class="normal"> </span><span class="function"><a href="SoupMessage.html#soup-message-set-response">soup_message_set_response</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">msg</span><span class="symbol">,</span><span class="normal"> mime_type</span><span class="symbol">,</span><span class="normal"> <a href="SoupMessageBody.html#SOUP-MEMORY-COPY:CAPS">SOUP_MEMORY_COPY</a></span><span class="symbol">,</span> +<span class="normal"> body</span><span class="symbol">-></span><span class="normal">data</span><span class="symbol">,</span><span class="normal"> body</span><span class="symbol">-></span><span class="normal">len</span><span class="symbol">);</span> +<span class="cbracket">}</span></pre></td> + </tr> + </tbody> + </table> +</div> + +</div> +<div class="refsect3"> +<a name="id-1.2.5.5.8"></a><h4>Responding with <code class="literal">chunked</code> Encoding</h4> +<p> +If you want to supply the response body in chunks as it becomes +available, use <code class="literal">chunked</code> encoding instead. In this +case, first call <a class="link" href="SoupMessageHeaders.html#soup-message-headers-set-encoding" title="soup_message_headers_set_encoding ()"><code class="function">soup_message_headers_set_encoding</code></a> <code class="literal">(msg->response_headers, <a class="link" href="SoupMessageHeaders.html#SoupEncoding" title="enum SoupEncoding">SOUP_ENCODING_CHUNKED</a>)</code> +to tell <span class="application">libsoup</span> that you'll be using +chunked encoding. Then call <a class="link" href="SoupMessageBody.html#soup-message-body-append" title="soup_message_body_append ()"><code class="function">soup_message_body_append</code></a> +(or <a class="link" href="SoupMessageBody.html#soup-message-body-append-buffer" title="soup_message_body_append_buffer ()"><code class="function">soup_message_body_append_buffer</code></a>) +on <code class="literal">msg->response_body</code> with each chunk of the +response body as it becomes available, and call <a class="link" href="SoupMessageBody.html#soup-message-body-complete" title="soup_message_body_complete ()"><code class="function">soup_message_body_complete</code></a> +when the response is complete. After each of these calls, you must +also call <a class="link" href="SoupServer.html#soup-server-unpause-message" title="soup_server_unpause_message ()"><code class="function">soup_server_unpause_message</code></a> +to cause the chunk to be sent. (You do not normally need to call <a class="link" href="SoupServer.html#soup-server-pause-message" title="soup_server_pause_message ()"><code class="function">soup_server_pause_message</code></a>, +because I/O is automatically paused when doing a +<code class="literal">chunked</code> transfer if no chunks are available.) +</p> +<p> +When using chunked encoding, you must also connect to the <a class="link" href="SoupMessage.html#SoupMessage-finished" title="The “finished” signal">finished</a> signal on the message, +so that you will be notified if the client disconnects between two +chunks; <span class="type">SoupServer</span> will unref the message if that +happens, so you must stop adding new chunks to the response at that +point. (An alternate possibility is to write each new chunk only when +the <a class="link" href="SoupMessage.html#SoupMessage-wrote-chunk" title="The “wrote-chunk” signal">wrote_chunk</a> signal +is emitted indicating that the previous one was written successfully.) +</p> +<p> +The <span class="bold"><strong><code class="literal">simple-proxy</code></strong></span> +example in the <code class="literal">examples/</code> directory gives an example of +using <code class="literal">chunked</code> encoding. +</p> +</div> +</div> +<hr> +<div class="refsect2"> +<a name="id-1.2.5.6"></a><h3>Handling Authentication</h3> +<p> +To have <a class="link" href="SoupServer.html" title="SoupServer"><span class="type">SoupServer</span></a> +handle HTTP authentication for you, create a <a class="link" href="SoupAuthDomainBasic.html" title="SoupAuthDomainBasic"><span class="type">SoupAuthDomainBasic</span></a> +or <a class="link" href="SoupAuthDomainDigest.html" title="SoupAuthDomainDigest"><span class="type">SoupAuthDomainDigest</span></a>, +and pass it to <a class="link" href="SoupServer.html#soup-server-add-auth-domain" title="soup_server_add_auth_domain ()"><code class="function">soup_server_add_auth_domain</code></a>: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="usertype">SoupAuthDomain</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">domain</span><span class="symbol">;</span> + +<span class="normal">domain </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="SoupAuthDomainBasic.html#soup-auth-domain-basic-new">soup_auth_domain_basic_new</a></span><span class="normal"> </span><span class="symbol">(</span> +<span class="normal"> <a href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-REALM:CAPS">SOUP_AUTH_DOMAIN_REALM</a></span><span class="symbol">,</span><span class="normal"> </span><span class="string">"My Realm"</span><span class="symbol">,</span> +<span class="normal"> <a href="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-CALLBACK:CAPS">SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK</a></span><span class="symbol">,</span><span class="normal"> auth_callback</span><span class="symbol">,</span> +<span class="normal"> <a href="SoupAuthDomainBasic.html#SOUP-AUTH-DOMAIN-BASIC-AUTH-DATA:CAPS">SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA</a></span><span class="symbol">,</span><span class="normal"> auth_data</span><span class="symbol">,</span> +<span class="normal"> <a href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-ADD-PATH:CAPS">SOUP_AUTH_DOMAIN_ADD_PATH</a></span><span class="symbol">,</span><span class="normal"> </span><span class="string">"/foo"</span><span class="symbol">,</span> +<span class="normal"> <a href="SoupAuthDomain.html#SOUP-AUTH-DOMAIN-ADD-PATH:CAPS">SOUP_AUTH_DOMAIN_ADD_PATH</a></span><span class="symbol">,</span><span class="normal"> </span><span class="string">"/bar/private"</span><span class="symbol">,</span> +<span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> +<span class="function"><a href="SoupServer.html#soup-server-add-auth-domain">soup_server_add_auth_domain</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">server</span><span class="symbol">,</span><span class="normal"> domain</span><span class="symbol">);</span> +<span class="function"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">domain</span><span class="symbol">);</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +Then, every request under one of the auth domain's paths will be +passed to the <code class="literal">auth_callback</code> first before being +passed to the <code class="literal">server_callback</code>: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="keyword">static</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean">gboolean</a></span> +<span class="function">auth_callback</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">SoupAuthDomain</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">domain</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">SoupMessage</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">msg</span><span class="symbol">,</span> +<span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">username</span><span class="symbol">,</span><span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">password</span><span class="symbol">,</span> +<span class="normal"> </span><span class="usertype">gpointer</span><span class="normal"> user_data</span><span class="symbol">)</span> +<span class="cbracket">{</span> +<span class="normal"> </span><span class="usertype">MyServerData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">server_data </span><span class="symbol">=</span><span class="normal"> user_data</span><span class="symbol">;</span> +<span class="normal"> </span><span class="usertype">MyUserData</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">user</span><span class="symbol">;</span> + +<span class="normal"> user </span><span class="symbol">=</span><span class="normal"> </span><span class="function">my_server_data_lookup_user</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">server_data</span><span class="symbol">,</span><span class="normal"> username</span><span class="symbol">);</span> +<span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">user</span><span class="symbol">)</span> +<span class="normal"> </span><span class="keyword">return</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span> + +<span class="normal"> </span><span class="comment">/* </span><span class="todo">FIXME:</span><span class="comment"> Don't do this. Keeping a cleartext password database</span> +<span class="comment"> * is bad.</span> +<span class="comment"> */</span> +<span class="normal"> </span><span class="keyword">return</span><span class="normal"> </span><span class="function">strcmp</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">password</span><span class="symbol">,</span><span class="normal"> user</span><span class="symbol">-></span><span class="normal">password</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">==</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span> +<span class="cbracket">}</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p> +The <a class="link" href="SoupAuthDomainBasic.html#SoupAuthDomainBasicAuthCallback" title="SoupAuthDomainBasicAuthCallback ()"><span class="type">SoupAuthDomainBasicAuthCallback</span></a> +is given the username and password from the +<code class="literal">Authorization</code> header and must determine, in some +server-specific manner, whether or not to accept them. (In this +example we compare the password against a cleartext password database, +but it would be better to store the password somehow encoded, as in +the UNIX password database. Alternatively, you may need to delegate +the password check to PAM or some other service.) +</p> +<p> +If you are using Digest authentication, note that <a class="link" href="SoupAuthDomainDigest.html#SoupAuthDomainDigestAuthCallback" title="SoupAuthDomainDigestAuthCallback ()"><span class="type">SoupAuthDomainDigestAuthCallback</span></a> +works completely differently (since the server doesn't receive the +cleartext password from the client in that case, so there's no way to +compare it directly). See the documentation for <a class="link" href="SoupAuthDomainDigest.html" title="SoupAuthDomainDigest"><span class="type">SoupAuthDomainDigest</span></a> +for more details. +</p> +<p> +You can have multiple <span class="type">SoupAuthDomain</span>s attached to a +<code class="literal">SoupServer</code>, either in separate parts of the path +hierarchy, or overlapping. (Eg, you might want to accept either Basic +or Digest authentication for a given path.) When more than one auth +domain covers a given path, the request will be accepted if the user +authenticates successfully against <span class="emphasis"><em>any</em></span> of the +domains. +</p> +<p> +If you want to require authentication for some requests under a +certain path, but not all of them (eg, you want to authenticate +<code class="literal">PUT</code> requests, but not <code class="literal">GET</code> +requests), use a <a class="link" href="SoupAuthDomain.html#SoupAuthDomainFilter" title="SoupAuthDomainFilter ()"><span class="type">SoupAuthDomainFilter</span></a>. +</p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/libsoup-session-porting.html b/docs/reference/html/libsoup-session-porting.html new file mode 100644 index 00000000..8d536a76 --- /dev/null +++ b/docs/reference/html/libsoup-session-porting.html @@ -0,0 +1,218 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>libsoup Reference Manual: Porting to the new SoupSession</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="libsoup Reference Manual"> +<link rel="up" href="ch01.html" title="Tutorial"> +<link rel="prev" href="libsoup-server-howto.html" title="Soup Server Basics"> +<link rel="next" href="ch02.html" title="Core API"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="libsoup-server-howto.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="ch02.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="libsoup-session-porting"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle">Porting to the new SoupSession</span></h2> +<p>Porting to the new SoupSession — Notes on +porting from SoupSessionAsync and SoupSessionSync to SoupSession</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect2"> +<a name="intro"></a><h3>Introduction</h3> +<p> +As of libsoup 2.42, <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> is no longer an +abstract class, and the base <span class="type">SoupSession</span> class is now +preferred over its traditional subclasses, <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> and +<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>. +</p> +<p> +There are several changes in behavior between the old and new sessions +to be aware of. +</p> +</div> +<hr> +<div class="refsect2"> +<a name="defaults"></a><h3>Different defaults</h3> +<p> +The new <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> +has different (and hopefully better) defaults than <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a> and +<a class="link" href="SoupSessionSync.html" title="SoupSessionSync"><span class="type">SoupSessionSync</span></a>: +</p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> +<p> + The system TLS/SSL certificate database is used by default to + validate https certificates, and sites with invalid certificates + will refuse to load with a + <a class="link" href="libsoup-2.4-soup-status.html#SOUP-STATUS-SSL-FAILED:CAPS"><code class="literal">SOUP_STATUS_SSL_FAILED</code></a> + error. + </p> +<p> + You can still override the CA database as before, by setting the + <a class="link" href="SoupSession.html#SoupSession--ssl-ca-file" title="The “ssl-ca-file” property"><span class="type">"ssl-ca-file"</span></a> + property, although the + <a class="link" href="SoupSession.html#SoupSession--tls-database" title="The “tls-database” property"><span class="type">"tls-database"</span></a> + property is preferred, since it allows you to do proper error + handling. + </p> +<p> + If you want to accept all certificates, set + <a class="link" href="SoupSession.html#SoupSession--ssl-strict" title="The “ssl-strict” property"><span class="type">"ssl-strict"</span></a> to + <code class="literal">FALSE</code>. Note that libsoup will still check + certificates, it will just continue with the HTTP request even + if the certificate fails to validate. You can use + <a class="link" href="SoupMessage.html#soup-message-get-https-status" title="soup_message_get_https_status ()"><code class="function">soup_message_get_https_status()</code></a> + to look at the certificate after the fact. + </p> +</li> +<li class="listitem"><p> + The + <a class="link" href="SoupSession.html#SoupSession--timeout" title="The “timeout” property"><span class="type">"timeout"</span></a> + and + <a class="link" href="SoupSession.html#SoupSession--idle-timeout" title="The “idle-timeout” property"><span class="type">"idle-timeout"</span></a> + properties both default to 60 seconds. + </p></li> +<li class="listitem"><p> + The + <a class="link" href="SoupSession.html#SoupSession--http-aliases" title="The “http-aliases” property"><span class="type">"http-aliases"</span></a> + property defaults to <code class="literal">NULL</code>, meaning that URI + schemes like "<code class="literal">webcal</code>" and + "<code class="literal">dav</code>" (and "<code class="literal">ftp</code>") are not + considered to be aliases for "<code class="literal">http</code>", and so + libsoup will not accept requests for such URIs, and will not + follow redirects to such URIs. + </p></li> +<li class="listitem"><p> + The new + <a class="link" href="SoupSession.html#SoupSession--proxy-resolver" title="The “proxy-resolver” property"><span class="type">"proxy-resolver"</span></a> + property is now initialized to the default + <span class="type">GProxyResolver</span>, + meaning that it will automatically use the user's system proxy + configuration. This replaces the use of the + <a class="link" href="SoupProxyResolverDefault.html" title="SoupProxyResolverDefault"><span class="type">SoupProxyResolverDefault</span></a>, + session feature in earlier releases. You can set this property to + <code class="literal">NULL</code> if you don't want to use proxies, and the + <a class="link" href="SoupSession.html#SoupSession--proxy-uri" title="The “proxy-uri” property"><span class="type">"proxy-uri"</span></a> + property still works if you want to use a single proxy for all requests. + </p></li> +<li class="listitem"><p> + Every session gets a + <a class="link" href="SoupContentDecoder.html" title="SoupContentDecoder"><span class="type">SoupContentDecoder</span></a> + attached to it by default, meaning that it will automatically + handle (and request) "gzip"- and "deflate"-encoded response + bodies. + </p></li> +</ul></div> +</div> +<hr> +<div class="refsect2"> +<a name="behavior"></a><h3>Differences in feature behavior</h3> +<p> +If you are using NTLM authentication, the new <span class="type">SoupSession</span> +behaves slightly differently from the old session types. +</p> +<p> +First, the deprecated <code class="literal">SOUP_SESSION_USE_NTLM</code> +property is no longer supported. If you want to add support for NTLM +to a session, call <a class="link" href="SoupSession.html#soup-session-add-feature-by-type" title="soup_session_add_feature_by_type ()"><code class="function">soup_session_add_feature_by_type()</code></a>, +passing <a class="link" href="SoupAuth.html#SOUP-TYPE-AUTH-NTLM:CAPS" title="SOUP_TYPE_AUTH_NTLM"><code class="literal">SOUP_TYPE_AUTH_NTLM</code></a>. +</p> +<p> +Second, with the old session types, enabling NTLM would cause all +(otherwise-unauthenticated) requests to be sent with an NTLM request +in the <code class="literal">Authorization</code> header. That is, libsoup would +assume that all servers supported NTLM, and would attempt to begin +negotiating NTLM authentication before the server ever returned a 401 +response. With the plain <span class="type">SoupSession</span>, this no longer +happens. If you want the old behavior, you need to call <a class="link" href="SoupAuthManager.html#soup-auth-manager-use-auth" title="soup_auth_manager_use_auth ()"><code class="function">soup_auth_manager_use_auth()</code></a> +for each host to "preload" the NTLM authentication: +</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4 +5 +6 +7 +8 +9 +10</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="usertype">SoupAuthManager</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">auth_manager</span><span class="symbol">;</span> +<span class="usertype">SoupAuth</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">auth</span><span class="symbol">;</span> +<span class="usertype">SoupURI</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">uri</span><span class="symbol">;</span> + +<span class="normal">auth_manager </span><span class="symbol">=</span><span class="normal"> </span><span class="function">SOUP_AUTH_MANAGER</span><span class="normal"> </span><span class="symbol">(</span><span class="function"><a href="SoupSession.html#soup-session-get-feature">soup_session_get_feature</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">session</span><span class="symbol">,</span><span class="normal"> <a href="SoupAuthManager.html#SOUP-TYPE-AUTH-MANAGER:CAPS">SOUP_TYPE_AUTH_MANAGER</a></span><span class="symbol">));</span> +<span class="normal">auth </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-new">g_object_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="SoupAuth.html#SOUP-TYPE-AUTH-NTLM:CAPS">SOUP_TYPE_AUTH_NTLM</a></span><span class="symbol">,</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span> +<span class="normal">uri </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="SoupURI.html#soup-uri-new">soup_uri_new</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"http://ntlm-using-host.example.com/"</span><span class="symbol">);</span> +<span class="function"><a href="SoupAuthManager.html#soup-auth-manager-use-auth">soup_auth_manager_use_auth</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">auth_manager</span><span class="symbol">,</span><span class="normal"> uri</span><span class="symbol">,</span><span class="normal"> auth</span><span class="symbol">);</span> +<span class="function"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">auth</span><span class="symbol">);</span> +<span class="function"><a href="SoupURI.html#soup-uri-free">soup_uri_free</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">auth</span><span class="symbol">);</span></pre></td> + </tr> + </tbody> + </table> +</div> + +</div> +<hr> +<div class="refsect2"> +<a name="apis"></a><h3>Differences in SoupMessage-sending APIs</h3> +<p> +<span class="type">SoupSessionAsync</span> always uses asynchronous I/O, and +<span class="type">SoupSessionSync</span> always uses blocking I/O, regardless of +the operation. In the new <span class="type">SoupSession</span>, <a class="link" href="SoupSession.html#soup-session-queue-message" title="soup_session_queue_message ()"><code class="function">soup_session_queue_message()</code></a> +uses asynchronous I/O (like <span class="type">SoupSessionAsync</span>), and <a class="link" href="SoupSession.html#soup-session-send-message" title="soup_session_send_message ()"><code class="function">soup_session_send_message()</code></a> +uses blocking I/O (like <span class="type">SoupSessionSync</span>). There is no API +on the plain <span class="type">SoupSession</span> that simulates the effect of +calling <code class="function">soup_session_send_message()</code> on a +<span class="type">SoupSessionAsync</span> (ie, running the main loop internally), +or of calling <code class="function">soup_session_queue_message()</code> on a +<span class="type">SoupSessionSync</span> (ie, automatically sending the request in +another thread). +</p> +</div> +<hr> +<div class="refsect2"> +<a name="async"></a><h3>Differences in Asynchronous I/O</h3> +<p> +As compared to <a class="link" href="SoupSessionAsync.html" title="SoupSessionAsync"><span class="type">SoupSessionAsync</span></a>, <a class="link" href="SoupSession.html" title="SoupSession"><span class="type">SoupSession</span></a> behaves more +like gio with respect to asynchronous I/O. +</p> +<p> +In particular, the <a class="link" href="SoupSession.html#SoupSession--async-context" title="The “async-context” property"><span class="type">"async-context"</span></a> +and <a class="link" href="SoupSession.html#SoupSession--use-thread-context" title="The “use-thread-context” property"><span class="type">"use-thread-context"</span></a> +properties are now effectively unused, and the session always queues +asynchronous requests in the <a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> that was is +the thread default when the asynchronous operation is started. Session +bookkeeping tasks (like closing idle connections) happen in the +context that was thread default when the session was created. +</p> +<p> +Additionally, <a class="link" href="SoupSession.html#soup-session-cancel-message" title="soup_session_cancel_message ()"><code class="function">soup_session_cancel_message()</code></a> +now acts asynchronously when you cancel an asynchronous request; +rather than having the request's callback be called from inside +<code class="function">soup_session_cancel_message()</code>, it just gets called +when you need return to the main loop. +</p> +</div> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file diff --git a/docs/reference/html/right-insensitive.png b/docs/reference/html/right-insensitive.png Binary files differnew file mode 100644 index 00000000..4c95785b --- /dev/null +++ b/docs/reference/html/right-insensitive.png diff --git a/docs/reference/html/right.png b/docs/reference/html/right.png Binary files differnew file mode 100644 index 00000000..76260ec8 --- /dev/null +++ b/docs/reference/html/right.png diff --git a/docs/reference/html/style.css b/docs/reference/html/style.css new file mode 100644 index 00000000..705a5c9a --- /dev/null +++ b/docs/reference/html/style.css @@ -0,0 +1,461 @@ +body +{ + font-family: cantarell, sans-serif; +} +.synopsis, .classsynopsis +{ + /* tango:aluminium 1/2 */ + background: #eeeeec; + background: rgba(238, 238, 236, 0.5); + border: solid 1px rgb(238, 238, 236); + padding: 0.5em; +} +.programlisting +{ + /* tango:sky blue 0/1 */ + /* fallback for no rgba support */ + background: #e6f3ff; + border: solid 1px #729fcf; + background: rgba(114, 159, 207, 0.1); + border: solid 1px rgba(114, 159, 207, 0.2); + padding: 0.5em; +} +.variablelist +{ + padding: 4px; + margin-left: 3em; +} +.variablelist td:first-child +{ + vertical-align: top; +} + +@media screen { + sup a.footnote + { + position: relative; + top: 0em ! important; + } + /* this is needed so that the local anchors are displayed below the naviagtion */ + div.footnote a[name], div.refnamediv a[name], div.refsect1 a[name], div.refsect2 a[name], div.index a[name], div.glossary a[name], div.sect1 a[name] + { + display: inline-block; + position: relative; + top:-5em; + } + /* this seems to be a bug in the xsl style sheets when generating indexes */ + div.index div.index + { + top: 0em; + } + /* make space for the fixed navigation bar and add space at the bottom so that + * link targets appear somewhat close to top + */ + body + { + padding-top: 5em; + padding-bottom: 500px; + max-width: 60em; + } + p + { + max-width: 60em; + } + /* style and size the navigation bar */ + table.navigation#top + { + position: fixed; + background: #e2e2e2; + border-bottom: solid 1px #babdb6; + margin-top: 0; + margin-bottom: 0; + top: 0; + left: 0; + height: 3em; + z-index: 10; + } + .navigation a, .navigation a:visited + { + /* tango:sky blue 3 */ + color: #204a87; + } + .navigation a:hover + { + /* tango:sky blue 2 */ + color: #3465a4; + } + td.shortcuts + { + /* tango:sky blue 2 */ + color: #3465a4; + font-size: 80%; + white-space: nowrap; + } + td.shortcuts .dim + { + color: #babdb6; + } +} +@media screen and (min-width: 60em) { + /* screen larger than 60em */ + body { margin: auto; } +} +@media screen and (max-width: 60em) { + /* screen less than 60em */ + #nav_hierarchy { display: none; } + #nav_interfaces { display: none; } + #nav_prerequisites { display: none; } + #nav_derived_interfaces { display: none; } + #nav_implementations { display: none; } + #nav_child_properties { display: none; } + #nav_style_properties { display: none; } + #nav_index { display: none; } + #nav_glossary { display: none; } + .gallery_image { display: none; } + .property_flags { display: none; } + .signal_flags { display: none; } + .parameter_annotations { display: none; } + .enum_member_annotations { display: none; } + .struct_member_annotations { display: none; } + .union_member_annotations { display: none; } + /* now that a column is hidden, optimize space */ + col.parameters_name { width: auto; } + col.parameters_description { width: auto; } + col.struct_members_name { width: auto; } + col.struct_members_description { width: auto; } + col.enum_members_name { width: auto; } + col.enum_members_description { width: auto; } + col.union_members_name { width: auto; } + col.union_members_description { width: auto; } +} +@media print { + table.navigation { + visibility: collapse; + display: none; + } + div.titlepage table.navigation { + visibility: visible; + display: table; + background: #e2e2e2; + border: solid 1px #babdb6; + margin-top: 0; + margin-bottom: 0; + top: 0; + left: 0; + height: 3em; + } +} + +.navigation .title +{ + font-size: 120%; +} + +div.gallery-float +{ + float: left; + padding: 10px; +} +div.gallery-float img +{ + border-style: none; +} +div.gallery-spacer +{ + clear: both; +} + +a, a:visited +{ + text-decoration: none; + /* tango:sky blue 2 */ + color: #3465a4; +} +a:hover +{ + text-decoration: underline; + /* tango:sky blue 1 */ + color: #729fcf; +} + +div.informaltable table +{ + border-collapse: separate; + border-spacing: 20px 3px; + border: none; +} + +div.informaltable table td, div.informaltable table th +{ + vertical-align: top; +} + +.function_type, +.variable_type, +.property_type, +.signal_type, +.parameter_name, +.struct_member_name, +.union_member_name, +.define_keyword, +.datatype_keyword, +.typedef_keyword +{ + text-align: right; +} + +/* dim non-primary columns */ +.c_punctuation, +.function_type, +.variable_type, +.property_type, +.signal_type, +.define_keyword, +.datatype_keyword, +.typedef_keyword, +.property_flags, +.signal_flags, +.parameter_annotations, +.enum_member_annotations, +.struct_member_annotations, +.union_member_annotations +{ + color: #888a85; +} + +.function_type a, +.function_type a:visited, +.function_type a:hover, +.property_type a, +.property_type a:visited, +.property_type a:hover, +.signal_type a, +.signal_type a:visited, +.signal_type a:hover, +.signal_flags a, +.signal_flags a:visited, +.signal_flags a:hover +{ + color: #729fcf; +} + +div.table table +{ + border-collapse: collapse; + border-spacing: 0px; + /* tango:aluminium 3 */ + border: solid 1px #babdb6; +} + +div.table table td, div.table table th +{ + /* tango:aluminium 3 */ + border: solid 1px #babdb6; + padding: 3px; + vertical-align: top; +} + +div.table table th +{ + /* tango:aluminium 2 */ + background-color: #d3d7cf; +} + +h4 +{ + color: #555753; +} + +hr +{ + /* tango:aluminium 1 */ + color: #d3d7cf; + background: #d3d7cf; + border: none 0px; + height: 1px; + clear: both; + margin: 2.0em 0em 2.0em 0em; +} + +dl.toc dt +{ + padding-bottom: 0.25em; +} + +dl.toc > dd > dl > dt +{ + padding-top: 0.25em; + padding-bottom: 0.25em; +} + +dl.toc > dt +{ + padding-top: 1em; + padding-bottom: 0.5em; + font-weight: bold; +} + +.parameter +{ + font-style: normal; +} + +.footer +{ + padding-top: 3.5em; + /* tango:aluminium 3 */ + color: #babdb6; + text-align: center; + font-size: 80%; +} + +.informalfigure, +.figure +{ + margin: 1em; +} + +.informalexample, +.example +{ + margin-top: 1em; + margin-bottom: 1em; +} + +.warning +{ + /* tango:orange 0/1 */ + background: #ffeed9; + background: rgba(252, 175, 62, 0.1); + border-color: #ffb04f; + border-color: rgba(252, 175, 62, 0.2); +} +.note +{ + /* tango:chameleon 0/0.5 */ + background: #d8ffb2; + background: rgba(138, 226, 52, 0.1); + border-color: #abf562; + border-color: rgba(138, 226, 52, 0.2); +} +div.blockquote +{ + border-color: #eeeeec; +} +.note, .warning, div.blockquote +{ + padding: 0.5em; + border-width: 1px; + border-style: solid; + margin: 2em; +} +.note p, .warning p +{ + margin: 0; +} + +div.warning h3.title, +div.note h3.title +{ + display: none; +} + +p + div.section +{ + margin-top: 1em; +} + +div.refnamediv, +div.refsynopsisdiv, +div.refsect1, +div.refsect2, +div.toc, +div.section +{ + margin-bottom: 1em; +} + +/* blob links */ +h2 .extralinks, h3 .extralinks +{ + float: right; + /* tango:aluminium 3 */ + color: #babdb6; + font-size: 80%; + font-weight: normal; +} + +.lineart +{ + color: #d3d7cf; + font-weight: normal; +} + +.annotation +{ + /* tango:aluminium 5 */ + color: #555753; + font-weight: normal; +} + +.structfield +{ + font-style: normal; + font-weight: normal; +} + +/* code listings */ + +.listing_code .programlisting .cbracket { color: #a40000; } /* tango: scarlet red 3 */ +.listing_code .programlisting .comment { color: #a1a39d; } /* tango: aluminium 4 */ +.listing_code .programlisting .function { color: #000000; font-weight: bold; } +.listing_code .programlisting .function a { color: #11326b; font-weight: bold; } /* tango: sky blue 4 */ +.listing_code .programlisting .keyword { color: #4e9a06; } /* tango: chameleon 3 */ +.listing_code .programlisting .linenum { color: #babdb6; } /* tango: aluminium 3 */ +.listing_code .programlisting .normal { color: #000000; } +.listing_code .programlisting .number { color: #75507b; } /* tango: plum 2 */ +.listing_code .programlisting .preproc { color: #204a87; } /* tango: sky blue 3 */ +.listing_code .programlisting .string { color: #c17d11; } /* tango: chocolate 2 */ +.listing_code .programlisting .type { color: #000000; } +.listing_code .programlisting .type a { color: #11326b; } /* tango: sky blue 4 */ +.listing_code .programlisting .symbol { color: #ce5c00; } /* tango: orange 3 */ + +.listing_frame { + /* tango:sky blue 1 */ + border: solid 1px #729fcf; + border: solid 1px rgba(114, 159, 207, 0.2); + padding: 0px; +} + +.listing_lines, .listing_code { + margin-top: 0px; + margin-bottom: 0px; + padding: 0.5em; +} +.listing_lines { + /* this just adds visual clutter and + takes precious room from small screens */ + display: none; +} +.listing_lines { + /* tango:sky blue 0.5 */ + background: #a6c5e3; + background: rgba(114, 159, 207, 0.2); + /* tango:aluminium 6 */ + color: #2e3436; +} +.listing_code { + /* tango:sky blue 0 */ + background: #e6f3ff; + background: rgba(114, 159, 207, 0.1); +} +.listing_code .programlisting { + /* override from previous */ + border: none 0px; + padding: 0px; + background: none; +} +.listing_lines pre, .listing_code pre { + margin: 0px; +} + diff --git a/docs/reference/html/up-insensitive.png b/docs/reference/html/up-insensitive.png Binary files differnew file mode 100644 index 00000000..f4049860 --- /dev/null +++ b/docs/reference/html/up-insensitive.png diff --git a/docs/reference/html/up.png b/docs/reference/html/up.png Binary files differnew file mode 100644 index 00000000..80b4b37e --- /dev/null +++ b/docs/reference/html/up.png diff --git a/docs/reference/libsoup-2.4-docs.sgml b/docs/reference/libsoup-2.4-docs.sgml index f28c6059..c0c8a05c 100644 --- a/docs/reference/libsoup-2.4-docs.sgml +++ b/docs/reference/libsoup-2.4-docs.sgml @@ -10,6 +10,7 @@ <title>Tutorial</title> <xi:include href="build-howto.xml"/> <xi:include href="client-howto.xml"/> + <xi:include href="request-howto.xml"/> <xi:include href="server-howto.xml"/> <xi:include href="session-porting.xml"/> </chapter> @@ -53,7 +54,6 @@ <xi:include href="xml/soup-cookie-jar-text.xml"/> <xi:include href="xml/soup-cookie-jar-db.xml"/> <xi:include href="xml/soup-logger.xml"/> - <xi:include href="xml/soup-proxy-uri-resolver.xml"/> <xi:include href="xml/soup-proxy-resolver-default.xml"/> </chapter> diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt index 4b6ebfd9..03d35d4b 100644 --- a/docs/reference/libsoup-2.4-sections.txt +++ b/docs/reference/libsoup-2.4-sections.txt @@ -51,8 +51,10 @@ SOUP_MESSAGE_SERVER_SIDE SOUP_MESSAGE_FIRST_PARTY SOUP_MESSAGE_PRIORITY SOUP_MESSAGE_REQUEST_BODY +SOUP_MESSAGE_REQUEST_BODY_DATA SOUP_MESSAGE_REQUEST_HEADERS SOUP_MESSAGE_RESPONSE_BODY +SOUP_MESSAGE_RESPONSE_BODY_DATA SOUP_MESSAGE_RESPONSE_HEADERS SOUP_MESSAGE_TLS_CERTIFICATE SOUP_MESSAGE_TLS_ERRORS @@ -199,13 +201,14 @@ SOUP_STATUS_IS_SUCCESSFUL SOUP_STATUS_IS_REDIRECTION SOUP_STATUS_IS_CLIENT_ERROR SOUP_STATUS_IS_SERVER_ERROR -SoupKnownStatusCode +SoupStatus soup_status_get_phrase soup_status_proxify <SUBSECTION> SOUP_HTTP_ERROR <SUBSECTION Private> soup_http_error_quark +SoupKnownStatusCode </SECTION> <SECTION> @@ -247,6 +250,8 @@ SOUP_SERVER_TLS_CERTIFICATE SOUP_SERVER_ASYNC_CONTEXT SOUP_SERVER_RAW_PATHS SOUP_SERVER_SERVER_HEADER +SOUP_SERVER_HTTP_ALIASES +SOUP_SERVER_HTTPS_ALIASES <SUBSECTION Standard> SOUP_SERVER SOUP_IS_SERVER @@ -435,13 +440,15 @@ soup_session_get_feature_for_message soup_session_has_feature <SUBSECTION> SOUP_SESSION_PROXY_URI +SOUP_SESSION_PROXY_RESOLVER SOUP_SESSION_MAX_CONNS SOUP_SESSION_MAX_CONNS_PER_HOST -SOUP_SESSION_USE_NTLM -SOUP_SESSION_SSL_CA_FILE -SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE SOUP_SESSION_TLS_DATABASE +SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE +SOUP_SESSION_SSL_CA_FILE +SOUP_SESSION_SSL_STRICT SOUP_SESSION_ASYNC_CONTEXT +SOUP_SESSION_USE_THREAD_CONTEXT SOUP_SESSION_TIMEOUT SOUP_SESSION_IDLE_TIMEOUT SOUP_SESSION_USER_AGENT @@ -450,10 +457,9 @@ SOUP_SESSION_ADD_FEATURE_BY_TYPE SOUP_SESSION_REMOVE_FEATURE_BY_TYPE SOUP_SESSION_ACCEPT_LANGUAGE SOUP_SESSION_ACCEPT_LANGUAGE_AUTO -SOUP_SESSION_SSL_STRICT SOUP_SESSION_HTTP_ALIASES SOUP_SESSION_HTTPS_ALIASES -SOUP_SESSION_USE_THREAD_CONTEXT +SOUP_SESSION_LOCAL_ADDRESS <SUBSECTION Standard> SOUP_IS_SESSION SOUP_IS_SESSION_CLASS @@ -469,6 +475,7 @@ SoupConnection SoupConnectionState SoupMessageQueue SoupMessageQueueItem +SOUP_SESSION_USE_NTLM </SECTION> <SECTION> @@ -1019,24 +1026,6 @@ soup_cookie_jar_db_get_type </SECTION> <SECTION> -<FILE>soup-proxy-uri-resolver</FILE> -<TITLE>SoupProxyURIResolver</TITLE> -SoupProxyURIResolver -SoupProxyURIResolverCallback -soup_proxy_uri_resolver_get_proxy_uri_async -soup_proxy_uri_resolver_get_proxy_uri_sync -<SUBSECTION Standard> -SoupProxyURIResolverInterface -SOUP_IS_PROXY_URI_RESOLVER -SOUP_IS_PROXY_URI_RESOLVER_CLASS -SOUP_PROXY_URI_RESOLVER -SOUP_PROXY_URI_RESOLVER_CLASS -SOUP_PROXY_URI_RESOLVER_GET_CLASS -SOUP_TYPE_PROXY_URI_RESOLVER -soup_proxy_uri_resolver_get_type -</SECTION> - -<SECTION> <FILE>soup-content-sniffer</FILE> <TITLE>SoupContentSniffer</TITLE> SoupContentSniffer @@ -1077,11 +1066,7 @@ SOUP_CACHE_GET_CLASS SoupCacheClass SoupCachePrivate <SUBSECTION Private> -soup_cache_generate_conditional_request -soup_cache_get_cacheability soup_cache_get_type -soup_cache_has_response -soup_cache_send_response SoupCacheResponse SoupCacheability </SECTION> @@ -1233,6 +1218,7 @@ SOUP_VERSION_2_38 SOUP_VERSION_2_40 SOUP_VERSION_2_42 SOUP_VERSION_2_44 +SOUP_VERSION_2_46 <SUBSECTION Private> SOUP_AVAILABLE_IN_2_24 SOUP_AVAILABLE_IN_2_26 @@ -1245,6 +1231,7 @@ SOUP_AVAILABLE_IN_2_38 SOUP_AVAILABLE_IN_2_40 SOUP_AVAILABLE_IN_2_42 SOUP_AVAILABLE_IN_2_44 +SOUP_AVAILABLE_IN_2_46 SOUP_DEPRECATED_IN_2_24 SOUP_DEPRECATED_IN_2_24_FOR SOUP_DEPRECATED_IN_2_26 @@ -1267,6 +1254,8 @@ SOUP_DEPRECATED_IN_2_42 SOUP_DEPRECATED_IN_2_42_FOR SOUP_DEPRECATED_IN_2_44 SOUP_DEPRECATED_IN_2_44_FOR +SOUP_DEPRECATED_IN_2_46 +SOUP_DEPRECATED_IN_2_46_FOR SOUP_ENCODE_VERSION SOUP_VERSION_CUR_STABLE SOUP_VERSION_PREV_STABLE diff --git a/docs/reference/libsoup-2.4.types b/docs/reference/libsoup-2.4.types new file mode 100644 index 00000000..3e9a59eb --- /dev/null +++ b/docs/reference/libsoup-2.4.types @@ -0,0 +1,38 @@ +soup_address_get_type +soup_auth_basic_get_type +soup_auth_digest_get_type +soup_auth_domain_basic_get_type +soup_auth_domain_digest_get_type +soup_auth_domain_get_type +soup_auth_get_type +soup_auth_manager_get_type +soup_auth_ntlm_get_type +soup_buffer_get_type +soup_byte_array_get_type +soup_cache_get_type +soup_client_context_get_type +soup_content_decoder_get_type +soup_content_sniffer_get_type +soup_cookie_get_type +soup_cookie_jar_db_get_type +soup_cookie_jar_get_type +soup_cookie_jar_text_get_type +soup_date_get_type +soup_logger_get_type +soup_message_body_get_type +soup_message_get_type +soup_message_headers_get_type +soup_multipart_get_type +soup_multipart_input_stream_get_type +soup_proxy_resolver_default_get_type +soup_request_data_get_type +soup_request_file_get_type +soup_request_get_type +soup_request_http_get_type +soup_server_get_type +soup_session_async_get_type +soup_session_feature_get_type +soup_session_get_type +soup_session_sync_get_type +soup_socket_get_type +soup_uri_get_type diff --git a/docs/reference/request-howto.xml b/docs/reference/request-howto.xml new file mode 100644 index 00000000..55a46431 --- /dev/null +++ b/docs/reference/request-howto.xml @@ -0,0 +1,184 @@ +<?xml version="1.0"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<refentry id="libsoup-request-howto"> +<refmeta> +<refentrytitle>libsoup Client SoupRequest API</refentrytitle> +<manvolnum>3</manvolnum> +<refmiscinfo>LIBSOUP Library</refmiscinfo> +</refmeta> + +<refnamediv> +<refname>libsoup Client SoupRequest API</refname><refpurpose>Using +libsoup with a mix of <literal>http</literal> and non-<literal>http</literal> URIs.</refpurpose> +</refnamediv> + +<refsect2> +<title><type>SoupRequest</type></title> + +<para> +<link linkend="SoupRequest"><type>SoupRequest</type></link> is an +abstract type representing a request for a particular URI. The +<type>SoupRequest</type> API is an alternative to the <link +linkend="SoupMessage"><type>SoupMessage</type></link>-based <link +linkend="SoupSession"><type>SoupSession</type></link> APIs which may be +useful to programs that want to deal with multiple kinds of URIs. +</para> + +<para> +<type>SoupRequest</type> officially became part of the +<application>libsoup</application> API in 2.42 with the addition of +<link +linkend="soup-session-request"><function>soup_session_request</function></link> +and the related functions. However, parts of it are also available as +far back as <application>libsoup</application> 2.34 via the +(now-deprecated) <type>SoupRequester</type> session feature, if you +define <literal>LIBSOUP_USE_UNSTABLE_REQUEST_API</literal> before +including the <application>libsoup</application> headers. +</para> + +<para> +Additionally, before <application>libsoup</application> 2.42, the +<type>SoupRequest</type> API was the only way to stream an HTTP +response body via <link +linkend="GInputStream"><type>GInputStream</type></link>. As of 2.42, +there are streaming APIs based on <type>SoupMessage</type> (<link +linkend="soup-session-send"><function>soup_session_send</function></link> +and <link +linkend="soup-session-send-async"><function>soup_session_send_async</function></link>), +so applications that are using <type>SoupRequest</type> with only +<literal>http</literal> and <literal>https</literal> URIs can be +ported to those APIs now. +</para> + +</refsect2> + +<refsect2> +<title>Creating a SoupRequest</title> + +<para> +There are four <type>SoupSession</type> methods for creating +<type>SoupRequest</type>s: +</para> + +<itemizedlist> + <listitem> + <para> + <link linkend="soup-session-request"><function>soup_session_request</function></link> + takes an arbitrary URI as a string, and returns a <link + linkend="SoupRequest"><type>SoupRequest</type></link>. + </para> + </listitem> + <listitem> + <para> + <link linkend="soup-session-request-uri"><function>soup_session_request_uri</function></link> + takes an arbitrary URI as a <link linkend="SoupURI"><type>SoupURI</type></link>, + and returns a <link linkend="SoupRequest"><type>SoupRequest</type></link>. + </para> + </listitem> + <listitem> + <para> + <link linkend="soup-session-request-http"><function>soup_session_request_http</function></link> + takes an HTTP method and an <literal>http</literal> or <literal>https</literal> URI as a string, and returns a <link + linkend="SoupRequestHTTP"><type>SoupRequestHTTP</type></link>. + </para> + </listitem> + <listitem> + <para> + <link linkend="soup-session-request-http-uri"><function>soup_session_request_http_uri</function></link> + takes an HTTP method and an <literal>http</literal> or <literal>https</literal> URI as a <link linkend="SoupURI"><type>SoupURI</type></link>, + and returns a <link linkend="SoupRequestHTTP"><type>SoupRequestHTTP</type></link>. + </para> + </listitem> +</itemizedlist> + +</refsect2> + +<refsect2> +<title>Sending a SoupRequest</title> + +<para> +Once you have created a <type>SoupRequest</type>, you can send it with +either <link +linkend="soup-request-send"><function>soup_request_send</function></link> +or <link +linkend="soup-request-send-async"><function>soup_request_send_async</function></link>. +This will provide you with a <link +linkend="GInputStream"><type>GInputStream</type></link> which you can +read to get the response body. +</para> + +<para> +After sending, you can use <link +linkend="soup-request-get-content-length"><function>soup_request_get_content_length</function></link> +and <link +linkend="soup-request-get-content-type"><function>soup_request_get_content_type</function></link> +to get information about the response body. +</para> + +<para> +As with the streaming <type>SoupMessage</type>-based APIs, +<function>soup_request_send</function> and +<function>soup_request_send_async</function> only return errors if a +transport-level problem occurs (eg, it could not connect to the host, +or the request was cancelled). In the case of an HTTP request, use the +message's <structfield>status_code</structfield> field to determine +whether the request was successful or not at the HTTP level (ie, "<literal>200 +OK</literal>" vs "<literal>401 Bad Request</literal>"). (You can call <link +linkend="soup-request-http-get-message"><function>soup_request_http_get_message</function></link> +to get the request's corresponding <link +linkend="SoupMessage"><type>SoupMessage</type></link>, to look at the +status code or other HTTP metadata.) +</para> + +</refsect2> + +<refsect2> +<title>Supported URI types, and adding your own</title> + +<para> +Different URI types are implemented by different subclasses of +<type>SoupRequest</type>. <application>libsoup</application> currently +implements three <type>SoupRequest</type> classes: +</para> + +<variablelist> + <varlistentry> + <term><link linkend="SoupRequestHTTP"><type>SoupRequestHTTP</type></link></term> + <listitem><para> + Handles <literal>http</literal> and + <literal>https</literal> URI. + </para></listitem> + </varlistentry> + <varlistentry> + <term><link linkend="SoupRequestData"><type>SoupRequestData</type></link></term> + <listitem><para> + Handles <literal>data</literal> URIs containing inline data. + </para></listitem> + </varlistentry> + <varlistentry> + <term><link linkend="SoupRequestFile"><type>SoupRequestFile</type></link></term> + <listitem><para> + Handles <literal>file</literal> and + <link linkend="GResource"><literal>resource</literal></link> URIs. + If you request a URI corresponding to a directory, this + will generate an HTML listing of the directory. + </para></listitem> + </varlistentry> +</variablelist> + +<para> +You can add additional URI types by implementing your own +<type>SoupRequest</type> subclass; set the +<type>SoupRequestClass</type>'s <structfield>schemes</structfield> +field to point to a <literal>NULL</literal>-terminated array of scheme +names, implement the various <type>SoupRequest</type> methods, and +then register the type with your <type>SoupSession</type> by calling +<link linkend="soup-session-add-feature-by-type"><function>soup_session_add_feature_by_type</function></link> +and passing the <link linkend="GType"><type>GType</type></link> of +your request class. +</para> + +</refsect2> + +</refentry> diff --git a/docs/reference/server-howto.xml b/docs/reference/server-howto.xml index 76c19182..05fb0c05 100644 --- a/docs/reference/server-howto.xml +++ b/docs/reference/server-howto.xml @@ -100,7 +100,7 @@ to set a callback to handle certain URI paths. <informalexample><programlisting> soup_server_add_handler (server, "/foo", server_callback, - data, destroy_notify); + data, destroy_notify); </programlisting></informalexample> <para> @@ -131,11 +131,11 @@ A handler callback looks something like this: <informalexample><programlisting> static void server_callback (SoupServer *server, - SoupMessage *msg, - const char *path, - GHashTable *query, - SoupClientContext *client, - gpointer user_data) + SoupMessage *msg, + const char *path, + GHashTable *query, + SoupClientContext *client, + gpointer user_data) { ... } @@ -192,11 +192,11 @@ data available at once. <informalexample><programlisting> static void server_callback (SoupServer *server, - SoupMessage *msg, - const char *path, - GHashTable *query, - SoupClientContext *client, - gpointer user_data) + SoupMessage *msg, + const char *path, + GHashTable *query, + SoupClientContext *client, + gpointer user_data) { MyServerData *server_data = user_data; const char *mime_type; @@ -219,7 +219,7 @@ server_callback (SoupServer *server, soup_message_set_status (msg, SOUP_STATUS_OK); soup_message_set_response (msg, mime_type, SOUP_MEMORY_COPY, - body->data, body->len); + body->data, body->len); } </programlisting></informalexample> @@ -264,7 +264,7 @@ is emitted indicating that the previous one was written successfully.) <para> The <emphasis role="bold"><literal>simple-proxy</literal></emphasis> -example in the <literal>tests/</literal> directory gives an example of +example in the <literal>examples/</literal> directory gives an example of using <literal>chunked</literal> encoding. </para> @@ -308,8 +308,8 @@ passed to the <literal>server_callback</literal>: <informalexample><programlisting> static gboolean auth_callback (SoupAuthDomain *domain, SoupMessage *msg, - const char *username, const char *password, - gpointer user_data) + const char *username, const char *password, + gpointer user_data) { MyServerData *server_data = user_data; MyUserData *user; @@ -360,8 +360,8 @@ domains. <para> If you want to require authentication for some requests under a certain path, but not all of them (eg, you want to authenticate -<literal>PUT</literal>s, but not <literal>GET</literal>s), use a -<link +<literal>PUT</literal> requests, but not <literal>GET</literal> +requests), use a <link linkend="SoupAuthDomainFilter"><type>SoupAuthDomainFilter</type></link>. </para> diff --git a/docs/reference/session-porting.xml b/docs/reference/session-porting.xml index bf1aa411..67a433a1 100644 --- a/docs/reference/session-porting.xml +++ b/docs/reference/session-porting.xml @@ -92,13 +92,26 @@ linkend="SoupSessionAsync"><type>SoupSessionAsync</type></link> and </listitem> <listitem> <para> + The new + <link linkend="SoupSession--proxy-resolver"><type>"proxy-resolver"</type></link> + property is now initialized to the default + <link linkend="GProxyResolver"><type>GProxyResolver</type></link>, + meaning that it will automatically use the user's system proxy + configuration. This replaces the use of the + <link linkend="SoupProxyResolverDefault"><type>SoupProxyResolverDefault</type></link>, + session feature in earlier releases. You can set this property to + <literal>NULL</literal> if you don't want to use proxies, and the + <link linkend="SoupSession--proxy-uri"><type>"proxy-uri"</type></link> + property still works if you want to use a single proxy for all requests. + </para> + </listitem> + <listitem> + <para> Every session gets a - <link linkend="SoupProxyResolverDefault"><type>SoupProxyResolverDefault</type></link> - and a <link linkend="SoupContentDecoder"><type>SoupContentDecoder</type></link> attached to it by default, meaning that it will automatically - use the user's system proxy configuration, and will handle (and - request) "gzip"- and "deflate"-encoded response bodies. + handle (and request) "gzip"- and "deflate"-encoded response + bodies. </para> </listitem> </itemizedlist> diff --git a/docs/reference/tmpl/libsoup-2.4-unused.sgml b/docs/reference/tmpl/libsoup-2.4-unused.sgml new file mode 100644 index 00000000..d9049556 --- /dev/null +++ b/docs/reference/tmpl/libsoup-2.4-unused.sgml @@ -0,0 +1,28 @@ +<!-- ##### SECTION ./tmpl/soup-server-deprecated.sgml:Image ##### --> + + + +<!-- ##### SECTION ./tmpl/soup-server-deprecated.sgml:Long_Description ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/soup-server-deprecated.sgml:See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION ./tmpl/soup-server-deprecated.sgml:Short_Description ##### --> + + + +<!-- ##### SECTION ./tmpl/soup-server-deprecated.sgml:Stability_Level ##### --> + + + +<!-- ##### SECTION ./tmpl/soup-server-deprecated.sgml:Title ##### --> +SoupServer deprecated API + + diff --git a/docs/reference/tmpl/soup-address.sgml b/docs/reference/tmpl/soup-address.sgml new file mode 100644 index 00000000..207a3bbb --- /dev/null +++ b/docs/reference/tmpl/soup-address.sgml @@ -0,0 +1,271 @@ +<!-- ##### SECTION Title ##### --> +SoupAddress + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupAddress ##### --> +<para> + +</para> + + +<!-- ##### ARG SoupAddress:family ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAddress:name ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAddress:physical ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAddress:port ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAddress:protocol ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAddress:sockaddr ##### --> +<para> + +</para> + +<!-- ##### ENUM SoupAddressFamily ##### --> +<para> + +</para> + +@SOUP_ADDRESS_FAMILY_INVALID: +@SOUP_ADDRESS_FAMILY_IPV4: +@SOUP_ADDRESS_FAMILY_IPV6: + +<!-- ##### MACRO SOUP_ADDRESS_ANY_PORT ##### --> +<para> + +</para> + + + +<!-- ##### FUNCTION soup_address_new ##### --> +<para> + +</para> + +@name: +@port: +@Returns: + + +<!-- ##### FUNCTION soup_address_new_from_sockaddr ##### --> +<para> + +</para> + +@sa: +@len: +@Returns: + + +<!-- ##### FUNCTION soup_address_new_any ##### --> +<para> + +</para> + +@family: +@port: +@Returns: + + +<!-- ##### USER_FUNCTION SoupAddressCallback ##### --> +<para> + +</para> + +@addr: +@status: +@user_data: + + +<!-- ##### FUNCTION soup_address_resolve_async ##### --> +<para> + +</para> + +@addr: +@async_context: +@cancellable: +@callback: +@user_data: + + +<!-- ##### FUNCTION soup_address_resolve_sync ##### --> +<para> + +</para> + +@addr: +@cancellable: +@Returns: + + +<!-- ##### FUNCTION soup_address_is_resolved ##### --> +<para> + +</para> + +@addr: +@Returns: + + +<!-- ##### FUNCTION soup_address_get_name ##### --> +<para> + +</para> + +@addr: +@Returns: + + +<!-- ##### FUNCTION soup_address_get_sockaddr ##### --> +<para> + +</para> + +@addr: +@len: +@Returns: + + +<!-- ##### FUNCTION soup_address_get_gsockaddr ##### --> +<para> + +</para> + +@addr: +@Returns: + + +<!-- ##### FUNCTION soup_address_get_physical ##### --> +<para> + +</para> + +@addr: +@Returns: + + +<!-- ##### FUNCTION soup_address_get_port ##### --> +<para> + +</para> + +@addr: +@Returns: + + +<!-- ##### FUNCTION soup_address_equal_by_name ##### --> +<para> + +</para> + +@addr1: +@addr2: +@Returns: + + +<!-- ##### FUNCTION soup_address_hash_by_name ##### --> +<para> + +</para> + +@addr: +@Returns: + + +<!-- ##### FUNCTION soup_address_equal_by_ip ##### --> +<para> + +</para> + +@addr1: +@addr2: +@Returns: + + +<!-- ##### FUNCTION soup_address_hash_by_ip ##### --> +<para> + +</para> + +@addr: +@Returns: + + +<!-- ##### MACRO SOUP_ADDRESS_FAMILY ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_ADDRESS_NAME ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_ADDRESS_PHYSICAL ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_ADDRESS_PORT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_ADDRESS_SOCKADDR ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_ADDRESS_PROTOCOL ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-auth-domain-basic.sgml b/docs/reference/tmpl/soup-auth-domain-basic.sgml new file mode 100644 index 00000000..0b9a30cb --- /dev/null +++ b/docs/reference/tmpl/soup-auth-domain-basic.sgml @@ -0,0 +1,86 @@ +<!-- ##### SECTION Title ##### --> +SoupAuthDomainBasic + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupAuthDomainBasic ##### --> +<para> + +</para> + + +<!-- ##### ARG SoupAuthDomainBasic:auth-callback ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuthDomainBasic:auth-data ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_auth_domain_basic_new ##### --> +<para> + +</para> + +@optname1: +@...: +@Returns: + + +<!-- ##### USER_FUNCTION SoupAuthDomainBasicAuthCallback ##### --> +<para> + +</para> + +@domain: +@msg: +@username: +@password: +@user_data: +@Returns: + + +<!-- ##### FUNCTION soup_auth_domain_basic_set_auth_callback ##### --> +<para> + +</para> + +@domain: +@callback: +@user_data: +@dnotify: + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_BASIC_AUTH_CALLBACK ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_BASIC_AUTH_DATA ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-auth-domain-digest.sgml b/docs/reference/tmpl/soup-auth-domain-digest.sgml new file mode 100644 index 00000000..942cf3c9 --- /dev/null +++ b/docs/reference/tmpl/soup-auth-domain-digest.sgml @@ -0,0 +1,96 @@ +<!-- ##### SECTION Title ##### --> +SoupAuthDomainDigest + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupAuthDomainDigest ##### --> +<para> + +</para> + + +<!-- ##### ARG SoupAuthDomainDigest:auth-callback ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuthDomainDigest:auth-data ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_auth_domain_digest_new ##### --> +<para> + +</para> + +@optname1: +@...: +@Returns: + + +<!-- ##### USER_FUNCTION SoupAuthDomainDigestAuthCallback ##### --> +<para> + +</para> + +@domain: +@msg: +@username: +@user_data: +@Returns: + + +<!-- ##### FUNCTION soup_auth_domain_digest_set_auth_callback ##### --> +<para> + +</para> + +@domain: +@callback: +@user_data: +@dnotify: + + +<!-- ##### FUNCTION soup_auth_domain_digest_encode_password ##### --> +<para> + +</para> + +@username: +@realm: +@password: +@Returns: + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-auth-domain.sgml b/docs/reference/tmpl/soup-auth-domain.sgml new file mode 100644 index 00000000..ba058c0d --- /dev/null +++ b/docs/reference/tmpl/soup-auth-domain.sgml @@ -0,0 +1,237 @@ +<!-- ##### SECTION Title ##### --> +SoupAuthDomain + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupAuthDomain ##### --> +<para> + +</para> + + +<!-- ##### ARG SoupAuthDomain:add-path ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuthDomain:filter ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuthDomain:filter-data ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuthDomain:generic-auth-callback ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuthDomain:generic-auth-data ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuthDomain:proxy ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuthDomain:realm ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuthDomain:remove-path ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_auth_domain_add_path ##### --> +<para> + +</para> + +@domain: +@path: + + +<!-- ##### FUNCTION soup_auth_domain_remove_path ##### --> +<para> + +</para> + +@domain: +@path: + + +<!-- ##### USER_FUNCTION SoupAuthDomainFilter ##### --> +<para> + +</para> + +@domain: +@msg: +@user_data: +@Returns: + + +<!-- ##### FUNCTION soup_auth_domain_set_filter ##### --> +<para> + +</para> + +@domain: +@filter: +@filter_data: +@dnotify: + + +<!-- ##### FUNCTION soup_auth_domain_get_realm ##### --> +<para> + +</para> + +@domain: +@Returns: + + +<!-- ##### USER_FUNCTION SoupAuthDomainGenericAuthCallback ##### --> +<para> + +</para> + +@domain: +@msg: +@username: +@user_data: +@Returns: + + +<!-- ##### FUNCTION soup_auth_domain_set_generic_auth_callback ##### --> +<para> + +</para> + +@domain: +@auth_callback: +@auth_data: +@dnotify: + + +<!-- ##### FUNCTION soup_auth_domain_check_password ##### --> +<para> + +</para> + +@domain: +@msg: +@username: +@password: +@Returns: + + +<!-- ##### FUNCTION soup_auth_domain_covers ##### --> +<para> + +</para> + +@domain: +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_auth_domain_accepts ##### --> +<para> + +</para> + +@domain: +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_auth_domain_challenge ##### --> +<para> + +</para> + +@domain: +@msg: + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_REALM ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_PROXY ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_ADD_PATH ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_REMOVE_PATH ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_FILTER ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_FILTER_DATA ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-auth-manager.sgml b/docs/reference/tmpl/soup-auth-manager.sgml new file mode 100644 index 00000000..7834d920 --- /dev/null +++ b/docs/reference/tmpl/soup-auth-manager.sgml @@ -0,0 +1,55 @@ +<!-- ##### SECTION Title ##### --> +SoupAuthManager + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupAuthManager ##### --> +<para> + +</para> + + +<!-- ##### SIGNAL SoupAuthManager::authenticate ##### --> +<para> + +</para> + +@soupauthmanager: the object which received the signal. +@arg1: +@arg2: +@arg3: + +<!-- ##### MACRO SOUP_TYPE_AUTH_MANAGER ##### --> +<para> + +</para> + + + +<!-- ##### FUNCTION soup_auth_manager_use_auth ##### --> +<para> + +</para> + +@manager: +@uri: +@auth: + + diff --git a/docs/reference/tmpl/soup-auth.sgml b/docs/reference/tmpl/soup-auth.sgml new file mode 100644 index 00000000..fb3d4914 --- /dev/null +++ b/docs/reference/tmpl/soup-auth.sgml @@ -0,0 +1,234 @@ +<!-- ##### SECTION Title ##### --> +SoupAuth + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupAuth ##### --> +<para> + +</para> + + +<!-- ##### ARG SoupAuth:host ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuth:is-authenticated ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuth:is-for-proxy ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuth:realm ##### --> +<para> + +</para> + +<!-- ##### ARG SoupAuth:scheme-name ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_auth_new ##### --> +<para> + +</para> + +@type: +@msg: +@auth_header: +@Returns: + + +<!-- ##### FUNCTION soup_auth_update ##### --> +<para> + +</para> + +@auth: +@msg: +@auth_header: +@Returns: + + +<!-- ##### MACRO SOUP_TYPE_AUTH_BASIC ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_TYPE_AUTH_DIGEST ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_TYPE_AUTH_NTLM ##### --> +<para> + +</para> + + + +<!-- ##### FUNCTION soup_auth_is_for_proxy ##### --> +<para> + +</para> + +@auth: +@Returns: + + +<!-- ##### FUNCTION soup_auth_get_scheme_name ##### --> +<para> + +</para> + +@auth: +@Returns: + + +<!-- ##### FUNCTION soup_auth_get_host ##### --> +<para> + +</para> + +@auth: +@Returns: + + +<!-- ##### FUNCTION soup_auth_get_realm ##### --> +<para> + +</para> + +@auth: +@Returns: + + +<!-- ##### FUNCTION soup_auth_get_info ##### --> +<para> + +</para> + +@auth: +@Returns: + + +<!-- ##### FUNCTION soup_auth_authenticate ##### --> +<para> + +</para> + +@auth: +@username: +@password: + + +<!-- ##### FUNCTION soup_auth_is_authenticated ##### --> +<para> + +</para> + +@auth: +@Returns: + + +<!-- ##### FUNCTION soup_auth_is_ready ##### --> +<para> + +</para> + +@auth: +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_auth_get_authorization ##### --> +<para> + +</para> + +@auth: +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_auth_get_protection_space ##### --> +<para> + +</para> + +@auth: +@source_uri: +@Returns: + + +<!-- ##### FUNCTION soup_auth_free_protection_space ##### --> +<para> + +</para> + +@auth: +@space: + + +<!-- ##### MACRO SOUP_AUTH_SCHEME_NAME ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_REALM ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_HOST ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_IS_FOR_PROXY ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_AUTH_IS_AUTHENTICATED ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-cache.sgml b/docs/reference/tmpl/soup-cache.sgml new file mode 100644 index 00000000..30d60d5f --- /dev/null +++ b/docs/reference/tmpl/soup-cache.sgml @@ -0,0 +1,106 @@ +<!-- ##### SECTION Title ##### --> +SoupCache + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupCache ##### --> +<para> + +</para> + + +<!-- ##### ARG SoupCache:cache-dir ##### --> +<para> + +</para> + +<!-- ##### ARG SoupCache:cache-type ##### --> +<para> + +</para> + +<!-- ##### ENUM SoupCacheType ##### --> +<para> + +</para> + +@SOUP_CACHE_SINGLE_USER: +@SOUP_CACHE_SHARED: + +<!-- ##### FUNCTION soup_cache_new ##### --> +<para> + +</para> + +@cache_dir: +@cache_type: +@Returns: + + +<!-- ##### FUNCTION soup_cache_flush ##### --> +<para> + +</para> + +@cache: + + +<!-- ##### FUNCTION soup_cache_clear ##### --> +<para> + +</para> + +@cache: + + +<!-- ##### FUNCTION soup_cache_dump ##### --> +<para> + +</para> + +@cache: + + +<!-- ##### FUNCTION soup_cache_load ##### --> +<para> + +</para> + +@cache: + + +<!-- ##### FUNCTION soup_cache_get_max_size ##### --> +<para> + +</para> + +@cache: +@Returns: + + +<!-- ##### FUNCTION soup_cache_set_max_size ##### --> +<para> + +</para> + +@cache: +@max_size: + + diff --git a/docs/reference/tmpl/soup-content-decoder.sgml b/docs/reference/tmpl/soup-content-decoder.sgml new file mode 100644 index 00000000..23b9b453 --- /dev/null +++ b/docs/reference/tmpl/soup-content-decoder.sgml @@ -0,0 +1,28 @@ +<!-- ##### SECTION Title ##### --> +SoupContentDecoder + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupContentDecoder ##### --> +<para> + +</para> + + diff --git a/docs/reference/tmpl/soup-content-sniffer.sgml b/docs/reference/tmpl/soup-content-sniffer.sgml new file mode 100644 index 00000000..d6cd00e1 --- /dev/null +++ b/docs/reference/tmpl/soup-content-sniffer.sgml @@ -0,0 +1,58 @@ +<!-- ##### SECTION Title ##### --> +SoupContentSniffer + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupContentSniffer ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION soup_content_sniffer_new ##### --> +<para> + +</para> + +@void: +@Returns: + + +<!-- ##### FUNCTION soup_content_sniffer_sniff ##### --> +<para> + +</para> + +@sniffer: +@msg: +@buffer: +@params: +@Returns: + + +<!-- ##### FUNCTION soup_content_sniffer_get_buffer_size ##### --> +<para> + +</para> + +@sniffer: +@Returns: + + diff --git a/docs/reference/tmpl/soup-cookie-jar-db.sgml b/docs/reference/tmpl/soup-cookie-jar-db.sgml new file mode 100644 index 00000000..8d863125 --- /dev/null +++ b/docs/reference/tmpl/soup-cookie-jar-db.sgml @@ -0,0 +1,50 @@ +<!-- ##### SECTION Title ##### --> +SoupCookieJarDB + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupCookieJarDB ##### --> +<para> + +</para> + + +<!-- ##### ARG SoupCookieJarDB:filename ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_cookie_jar_db_new ##### --> +<para> + +</para> + +@filename: +@read_only: +@Returns: + + +<!-- ##### MACRO SOUP_COOKIE_JAR_DB_FILENAME ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-cookie-jar-text.sgml b/docs/reference/tmpl/soup-cookie-jar-text.sgml new file mode 100644 index 00000000..7fa93d15 --- /dev/null +++ b/docs/reference/tmpl/soup-cookie-jar-text.sgml @@ -0,0 +1,50 @@ +<!-- ##### SECTION Title ##### --> +SoupCookieJarText + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupCookieJarText ##### --> +<para> + +</para> + + +<!-- ##### ARG SoupCookieJarText:filename ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_cookie_jar_text_new ##### --> +<para> + +</para> + +@filename: +@read_only: +@Returns: + + +<!-- ##### MACRO SOUP_COOKIE_JAR_TEXT_FILENAME ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-cookie-jar.sgml b/docs/reference/tmpl/soup-cookie-jar.sgml new file mode 100644 index 00000000..3f45a214 --- /dev/null +++ b/docs/reference/tmpl/soup-cookie-jar.sgml @@ -0,0 +1,186 @@ +<!-- ##### SECTION Title ##### --> +SoupCookieJar + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupCookieJar ##### --> +<para> + +</para> + + +<!-- ##### SIGNAL SoupCookieJar::changed ##### --> +<para> + +</para> + +@soupcookiejar: the object which received the signal. +@arg1: +@arg2: + +<!-- ##### ARG SoupCookieJar:accept-policy ##### --> +<para> + +</para> + +<!-- ##### ARG SoupCookieJar:read-only ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_cookie_jar_new ##### --> +<para> + +</para> + +@void: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_jar_get_cookies ##### --> +<para> + +</para> + +@jar: +@uri: +@for_http: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_jar_get_cookie_list ##### --> +<para> + +</para> + +@jar: +@uri: +@for_http: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_jar_set_cookie ##### --> +<para> + +</para> + +@jar: +@uri: +@cookie: + + +<!-- ##### FUNCTION soup_cookie_jar_set_cookie_with_first_party ##### --> +<para> + +</para> + +@jar: +@uri: +@first_party: +@cookie: + + +<!-- ##### FUNCTION soup_cookie_jar_add_cookie ##### --> +<para> + +</para> + +@jar: +@cookie: + + +<!-- ##### FUNCTION soup_cookie_jar_add_cookie_with_first_party ##### --> +<para> + +</para> + +@jar: +@first_party: +@cookie: + + +<!-- ##### FUNCTION soup_cookie_jar_delete_cookie ##### --> +<para> + +</para> + +@jar: +@cookie: + + +<!-- ##### FUNCTION soup_cookie_jar_all_cookies ##### --> +<para> + +</para> + +@jar: +@Returns: + + +<!-- ##### ENUM SoupCookieJarAcceptPolicy ##### --> +<para> + +</para> + +@SOUP_COOKIE_JAR_ACCEPT_ALWAYS: +@SOUP_COOKIE_JAR_ACCEPT_NEVER: +@SOUP_COOKIE_JAR_ACCEPT_NO_THIRD_PARTY: + +<!-- ##### FUNCTION soup_cookie_jar_get_accept_policy ##### --> +<para> + +</para> + +@jar: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_jar_set_accept_policy ##### --> +<para> + +</para> + +@jar: +@policy: + + +<!-- ##### FUNCTION soup_cookie_jar_is_persistent ##### --> +<para> + +</para> + +@jar: +@Returns: + + +<!-- ##### MACRO SOUP_COOKIE_JAR_READ_ONLY ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_COOKIE_JAR_ACCEPT_POLICY ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-cookie.sgml b/docs/reference/tmpl/soup-cookie.sgml new file mode 100644 index 00000000..5e850bc2 --- /dev/null +++ b/docs/reference/tmpl/soup-cookie.sgml @@ -0,0 +1,322 @@ +<!-- ##### SECTION Title ##### --> +SoupCookie + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupCookie ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION soup_cookie_new ##### --> +<para> + +</para> + +@name: +@value: +@domain: +@path: +@max_age: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_parse ##### --> +<para> + +</para> + +@header: +@origin: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_copy ##### --> +<para> + +</para> + +@cookie: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_free ##### --> +<para> + +</para> + +@cookie: + + +<!-- ##### FUNCTION soup_cookie_set_name ##### --> +<para> + +</para> + +@cookie: +@name: + + +<!-- ##### FUNCTION soup_cookie_get_name ##### --> +<para> + +</para> + +@cookie: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_set_value ##### --> +<para> + +</para> + +@cookie: +@value: + + +<!-- ##### FUNCTION soup_cookie_get_value ##### --> +<para> + +</para> + +@cookie: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_set_domain ##### --> +<para> + +</para> + +@cookie: +@domain: + + +<!-- ##### FUNCTION soup_cookie_get_domain ##### --> +<para> + +</para> + +@cookie: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_set_path ##### --> +<para> + +</para> + +@cookie: +@path: + + +<!-- ##### FUNCTION soup_cookie_get_path ##### --> +<para> + +</para> + +@cookie: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_set_max_age ##### --> +<para> + +</para> + +@cookie: +@max_age: + + +<!-- ##### MACRO SOUP_COOKIE_MAX_AGE_ONE_HOUR ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_COOKIE_MAX_AGE_ONE_DAY ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_COOKIE_MAX_AGE_ONE_WEEK ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_COOKIE_MAX_AGE_ONE_YEAR ##### --> +<para> + +</para> + + + +<!-- ##### FUNCTION soup_cookie_set_expires ##### --> +<para> + +</para> + +@cookie: +@expires: + + +<!-- ##### FUNCTION soup_cookie_get_expires ##### --> +<para> + +</para> + +@cookie: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_set_secure ##### --> +<para> + +</para> + +@cookie: +@secure: + + +<!-- ##### FUNCTION soup_cookie_get_secure ##### --> +<para> + +</para> + +@cookie: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_set_http_only ##### --> +<para> + +</para> + +@cookie: +@http_only: + + +<!-- ##### FUNCTION soup_cookie_get_http_only ##### --> +<para> + +</para> + +@cookie: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_applies_to_uri ##### --> +<para> + +</para> + +@cookie: +@uri: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_domain_matches ##### --> +<para> + +</para> + +@cookie: +@host: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_to_cookie_header ##### --> +<para> + +</para> + +@cookie: +@Returns: + + +<!-- ##### FUNCTION soup_cookie_to_set_cookie_header ##### --> +<para> + +</para> + +@cookie: +@Returns: + + +<!-- ##### FUNCTION soup_cookies_from_request ##### --> +<para> + +</para> + +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_cookies_from_response ##### --> +<para> + +</para> + +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_cookies_to_request ##### --> +<para> + +</para> + +@cookies: +@msg: + + +<!-- ##### FUNCTION soup_cookies_to_response ##### --> +<para> + +</para> + +@cookies: +@msg: + + +<!-- ##### FUNCTION soup_cookies_to_cookie_header ##### --> +<para> + +</para> + +@cookies: +@Returns: + + +<!-- ##### FUNCTION soup_cookies_free ##### --> +<para> + +</para> + +@cookies: + + diff --git a/docs/reference/tmpl/soup-form.sgml b/docs/reference/tmpl/soup-form.sgml new file mode 100644 index 00000000..b80fa4b6 --- /dev/null +++ b/docs/reference/tmpl/soup-form.sgml @@ -0,0 +1,140 @@ +<!-- ##### SECTION Title ##### --> +HTML Form Support + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### MACRO SOUP_FORM_MIME_TYPE_MULTIPART ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_FORM_MIME_TYPE_URLENCODED ##### --> +<para> + +</para> + + + +<!-- ##### FUNCTION soup_form_decode ##### --> +<para> + +</para> + +@encoded_form: +@Returns: + + +<!-- ##### FUNCTION soup_form_decode_multipart ##### --> +<para> + +</para> + +@msg: +@file_control_name: +@filename: +@content_type: +@file: +@Returns: + + +<!-- ##### FUNCTION soup_form_encode ##### --> +<para> + +</para> + +@first_field: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_form_encode_datalist ##### --> +<para> + +</para> + +@form_data_set: +@Returns: + + +<!-- ##### FUNCTION soup_form_encode_hash ##### --> +<para> + +</para> + +@form_data_set: +@Returns: + + +<!-- ##### FUNCTION soup_form_encode_valist ##### --> +<para> + +</para> + +@first_field: +@args: +@Returns: + + +<!-- ##### FUNCTION soup_form_request_new ##### --> +<para> + +</para> + +@method: +@uri: +@first_field: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_form_request_new_from_datalist ##### --> +<para> + +</para> + +@method: +@uri: +@form_data_set: +@Returns: + + +<!-- ##### FUNCTION soup_form_request_new_from_hash ##### --> +<para> + +</para> + +@method: +@uri: +@form_data_set: +@Returns: + + +<!-- ##### FUNCTION soup_form_request_new_from_multipart ##### --> +<para> + +</para> + +@uri: +@multipart: +@Returns: + + diff --git a/docs/reference/tmpl/soup-logger.sgml b/docs/reference/tmpl/soup-logger.sgml new file mode 100644 index 00000000..5056e1f5 --- /dev/null +++ b/docs/reference/tmpl/soup-logger.sgml @@ -0,0 +1,122 @@ +<!-- ##### SECTION Title ##### --> +SoupLogger + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupLogger ##### --> +<para> + +</para> + + +<!-- ##### ENUM SoupLoggerLogLevel ##### --> +<para> + +</para> + +@SOUP_LOGGER_LOG_NONE: +@SOUP_LOGGER_LOG_MINIMAL: +@SOUP_LOGGER_LOG_HEADERS: +@SOUP_LOGGER_LOG_BODY: + +<!-- ##### FUNCTION soup_logger_new ##### --> +<para> + +</para> + +@level: +@max_body_size: +@Returns: + + +<!-- ##### FUNCTION soup_logger_attach ##### --> +<para> + +</para> + +@logger: +@session: + + +<!-- ##### FUNCTION soup_logger_detach ##### --> +<para> + +</para> + +@logger: +@session: + + +<!-- ##### USER_FUNCTION SoupLoggerFilter ##### --> +<para> + +</para> + +@logger: +@msg: +@user_data: +@Returns: + + +<!-- ##### FUNCTION soup_logger_set_request_filter ##### --> +<para> + +</para> + +@logger: +@request_filter: +@filter_data: +@destroy: + + +<!-- ##### FUNCTION soup_logger_set_response_filter ##### --> +<para> + +</para> + +@logger: +@response_filter: +@filter_data: +@destroy: + + +<!-- ##### USER_FUNCTION SoupLoggerPrinter ##### --> +<para> + +</para> + +@logger: +@level: +@direction: +@data: +@user_data: + + +<!-- ##### FUNCTION soup_logger_set_printer ##### --> +<para> + +</para> + +@logger: +@printer: +@printer_data: +@destroy: + + diff --git a/docs/reference/tmpl/soup-message-body.sgml b/docs/reference/tmpl/soup-message-body.sgml new file mode 100644 index 00000000..7fc31a57 --- /dev/null +++ b/docs/reference/tmpl/soup-message-body.sgml @@ -0,0 +1,251 @@ +<!-- ##### SECTION Title ##### --> +SoupMessageBody + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupBuffer ##### --> +<para> + +</para> + + +<!-- ##### ENUM SoupMemoryUse ##### --> +<para> + +</para> + +@SOUP_MEMORY_STATIC: +@SOUP_MEMORY_TAKE: +@SOUP_MEMORY_COPY: +@SOUP_MEMORY_TEMPORARY: + +<!-- ##### FUNCTION soup_buffer_new ##### --> +<para> + +</para> + +@use: +@data: +@length: +@Returns: + + +<!-- ##### FUNCTION soup_buffer_new_subbuffer ##### --> +<para> + +</para> + +@parent: +@offset: +@length: +@Returns: + + +<!-- ##### FUNCTION soup_buffer_new_with_owner ##### --> +<para> + +</para> + +@data: +@length: +@owner: +@owner_dnotify: +@Returns: + + +<!-- ##### FUNCTION soup_buffer_new_take ##### --> +<para> + +</para> + +@data: +@length: +@Returns: + + +<!-- ##### FUNCTION soup_buffer_get_owner ##### --> +<para> + +</para> + +@buffer: +@Returns: + + +<!-- ##### FUNCTION soup_buffer_get_data ##### --> +<para> + +</para> + +@buffer: +@data: +@length: + + +<!-- ##### FUNCTION soup_buffer_copy ##### --> +<para> + +</para> + +@buffer: +@Returns: + + +<!-- ##### FUNCTION soup_buffer_free ##### --> +<para> + +</para> + +@buffer: + + +<!-- ##### FUNCTION soup_buffer_get_as_bytes ##### --> +<para> + +</para> + +@buffer: +@Returns: + + +<!-- ##### STRUCT SoupMessageBody ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION soup_message_body_new ##### --> +<para> + +</para> + +@void: +@Returns: + + +<!-- ##### FUNCTION soup_message_body_free ##### --> +<para> + +</para> + +@body: + + +<!-- ##### FUNCTION soup_message_body_set_accumulate ##### --> +<para> + +</para> + +@body: +@accumulate: + + +<!-- ##### FUNCTION soup_message_body_get_accumulate ##### --> +<para> + +</para> + +@body: +@Returns: + + +<!-- ##### FUNCTION soup_message_body_append ##### --> +<para> + +</para> + +@body: +@use: +@data: +@length: + + +<!-- ##### FUNCTION soup_message_body_append_buffer ##### --> +<para> + +</para> + +@body: +@buffer: + + +<!-- ##### FUNCTION soup_message_body_append_take ##### --> +<para> + +</para> + +@body: +@data: +@length: + + +<!-- ##### FUNCTION soup_message_body_truncate ##### --> +<para> + +</para> + +@body: + + +<!-- ##### FUNCTION soup_message_body_complete ##### --> +<para> + +</para> + +@body: + + +<!-- ##### FUNCTION soup_message_body_flatten ##### --> +<para> + +</para> + +@body: +@Returns: + + +<!-- ##### FUNCTION soup_message_body_get_chunk ##### --> +<para> + +</para> + +@body: +@offset: +@Returns: + + +<!-- ##### FUNCTION soup_message_body_got_chunk ##### --> +<para> + +</para> + +@body: +@chunk: + + +<!-- ##### FUNCTION soup_message_body_wrote_chunk ##### --> +<para> + +</para> + +@body: +@chunk: + + diff --git a/docs/reference/tmpl/soup-message-headers.sgml b/docs/reference/tmpl/soup-message-headers.sgml new file mode 100644 index 00000000..b29eb9e7 --- /dev/null +++ b/docs/reference/tmpl/soup-message-headers.sgml @@ -0,0 +1,362 @@ +<!-- ##### SECTION Title ##### --> +SoupMessageHeaders + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### TYPEDEF SoupMessageHeaders ##### --> +<para> + +</para> + + +<!-- ##### ENUM SoupMessageHeadersType ##### --> +<para> + +</para> + +@SOUP_MESSAGE_HEADERS_REQUEST: +@SOUP_MESSAGE_HEADERS_RESPONSE: +@SOUP_MESSAGE_HEADERS_MULTIPART: + +<!-- ##### FUNCTION soup_message_headers_new ##### --> +<para> + +</para> + +@type: +@Returns: + + +<!-- ##### FUNCTION soup_message_headers_free ##### --> +<para> + +</para> + +@hdrs: + + +<!-- ##### FUNCTION soup_message_headers_append ##### --> +<para> + +</para> + +@hdrs: +@name: +@value: + + +<!-- ##### FUNCTION soup_message_headers_replace ##### --> +<para> + +</para> + +@hdrs: +@name: +@value: + + +<!-- ##### FUNCTION soup_message_headers_remove ##### --> +<para> + +</para> + +@hdrs: +@name: + + +<!-- ##### FUNCTION soup_message_headers_clear ##### --> +<para> + +</para> + +@hdrs: + + +<!-- ##### FUNCTION soup_message_headers_clean_connection_headers ##### --> +<para> + +</para> + +@hdrs: + + +<!-- ##### FUNCTION soup_message_headers_get_one ##### --> +<para> + +</para> + +@hdrs: +@name: +@Returns: + + +<!-- ##### FUNCTION soup_message_headers_get_list ##### --> +<para> + +</para> + +@hdrs: +@name: +@Returns: + + +<!-- ##### FUNCTION soup_message_headers_get ##### --> +<para> + +</para> + +@hdrs: +@name: +@Returns: + + +<!-- ##### USER_FUNCTION SoupMessageHeadersForeachFunc ##### --> +<para> + +</para> + +@name: +@value: +@user_data: + + +<!-- ##### FUNCTION soup_message_headers_foreach ##### --> +<para> + +</para> + +@hdrs: +@func: +@user_data: + + +<!-- ##### STRUCT SoupMessageHeadersIter ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION soup_message_headers_iter_init ##### --> +<para> + +</para> + +@iter: +@hdrs: + + +<!-- ##### FUNCTION soup_message_headers_iter_next ##### --> +<para> + +</para> + +@iter: +@name: +@value: +@Returns: + + +<!-- ##### ENUM SoupEncoding ##### --> +<para> + +</para> + +@SOUP_ENCODING_UNRECOGNIZED: +@SOUP_ENCODING_NONE: +@SOUP_ENCODING_CONTENT_LENGTH: +@SOUP_ENCODING_EOF: +@SOUP_ENCODING_CHUNKED: +@SOUP_ENCODING_BYTERANGES: + +<!-- ##### FUNCTION soup_message_headers_get_encoding ##### --> +<para> + +</para> + +@hdrs: +@Returns: + + +<!-- ##### FUNCTION soup_message_headers_set_encoding ##### --> +<para> + +</para> + +@hdrs: +@encoding: + + +<!-- ##### FUNCTION soup_message_headers_get_content_length ##### --> +<para> + +</para> + +@hdrs: +@Returns: + + +<!-- ##### FUNCTION soup_message_headers_set_content_length ##### --> +<para> + +</para> + +@hdrs: +@content_length: + + +<!-- ##### ENUM SoupExpectation ##### --> +<para> + +</para> + +@SOUP_EXPECTATION_UNRECOGNIZED: +@SOUP_EXPECTATION_CONTINUE: + +<!-- ##### FUNCTION soup_message_headers_get_expectations ##### --> +<para> + +</para> + +@hdrs: +@Returns: + + +<!-- ##### FUNCTION soup_message_headers_set_expectations ##### --> +<para> + +</para> + +@hdrs: +@expectations: + + +<!-- ##### FUNCTION soup_message_headers_get_content_type ##### --> +<para> + +</para> + +@hdrs: +@params: +@Returns: + + +<!-- ##### FUNCTION soup_message_headers_set_content_type ##### --> +<para> + +</para> + +@hdrs: +@content_type: +@params: + + +<!-- ##### FUNCTION soup_message_headers_get_content_disposition ##### --> +<para> + +</para> + +@hdrs: +@disposition: +@params: +@Returns: + + +<!-- ##### FUNCTION soup_message_headers_set_content_disposition ##### --> +<para> + +</para> + +@hdrs: +@disposition: +@params: + + +<!-- ##### STRUCT SoupRange ##### --> +<para> + +</para> + +@start: +@end: + +<!-- ##### FUNCTION soup_message_headers_get_ranges ##### --> +<para> + +</para> + +@hdrs: +@total_length: +@ranges: +@length: +@Returns: + + +<!-- ##### FUNCTION soup_message_headers_set_ranges ##### --> +<para> + +</para> + +@hdrs: +@ranges: +@length: + + +<!-- ##### FUNCTION soup_message_headers_set_range ##### --> +<para> + +</para> + +@hdrs: +@start: +@end: + + +<!-- ##### FUNCTION soup_message_headers_free_ranges ##### --> +<para> + +</para> + +@hdrs: +@ranges: + + +<!-- ##### FUNCTION soup_message_headers_get_content_range ##### --> +<para> + +</para> + +@hdrs: +@start: +@end: +@total_length: +@Returns: + + +<!-- ##### FUNCTION soup_message_headers_set_content_range ##### --> +<para> + +</para> + +@hdrs: +@start: +@end: +@total_length: + + diff --git a/docs/reference/tmpl/soup-message.sgml b/docs/reference/tmpl/soup-message.sgml new file mode 100644 index 00000000..bcf953b6 --- /dev/null +++ b/docs/reference/tmpl/soup-message.sgml @@ -0,0 +1,626 @@ +<!-- ##### SECTION Title ##### --> +SoupMessage + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupMessage ##### --> +<para> + +</para> + +@method: +@status_code: +@reason_phrase: +@request_body: +@request_headers: +@response_body: +@response_headers: + +<!-- ##### SIGNAL SoupMessage::content-sniffed ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. +@arg1: +@arg2: + +<!-- ##### SIGNAL SoupMessage::finished ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. + +<!-- ##### SIGNAL SoupMessage::got-body ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. + +<!-- ##### SIGNAL SoupMessage::got-chunk ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. +@arg1: + +<!-- ##### SIGNAL SoupMessage::got-headers ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. + +<!-- ##### SIGNAL SoupMessage::got-informational ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. + +<!-- ##### SIGNAL SoupMessage::network-event ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. +@arg1: +@arg2: + +<!-- ##### SIGNAL SoupMessage::restarted ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. + +<!-- ##### SIGNAL SoupMessage::wrote-body ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. + +<!-- ##### SIGNAL SoupMessage::wrote-body-data ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. +@arg1: + +<!-- ##### SIGNAL SoupMessage::wrote-chunk ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. + +<!-- ##### SIGNAL SoupMessage::wrote-headers ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. + +<!-- ##### SIGNAL SoupMessage::wrote-informational ##### --> +<para> + +</para> + +@soupmessage: the object which received the signal. + +<!-- ##### ARG SoupMessage:first-party ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:flags ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:http-version ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:method ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:priority ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:reason-phrase ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:request-body ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:request-body-data ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:request-headers ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:response-body ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:response-body-data ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:response-headers ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:server-side ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:status-code ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:tls-certificate ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:tls-errors ##### --> +<para> + +</para> + +<!-- ##### ARG SoupMessage:uri ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_message_new ##### --> +<para> + +</para> + +@method: +@uri_string: +@Returns: + + +<!-- ##### FUNCTION soup_message_new_from_uri ##### --> +<para> + +</para> + +@method: +@uri: +@Returns: + + +<!-- ##### FUNCTION soup_message_set_request ##### --> +<para> + +</para> + +@msg: +@content_type: +@req_use: +@req_body: +@req_length: + + +<!-- ##### FUNCTION soup_message_set_response ##### --> +<para> + +</para> + +@msg: +@content_type: +@resp_use: +@resp_body: +@resp_length: + + +<!-- ##### ENUM SoupHTTPVersion ##### --> +<para> + +</para> + +@SOUP_HTTP_1_0: +@SOUP_HTTP_1_1: + +<!-- ##### FUNCTION soup_message_set_http_version ##### --> +<para> + +</para> + +@msg: +@version: + + +<!-- ##### FUNCTION soup_message_get_http_version ##### --> +<para> + +</para> + +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_message_get_uri ##### --> +<para> + +</para> + +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_message_set_uri ##### --> +<para> + +</para> + +@msg: +@uri: + + +<!-- ##### FUNCTION soup_message_get_address ##### --> +<para> + +</para> + +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_message_set_status ##### --> +<para> + +</para> + +@msg: +@status_code: + + +<!-- ##### FUNCTION soup_message_set_status_full ##### --> +<para> + +</para> + +@msg: +@status_code: +@reason_phrase: + + +<!-- ##### FUNCTION soup_message_set_redirect ##### --> +<para> + +</para> + +@msg: +@status_code: +@redirect_uri: + + +<!-- ##### FUNCTION soup_message_is_keepalive ##### --> +<para> + +</para> + +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_message_get_https_status ##### --> +<para> + +</para> + +@msg: +@certificate: +@errors: +@Returns: + + +<!-- ##### FUNCTION soup_message_set_first_party ##### --> +<para> + +</para> + +@msg: +@first_party: + + +<!-- ##### FUNCTION soup_message_get_first_party ##### --> +<para> + +</para> + +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_message_add_header_handler ##### --> +<para> + +</para> + +@msg: +@signal: +@header: +@callback: +@user_data: +@Returns: + + +<!-- ##### FUNCTION soup_message_add_status_code_handler ##### --> +<para> + +</para> + +@msg: +@signal: +@status_code: +@callback: +@user_data: +@Returns: + + +<!-- ##### ENUM SoupMessageFlags ##### --> +<para> + +</para> + +@SOUP_MESSAGE_NO_REDIRECT: +@SOUP_MESSAGE_CAN_REBUILD: +@SOUP_MESSAGE_OVERWRITE_CHUNKS: +@SOUP_MESSAGE_CONTENT_DECODED: +@SOUP_MESSAGE_CERTIFICATE_TRUSTED: +@SOUP_MESSAGE_NEW_CONNECTION: +@SOUP_MESSAGE_IDEMPOTENT: + +<!-- ##### FUNCTION soup_message_set_flags ##### --> +<para> + +</para> + +@msg: +@flags: + + +<!-- ##### FUNCTION soup_message_get_flags ##### --> +<para> + +</para> + +@msg: +@Returns: + + +<!-- ##### USER_FUNCTION SoupChunkAllocator ##### --> +<para> + +</para> + +@msg: +@max_len: +@user_data: +@Returns: + + +<!-- ##### FUNCTION soup_message_set_chunk_allocator ##### --> +<para> + +</para> + +@msg: +@allocator: +@user_data: +@destroy_notify: + + +<!-- ##### FUNCTION soup_message_disable_feature ##### --> +<para> + +</para> + +@msg: +@feature_type: + + +<!-- ##### FUNCTION soup_message_get_soup_request ##### --> +<para> + +</para> + +@msg: +@Returns: + + +<!-- ##### ENUM SoupMessagePriority ##### --> +<para> + +</para> + +@SOUP_MESSAGE_PRIORITY_VERY_LOW: +@SOUP_MESSAGE_PRIORITY_LOW: +@SOUP_MESSAGE_PRIORITY_NORMAL: +@SOUP_MESSAGE_PRIORITY_HIGH: +@SOUP_MESSAGE_PRIORITY_VERY_HIGH: + +<!-- ##### FUNCTION soup_message_get_priority ##### --> +<para> + +</para> + +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_message_set_priority ##### --> +<para> + +</para> + +@msg: +@priority: + + +<!-- ##### MACRO SOUP_MESSAGE_METHOD ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_URI ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_HTTP_VERSION ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_FLAGS ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_STATUS_CODE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_REASON_PHRASE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_SERVER_SIDE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_FIRST_PARTY ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_PRIORITY ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_REQUEST_BODY ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_REQUEST_BODY_DATA ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_REQUEST_HEADERS ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_RESPONSE_BODY ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_RESPONSE_BODY_DATA ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_RESPONSE_HEADERS ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_TLS_CERTIFICATE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MESSAGE_TLS_ERRORS ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-method.sgml b/docs/reference/tmpl/soup-method.sgml new file mode 100644 index 00000000..d2996e19 --- /dev/null +++ b/docs/reference/tmpl/soup-method.sgml @@ -0,0 +1,127 @@ +<!-- ##### SECTION Title ##### --> +soup-method + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### MACRO SOUP_METHOD_OPTIONS ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_GET ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_HEAD ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_PUT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_POST ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_DELETE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_TRACE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_CONNECT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_PROPFIND ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_PROPPATCH ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_MKCOL ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_COPY ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_MOVE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_LOCK ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_METHOD_UNLOCK ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-misc.sgml b/docs/reference/tmpl/soup-misc.sgml new file mode 100644 index 00000000..92d2f0a1 --- /dev/null +++ b/docs/reference/tmpl/soup-misc.sgml @@ -0,0 +1,399 @@ +<!-- ##### SECTION Title ##### --> +Soup Miscellaneous Utilities + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupDate ##### --> +<para> + +</para> + + +<!-- ##### ENUM SoupDateFormat ##### --> +<para> + +</para> + +@SOUP_DATE_HTTP: +@SOUP_DATE_COOKIE: +@SOUP_DATE_RFC2822: +@SOUP_DATE_ISO8601_COMPACT: +@SOUP_DATE_ISO8601_FULL: +@SOUP_DATE_ISO8601: +@SOUP_DATE_ISO8601_XMLRPC: + +<!-- ##### FUNCTION soup_date_new ##### --> +<para> + +</para> + +@year: +@month: +@day: +@hour: +@minute: +@second: +@Returns: + + +<!-- ##### FUNCTION soup_date_new_from_string ##### --> +<para> + +</para> + +@date_string: +@Returns: + + +<!-- ##### FUNCTION soup_date_new_from_time_t ##### --> +<para> + +</para> + +@when: +@Returns: + + +<!-- ##### FUNCTION soup_date_new_from_now ##### --> +<para> + +</para> + +@offset_seconds: +@Returns: + + +<!-- ##### FUNCTION soup_date_to_string ##### --> +<para> + +</para> + +@date: +@format: +@Returns: + + +<!-- ##### FUNCTION soup_date_to_time_t ##### --> +<para> + +</para> + +@date: +@Returns: + + +<!-- ##### FUNCTION soup_date_to_timeval ##### --> +<para> + +</para> + +@date: +@time: + + +<!-- ##### FUNCTION soup_date_is_past ##### --> +<para> + +</para> + +@date: +@Returns: + + +<!-- ##### FUNCTION soup_date_get_day ##### --> +<para> + +</para> + +@date: +@Returns: + + +<!-- ##### FUNCTION soup_date_get_hour ##### --> +<para> + +</para> + +@date: +@Returns: + + +<!-- ##### FUNCTION soup_date_get_minute ##### --> +<para> + +</para> + +@date: +@Returns: + + +<!-- ##### FUNCTION soup_date_get_month ##### --> +<para> + +</para> + +@date: +@Returns: + + +<!-- ##### FUNCTION soup_date_get_offset ##### --> +<para> + +</para> + +@date: +@Returns: + + +<!-- ##### FUNCTION soup_date_get_second ##### --> +<para> + +</para> + +@date: +@Returns: + + +<!-- ##### FUNCTION soup_date_get_utc ##### --> +<para> + +</para> + +@date: +@Returns: + + +<!-- ##### FUNCTION soup_date_get_year ##### --> +<para> + +</para> + +@date: +@Returns: + + +<!-- ##### FUNCTION soup_date_free ##### --> +<para> + +</para> + +@date: + + +<!-- ##### FUNCTION soup_headers_parse_request ##### --> +<para> + +</para> + +@str: +@len: +@req_headers: +@req_method: +@req_path: +@ver: +@Returns: + + +<!-- ##### FUNCTION soup_headers_parse_response ##### --> +<para> + +</para> + +@str: +@len: +@headers: +@ver: +@status_code: +@reason_phrase: +@Returns: + + +<!-- ##### FUNCTION soup_headers_parse_status_line ##### --> +<para> + +</para> + +@status_line: +@ver: +@status_code: +@reason_phrase: +@Returns: + + +<!-- ##### FUNCTION soup_headers_parse ##### --> +<para> + +</para> + +@str: +@len: +@dest: +@Returns: + + +<!-- ##### FUNCTION soup_header_parse_list ##### --> +<para> + +</para> + +@header: +@Returns: + + +<!-- ##### FUNCTION soup_header_parse_quality_list ##### --> +<para> + +</para> + +@header: +@unacceptable: +@Returns: + + +<!-- ##### FUNCTION soup_header_free_list ##### --> +<para> + +</para> + +@list: + + +<!-- ##### FUNCTION soup_header_contains ##### --> +<para> + +</para> + +@header: +@token: +@Returns: + + +<!-- ##### FUNCTION soup_header_parse_param_list ##### --> +<para> + +</para> + +@header: +@Returns: + + +<!-- ##### FUNCTION soup_header_parse_semi_param_list ##### --> +<para> + +</para> + +@header: +@Returns: + + +<!-- ##### FUNCTION soup_header_free_param_list ##### --> +<para> + +</para> + +@param_list: + + +<!-- ##### FUNCTION soup_header_g_string_append_param ##### --> +<para> + +</para> + +@string: +@name: +@value: + + +<!-- ##### FUNCTION soup_header_g_string_append_param_quoted ##### --> +<para> + +</para> + +@string: +@name: +@value: + + +<!-- ##### FUNCTION soup_str_case_equal ##### --> +<para> + +</para> + +@v1: +@v2: +@Returns: + + +<!-- ##### FUNCTION soup_str_case_hash ##### --> +<para> + +</para> + +@key: +@Returns: + + +<!-- ##### FUNCTION soup_add_completion ##### --> +<para> + +</para> + +@async_context: +@function: +@data: +@Returns: + + +<!-- ##### FUNCTION soup_add_idle ##### --> +<para> + +</para> + +@async_context: +@function: +@data: +@Returns: + + +<!-- ##### FUNCTION soup_add_io_watch ##### --> +<para> + +</para> + +@async_context: +@chan: +@condition: +@function: +@data: +@Returns: + + +<!-- ##### FUNCTION soup_add_timeout ##### --> +<para> + +</para> + +@async_context: +@interval: +@function: +@data: +@Returns: + + diff --git a/docs/reference/tmpl/soup-multipart-input-stream.sgml b/docs/reference/tmpl/soup-multipart-input-stream.sgml new file mode 100644 index 00000000..12e3315d --- /dev/null +++ b/docs/reference/tmpl/soup-multipart-input-stream.sgml @@ -0,0 +1,86 @@ +<!-- ##### SECTION Title ##### --> +SoupMultipartInputStream + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupMultipartInputStream ##### --> +<para> + +</para> + + +<!-- ##### ARG SoupMultipartInputStream:message ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_multipart_input_stream_new ##### --> +<para> + +</para> + +@msg: +@base_stream: +@Returns: + + +<!-- ##### FUNCTION soup_multipart_input_stream_get_headers ##### --> +<para> + +</para> + +@multipart: +@Returns: + + +<!-- ##### FUNCTION soup_multipart_input_stream_next_part ##### --> +<para> + +</para> + +@multipart: +@cancellable: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_multipart_input_stream_next_part_async ##### --> +<para> + +</para> + +@multipart: +@io_priority: +@cancellable: +@callback: +@data: + + +<!-- ##### FUNCTION soup_multipart_input_stream_next_part_finish ##### --> +<para> + +</para> + +@multipart: +@result: +@error: +@Returns: + + diff --git a/docs/reference/tmpl/soup-multipart.sgml b/docs/reference/tmpl/soup-multipart.sgml new file mode 100644 index 00000000..5b0145d1 --- /dev/null +++ b/docs/reference/tmpl/soup-multipart.sgml @@ -0,0 +1,118 @@ +<!-- ##### SECTION Title ##### --> +SoupMultipart + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### TYPEDEF SoupMultipart ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION soup_multipart_new ##### --> +<para> + +</para> + +@mime_type: +@Returns: + + +<!-- ##### FUNCTION soup_multipart_new_from_message ##### --> +<para> + +</para> + +@headers: +@body: +@Returns: + + +<!-- ##### FUNCTION soup_multipart_free ##### --> +<para> + +</para> + +@multipart: + + +<!-- ##### FUNCTION soup_multipart_get_length ##### --> +<para> + +</para> + +@multipart: +@Returns: + + +<!-- ##### FUNCTION soup_multipart_get_part ##### --> +<para> + +</para> + +@multipart: +@part: +@headers: +@body: +@Returns: + + +<!-- ##### FUNCTION soup_multipart_append_part ##### --> +<para> + +</para> + +@multipart: +@headers: +@body: + + +<!-- ##### FUNCTION soup_multipart_append_form_string ##### --> +<para> + +</para> + +@multipart: +@control_name: +@data: + + +<!-- ##### FUNCTION soup_multipart_append_form_file ##### --> +<para> + +</para> + +@multipart: +@control_name: +@filename: +@content_type: +@body: + + +<!-- ##### FUNCTION soup_multipart_to_message ##### --> +<para> + +</para> + +@multipart: +@dest_headers: +@dest_body: + + diff --git a/docs/reference/tmpl/soup-proxy-resolver-default.sgml b/docs/reference/tmpl/soup-proxy-resolver-default.sgml new file mode 100644 index 00000000..a36aaa2f --- /dev/null +++ b/docs/reference/tmpl/soup-proxy-resolver-default.sgml @@ -0,0 +1,33 @@ +<!-- ##### SECTION Title ##### --> +SoupProxyResolverDefault + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupProxyResolverDefault ##### --> +<para> + +</para> + + +<!-- ##### ARG SoupProxyResolverDefault:gproxy-resolver ##### --> +<para> + +</para> + diff --git a/docs/reference/tmpl/soup-request-data.sgml b/docs/reference/tmpl/soup-request-data.sgml new file mode 100644 index 00000000..31ab1e0c --- /dev/null +++ b/docs/reference/tmpl/soup-request-data.sgml @@ -0,0 +1,28 @@ +<!-- ##### SECTION Title ##### --> +SoupRequestData + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupRequestData ##### --> +<para> + +</para> + + diff --git a/docs/reference/tmpl/soup-request-file.sgml b/docs/reference/tmpl/soup-request-file.sgml new file mode 100644 index 00000000..229a99cf --- /dev/null +++ b/docs/reference/tmpl/soup-request-file.sgml @@ -0,0 +1,37 @@ +<!-- ##### SECTION Title ##### --> +SoupRequestFile + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupRequestFile ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION soup_request_file_get_file ##### --> +<para> + +</para> + +@file: +@Returns: + + diff --git a/docs/reference/tmpl/soup-request-http.sgml b/docs/reference/tmpl/soup-request-http.sgml new file mode 100644 index 00000000..0a0d1cf3 --- /dev/null +++ b/docs/reference/tmpl/soup-request-http.sgml @@ -0,0 +1,37 @@ +<!-- ##### SECTION Title ##### --> +SoupRequestHTTP + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupRequestHTTP ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION soup_request_http_get_message ##### --> +<para> + +</para> + +@http: +@Returns: + + diff --git a/docs/reference/tmpl/soup-request.sgml b/docs/reference/tmpl/soup-request.sgml new file mode 100644 index 00000000..3003847a --- /dev/null +++ b/docs/reference/tmpl/soup-request.sgml @@ -0,0 +1,121 @@ +<!-- ##### SECTION Title ##### --> +SoupRequest + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupRequest ##### --> +<para> + +</para> + + +<!-- ##### ARG SoupRequest:session ##### --> +<para> + +</para> + +<!-- ##### ARG SoupRequest:uri ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_request_send ##### --> +<para> + +</para> + +@request: +@cancellable: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_request_send_async ##### --> +<para> + +</para> + +@request: +@cancellable: +@callback: +@user_data: + + +<!-- ##### FUNCTION soup_request_send_finish ##### --> +<para> + +</para> + +@request: +@result: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_request_get_content_length ##### --> +<para> + +</para> + +@request: +@Returns: + + +<!-- ##### FUNCTION soup_request_get_content_type ##### --> +<para> + +</para> + +@request: +@Returns: + + +<!-- ##### FUNCTION soup_request_get_session ##### --> +<para> + +</para> + +@request: +@Returns: + + +<!-- ##### FUNCTION soup_request_get_uri ##### --> +<para> + +</para> + +@request: +@Returns: + + +<!-- ##### MACRO SOUP_REQUEST_SESSION ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_REQUEST_URI ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-server-deprecated.sgml b/docs/reference/tmpl/soup-server-deprecated.sgml new file mode 100644 index 00000000..e18a391a --- /dev/null +++ b/docs/reference/tmpl/soup-server-deprecated.sgml @@ -0,0 +1,126 @@ +<!-- ##### SECTION Title ##### --> +SoupServer deprecated API + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### FUNCTION soup_server_get_port ##### --> +<para> + +</para> + +@server: +@Returns: + + +<!-- ##### FUNCTION soup_server_get_listener ##### --> +<para> + +</para> + +@server: +@Returns: + + +<!-- ##### FUNCTION soup_server_run ##### --> +<para> + +</para> + +@server: + + +<!-- ##### FUNCTION soup_server_run_async ##### --> +<para> + +</para> + +@server: + + +<!-- ##### FUNCTION soup_server_quit ##### --> +<para> + +</para> + +@server: + + +<!-- ##### FUNCTION soup_server_get_async_context ##### --> +<para> + +</para> + +@server: +@Returns: + + +<!-- ##### FUNCTION soup_client_context_get_socket ##### --> +<para> + +</para> + +@client: +@Returns: + + +<!-- ##### FUNCTION soup_client_context_get_address ##### --> +<para> + +</para> + +@client: +@Returns: + + +<!-- ##### MACRO SOUP_SERVER_PORT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_INTERFACE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_SSL_CERT_FILE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_SSL_KEY_FILE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_ASYNC_CONTEXT ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-server.sgml b/docs/reference/tmpl/soup-server.sgml new file mode 100644 index 00000000..81bff025 --- /dev/null +++ b/docs/reference/tmpl/soup-server.sgml @@ -0,0 +1,383 @@ +<!-- ##### SECTION Title ##### --> +SoupServer + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupServer ##### --> +<para> + +</para> + + +<!-- ##### SIGNAL SoupServer::request-aborted ##### --> +<para> + +</para> + +@soupserver: the object which received the signal. +@arg1: +@arg2: + +<!-- ##### SIGNAL SoupServer::request-finished ##### --> +<para> + +</para> + +@soupserver: the object which received the signal. +@arg1: +@arg2: + +<!-- ##### SIGNAL SoupServer::request-read ##### --> +<para> + +</para> + +@soupserver: the object which received the signal. +@arg1: +@arg2: + +<!-- ##### SIGNAL SoupServer::request-started ##### --> +<para> + +</para> + +@soupserver: the object which received the signal. +@arg1: +@arg2: + +<!-- ##### ARG SoupServer:async-context ##### --> +<para> + +</para> + +<!-- ##### ARG SoupServer:http-aliases ##### --> +<para> + +</para> + +<!-- ##### ARG SoupServer:https-aliases ##### --> +<para> + +</para> + +<!-- ##### ARG SoupServer:interface ##### --> +<para> + +</para> + +<!-- ##### ARG SoupServer:port ##### --> +<para> + +</para> + +<!-- ##### ARG SoupServer:raw-paths ##### --> +<para> + +</para> + +<!-- ##### ARG SoupServer:server-header ##### --> +<para> + +</para> + +<!-- ##### ARG SoupServer:ssl-cert-file ##### --> +<para> + +</para> + +<!-- ##### ARG SoupServer:ssl-key-file ##### --> +<para> + +</para> + +<!-- ##### ARG SoupServer:tls-certificate ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_server_new ##### --> +<para> + +</para> + +@optname1: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_server_is_https ##### --> +<para> + +</para> + +@server: +@Returns: + + +<!-- ##### FUNCTION soup_server_get_port ##### --> +<para> + +</para> + +@server: +@Returns: + + +<!-- ##### FUNCTION soup_server_get_listener ##### --> +<para> + +</para> + +@server: +@Returns: + + +<!-- ##### FUNCTION soup_server_run ##### --> +<para> + +</para> + +@server: + + +<!-- ##### FUNCTION soup_server_run_async ##### --> +<para> + +</para> + +@server: + + +<!-- ##### FUNCTION soup_server_quit ##### --> +<para> + +</para> + +@server: + + +<!-- ##### FUNCTION soup_server_disconnect ##### --> +<para> + +</para> + +@server: + + +<!-- ##### FUNCTION soup_server_get_async_context ##### --> +<para> + +</para> + +@server: +@Returns: + + +<!-- ##### USER_FUNCTION SoupServerCallback ##### --> +<para> + +</para> + +@server: +@msg: +@path: +@query: +@client: +@user_data: + + +<!-- ##### FUNCTION soup_server_add_handler ##### --> +<para> + +</para> + +@server: +@path: +@callback: +@user_data: +@destroy: + + +<!-- ##### FUNCTION soup_server_remove_handler ##### --> +<para> + +</para> + +@server: +@path: + + +<!-- ##### TYPEDEF SoupClientContext ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION soup_client_context_get_socket ##### --> +<para> + +</para> + +@client: +@Returns: + + +<!-- ##### FUNCTION soup_client_context_get_address ##### --> +<para> + +</para> + +@client: +@Returns: + + +<!-- ##### FUNCTION soup_client_context_get_host ##### --> +<para> + +</para> + +@client: +@Returns: + + +<!-- ##### FUNCTION soup_client_context_get_auth_domain ##### --> +<para> + +</para> + +@client: +@Returns: + + +<!-- ##### FUNCTION soup_client_context_get_auth_user ##### --> +<para> + +</para> + +@client: +@Returns: + + +<!-- ##### FUNCTION soup_server_add_auth_domain ##### --> +<para> + +</para> + +@server: +@auth_domain: + + +<!-- ##### FUNCTION soup_server_remove_auth_domain ##### --> +<para> + +</para> + +@server: +@auth_domain: + + +<!-- ##### FUNCTION soup_server_pause_message ##### --> +<para> + +</para> + +@server: +@msg: + + +<!-- ##### FUNCTION soup_server_unpause_message ##### --> +<para> + +</para> + +@server: +@msg: + + +<!-- ##### MACRO SOUP_SERVER_PORT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_INTERFACE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_SSL_CERT_FILE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_SSL_KEY_FILE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_TLS_CERTIFICATE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_ASYNC_CONTEXT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_RAW_PATHS ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_SERVER_HEADER ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_HTTP_ALIASES ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SERVER_HTTPS_ALIASES ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-session-async.sgml b/docs/reference/tmpl/soup-session-async.sgml new file mode 100644 index 00000000..84ce2d8b --- /dev/null +++ b/docs/reference/tmpl/soup-session-async.sgml @@ -0,0 +1,47 @@ +<!-- ##### SECTION Title ##### --> +SoupSessionAsync + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupSessionAsync ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION soup_session_async_new ##### --> +<para> + +</para> + +@void: +@Returns: + + +<!-- ##### FUNCTION soup_session_async_new_with_options ##### --> +<para> + +</para> + +@optname1: +@...: +@Returns: + + diff --git a/docs/reference/tmpl/soup-session-feature.sgml b/docs/reference/tmpl/soup-session-feature.sgml new file mode 100644 index 00000000..7ba9a25a --- /dev/null +++ b/docs/reference/tmpl/soup-session-feature.sgml @@ -0,0 +1,43 @@ +<!-- ##### SECTION Title ##### --> +SoupSessionFeature + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupSessionFeature ##### --> +<para> + +</para> + + +<!-- ##### STRUCT SoupSessionFeatureInterface ##### --> +<para> + +</para> + +@parent: +@attach: +@detach: +@request_queued: +@request_started: +@request_unqueued: +@add_feature: +@remove_feature: +@has_feature: + diff --git a/docs/reference/tmpl/soup-session-sync.sgml b/docs/reference/tmpl/soup-session-sync.sgml new file mode 100644 index 00000000..3f520a5a --- /dev/null +++ b/docs/reference/tmpl/soup-session-sync.sgml @@ -0,0 +1,47 @@ +<!-- ##### SECTION Title ##### --> +SoupSessionSync + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupSessionSync ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION soup_session_sync_new ##### --> +<para> + +</para> + +@void: +@Returns: + + +<!-- ##### FUNCTION soup_session_sync_new_with_options ##### --> +<para> + +</para> + +@optname1: +@...: +@Returns: + + diff --git a/docs/reference/tmpl/soup-session.sgml b/docs/reference/tmpl/soup-session.sgml new file mode 100644 index 00000000..8de079a8 --- /dev/null +++ b/docs/reference/tmpl/soup-session.sgml @@ -0,0 +1,656 @@ +<!-- ##### SECTION Title ##### --> +SoupSession + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupSession ##### --> +<para> + +</para> + + +<!-- ##### SIGNAL SoupSession::authenticate ##### --> +<para> + +</para> + +@soupsession: the object which received the signal. +@arg1: +@arg2: +@arg3: + +<!-- ##### SIGNAL SoupSession::connection-created ##### --> +<para> + +</para> + +@soupsession: the object which received the signal. +@arg1: + +<!-- ##### SIGNAL SoupSession::request-queued ##### --> +<para> + +</para> + +@soupsession: the object which received the signal. +@arg1: + +<!-- ##### SIGNAL SoupSession::request-started ##### --> +<para> + +</para> + +@soupsession: the object which received the signal. +@arg1: +@arg2: + +<!-- ##### SIGNAL SoupSession::request-unqueued ##### --> +<para> + +</para> + +@soupsession: the object which received the signal. +@arg1: + +<!-- ##### SIGNAL SoupSession::tunneling ##### --> +<para> + +</para> + +@soupsession: the object which received the signal. +@arg1: + +<!-- ##### ARG SoupSession:accept-language ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:accept-language-auto ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:add-feature ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:add-feature-by-type ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:async-context ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:http-aliases ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:https-aliases ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:idle-timeout ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:local-address ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:max-conns ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:max-conns-per-host ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:proxy-resolver ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:proxy-uri ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:remove-feature-by-type ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:ssl-ca-file ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:ssl-strict ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:ssl-use-system-ca-file ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:timeout ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:tls-database ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:use-ntlm ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:use-thread-context ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSession:user-agent ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_session_new ##### --> +<para> + +</para> + +@void: +@Returns: + + +<!-- ##### FUNCTION soup_session_new_with_options ##### --> +<para> + +</para> + +@optname1: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_session_request ##### --> +<para> + +</para> + +@session: +@uri_string: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_session_request_uri ##### --> +<para> + +</para> + +@session: +@uri: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_session_request_http ##### --> +<para> + +</para> + +@session: +@method: +@uri_string: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_session_request_http_uri ##### --> +<para> + +</para> + +@session: +@method: +@uri: +@error: +@Returns: + + +<!-- ##### ENUM SoupRequestError ##### --> +<para> + +</para> + +@SOUP_REQUEST_ERROR_BAD_URI: +@SOUP_REQUEST_ERROR_UNSUPPORTED_URI_SCHEME: +@SOUP_REQUEST_ERROR_PARSING: +@SOUP_REQUEST_ERROR_ENCODING: + +<!-- ##### MACRO SOUP_REQUEST_ERROR ##### --> +<para> + +</para> + + + +<!-- ##### USER_FUNCTION SoupSessionCallback ##### --> +<para> + +</para> + +@session: +@msg: +@user_data: + + +<!-- ##### FUNCTION soup_session_queue_message ##### --> +<para> + +</para> + +@session: +@msg: +@callback: +@user_data: + + +<!-- ##### FUNCTION soup_session_requeue_message ##### --> +<para> + +</para> + +@session: +@msg: + + +<!-- ##### FUNCTION soup_session_send_message ##### --> +<para> + +</para> + +@session: +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_session_cancel_message ##### --> +<para> + +</para> + +@session: +@msg: +@status_code: + + +<!-- ##### FUNCTION soup_session_send ##### --> +<para> + +</para> + +@session: +@msg: +@cancellable: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_session_send_async ##### --> +<para> + +</para> + +@session: +@msg: +@cancellable: +@callback: +@user_data: + + +<!-- ##### FUNCTION soup_session_send_finish ##### --> +<para> + +</para> + +@session: +@result: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_session_prefetch_dns ##### --> +<para> + +</para> + +@session: +@hostname: +@cancellable: +@callback: +@user_data: + + +<!-- ##### FUNCTION soup_session_prepare_for_uri ##### --> +<para> + +</para> + +@session: +@uri: + + +<!-- ##### FUNCTION soup_session_abort ##### --> +<para> + +</para> + +@session: + + +<!-- ##### FUNCTION soup_session_would_redirect ##### --> +<para> + +</para> + +@session: +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_session_redirect_message ##### --> +<para> + +</para> + +@session: +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_session_pause_message ##### --> +<para> + +</para> + +@session: +@msg: + + +<!-- ##### FUNCTION soup_session_unpause_message ##### --> +<para> + +</para> + +@session: +@msg: + + +<!-- ##### FUNCTION soup_session_get_async_context ##### --> +<para> + +</para> + +@session: +@Returns: + + +<!-- ##### FUNCTION soup_session_add_feature ##### --> +<para> + +</para> + +@session: +@feature: + + +<!-- ##### FUNCTION soup_session_add_feature_by_type ##### --> +<para> + +</para> + +@session: +@feature_type: + + +<!-- ##### FUNCTION soup_session_remove_feature ##### --> +<para> + +</para> + +@session: +@feature: + + +<!-- ##### FUNCTION soup_session_remove_feature_by_type ##### --> +<para> + +</para> + +@session: +@feature_type: + + +<!-- ##### FUNCTION soup_session_get_features ##### --> +<para> + +</para> + +@session: +@feature_type: +@Returns: + + +<!-- ##### FUNCTION soup_session_get_feature ##### --> +<para> + +</para> + +@session: +@feature_type: +@Returns: + + +<!-- ##### FUNCTION soup_session_get_feature_for_message ##### --> +<para> + +</para> + +@session: +@feature_type: +@msg: +@Returns: + + +<!-- ##### FUNCTION soup_session_has_feature ##### --> +<para> + +</para> + +@session: +@feature_type: +@Returns: + + +<!-- ##### MACRO SOUP_SESSION_PROXY_URI ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_PROXY_RESOLVER ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_MAX_CONNS ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_MAX_CONNS_PER_HOST ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_TLS_DATABASE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_SSL_USE_SYSTEM_CA_FILE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_SSL_CA_FILE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_SSL_STRICT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_ASYNC_CONTEXT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_USE_THREAD_CONTEXT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_TIMEOUT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_IDLE_TIMEOUT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_USER_AGENT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_ADD_FEATURE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_ADD_FEATURE_BY_TYPE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_REMOVE_FEATURE_BY_TYPE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_ACCEPT_LANGUAGE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_ACCEPT_LANGUAGE_AUTO ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_HTTP_ALIASES ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_HTTPS_ALIASES ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SESSION_LOCAL_ADDRESS ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-socket.sgml b/docs/reference/tmpl/soup-socket.sgml new file mode 100644 index 00000000..fe26d3fa --- /dev/null +++ b/docs/reference/tmpl/soup-socket.sgml @@ -0,0 +1,411 @@ +<!-- ##### SECTION Title ##### --> +SoupSocket + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupSocket ##### --> +<para> + +</para> + + +<!-- ##### SIGNAL SoupSocket::disconnected ##### --> +<para> + +</para> + +@soupsocket: the object which received the signal. + +<!-- ##### SIGNAL SoupSocket::event ##### --> +<para> + +</para> + +@soupsocket: the object which received the signal. +@arg1: +@arg2: + +<!-- ##### SIGNAL SoupSocket::new-connection ##### --> +<para> + +</para> + +@soupsocket: the object which received the signal. +@arg1: + +<!-- ##### SIGNAL SoupSocket::readable ##### --> +<para> + +</para> + +@soupsocket: the object which received the signal. + +<!-- ##### SIGNAL SoupSocket::writable ##### --> +<para> + +</para> + +@soupsocket: the object which received the signal. + +<!-- ##### ARG SoupSocket:async-context ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:clean-dispose ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:is-server ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:local-address ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:non-blocking ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:proxy-resolver ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:remote-address ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:ssl-creds ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:ssl-fallback ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:ssl-strict ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:timeout ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:tls-certificate ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:tls-errors ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:trusted-certificate ##### --> +<para> + +</para> + +<!-- ##### ARG SoupSocket:use-thread-context ##### --> +<para> + +</para> + +<!-- ##### FUNCTION soup_socket_new ##### --> +<para> + +</para> + +@optname1: +@...: +@Returns: + + +<!-- ##### USER_FUNCTION SoupSocketCallback ##### --> +<para> + +</para> + +@sock: +@status: +@user_data: + + +<!-- ##### FUNCTION soup_socket_connect_async ##### --> +<para> + +</para> + +@sock: +@cancellable: +@callback: +@user_data: + + +<!-- ##### FUNCTION soup_socket_connect_sync ##### --> +<para> + +</para> + +@sock: +@cancellable: +@Returns: + + +<!-- ##### FUNCTION soup_socket_listen ##### --> +<para> + +</para> + +@sock: +@Returns: + + +<!-- ##### FUNCTION soup_socket_start_ssl ##### --> +<para> + +</para> + +@sock: +@cancellable: +@Returns: + + +<!-- ##### FUNCTION soup_socket_start_proxy_ssl ##### --> +<para> + +</para> + +@sock: +@ssl_host: +@cancellable: +@Returns: + + +<!-- ##### FUNCTION soup_socket_is_ssl ##### --> +<para> + +</para> + +@sock: +@Returns: + + +<!-- ##### FUNCTION soup_socket_disconnect ##### --> +<para> + +</para> + +@sock: + + +<!-- ##### FUNCTION soup_socket_is_connected ##### --> +<para> + +</para> + +@sock: +@Returns: + + +<!-- ##### FUNCTION soup_socket_get_local_address ##### --> +<para> + +</para> + +@sock: +@Returns: + + +<!-- ##### FUNCTION soup_socket_get_remote_address ##### --> +<para> + +</para> + +@sock: +@Returns: + + +<!-- ##### FUNCTION soup_socket_get_fd ##### --> +<para> + +</para> + +@sock: +@Returns: + + +<!-- ##### ENUM SoupSocketIOStatus ##### --> +<para> + +</para> + +@SOUP_SOCKET_OK: +@SOUP_SOCKET_WOULD_BLOCK: +@SOUP_SOCKET_EOF: +@SOUP_SOCKET_ERROR: + +<!-- ##### FUNCTION soup_socket_read ##### --> +<para> + +</para> + +@sock: +@buffer: +@len: +@nread: +@cancellable: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_socket_read_until ##### --> +<para> + +</para> + +@sock: +@buffer: +@len: +@boundary: +@boundary_len: +@nread: +@got_boundary: +@cancellable: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_socket_write ##### --> +<para> + +</para> + +@sock: +@buffer: +@len: +@nwrote: +@cancellable: +@error: +@Returns: + + +<!-- ##### MACRO SOUP_SOCKET_LOCAL_ADDRESS ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_REMOTE_ADDRESS ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_FLAG_NONBLOCKING ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_IS_SERVER ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_SSL_CREDENTIALS ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_ASYNC_CONTEXT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_TIMEOUT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_SSL_FALLBACK ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_SSL_STRICT ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_TLS_CERTIFICATE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_TLS_ERRORS ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_TRUSTED_CERTIFICATE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_SOCKET_USE_THREAD_CONTEXT ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-status.sgml b/docs/reference/tmpl/soup-status.sgml new file mode 100644 index 00000000..38fe6ba6 --- /dev/null +++ b/docs/reference/tmpl/soup-status.sgml @@ -0,0 +1,164 @@ +<!-- ##### SECTION Title ##### --> +soup-status + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### MACRO SOUP_STATUS_IS_TRANSPORT_ERROR ##### --> +<para> + +</para> + +@status: + + +<!-- ##### MACRO SOUP_STATUS_IS_INFORMATIONAL ##### --> +<para> + +</para> + +@status: + + +<!-- ##### MACRO SOUP_STATUS_IS_SUCCESSFUL ##### --> +<para> + +</para> + +@status: + + +<!-- ##### MACRO SOUP_STATUS_IS_REDIRECTION ##### --> +<para> + +</para> + +@status: + + +<!-- ##### MACRO SOUP_STATUS_IS_CLIENT_ERROR ##### --> +<para> + +</para> + +@status: + + +<!-- ##### MACRO SOUP_STATUS_IS_SERVER_ERROR ##### --> +<para> + +</para> + +@status: + + +<!-- ##### ENUM SoupStatus ##### --> +<para> + +</para> + +@SOUP_STATUS_NONE: +@SOUP_STATUS_CANCELLED: +@SOUP_STATUS_CANT_RESOLVE: +@SOUP_STATUS_CANT_RESOLVE_PROXY: +@SOUP_STATUS_CANT_CONNECT: +@SOUP_STATUS_CANT_CONNECT_PROXY: +@SOUP_STATUS_SSL_FAILED: +@SOUP_STATUS_IO_ERROR: +@SOUP_STATUS_MALFORMED: +@SOUP_STATUS_TRY_AGAIN: +@SOUP_STATUS_TOO_MANY_REDIRECTS: +@SOUP_STATUS_TLS_FAILED: +@SOUP_STATUS_CONTINUE: +@SOUP_STATUS_SWITCHING_PROTOCOLS: +@SOUP_STATUS_PROCESSING: +@SOUP_STATUS_OK: +@SOUP_STATUS_CREATED: +@SOUP_STATUS_ACCEPTED: +@SOUP_STATUS_NON_AUTHORITATIVE: +@SOUP_STATUS_NO_CONTENT: +@SOUP_STATUS_RESET_CONTENT: +@SOUP_STATUS_PARTIAL_CONTENT: +@SOUP_STATUS_MULTI_STATUS: +@SOUP_STATUS_MULTIPLE_CHOICES: +@SOUP_STATUS_MOVED_PERMANENTLY: +@SOUP_STATUS_FOUND: +@SOUP_STATUS_MOVED_TEMPORARILY: +@SOUP_STATUS_SEE_OTHER: +@SOUP_STATUS_NOT_MODIFIED: +@SOUP_STATUS_USE_PROXY: +@SOUP_STATUS_NOT_APPEARING_IN_THIS_PROTOCOL: +@SOUP_STATUS_TEMPORARY_REDIRECT: +@SOUP_STATUS_BAD_REQUEST: +@SOUP_STATUS_UNAUTHORIZED: +@SOUP_STATUS_PAYMENT_REQUIRED: +@SOUP_STATUS_FORBIDDEN: +@SOUP_STATUS_NOT_FOUND: +@SOUP_STATUS_METHOD_NOT_ALLOWED: +@SOUP_STATUS_NOT_ACCEPTABLE: +@SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED: +@SOUP_STATUS_PROXY_UNAUTHORIZED: +@SOUP_STATUS_REQUEST_TIMEOUT: +@SOUP_STATUS_CONFLICT: +@SOUP_STATUS_GONE: +@SOUP_STATUS_LENGTH_REQUIRED: +@SOUP_STATUS_PRECONDITION_FAILED: +@SOUP_STATUS_REQUEST_ENTITY_TOO_LARGE: +@SOUP_STATUS_REQUEST_URI_TOO_LONG: +@SOUP_STATUS_UNSUPPORTED_MEDIA_TYPE: +@SOUP_STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: +@SOUP_STATUS_INVALID_RANGE: +@SOUP_STATUS_EXPECTATION_FAILED: +@SOUP_STATUS_UNPROCESSABLE_ENTITY: +@SOUP_STATUS_LOCKED: +@SOUP_STATUS_FAILED_DEPENDENCY: +@SOUP_STATUS_INTERNAL_SERVER_ERROR: +@SOUP_STATUS_NOT_IMPLEMENTED: +@SOUP_STATUS_BAD_GATEWAY: +@SOUP_STATUS_SERVICE_UNAVAILABLE: +@SOUP_STATUS_GATEWAY_TIMEOUT: +@SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED: +@SOUP_STATUS_INSUFFICIENT_STORAGE: +@SOUP_STATUS_NOT_EXTENDED: + +<!-- ##### FUNCTION soup_status_get_phrase ##### --> +<para> + +</para> + +@status_code: +@Returns: + + +<!-- ##### FUNCTION soup_status_proxify ##### --> +<para> + +</para> + +@status_code: +@Returns: + + +<!-- ##### MACRO SOUP_HTTP_ERROR ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-tld.sgml b/docs/reference/tmpl/soup-tld.sgml new file mode 100644 index 00000000..cebe2e7d --- /dev/null +++ b/docs/reference/tmpl/soup-tld.sgml @@ -0,0 +1,58 @@ +<!-- ##### SECTION Title ##### --> +Top Level Domain utils + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### FUNCTION soup_tld_get_base_domain ##### --> +<para> + +</para> + +@hostname: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_tld_domain_is_public_suffix ##### --> +<para> + +</para> + +@domain: +@Returns: + + +<!-- ##### MACRO SOUP_TLD_ERROR ##### --> +<para> + +</para> + + + +<!-- ##### ENUM SoupTLDError ##### --> +<para> + +</para> + +@SOUP_TLD_ERROR_INVALID_HOSTNAME: +@SOUP_TLD_ERROR_IS_IP_ADDRESS: +@SOUP_TLD_ERROR_NOT_ENOUGH_DOMAINS: +@SOUP_TLD_ERROR_NO_BASE_DOMAIN: + diff --git a/docs/reference/tmpl/soup-uri.sgml b/docs/reference/tmpl/soup-uri.sgml new file mode 100644 index 00000000..64d5c92e --- /dev/null +++ b/docs/reference/tmpl/soup-uri.sgml @@ -0,0 +1,371 @@ +<!-- ##### SECTION Title ##### --> +SoupURI + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SoupURI ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION soup_uri_new_with_base ##### --> +<para> + +</para> + +@base: +@uri_string: +@Returns: + + +<!-- ##### FUNCTION soup_uri_new ##### --> +<para> + +</para> + +@uri_string: +@Returns: + + +<!-- ##### FUNCTION soup_uri_to_string ##### --> +<para> + +</para> + +@uri: +@just_path_and_query: +@Returns: + + +<!-- ##### FUNCTION soup_uri_copy ##### --> +<para> + +</para> + +@uri: +@Returns: + + +<!-- ##### FUNCTION soup_uri_copy_host ##### --> +<para> + +</para> + +@uri: +@Returns: + + +<!-- ##### FUNCTION soup_uri_equal ##### --> +<para> + +</para> + +@uri1: +@uri2: +@Returns: + + +<!-- ##### FUNCTION soup_uri_host_equal ##### --> +<para> + +</para> + +@v1: +@v2: +@Returns: + + +<!-- ##### FUNCTION soup_uri_host_hash ##### --> +<para> + +</para> + +@key: +@Returns: + + +<!-- ##### FUNCTION soup_uri_free ##### --> +<para> + +</para> + +@uri: + + +<!-- ##### FUNCTION soup_uri_encode ##### --> +<para> + +</para> + +@part: +@escape_extra: +@Returns: + + +<!-- ##### FUNCTION soup_uri_decode ##### --> +<para> + +</para> + +@part: +@Returns: + + +<!-- ##### FUNCTION soup_uri_normalize ##### --> +<para> + +</para> + +@part: +@unescape_extra: +@Returns: + + +<!-- ##### MACRO SOUP_URI_SCHEME_HTTP ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_URI_SCHEME_HTTPS ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_URI_SCHEME_DATA ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_URI_SCHEME_FILE ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_URI_SCHEME_FTP ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_URI_SCHEME_RESOURCE ##### --> +<para> + +</para> + + + +<!-- ##### FUNCTION soup_uri_uses_default_port ##### --> +<para> + +</para> + +@uri: +@Returns: + + +<!-- ##### MACRO SOUP_URI_IS_VALID ##### --> +<para> + +</para> + +@uri: + + +<!-- ##### MACRO SOUP_URI_VALID_FOR_HTTP ##### --> +<para> + +</para> + +@uri: + + +<!-- ##### FUNCTION soup_uri_set_scheme ##### --> +<para> + +</para> + +@uri: +@scheme: + + +<!-- ##### FUNCTION soup_uri_get_scheme ##### --> +<para> + +</para> + +@uri: +@Returns: + + +<!-- ##### FUNCTION soup_uri_set_user ##### --> +<para> + +</para> + +@uri: +@user: + + +<!-- ##### FUNCTION soup_uri_get_user ##### --> +<para> + +</para> + +@uri: +@Returns: + + +<!-- ##### FUNCTION soup_uri_set_password ##### --> +<para> + +</para> + +@uri: +@password: + + +<!-- ##### FUNCTION soup_uri_get_password ##### --> +<para> + +</para> + +@uri: +@Returns: + + +<!-- ##### FUNCTION soup_uri_set_host ##### --> +<para> + +</para> + +@uri: +@host: + + +<!-- ##### FUNCTION soup_uri_get_host ##### --> +<para> + +</para> + +@uri: +@Returns: + + +<!-- ##### FUNCTION soup_uri_set_port ##### --> +<para> + +</para> + +@uri: +@port: + + +<!-- ##### FUNCTION soup_uri_get_port ##### --> +<para> + +</para> + +@uri: +@Returns: + + +<!-- ##### FUNCTION soup_uri_set_path ##### --> +<para> + +</para> + +@uri: +@path: + + +<!-- ##### FUNCTION soup_uri_get_path ##### --> +<para> + +</para> + +@uri: +@Returns: + + +<!-- ##### FUNCTION soup_uri_set_query ##### --> +<para> + +</para> + +@uri: +@query: + + +<!-- ##### FUNCTION soup_uri_set_query_from_form ##### --> +<para> + +</para> + +@uri: +@form: + + +<!-- ##### FUNCTION soup_uri_set_query_from_fields ##### --> +<para> + +</para> + +@uri: +@first_field: +@...: + + +<!-- ##### FUNCTION soup_uri_get_query ##### --> +<para> + +</para> + +@uri: +@Returns: + + +<!-- ##### FUNCTION soup_uri_set_fragment ##### --> +<para> + +</para> + +@uri: +@fragment: + + +<!-- ##### FUNCTION soup_uri_get_fragment ##### --> +<para> + +</para> + +@uri: +@Returns: + + diff --git a/docs/reference/tmpl/soup-value-utils.sgml b/docs/reference/tmpl/soup-value-utils.sgml new file mode 100644 index 00000000..aa70d0e2 --- /dev/null +++ b/docs/reference/tmpl/soup-value-utils.sgml @@ -0,0 +1,203 @@ +<!-- ##### SECTION Title ##### --> +GValue Support + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### FUNCTION soup_value_hash_new ##### --> +<para> + +</para> + +@void: +@Returns: + + +<!-- ##### FUNCTION soup_value_hash_new_with_vals ##### --> +<para> + +</para> + +@first_key: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_value_hash_insert_value ##### --> +<para> + +</para> + +@hash: +@key: +@value: + + +<!-- ##### FUNCTION soup_value_hash_insert ##### --> +<para> + +</para> + +@hash: +@key: +@type: +@...: + + +<!-- ##### FUNCTION soup_value_hash_insert_vals ##### --> +<para> + +</para> + +@hash: +@first_key: +@...: + + +<!-- ##### FUNCTION soup_value_hash_lookup ##### --> +<para> + +</para> + +@hash: +@key: +@type: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_value_hash_lookup_vals ##### --> +<para> + +</para> + +@hash: +@first_key: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_value_array_from_args ##### --> +<para> + +</para> + +@args: +@Returns: + + +<!-- ##### FUNCTION soup_value_array_to_args ##### --> +<para> + +</para> + +@array: +@args: +@Returns: + + +<!-- ##### FUNCTION soup_value_array_new ##### --> +<para> + +</para> + +@void: +@Returns: + + +<!-- ##### FUNCTION soup_value_array_new_with_vals ##### --> +<para> + +</para> + +@first_type: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_value_array_insert ##### --> +<para> + +</para> + +@array: +@index_: +@type: +@...: + + +<!-- ##### FUNCTION soup_value_array_append ##### --> +<para> + +</para> + +@array: +@type: +@...: + + +<!-- ##### FUNCTION soup_value_array_append_vals ##### --> +<para> + +</para> + +@array: +@first_type: +@...: + + +<!-- ##### FUNCTION soup_value_array_get_nth ##### --> +<para> + +</para> + +@array: +@index_: +@type: +@...: +@Returns: + + +<!-- ##### MACRO SOUP_VALUE_SETV ##### --> +<para> + +</para> + +@val: +@type: +@args: + + +<!-- ##### MACRO SOUP_VALUE_GETV ##### --> +<para> + +</para> + +@val: +@type: +@args: + + +<!-- ##### MACRO SOUP_TYPE_BYTE_ARRAY ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-version.sgml b/docs/reference/tmpl/soup-version.sgml new file mode 100644 index 00000000..d7e2847b --- /dev/null +++ b/docs/reference/tmpl/soup-version.sgml @@ -0,0 +1,189 @@ +<!-- ##### SECTION Title ##### --> +Version Information + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### FUNCTION soup_get_major_version ##### --> +<para> + +</para> + +@void: +@Returns: + + +<!-- ##### FUNCTION soup_get_minor_version ##### --> +<para> + +</para> + +@void: +@Returns: + + +<!-- ##### FUNCTION soup_get_micro_version ##### --> +<para> + +</para> + +@void: +@Returns: + + +<!-- ##### FUNCTION soup_check_version ##### --> +<para> + +</para> + +@major: +@minor: +@micro: +@Returns: + + +<!-- ##### MACRO SOUP_MAJOR_VERSION ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MINOR_VERSION ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_MICRO_VERSION ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_CHECK_VERSION ##### --> +<para> + +</para> + +@major: +@minor: +@micro: + + +<!-- ##### MACRO SOUP_VERSION_MIN_REQUIRED ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_MAX_ALLOWED ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_24 ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_26 ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_28 ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_30 ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_32 ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_34 ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_36 ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_38 ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_40 ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_42 ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_44 ##### --> +<para> + +</para> + + + +<!-- ##### MACRO SOUP_VERSION_2_46 ##### --> +<para> + +</para> + + + diff --git a/docs/reference/tmpl/soup-xmlrpc.sgml b/docs/reference/tmpl/soup-xmlrpc.sgml new file mode 100644 index 00000000..4a5e7e9f --- /dev/null +++ b/docs/reference/tmpl/soup-xmlrpc.sgml @@ -0,0 +1,157 @@ +<!-- ##### SECTION Title ##### --> +XMLRPC Support + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### FUNCTION soup_xmlrpc_build_method_call ##### --> +<para> + +</para> + +@method_name: +@params: +@n_params: +@Returns: + + +<!-- ##### FUNCTION soup_xmlrpc_request_new ##### --> +<para> + +</para> + +@uri: +@method_name: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_xmlrpc_parse_method_response ##### --> +<para> + +</para> + +@method_response: +@length: +@value: +@error: +@Returns: + + +<!-- ##### FUNCTION soup_xmlrpc_extract_method_response ##### --> +<para> + +</para> + +@method_response: +@length: +@error: +@type: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_xmlrpc_parse_method_call ##### --> +<para> + +</para> + +@method_call: +@length: +@method_name: +@params: +@Returns: + + +<!-- ##### FUNCTION soup_xmlrpc_extract_method_call ##### --> +<para> + +</para> + +@method_call: +@length: +@method_name: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_xmlrpc_build_method_response ##### --> +<para> + +</para> + +@value: +@Returns: + + +<!-- ##### FUNCTION soup_xmlrpc_build_fault ##### --> +<para> + +</para> + +@fault_code: +@fault_format: +@...: +@Returns: + + +<!-- ##### FUNCTION soup_xmlrpc_set_response ##### --> +<para> + +</para> + +@msg: +@type: +@...: + + +<!-- ##### FUNCTION soup_xmlrpc_set_fault ##### --> +<para> + +</para> + +@msg: +@fault_code: +@fault_format: +@...: + + +<!-- ##### MACRO SOUP_XMLRPC_FAULT ##### --> +<para> + +</para> + + + +<!-- ##### ENUM SoupXMLRPCFault ##### --> +<para> + +</para> + +@SOUP_XMLRPC_FAULT_PARSE_ERROR_NOT_WELL_FORMED: +@SOUP_XMLRPC_FAULT_PARSE_ERROR_UNSUPPORTED_ENCODING: +@SOUP_XMLRPC_FAULT_PARSE_ERROR_INVALID_CHARACTER_FOR_ENCODING: +@SOUP_XMLRPC_FAULT_SERVER_ERROR_INVALID_XML_RPC: +@SOUP_XMLRPC_FAULT_SERVER_ERROR_REQUESTED_METHOD_NOT_FOUND: +@SOUP_XMLRPC_FAULT_SERVER_ERROR_INVALID_METHOD_PARAMETERS: +@SOUP_XMLRPC_FAULT_SERVER_ERROR_INTERNAL_XML_RPC_ERROR: +@SOUP_XMLRPC_FAULT_APPLICATION_ERROR: +@SOUP_XMLRPC_FAULT_SYSTEM_ERROR: +@SOUP_XMLRPC_FAULT_TRANSPORT_ERROR: + diff --git a/docs/specs/README b/docs/specs/README deleted file mode 100644 index 0dee62d0..00000000 --- a/docs/specs/README +++ /dev/null @@ -1,13 +0,0 @@ -rfc1945 - HTTP/1.0 -rfc2068 - HTTP/1.1 (mostly obsoleted original specification) -rfc2109 - HTTP State Management Mechanism -rfc2145 - Use and Interpretation of HTTP Version Numbers -rfc2324 - Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0) -rfc2388 - Returning Values from Forms: multipart/form-data -rfc2518 - HTTP Extensions for Distributed Authoring -- WEBDAV -rfc2616 - HTTP/1.1 (revised) [plus errata] -rfc2617 - HTTP Authentication: Basic and Digest Access Authentication [plus errata] -rfc2817 - Upgrading to TLS Within HTTP/1.1 -rfc2818 - HTTP Over TLS -rfc2965 - HTTP State Management Mechanism (allegedly obsoletes 2109) -rfc3986 - Uniform Resource Identifiers (URI): Generic Syntax diff --git a/docs/specs/rfc1945.txt b/docs/specs/rfc1945.txt deleted file mode 100644 index 37f3f23c..00000000 --- a/docs/specs/rfc1945.txt +++ /dev/null @@ -1,3363 +0,0 @@ - - - - - - -Network Working Group T. Berners-Lee -Request for Comments: 1945 MIT/LCS -Category: Informational R. Fielding - UC Irvine - H. Frystyk - MIT/LCS - May 1996 - - - Hypertext Transfer Protocol -- HTTP/1.0 - -Status of This Memo - - This memo provides information for the Internet community. This memo - does not specify an Internet standard of any kind. Distribution of - this memo is unlimited. - -IESG Note: - - The IESG has concerns about this protocol, and expects this document - to be replaced relatively soon by a standards track document. - -Abstract - - The Hypertext Transfer Protocol (HTTP) is an application-level - protocol with the lightness and speed necessary for distributed, - collaborative, hypermedia information systems. It is a generic, - stateless, object-oriented protocol which can be used for many tasks, - such as name servers and distributed object management systems, - through extension of its request methods (commands). A feature of - HTTP is the typing of data representation, allowing systems to be - built independently of the data being transferred. - - HTTP has been in use by the World-Wide Web global information - initiative since 1990. This specification reflects common usage of - the protocol referred to as "HTTP/1.0". - -Table of Contents - - 1. Introduction .............................................. 4 - 1.1 Purpose .............................................. 4 - 1.2 Terminology .......................................... 4 - 1.3 Overall Operation .................................... 6 - 1.4 HTTP and MIME ........................................ 8 - 2. Notational Conventions and Generic Grammar ................ 8 - 2.1 Augmented BNF ........................................ 8 - 2.2 Basic Rules .......................................... 10 - 3. Protocol Parameters ....................................... 12 - - - -Berners-Lee, et al Informational [Page 1] - -RFC 1945 HTTP/1.0 May 1996 - - - 3.1 HTTP Version ......................................... 12 - 3.2 Uniform Resource Identifiers ......................... 14 - 3.2.1 General Syntax ................................ 14 - 3.2.2 http URL ...................................... 15 - 3.3 Date/Time Formats .................................... 15 - 3.4 Character Sets ....................................... 17 - 3.5 Content Codings ...................................... 18 - 3.6 Media Types .......................................... 19 - 3.6.1 Canonicalization and Text Defaults ............ 19 - 3.6.2 Multipart Types ............................... 20 - 3.7 Product Tokens ....................................... 20 - 4. HTTP Message .............................................. 21 - 4.1 Message Types ........................................ 21 - 4.2 Message Headers ...................................... 22 - 4.3 General Header Fields ................................ 23 - 5. Request ................................................... 23 - 5.1 Request-Line ......................................... 23 - 5.1.1 Method ........................................ 24 - 5.1.2 Request-URI ................................... 24 - 5.2 Request Header Fields ................................ 25 - 6. Response .................................................. 25 - 6.1 Status-Line .......................................... 26 - 6.1.1 Status Code and Reason Phrase ................. 26 - 6.2 Response Header Fields ............................... 28 - 7. Entity .................................................... 28 - 7.1 Entity Header Fields ................................. 29 - 7.2 Entity Body .......................................... 29 - 7.2.1 Type .......................................... 29 - 7.2.2 Length ........................................ 30 - 8. Method Definitions ........................................ 30 - 8.1 GET .................................................. 31 - 8.2 HEAD ................................................. 31 - 8.3 POST ................................................. 31 - 9. Status Code Definitions ................................... 32 - 9.1 Informational 1xx .................................... 32 - 9.2 Successful 2xx ....................................... 32 - 9.3 Redirection 3xx ...................................... 34 - 9.4 Client Error 4xx ..................................... 35 - 9.5 Server Error 5xx ..................................... 37 - 10. Header Field Definitions .................................. 37 - 10.1 Allow ............................................... 38 - 10.2 Authorization ....................................... 38 - 10.3 Content-Encoding .................................... 39 - 10.4 Content-Length ...................................... 39 - 10.5 Content-Type ........................................ 40 - 10.6 Date ................................................ 40 - 10.7 Expires ............................................. 41 - 10.8 From ................................................ 42 - - - -Berners-Lee, et al Informational [Page 2] - -RFC 1945 HTTP/1.0 May 1996 - - - 10.9 If-Modified-Since ................................... 42 - 10.10 Last-Modified ....................................... 43 - 10.11 Location ............................................ 44 - 10.12 Pragma .............................................. 44 - 10.13 Referer ............................................. 44 - 10.14 Server .............................................. 45 - 10.15 User-Agent .......................................... 46 - 10.16 WWW-Authenticate .................................... 46 - 11. Access Authentication ..................................... 47 - 11.1 Basic Authentication Scheme ......................... 48 - 12. Security Considerations ................................... 49 - 12.1 Authentication of Clients ........................... 49 - 12.2 Safe Methods ........................................ 49 - 12.3 Abuse of Server Log Information ..................... 50 - 12.4 Transfer of Sensitive Information ................... 50 - 12.5 Attacks Based On File and Path Names ................ 51 - 13. Acknowledgments ........................................... 51 - 14. References ................................................ 52 - 15. Authors' Addresses ........................................ 54 - Appendix A. Internet Media Type message/http ................ 55 - Appendix B. Tolerant Applications ........................... 55 - Appendix C. Relationship to MIME ............................ 56 - C.1 Conversion to Canonical Form ......................... 56 - C.2 Conversion of Date Formats ........................... 57 - C.3 Introduction of Content-Encoding ..................... 57 - C.4 No Content-Transfer-Encoding ......................... 57 - C.5 HTTP Header Fields in Multipart Body-Parts ........... 57 - Appendix D. Additional Features ............................. 57 - D.1 Additional Request Methods ........................... 58 - D.1.1 PUT ........................................... 58 - D.1.2 DELETE ........................................ 58 - D.1.3 LINK .......................................... 58 - D.1.4 UNLINK ........................................ 58 - D.2 Additional Header Field Definitions .................. 58 - D.2.1 Accept ........................................ 58 - D.2.2 Accept-Charset ................................ 59 - D.2.3 Accept-Encoding ............................... 59 - D.2.4 Accept-Language ............................... 59 - D.2.5 Content-Language .............................. 59 - D.2.6 Link .......................................... 59 - D.2.7 MIME-Version .................................. 59 - D.2.8 Retry-After ................................... 60 - D.2.9 Title ......................................... 60 - D.2.10 URI ........................................... 60 - - - - - - - -Berners-Lee, et al Informational [Page 3] - -RFC 1945 HTTP/1.0 May 1996 - - -1. Introduction - -1.1 Purpose - - The Hypertext Transfer Protocol (HTTP) is an application-level - protocol with the lightness and speed necessary for distributed, - collaborative, hypermedia information systems. HTTP has been in use - by the World-Wide Web global information initiative since 1990. This - specification reflects common usage of the protocol referred too as - "HTTP/1.0". This specification describes the features that seem to be - consistently implemented in most HTTP/1.0 clients and servers. The - specification is split into two sections. Those features of HTTP for - which implementations are usually consistent are described in the - main body of this document. Those features which have few or - inconsistent implementations are listed in Appendix D. - - Practical information systems require more functionality than simple - retrieval, including search, front-end update, and annotation. HTTP - allows an open-ended set of methods to be used to indicate the - purpose of a request. It builds on the discipline of reference - provided by the Uniform Resource Identifier (URI) [2], as a location - (URL) [4] or name (URN) [16], for indicating the resource on which a - method is to be applied. Messages are passed in a format similar to - that used by Internet Mail [7] and the Multipurpose Internet Mail - Extensions (MIME) [5]. - - HTTP is also used as a generic protocol for communication between - user agents and proxies/gateways to other Internet protocols, such as - SMTP [12], NNTP [11], FTP [14], Gopher [1], and WAIS [8], allowing - basic hypermedia access to resources available from diverse - applications and simplifying the implementation of user agents. - -1.2 Terminology - - This specification uses a number of terms to refer to the roles - played by participants in, and objects of, the HTTP communication. - - connection - - A transport layer virtual circuit established between two - application programs for the purpose of communication. - - message - - The basic unit of HTTP communication, consisting of a structured - sequence of octets matching the syntax defined in Section 4 and - transmitted via the connection. - - - - -Berners-Lee, et al Informational [Page 4] - -RFC 1945 HTTP/1.0 May 1996 - - - request - - An HTTP request message (as defined in Section 5). - - response - - An HTTP response message (as defined in Section 6). - - resource - - A network data object or service which can be identified by a - URI (Section 3.2). - - entity - - A particular representation or rendition of a data resource, or - reply from a service resource, that may be enclosed within a - request or response message. An entity consists of - metainformation in the form of entity headers and content in the - form of an entity body. - - client - - An application program that establishes connections for the - purpose of sending requests. - - user agent - - The client which initiates a request. These are often browsers, - editors, spiders (web-traversing robots), or other end user - tools. - - server - - An application program that accepts connections in order to - service requests by sending back responses. - - origin server - - The server on which a given resource resides or is to be created. - - proxy - - An intermediary program which acts as both a server and a client - for the purpose of making requests on behalf of other clients. - Requests are serviced internally or by passing them, with - possible translation, on to other servers. A proxy must - interpret and, if necessary, rewrite a request message before - - - -Berners-Lee, et al Informational [Page 5] - -RFC 1945 HTTP/1.0 May 1996 - - - forwarding it. Proxies are often used as client-side portals - through network firewalls and as helper applications for - handling requests via protocols not implemented by the user - agent. - - gateway - - A server which acts as an intermediary for some other server. - Unlike a proxy, a gateway receives requests as if it were the - origin server for the requested resource; the requesting client - may not be aware that it is communicating with a gateway. - Gateways are often used as server-side portals through network - firewalls and as protocol translators for access to resources - stored on non-HTTP systems. - - tunnel - - A tunnel is an intermediary program which is acting as a blind - relay between two connections. Once active, a tunnel is not - considered a party to the HTTP communication, though the tunnel - may have been initiated by an HTTP request. The tunnel ceases to - exist when both ends of the relayed connections are closed. - Tunnels are used when a portal is necessary and the intermediary - cannot, or should not, interpret the relayed communication. - - cache - - A program's local store of response messages and the subsystem - that controls its message storage, retrieval, and deletion. A - cache stores cachable responses in order to reduce the response - time and network bandwidth consumption on future, equivalent - requests. Any client or server may include a cache, though a - cache cannot be used by a server while it is acting as a tunnel. - - Any given program may be capable of being both a client and a server; - our use of these terms refers only to the role being performed by the - program for a particular connection, rather than to the program's - capabilities in general. Likewise, any server may act as an origin - server, proxy, gateway, or tunnel, switching behavior based on the - nature of each request. - -1.3 Overall Operation - - The HTTP protocol is based on a request/response paradigm. A client - establishes a connection with a server and sends a request to the - server in the form of a request method, URI, and protocol version, - followed by a MIME-like message containing request modifiers, client - information, and possible body content. The server responds with a - - - -Berners-Lee, et al Informational [Page 6] - -RFC 1945 HTTP/1.0 May 1996 - - - status line, including the message's protocol version and a success - or error code, followed by a MIME-like message containing server - information, entity metainformation, and possible body content. - - Most HTTP communication is initiated by a user agent and consists of - a request to be applied to a resource on some origin server. In the - simplest case, this may be accomplished via a single connection (v) - between the user agent (UA) and the origin server (O). - - request chain ------------------------> - UA -------------------v------------------- O - <----------------------- response chain - - A more complicated situation occurs when one or more intermediaries - are present in the request/response chain. There are three common - forms of intermediary: proxy, gateway, and tunnel. A proxy is a - forwarding agent, receiving requests for a URI in its absolute form, - rewriting all or parts of the message, and forwarding the reformatted - request toward the server identified by the URI. A gateway is a - receiving agent, acting as a layer above some other server(s) and, if - necessary, translating the requests to the underlying server's - protocol. A tunnel acts as a relay point between two connections - without changing the messages; tunnels are used when the - communication needs to pass through an intermediary (such as a - firewall) even when the intermediary cannot understand the contents - of the messages. - - request chain --------------------------------------> - UA -----v----- A -----v----- B -----v----- C -----v----- O - <------------------------------------- response chain - - The figure above shows three intermediaries (A, B, and C) between the - user agent and origin server. A request or response message that - travels the whole chain must pass through four separate connections. - This distinction is important because some HTTP communication options - may apply only to the connection with the nearest, non-tunnel - neighbor, only to the end-points of the chain, or to all connections - along the chain. Although the diagram is linear, each participant may - be engaged in multiple, simultaneous communications. For example, B - may be receiving requests from many clients other than A, and/or - forwarding requests to servers other than C, at the same time that it - is handling A's request. - - Any party to the communication which is not acting as a tunnel may - employ an internal cache for handling requests. The effect of a cache - is that the request/response chain is shortened if one of the - participants along the chain has a cached response applicable to that - request. The following illustrates the resulting chain if B has a - - - -Berners-Lee, et al Informational [Page 7] - -RFC 1945 HTTP/1.0 May 1996 - - - cached copy of an earlier response from O (via C) for a request which - has not been cached by UA or A. - - request chain ----------> - UA -----v----- A -----v----- B - - - - - - C - - - - - - O - <--------- response chain - - Not all responses are cachable, and some requests may contain - modifiers which place special requirements on cache behavior. Some - HTTP/1.0 applications use heuristics to describe what is or is not a - "cachable" response, but these rules are not standardized. - - On the Internet, HTTP communication generally takes place over TCP/IP - connections. The default port is TCP 80 [15], but other ports can be - used. This does not preclude HTTP from being implemented on top of - any other protocol on the Internet, or on other networks. HTTP only - presumes a reliable transport; any protocol that provides such - guarantees can be used, and the mapping of the HTTP/1.0 request and - response structures onto the transport data units of the protocol in - question is outside the scope of this specification. - - Except for experimental applications, current practice requires that - the connection be established by the client prior to each request and - closed by the server after sending the response. Both clients and - servers should be aware that either party may close the connection - prematurely, due to user action, automated time-out, or program - failure, and should handle such closing in a predictable fashion. In - any case, the closing of the connection by either or both parties - always terminates the current request, regardless of its status. - -1.4 HTTP and MIME - - HTTP/1.0 uses many of the constructs defined for MIME, as defined in - RFC 1521 [5]. Appendix C describes the ways in which the context of - HTTP allows for different use of Internet Media Types than is - typically found in Internet mail, and gives the rationale for those - differences. - -2. Notational Conventions and Generic Grammar - -2.1 Augmented BNF - - All of the mechanisms specified in this document are described in - both prose and an augmented Backus-Naur Form (BNF) similar to that - used by RFC 822 [7]. Implementors will need to be familiar with the - notation in order to understand this specification. The augmented BNF - includes the following constructs: - - - - -Berners-Lee, et al Informational [Page 8] - -RFC 1945 HTTP/1.0 May 1996 - - - name = definition - - The name of a rule is simply the name itself (without any - enclosing "<" and ">") and is separated from its definition by - the equal character "=". Whitespace is only significant in that - indentation of continuation lines is used to indicate a rule - definition that spans more than one line. Certain basic rules - are in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. - Angle brackets are used within definitions whenever their - presence will facilitate discerning the use of rule names. - - "literal" - - Quotation marks surround literal text. Unless stated otherwise, - the text is case-insensitive. - - rule1 | rule2 - - Elements separated by a bar ("I") are alternatives, - e.g., "yes | no" will accept yes or no. - - (rule1 rule2) - - Elements enclosed in parentheses are treated as a single - element. Thus, "(elem (foo | bar) elem)" allows the token - sequences "elem foo elem" and "elem bar elem". - - *rule - - The character "*" preceding an element indicates repetition. The - full form is "<n>*<m>element" indicating at least <n> and at - most <m> occurrences of element. Default values are 0 and - infinity so that "*(element)" allows any number, including zero; - "1*element" requires at least one; and "1*2element" allows one - or two. - - [rule] - - Square brackets enclose optional elements; "[foo bar]" is - equivalent to "*1(foo bar)". - - N rule - - Specific repetition: "<n>(element)" is equivalent to - "<n>*<n>(element)"; that is, exactly <n> occurrences of - (element). Thus 2DIGIT is a 2-digit number, and 3ALPHA is a - string of three alphabetic characters. - - - - -Berners-Lee, et al Informational [Page 9] - -RFC 1945 HTTP/1.0 May 1996 - - - #rule - - A construct "#" is defined, similar to "*", for defining lists - of elements. The full form is "<n>#<m>element" indicating at - least <n> and at most <m> elements, each separated by one or - more commas (",") and optional linear whitespace (LWS). This - makes the usual form of lists very easy; a rule such as - "( *LWS element *( *LWS "," *LWS element ))" can be shown as - "1#element". Wherever this construct is used, null elements are - allowed, but do not contribute to the count of elements present. - That is, "(element), , (element)" is permitted, but counts as - only two elements. Therefore, where at least one element is - required, at least one non-null element must be present. Default - values are 0 and infinity so that "#(element)" allows any - number, including zero; "1#element" requires at least one; and - "1#2element" allows one or two. - - ; comment - - A semi-colon, set off some distance to the right of rule text, - starts a comment that continues to the end of line. This is a - simple way of including useful notes in parallel with the - specifications. - - implied *LWS - - The grammar described by this specification is word-based. - Except where noted otherwise, linear whitespace (LWS) can be - included between any two adjacent words (token or - quoted-string), and between adjacent tokens and delimiters - (tspecials), without changing the interpretation of a field. At - least one delimiter (tspecials) must exist between any two - tokens, since they would otherwise be interpreted as a single - token. However, applications should attempt to follow "common - form" when generating HTTP constructs, since there exist some - implementations that fail to accept anything beyond the common - forms. - -2.2 Basic Rules - - The following rules are used throughout this specification to - describe basic parsing constructs. The US-ASCII coded character set - is defined by [17]. - - OCTET = <any 8-bit sequence of data> - CHAR = <any US-ASCII character (octets 0 - 127)> - UPALPHA = <any US-ASCII uppercase letter "A".."Z"> - LOALPHA = <any US-ASCII lowercase letter "a".."z"> - - - -Berners-Lee, et al Informational [Page 10] - -RFC 1945 HTTP/1.0 May 1996 - - - ALPHA = UPALPHA | LOALPHA - DIGIT = <any US-ASCII digit "0".."9"> - CTL = <any US-ASCII control character - (octets 0 - 31) and DEL (127)> - CR = <US-ASCII CR, carriage return (13)> - LF = <US-ASCII LF, linefeed (10)> - SP = <US-ASCII SP, space (32)> - HT = <US-ASCII HT, horizontal-tab (9)> - <"> = <US-ASCII double-quote mark (34)> - - HTTP/1.0 defines the octet sequence CR LF as the end-of-line marker - for all protocol elements except the Entity-Body (see Appendix B for - tolerant applications). The end-of-line marker within an Entity-Body - is defined by its associated media type, as described in Section 3.6. - - CRLF = CR LF - - HTTP/1.0 headers may be folded onto multiple lines if each - continuation line begins with a space or horizontal tab. All linear - whitespace, including folding, has the same semantics as SP. - - LWS = [CRLF] 1*( SP | HT ) - - However, folding of header lines is not expected by some - applications, and should not be generated by HTTP/1.0 applications. - - The TEXT rule is only used for descriptive field contents and values - that are not intended to be interpreted by the message parser. Words - of *TEXT may contain octets from character sets other than US-ASCII. - - TEXT = <any OCTET except CTLs, - but including LWS> - - Recipients of header field TEXT containing octets outside the US- - ASCII character set may assume that they represent ISO-8859-1 - characters. - - Hexadecimal numeric characters are used in several protocol elements. - - HEX = "A" | "B" | "C" | "D" | "E" | "F" - | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT - - Many HTTP/1.0 header field values consist of words separated by LWS - or special characters. These special characters must be in a quoted - string to be used within a parameter value. - - word = token | quoted-string - - - - -Berners-Lee, et al Informational [Page 11] - -RFC 1945 HTTP/1.0 May 1996 - - - token = 1*<any CHAR except CTLs or tspecials> - - tspecials = "(" | ")" | "<" | ">" | "@" - | "," | ";" | ":" | "\" | <"> - | "/" | "[" | "]" | "?" | "=" - | "{" | "}" | SP | HT - - Comments may be included in some HTTP header fields by surrounding - the comment text with parentheses. Comments are only allowed in - fields containing "comment" as part of their field value definition. - In all other fields, parentheses are considered part of the field - value. - - comment = "(" *( ctext | comment ) ")" - ctext = <any TEXT excluding "(" and ")"> - - A string of text is parsed as a single word if it is quoted using - double-quote marks. - - quoted-string = ( <"> *(qdtext) <"> ) - - qdtext = <any CHAR except <"> and CTLs, - but including LWS> - - Single-character quoting using the backslash ("\") character is not - permitted in HTTP/1.0. - -3. Protocol Parameters - -3.1 HTTP Version - - HTTP uses a "<major>.<minor>" numbering scheme to indicate versions - of the protocol. The protocol versioning policy is intended to allow - the sender to indicate the format of a message and its capacity for - understanding further HTTP communication, rather than the features - obtained via that communication. No change is made to the version - number for the addition of message components which do not affect - communication behavior or which only add to extensible field values. - The <minor> number is incremented when the changes made to the - protocol add features which do not change the general message parsing - algorithm, but which may add to the message semantics and imply - additional capabilities of the sender. The <major> number is - incremented when the format of a message within the protocol is - changed. - - The version of an HTTP message is indicated by an HTTP-Version field - in the first line of the message. If the protocol version is not - specified, the recipient must assume that the message is in the - - - -Berners-Lee, et al Informational [Page 12] - -RFC 1945 HTTP/1.0 May 1996 - - - simple HTTP/0.9 format. - - HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT - - Note that the major and minor numbers should be treated as separate - integers and that each may be incremented higher than a single digit. - Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is - lower than HTTP/12.3. Leading zeros should be ignored by recipients - and never generated by senders. - - This document defines both the 0.9 and 1.0 versions of the HTTP - protocol. Applications sending Full-Request or Full-Response - messages, as defined by this specification, must include an HTTP- - Version of "HTTP/1.0". - - HTTP/1.0 servers must: - - o recognize the format of the Request-Line for HTTP/0.9 and - HTTP/1.0 requests; - - o understand any valid request in the format of HTTP/0.9 or - HTTP/1.0; - - o respond appropriately with a message in the same protocol - version used by the client. - - HTTP/1.0 clients must: - - o recognize the format of the Status-Line for HTTP/1.0 responses; - - o understand any valid response in the format of HTTP/0.9 or - HTTP/1.0. - - Proxy and gateway applications must be careful in forwarding requests - that are received in a format different than that of the - application's native HTTP version. Since the protocol version - indicates the protocol capability of the sender, a proxy/gateway must - never send a message with a version indicator which is greater than - its native version; if a higher version request is received, the - proxy/gateway must either downgrade the request version or respond - with an error. Requests with a version lower than that of the - application's native format may be upgraded before being forwarded; - the proxy/gateway's response to that request must follow the server - requirements listed above. - - - - - - - -Berners-Lee, et al Informational [Page 13] - -RFC 1945 HTTP/1.0 May 1996 - - -3.2 Uniform Resource Identifiers - - URIs have been known by many names: WWW addresses, Universal Document - Identifiers, Universal Resource Identifiers [2], and finally the - combination of Uniform Resource Locators (URL) [4] and Names (URN) - [16]. As far as HTTP is concerned, Uniform Resource Identifiers are - simply formatted strings which identify--via name, location, or any - other characteristic--a network resource. - -3.2.1 General Syntax - - URIs in HTTP can be represented in absolute form or relative to some - known base URI [9], depending upon the context of their use. The two - forms are differentiated by the fact that absolute URIs always begin - with a scheme name followed by a colon. - - URI = ( absoluteURI | relativeURI ) [ "#" fragment ] - - absoluteURI = scheme ":" *( uchar | reserved ) - - relativeURI = net_path | abs_path | rel_path - - net_path = "//" net_loc [ abs_path ] - abs_path = "/" rel_path - rel_path = [ path ] [ ";" params ] [ "?" query ] - - path = fsegment *( "/" segment ) - fsegment = 1*pchar - segment = *pchar - - params = param *( ";" param ) - param = *( pchar | "/" ) - - scheme = 1*( ALPHA | DIGIT | "+" | "-" | "." ) - net_loc = *( pchar | ";" | "?" ) - query = *( uchar | reserved ) - fragment = *( uchar | reserved ) - - pchar = uchar | ":" | "@" | "&" | "=" | "+" - uchar = unreserved | escape - unreserved = ALPHA | DIGIT | safe | extra | national - - escape = "%" HEX HEX - reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" - extra = "!" | "*" | "'" | "(" | ")" | "," - safe = "$" | "-" | "_" | "." - unsafe = CTL | SP | <"> | "#" | "%" | "<" | ">" - national = <any OCTET excluding ALPHA, DIGIT, - - - -Berners-Lee, et al Informational [Page 14] - -RFC 1945 HTTP/1.0 May 1996 - - - reserved, extra, safe, and unsafe> - - For definitive information on URL syntax and semantics, see RFC 1738 - [4] and RFC 1808 [9]. The BNF above includes national characters not - allowed in valid URLs as specified by RFC 1738, since HTTP servers - are not restricted in the set of unreserved characters allowed to - represent the rel_path part of addresses, and HTTP proxies may - receive requests for URIs not defined by RFC 1738. - -3.2.2 http URL - - The "http" scheme is used to locate network resources via the HTTP - protocol. This section defines the scheme-specific syntax and - semantics for http URLs. - - http_URL = "http:" "//" host [ ":" port ] [ abs_path ] - - host = <A legal Internet host domain name - or IP address (in dotted-decimal form), - as defined by Section 2.1 of RFC 1123> - - port = *DIGIT - - If the port is empty or not given, port 80 is assumed. The semantics - are that the identified resource is located at the server listening - for TCP connections on that port of that host, and the Request-URI - for the resource is abs_path. If the abs_path is not present in the - URL, it must be given as "/" when used as a Request-URI (Section - 5.1.2). - - Note: Although the HTTP protocol is independent of the transport - layer protocol, the http URL only identifies resources by their - TCP location, and thus non-TCP resources must be identified by - some other URI scheme. - - The canonical form for "http" URLs is obtained by converting any - UPALPHA characters in host to their LOALPHA equivalent (hostnames are - case-insensitive), eliding the [ ":" port ] if the port is 80, and - replacing an empty abs_path with "/". - -3.3 Date/Time Formats - - HTTP/1.0 applications have historically allowed three different - formats for the representation of date/time stamps: - - Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 - Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 - Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format - - - -Berners-Lee, et al Informational [Page 15] - -RFC 1945 HTTP/1.0 May 1996 - - - The first format is preferred as an Internet standard and represents - a fixed-length subset of that defined by RFC 1123 [6] (an update to - RFC 822 [7]). The second format is in common use, but is based on the - obsolete RFC 850 [10] date format and lacks a four-digit year. - HTTP/1.0 clients and servers that parse the date value should accept - all three formats, though they must never generate the third - (asctime) format. - - Note: Recipients of date values are encouraged to be robust in - accepting date values that may have been generated by non-HTTP - applications, as is sometimes the case when retrieving or posting - messages via proxies/gateways to SMTP or NNTP. - - All HTTP/1.0 date/time stamps must be represented in Universal Time - (UT), also known as Greenwich Mean Time (GMT), without exception. - This is indicated in the first two formats by the inclusion of "GMT" - as the three-letter abbreviation for time zone, and should be assumed - when reading the asctime format. - - HTTP-date = rfc1123-date | rfc850-date | asctime-date - - rfc1123-date = wkday "," SP date1 SP time SP "GMT" - rfc850-date = weekday "," SP date2 SP time SP "GMT" - asctime-date = wkday SP date3 SP time SP 4DIGIT - - date1 = 2DIGIT SP month SP 4DIGIT - ; day month year (e.g., 02 Jun 1982) - date2 = 2DIGIT "-" month "-" 2DIGIT - ; day-month-year (e.g., 02-Jun-82) - date3 = month SP ( 2DIGIT | ( SP 1DIGIT )) - ; month day (e.g., Jun 2) - - time = 2DIGIT ":" 2DIGIT ":" 2DIGIT - ; 00:00:00 - 23:59:59 - - wkday = "Mon" | "Tue" | "Wed" - | "Thu" | "Fri" | "Sat" | "Sun" - - weekday = "Monday" | "Tuesday" | "Wednesday" - | "Thursday" | "Friday" | "Saturday" | "Sunday" - - month = "Jan" | "Feb" | "Mar" | "Apr" - | "May" | "Jun" | "Jul" | "Aug" - | "Sep" | "Oct" | "Nov" | "Dec" - - Note: HTTP requirements for the date/time stamp format apply - only to their usage within the protocol stream. Clients and - servers are not required to use these formats for user - - - -Berners-Lee, et al Informational [Page 16] - -RFC 1945 HTTP/1.0 May 1996 - - - presentation, request logging, etc. - -3.4 Character Sets - - HTTP uses the same definition of the term "character set" as that - described for MIME: - - The term "character set" is used in this document to refer to a - method used with one or more tables to convert a sequence of - octets into a sequence of characters. Note that unconditional - conversion in the other direction is not required, in that not all - characters may be available in a given character set and a - character set may provide more than one sequence of octets to - represent a particular character. This definition is intended to - allow various kinds of character encodings, from simple single- - table mappings such as US-ASCII to complex table switching methods - such as those that use ISO 2022's techniques. However, the - definition associated with a MIME character set name must fully - specify the mapping to be performed from octets to characters. In - particular, use of external profiling information to determine the - exact mapping is not permitted. - - Note: This use of the term "character set" is more commonly - referred to as a "character encoding." However, since HTTP and - MIME share the same registry, it is important that the terminology - also be shared. - - HTTP character sets are identified by case-insensitive tokens. The - complete set of tokens are defined by the IANA Character Set registry - [15]. However, because that registry does not define a single, - consistent token for each character set, we define here the preferred - names for those character sets most likely to be used with HTTP - entities. These character sets include those registered by RFC 1521 - [5] -- the US-ASCII [17] and ISO-8859 [18] character sets -- and - other names specifically recommended for use within MIME charset - parameters. - - charset = "US-ASCII" - | "ISO-8859-1" | "ISO-8859-2" | "ISO-8859-3" - | "ISO-8859-4" | "ISO-8859-5" | "ISO-8859-6" - | "ISO-8859-7" | "ISO-8859-8" | "ISO-8859-9" - | "ISO-2022-JP" | "ISO-2022-JP-2" | "ISO-2022-KR" - | "UNICODE-1-1" | "UNICODE-1-1-UTF-7" | "UNICODE-1-1-UTF-8" - | token - - Although HTTP allows an arbitrary token to be used as a charset - value, any token that has a predefined value within the IANA - Character Set registry [15] must represent the character set defined - - - -Berners-Lee, et al Informational [Page 17] - -RFC 1945 HTTP/1.0 May 1996 - - - by that registry. Applications should limit their use of character - sets to those defined by the IANA registry. - - The character set of an entity body should be labelled as the lowest - common denominator of the character codes used within that body, with - the exception that no label is preferred over the labels US-ASCII or - ISO-8859-1. - -3.5 Content Codings - - Content coding values are used to indicate an encoding transformation - that has been applied to a resource. Content codings are primarily - used to allow a document to be compressed or encrypted without losing - the identity of its underlying media type. Typically, the resource is - stored in this encoding and only decoded before rendering or - analogous usage. - - content-coding = "x-gzip" | "x-compress" | token - - Note: For future compatibility, HTTP/1.0 applications should - consider "gzip" and "compress" to be equivalent to "x-gzip" - and "x-compress", respectively. - - All content-coding values are case-insensitive. HTTP/1.0 uses - content-coding values in the Content-Encoding (Section 10.3) header - field. Although the value describes the content-coding, what is more - important is that it indicates what decoding mechanism will be - required to remove the encoding. Note that a single program may be - capable of decoding multiple content-coding formats. Two values are - defined by this specification: - - x-gzip - An encoding format produced by the file compression program - "gzip" (GNU zip) developed by Jean-loup Gailly. This format is - typically a Lempel-Ziv coding (LZ77) with a 32 bit CRC. - - x-compress - The encoding format produced by the file compression program - "compress". This format is an adaptive Lempel-Ziv-Welch coding - (LZW). - - Note: Use of program names for the identification of - encoding formats is not desirable and should be discouraged - for future encodings. Their use here is representative of - historical practice, not good design. - - - - - - -Berners-Lee, et al Informational [Page 18] - -RFC 1945 HTTP/1.0 May 1996 - - -3.6 Media Types - - HTTP uses Internet Media Types [13] in the Content-Type header field - (Section 10.5) in order to provide open and extensible data typing. - - media-type = type "/" subtype *( ";" parameter ) - type = token - subtype = token - - Parameters may follow the type/subtype in the form of attribute/value - pairs. - - parameter = attribute "=" value - attribute = token - value = token | quoted-string - - The type, subtype, and parameter attribute names are case- - insensitive. Parameter values may or may not be case-sensitive, - depending on the semantics of the parameter name. LWS must not be - generated between the type and subtype, nor between an attribute and - its value. Upon receipt of a media type with an unrecognized - parameter, a user agent should treat the media type as if the - unrecognized parameter and its value were not present. - - Some older HTTP applications do not recognize media type parameters. - HTTP/1.0 applications should only use media type parameters when they - are necessary to define the content of a message. - - Media-type values are registered with the Internet Assigned Number - Authority (IANA [15]). The media type registration process is - outlined in RFC 1590 [13]. Use of non-registered media types is - discouraged. - -3.6.1 Canonicalization and Text Defaults - - Internet media types are registered with a canonical form. In - general, an Entity-Body transferred via HTTP must be represented in - the appropriate canonical form prior to its transmission. If the body - has been encoded with a Content-Encoding, the underlying data should - be in canonical form prior to being encoded. - - Media subtypes of the "text" type use CRLF as the text line break - when in canonical form. However, HTTP allows the transport of text - media with plain CR or LF alone representing a line break when used - consistently within the Entity-Body. HTTP applications must accept - CRLF, bare CR, and bare LF as being representative of a line break in - text media received via HTTP. - - - - -Berners-Lee, et al Informational [Page 19] - -RFC 1945 HTTP/1.0 May 1996 - - - In addition, if the text media is represented in a character set that - does not use octets 13 and 10 for CR and LF respectively, as is the - case for some multi-byte character sets, HTTP allows the use of - whatever octet sequences are defined by that character set to - represent the equivalent of CR and LF for line breaks. This - flexibility regarding line breaks applies only to text media in the - Entity-Body; a bare CR or LF should not be substituted for CRLF - within any of the HTTP control structures (such as header fields and - multipart boundaries). - - The "charset" parameter is used with some media types to define the - character set (Section 3.4) of the data. When no explicit charset - parameter is provided by the sender, media subtypes of the "text" - type are defined to have a default charset value of "ISO-8859-1" when - received via HTTP. Data in character sets other than "ISO-8859-1" or - its subsets must be labelled with an appropriate charset value in - order to be consistently interpreted by the recipient. - - Note: Many current HTTP servers provide data using charsets other - than "ISO-8859-1" without proper labelling. This situation reduces - interoperability and is not recommended. To compensate for this, - some HTTP user agents provide a configuration option to allow the - user to change the default interpretation of the media type - character set when no charset parameter is given. - -3.6.2 Multipart Types - - MIME provides for a number of "multipart" types -- encapsulations of - several entities within a single message's Entity-Body. The multipart - types registered by IANA [15] do not have any special meaning for - HTTP/1.0, though user agents may need to understand each type in - order to correctly interpret the purpose of each body-part. An HTTP - user agent should follow the same or similar behavior as a MIME user - agent does upon receipt of a multipart type. HTTP servers should not - assume that all HTTP clients are prepared to handle multipart types. - - All multipart types share a common syntax and must include a boundary - parameter as part of the media type value. The message body is itself - a protocol element and must therefore use only CRLF to represent line - breaks between body-parts. Multipart body-parts may contain HTTP - header fields which are significant to the meaning of that part. - -3.7 Product Tokens - - Product tokens are used to allow communicating applications to - identify themselves via a simple product token, with an optional - slash and version designator. Most fields using product tokens also - allow subproducts which form a significant part of the application to - - - -Berners-Lee, et al Informational [Page 20] - -RFC 1945 HTTP/1.0 May 1996 - - - be listed, separated by whitespace. By convention, the products are - listed in order of their significance for identifying the - application. - - product = token ["/" product-version] - product-version = token - - Examples: - - User-Agent: CERN-LineMode/2.15 libwww/2.17b3 - - Server: Apache/0.8.4 - - Product tokens should be short and to the point -- use of them for - advertizing or other non-essential information is explicitly - forbidden. Although any token character may appear in a product- - version, this token should only be used for a version identifier - (i.e., successive versions of the same product should only differ in - the product-version portion of the product value). - -4. HTTP Message - -4.1 Message Types - - HTTP messages consist of requests from client to server and responses - from server to client. - - HTTP-message = Simple-Request ; HTTP/0.9 messages - | Simple-Response - | Full-Request ; HTTP/1.0 messages - | Full-Response - - Full-Request and Full-Response use the generic message format of RFC - 822 [7] for transferring entities. Both messages may include optional - header fields (also known as "headers") and an entity body. The - entity body is separated from the headers by a null line (i.e., a - line with nothing preceding the CRLF). - - Full-Request = Request-Line ; Section 5.1 - *( General-Header ; Section 4.3 - | Request-Header ; Section 5.2 - | Entity-Header ) ; Section 7.1 - CRLF - [ Entity-Body ] ; Section 7.2 - - Full-Response = Status-Line ; Section 6.1 - *( General-Header ; Section 4.3 - | Response-Header ; Section 6.2 - - - -Berners-Lee, et al Informational [Page 21] - -RFC 1945 HTTP/1.0 May 1996 - - - | Entity-Header ) ; Section 7.1 - CRLF - [ Entity-Body ] ; Section 7.2 - - Simple-Request and Simple-Response do not allow the use of any header - information and are limited to a single request method (GET). - - Simple-Request = "GET" SP Request-URI CRLF - - Simple-Response = [ Entity-Body ] - - Use of the Simple-Request format is discouraged because it prevents - the server from identifying the media type of the returned entity. - -4.2 Message Headers - - HTTP header fields, which include General-Header (Section 4.3), - Request-Header (Section 5.2), Response-Header (Section 6.2), and - Entity-Header (Section 7.1) fields, follow the same generic format as - that given in Section 3.1 of RFC 822 [7]. Each header field consists - of a name followed immediately by a colon (":"), a single space (SP) - character, and the field value. Field names are case-insensitive. - Header fields can be extended over multiple lines by preceding each - extra line with at least one SP or HT, though this is not - recommended. - - HTTP-header = field-name ":" [ field-value ] CRLF - - field-name = token - field-value = *( field-content | LWS ) - - field-content = <the OCTETs making up the field-value - and consisting of either *TEXT or combinations - of token, tspecials, and quoted-string> - - The order in which header fields are received is not significant. - However, it is "good practice" to send General-Header fields first, - followed by Request-Header or Response-Header fields prior to the - Entity-Header fields. - - Multiple HTTP-header fields with the same field-name may be present - in a message if and only if the entire field-value for that header - field is defined as a comma-separated list [i.e., #(values)]. It must - be possible to combine the multiple header fields into one "field- - name: field-value" pair, without changing the semantics of the - message, by appending each subsequent field-value to the first, each - separated by a comma. - - - - -Berners-Lee, et al Informational [Page 22] - -RFC 1945 HTTP/1.0 May 1996 - - -4.3 General Header Fields - - There are a few header fields which have general applicability for - both request and response messages, but which do not apply to the - entity being transferred. These headers apply only to the message - being transmitted. - - General-Header = Date ; Section 10.6 - | Pragma ; Section 10.12 - - General header field names can be extended reliably only in - combination with a change in the protocol version. However, new or - experimental header fields may be given the semantics of general - header fields if all parties in the communication recognize them to - be general header fields. Unrecognized header fields are treated as - Entity-Header fields. - -5. Request - - A request message from a client to a server includes, within the - first line of that message, the method to be applied to the resource, - the identifier of the resource, and the protocol version in use. For - backwards compatibility with the more limited HTTP/0.9 protocol, - there are two valid formats for an HTTP request: - - Request = Simple-Request | Full-Request - - Simple-Request = "GET" SP Request-URI CRLF - - Full-Request = Request-Line ; Section 5.1 - *( General-Header ; Section 4.3 - | Request-Header ; Section 5.2 - | Entity-Header ) ; Section 7.1 - CRLF - [ Entity-Body ] ; Section 7.2 - - If an HTTP/1.0 server receives a Simple-Request, it must respond with - an HTTP/0.9 Simple-Response. An HTTP/1.0 client capable of receiving - a Full-Response should never generate a Simple-Request. - -5.1 Request-Line - - The Request-Line begins with a method token, followed by the - Request-URI and the protocol version, and ending with CRLF. The - elements are separated by SP characters. No CR or LF are allowed - except in the final CRLF sequence. - - Request-Line = Method SP Request-URI SP HTTP-Version CRLF - - - -Berners-Lee, et al Informational [Page 23] - -RFC 1945 HTTP/1.0 May 1996 - - - Note that the difference between a Simple-Request and the Request- - Line of a Full-Request is the presence of the HTTP-Version field and - the availability of methods other than GET. - -5.1.1 Method - - The Method token indicates the method to be performed on the resource - identified by the Request-URI. The method is case-sensitive. - - Method = "GET" ; Section 8.1 - | "HEAD" ; Section 8.2 - | "POST" ; Section 8.3 - | extension-method - - extension-method = token - - The list of methods acceptable by a specific resource can change - dynamically; the client is notified through the return code of the - response if a method is not allowed on a resource. Servers should - return the status code 501 (not implemented) if the method is - unrecognized or not implemented. - - The methods commonly used by HTTP/1.0 applications are fully defined - in Section 8. - -5.1.2 Request-URI - - The Request-URI is a Uniform Resource Identifier (Section 3.2) and - identifies the resource upon which to apply the request. - - Request-URI = absoluteURI | abs_path - - The two options for Request-URI are dependent on the nature of the - request. - - The absoluteURI form is only allowed when the request is being made - to a proxy. The proxy is requested to forward the request and return - the response. If the request is GET or HEAD and a prior response is - cached, the proxy may use the cached message if it passes any - restrictions in the Expires header field. Note that the proxy may - forward the request on to another proxy or directly to the server - specified by the absoluteURI. In order to avoid request loops, a - proxy must be able to recognize all of its server names, including - any aliases, local variations, and the numeric IP address. An example - Request-Line would be: - - GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.0 - - - - -Berners-Lee, et al Informational [Page 24] - -RFC 1945 HTTP/1.0 May 1996 - - - The most common form of Request-URI is that used to identify a - resource on an origin server or gateway. In this case, only the - absolute path of the URI is transmitted (see Section 3.2.1, - abs_path). For example, a client wishing to retrieve the resource - above directly from the origin server would create a TCP connection - to port 80 of the host "www.w3.org" and send the line: - - GET /pub/WWW/TheProject.html HTTP/1.0 - - followed by the remainder of the Full-Request. Note that the absolute - path cannot be empty; if none is present in the original URI, it must - be given as "/" (the server root). - - The Request-URI is transmitted as an encoded string, where some - characters may be escaped using the "% HEX HEX" encoding defined by - RFC 1738 [4]. The origin server must decode the Request-URI in order - to properly interpret the request. - -5.2 Request Header Fields - - The request header fields allow the client to pass additional - information about the request, and about the client itself, to the - server. These fields act as request modifiers, with semantics - equivalent to the parameters on a programming language method - (procedure) invocation. - - Request-Header = Authorization ; Section 10.2 - | From ; Section 10.8 - | If-Modified-Since ; Section 10.9 - | Referer ; Section 10.13 - | User-Agent ; Section 10.15 - - Request-Header field names can be extended reliably only in - combination with a change in the protocol version. However, new or - experimental header fields may be given the semantics of request - header fields if all parties in the communication recognize them to - be request header fields. Unrecognized header fields are treated as - Entity-Header fields. - -6. Response - - After receiving and interpreting a request message, a server responds - in the form of an HTTP response message. - - Response = Simple-Response | Full-Response - - Simple-Response = [ Entity-Body ] - - - - -Berners-Lee, et al Informational [Page 25] - -RFC 1945 HTTP/1.0 May 1996 - - - Full-Response = Status-Line ; Section 6.1 - *( General-Header ; Section 4.3 - | Response-Header ; Section 6.2 - | Entity-Header ) ; Section 7.1 - CRLF - [ Entity-Body ] ; Section 7.2 - - A Simple-Response should only be sent in response to an HTTP/0.9 - Simple-Request or if the server only supports the more limited - HTTP/0.9 protocol. If a client sends an HTTP/1.0 Full-Request and - receives a response that does not begin with a Status-Line, it should - assume that the response is a Simple-Response and parse it - accordingly. Note that the Simple-Response consists only of the - entity body and is terminated by the server closing the connection. - -6.1 Status-Line - - The first line of a Full-Response message is the Status-Line, - consisting of the protocol version followed by a numeric status code - and its associated textual phrase, with each element separated by SP - characters. No CR or LF is allowed except in the final CRLF sequence. - - Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF - - Since a status line always begins with the protocol version and - status code - - "HTTP/" 1*DIGIT "." 1*DIGIT SP 3DIGIT SP - - (e.g., "HTTP/1.0 200 "), the presence of that expression is - sufficient to differentiate a Full-Response from a Simple-Response. - Although the Simple-Response format may allow such an expression to - occur at the beginning of an entity body, and thus cause a - misinterpretation of the message if it was given in response to a - Full-Request, most HTTP/0.9 servers are limited to responses of type - "text/html" and therefore would never generate such a response. - -6.1.1 Status Code and Reason Phrase - - The Status-Code element is a 3-digit integer result code of the - attempt to understand and satisfy the request. The Reason-Phrase is - intended to give a short textual description of the Status-Code. The - Status-Code is intended for use by automata and the Reason-Phrase is - intended for the human user. The client is not required to examine or - display the Reason-Phrase. - - - - - - -Berners-Lee, et al Informational [Page 26] - -RFC 1945 HTTP/1.0 May 1996 - - - The first digit of the Status-Code defines the class of response. The - last two digits do not have any categorization role. There are 5 - values for the first digit: - - o 1xx: Informational - Not used, but reserved for future use - - o 2xx: Success - The action was successfully received, - understood, and accepted. - - o 3xx: Redirection - Further action must be taken in order to - complete the request - - o 4xx: Client Error - The request contains bad syntax or cannot - be fulfilled - - o 5xx: Server Error - The server failed to fulfill an apparently - valid request - - The individual values of the numeric status codes defined for - HTTP/1.0, and an example set of corresponding Reason-Phrase's, are - presented below. The reason phrases listed here are only recommended - -- they may be replaced by local equivalents without affecting the - protocol. These codes are fully defined in Section 9. - - Status-Code = "200" ; OK - | "201" ; Created - | "202" ; Accepted - | "204" ; No Content - | "301" ; Moved Permanently - | "302" ; Moved Temporarily - | "304" ; Not Modified - | "400" ; Bad Request - | "401" ; Unauthorized - | "403" ; Forbidden - | "404" ; Not Found - | "500" ; Internal Server Error - | "501" ; Not Implemented - | "502" ; Bad Gateway - | "503" ; Service Unavailable - | extension-code - - extension-code = 3DIGIT - - Reason-Phrase = *<TEXT, excluding CR, LF> - - HTTP status codes are extensible, but the above codes are the only - ones generally recognized in current practice. HTTP applications are - not required to understand the meaning of all registered status - - - -Berners-Lee, et al Informational [Page 27] - -RFC 1945 HTTP/1.0 May 1996 - - - codes, though such understanding is obviously desirable. However, - applications must understand the class of any status code, as - indicated by the first digit, and treat any unrecognized response as - being equivalent to the x00 status code of that class, with the - exception that an unrecognized response must not be cached. For - example, if an unrecognized status code of 431 is received by the - client, it can safely assume that there was something wrong with its - request and treat the response as if it had received a 400 status - code. In such cases, user agents should present to the user the - entity returned with the response, since that entity is likely to - include human-readable information which will explain the unusual - status. - -6.2 Response Header Fields - - The response header fields allow the server to pass additional - information about the response which cannot be placed in the Status- - Line. These header fields give information about the server and about - further access to the resource identified by the Request-URI. - - Response-Header = Location ; Section 10.11 - | Server ; Section 10.14 - | WWW-Authenticate ; Section 10.16 - - Response-Header field names can be extended reliably only in - combination with a change in the protocol version. However, new or - experimental header fields may be given the semantics of response - header fields if all parties in the communication recognize them to - be response header fields. Unrecognized header fields are treated as - Entity-Header fields. - -7. Entity - - Full-Request and Full-Response messages may transfer an entity within - some requests and responses. An entity consists of Entity-Header - fields and (usually) an Entity-Body. In this section, both sender and - recipient refer to either the client or the server, depending on who - sends and who receives the entity. - - - - - - - - - - - - - -Berners-Lee, et al Informational [Page 28] - -RFC 1945 HTTP/1.0 May 1996 - - -7.1 Entity Header Fields - - Entity-Header fields define optional metainformation about the - Entity-Body or, if no body is present, about the resource identified - by the request. - - Entity-Header = Allow ; Section 10.1 - | Content-Encoding ; Section 10.3 - | Content-Length ; Section 10.4 - | Content-Type ; Section 10.5 - | Expires ; Section 10.7 - | Last-Modified ; Section 10.10 - | extension-header - - extension-header = HTTP-header - - The extension-header mechanism allows additional Entity-Header fields - to be defined without changing the protocol, but these fields cannot - be assumed to be recognizable by the recipient. Unrecognized header - fields should be ignored by the recipient and forwarded by proxies. - -7.2 Entity Body - - The entity body (if any) sent with an HTTP request or response is in - a format and encoding defined by the Entity-Header fields. - - Entity-Body = *OCTET - - An entity body is included with a request message only when the - request method calls for one. The presence of an entity body in a - request is signaled by the inclusion of a Content-Length header field - in the request message headers. HTTP/1.0 requests containing an - entity body must include a valid Content-Length header field. - - For response messages, whether or not an entity body is included with - a message is dependent on both the request method and the response - code. All responses to the HEAD request method must not include a - body, even though the presence of entity header fields may lead one - to believe they do. All 1xx (informational), 204 (no content), and - 304 (not modified) responses must not include a body. All other - responses must include an entity body or a Content-Length header - field defined with a value of zero (0). - -7.2.1 Type - - When an Entity-Body is included with a message, the data type of that - body is determined via the header fields Content-Type and Content- - Encoding. These define a two-layer, ordered encoding model: - - - -Berners-Lee, et al Informational [Page 29] - -RFC 1945 HTTP/1.0 May 1996 - - - entity-body := Content-Encoding( Content-Type( data ) ) - - A Content-Type specifies the media type of the underlying data. A - Content-Encoding may be used to indicate any additional content - coding applied to the type, usually for the purpose of data - compression, that is a property of the resource requested. The - default for the content encoding is none (i.e., the identity - function). - - Any HTTP/1.0 message containing an entity body should include a - Content-Type header field defining the media type of that body. If - and only if the media type is not given by a Content-Type header, as - is the case for Simple-Response messages, the recipient may attempt - to guess the media type via inspection of its content and/or the name - extension(s) of the URL used to identify the resource. If the media - type remains unknown, the recipient should treat it as type - "application/octet-stream". - -7.2.2 Length - - When an Entity-Body is included with a message, the length of that - body may be determined in one of two ways. If a Content-Length header - field is present, its value in bytes represents the length of the - Entity-Body. Otherwise, the body length is determined by the closing - of the connection by the server. - - Closing the connection cannot be used to indicate the end of a - request body, since it leaves no possibility for the server to send - back a response. Therefore, HTTP/1.0 requests containing an entity - body must include a valid Content-Length header field. If a request - contains an entity body and Content-Length is not specified, and the - server does not recognize or cannot calculate the length from other - fields, then the server should send a 400 (bad request) response. - - Note: Some older servers supply an invalid Content-Length when - sending a document that contains server-side includes dynamically - inserted into the data stream. It must be emphasized that this - will not be tolerated by future versions of HTTP. Unless the - client knows that it is receiving a response from a compliant - server, it should not depend on the Content-Length value being - correct. - -8. Method Definitions - - The set of common methods for HTTP/1.0 is defined below. Although - this set can be expanded, additional methods cannot be assumed to - share the same semantics for separately extended clients and servers. - - - - -Berners-Lee, et al Informational [Page 30] - -RFC 1945 HTTP/1.0 May 1996 - - -8.1 GET - - The GET method means retrieve whatever information (in the form of an - entity) is identified by the Request-URI. If the Request-URI refers - to a data-producing process, it is the produced data which shall be - returned as the entity in the response and not the source text of the - process, unless that text happens to be the output of the process. - - The semantics of the GET method changes to a "conditional GET" if the - request message includes an If-Modified-Since header field. A - conditional GET method requests that the identified resource be - transferred only if it has been modified since the date given by the - If-Modified-Since header, as described in Section 10.9. The - conditional GET method is intended to reduce network usage by - allowing cached entities to be refreshed without requiring multiple - requests or transferring unnecessary data. - -8.2 HEAD - - The HEAD method is identical to GET except that the server must not - return any Entity-Body in the response. The metainformation contained - in the HTTP headers in response to a HEAD request should be identical - to the information sent in response to a GET request. This method can - be used for obtaining metainformation about the resource identified - by the Request-URI without transferring the Entity-Body itself. This - method is often used for testing hypertext links for validity, - accessibility, and recent modification. - - There is no "conditional HEAD" request analogous to the conditional - GET. If an If-Modified-Since header field is included with a HEAD - request, it should be ignored. - -8.3 POST - - The POST method is used to request that the destination server accept - the entity enclosed in the request as a new subordinate of the - resource identified by the Request-URI in the Request-Line. POST is - designed to allow a uniform method to cover the following functions: - - o Annotation of existing resources; - - o Posting a message to a bulletin board, newsgroup, mailing list, - or similar group of articles; - - o Providing a block of data, such as the result of submitting a - form [3], to a data-handling process; - - o Extending a database through an append operation. - - - -Berners-Lee, et al Informational [Page 31] - -RFC 1945 HTTP/1.0 May 1996 - - - The actual function performed by the POST method is determined by the - server and is usually dependent on the Request-URI. The posted entity - is subordinate to that URI in the same way that a file is subordinate - to a directory containing it, a news article is subordinate to a - newsgroup to which it is posted, or a record is subordinate to a - database. - - A successful POST does not require that the entity be created as a - resource on the origin server or made accessible for future - reference. That is, the action performed by the POST method might not - result in a resource that can be identified by a URI. In this case, - either 200 (ok) or 204 (no content) is the appropriate response - status, depending on whether or not the response includes an entity - that describes the result. - - If a resource has been created on the origin server, the response - should be 201 (created) and contain an entity (preferably of type - "text/html") which describes the status of the request and refers to - the new resource. - - A valid Content-Length is required on all HTTP/1.0 POST requests. An - HTTP/1.0 server should respond with a 400 (bad request) message if it - cannot determine the length of the request message's content. - - Applications must not cache responses to a POST request because the - application has no way of knowing that the server would return an - equivalent response on some future request. - -9. Status Code Definitions - - Each Status-Code is described below, including a description of which - method(s) it can follow and any metainformation required in the - response. - -9.1 Informational 1xx - - This class of status code indicates a provisional response, - consisting only of the Status-Line and optional headers, and is - terminated by an empty line. HTTP/1.0 does not define any 1xx status - codes and they are not a valid response to a HTTP/1.0 request. - However, they may be useful for experimental applications which are - outside the scope of this specification. - -9.2 Successful 2xx - - This class of status code indicates that the client's request was - successfully received, understood, and accepted. - - - - -Berners-Lee, et al Informational [Page 32] - -RFC 1945 HTTP/1.0 May 1996 - - - 200 OK - - The request has succeeded. The information returned with the - response is dependent on the method used in the request, as follows: - - GET an entity corresponding to the requested resource is sent - in the response; - - HEAD the response must only contain the header information and - no Entity-Body; - - POST an entity describing or containing the result of the action. - - 201 Created - - The request has been fulfilled and resulted in a new resource being - created. The newly created resource can be referenced by the URI(s) - returned in the entity of the response. The origin server should - create the resource before using this Status-Code. If the action - cannot be carried out immediately, the server must include in the - response body a description of when the resource will be available; - otherwise, the server should respond with 202 (accepted). - - Of the methods defined by this specification, only POST can create a - resource. - - 202 Accepted - - The request has been accepted for processing, but the processing - has not been completed. The request may or may not eventually be - acted upon, as it may be disallowed when processing actually takes - place. There is no facility for re-sending a status code from an - asynchronous operation such as this. - - The 202 response is intentionally non-committal. Its purpose is to - allow a server to accept a request for some other process (perhaps - a batch-oriented process that is only run once per day) without - requiring that the user agent's connection to the server persist - until the process is completed. The entity returned with this - response should include an indication of the request's current - status and either a pointer to a status monitor or some estimate of - when the user can expect the request to be fulfilled. - - 204 No Content - - The server has fulfilled the request but there is no new - information to send back. If the client is a user agent, it should - not change its document view from that which caused the request to - - - -Berners-Lee, et al Informational [Page 33] - -RFC 1945 HTTP/1.0 May 1996 - - - be generated. This response is primarily intended to allow input - for scripts or other actions to take place without causing a change - to the user agent's active document view. The response may include - new metainformation in the form of entity headers, which should - apply to the document currently in the user agent's active view. - -9.3 Redirection 3xx - - This class of status code indicates that further action needs to be - taken by the user agent in order to fulfill the request. The action - required may be carried out by the user agent without interaction - with the user if and only if the method used in the subsequent - request is GET or HEAD. A user agent should never automatically - redirect a request more than 5 times, since such redirections usually - indicate an infinite loop. - - 300 Multiple Choices - - This response code is not directly used by HTTP/1.0 applications, - but serves as the default for interpreting the 3xx class of - responses. - - The requested resource is available at one or more locations. - Unless it was a HEAD request, the response should include an entity - containing a list of resource characteristics and locations from - which the user or user agent can choose the one most appropriate. - If the server has a preferred choice, it should include the URL in - a Location field; user agents may use this field value for - automatic redirection. - - 301 Moved Permanently - - The requested resource has been assigned a new permanent URL and - any future references to this resource should be done using that - URL. Clients with link editing capabilities should automatically - relink references to the Request-URI to the new reference returned - by the server, where possible. - - The new URL must be given by the Location field in the response. - Unless it was a HEAD request, the Entity-Body of the response - should contain a short note with a hyperlink to the new URL. - - If the 301 status code is received in response to a request using - the POST method, the user agent must not automatically redirect the - request unless it can be confirmed by the user, since this might - change the conditions under which the request was issued. - - - - - -Berners-Lee, et al Informational [Page 34] - -RFC 1945 HTTP/1.0 May 1996 - - - Note: When automatically redirecting a POST request after - receiving a 301 status code, some existing user agents will - erroneously change it into a GET request. - - 302 Moved Temporarily - - The requested resource resides temporarily under a different URL. - Since the redirection may be altered on occasion, the client should - continue to use the Request-URI for future requests. - - The URL must be given by the Location field in the response. Unless - it was a HEAD request, the Entity-Body of the response should - contain a short note with a hyperlink to the new URI(s). - - If the 302 status code is received in response to a request using - the POST method, the user agent must not automatically redirect the - request unless it can be confirmed by the user, since this might - change the conditions under which the request was issued. - - Note: When automatically redirecting a POST request after - receiving a 302 status code, some existing user agents will - erroneously change it into a GET request. - - 304 Not Modified - - If the client has performed a conditional GET request and access is - allowed, but the document has not been modified since the date and - time specified in the If-Modified-Since field, the server must - respond with this status code and not send an Entity-Body to the - client. Header fields contained in the response should only include - information which is relevant to cache managers or which may have - changed independently of the entity's Last-Modified date. Examples - of relevant header fields include: Date, Server, and Expires. A - cache should update its cached entity to reflect any new field - values given in the 304 response. - -9.4 Client Error 4xx - - The 4xx class of status code is intended for cases in which the - client seems to have erred. If the client has not completed the - request when a 4xx code is received, it should immediately cease - sending data to the server. Except when responding to a HEAD request, - the server should include an entity containing an explanation of the - error situation, and whether it is a temporary or permanent - condition. These status codes are applicable to any request method. - - - - - - -Berners-Lee, et al Informational [Page 35] - -RFC 1945 HTTP/1.0 May 1996 - - - Note: If the client is sending data, server implementations on TCP - should be careful to ensure that the client acknowledges receipt - of the packet(s) containing the response prior to closing the - input connection. If the client continues sending data to the - server after the close, the server's controller will send a reset - packet to the client, which may erase the client's unacknowledged - input buffers before they can be read and interpreted by the HTTP - application. - - 400 Bad Request - - The request could not be understood by the server due to malformed - syntax. The client should not repeat the request without - modifications. - - 401 Unauthorized - - The request requires user authentication. The response must include - a WWW-Authenticate header field (Section 10.16) containing a - challenge applicable to the requested resource. The client may - repeat the request with a suitable Authorization header field - (Section 10.2). If the request already included Authorization - credentials, then the 401 response indicates that authorization has - been refused for those credentials. If the 401 response contains - the same challenge as the prior response, and the user agent has - already attempted authentication at least once, then the user - should be presented the entity that was given in the response, - since that entity may include relevant diagnostic information. HTTP - access authentication is explained in Section 11. - - 403 Forbidden - - The server understood the request, but is refusing to fulfill it. - Authorization will not help and the request should not be repeated. - If the request method was not HEAD and the server wishes to make - public why the request has not been fulfilled, it should describe - the reason for the refusal in the entity body. This status code is - commonly used when the server does not wish to reveal exactly why - the request has been refused, or when no other response is - applicable. - - 404 Not Found - - The server has not found anything matching the Request-URI. No - indication is given of whether the condition is temporary or - permanent. If the server does not wish to make this information - available to the client, the status code 403 (forbidden) can be - used instead. - - - -Berners-Lee, et al Informational [Page 36] - -RFC 1945 HTTP/1.0 May 1996 - - -9.5 Server Error 5xx - - Response status codes beginning with the digit "5" indicate cases in - which the server is aware that it has erred or is incapable of - performing the request. If the client has not completed the request - when a 5xx code is received, it should immediately cease sending data - to the server. Except when responding to a HEAD request, the server - should include an entity containing an explanation of the error - situation, and whether it is a temporary or permanent condition. - These response codes are applicable to any request method and there - are no required header fields. - - 500 Internal Server Error - - The server encountered an unexpected condition which prevented it - from fulfilling the request. - - 501 Not Implemented - - The server does not support the functionality required to fulfill - the request. This is the appropriate response when the server does - not recognize the request method and is not capable of supporting - it for any resource. - - 502 Bad Gateway - - The server, while acting as a gateway or proxy, received an invalid - response from the upstream server it accessed in attempting to - fulfill the request. - - 503 Service Unavailable - - The server is currently unable to handle the request due to a - temporary overloading or maintenance of the server. The implication - is that this is a temporary condition which will be alleviated - after some delay. - - Note: The existence of the 503 status code does not imply - that a server must use it when becoming overloaded. Some - servers may wish to simply refuse the connection. - -10. Header Field Definitions - - This section defines the syntax and semantics of all commonly used - HTTP/1.0 header fields. For general and entity header fields, both - sender and recipient refer to either the client or the server, - depending on who sends and who receives the message. - - - - -Berners-Lee, et al Informational [Page 37] - -RFC 1945 HTTP/1.0 May 1996 - - -10.1 Allow - - The Allow entity-header field lists the set of methods supported by - the resource identified by the Request-URI. The purpose of this field - is strictly to inform the recipient of valid methods associated with - the resource. The Allow header field is not permitted in a request - using the POST method, and thus should be ignored if it is received - as part of a POST entity. - - Allow = "Allow" ":" 1#method - - Example of use: - - Allow: GET, HEAD - - This field cannot prevent a client from trying other methods. - However, the indications given by the Allow header field value should - be followed. The actual set of allowed methods is defined by the - origin server at the time of each request. - - A proxy must not modify the Allow header field even if it does not - understand all the methods specified, since the user agent may have - other means of communicating with the origin server. - - The Allow header field does not indicate what methods are implemented - by the server. - -10.2 Authorization - - A user agent that wishes to authenticate itself with a server-- - usually, but not necessarily, after receiving a 401 response--may do - so by including an Authorization request-header field with the - request. The Authorization field value consists of credentials - containing the authentication information of the user agent for the - realm of the resource being requested. - - Authorization = "Authorization" ":" credentials - - HTTP access authentication is described in Section 11. If a request - is authenticated and a realm specified, the same credentials should - be valid for all other requests within this realm. - - Responses to requests containing an Authorization field are not - cachable. - - - - - - - -Berners-Lee, et al Informational [Page 38] - -RFC 1945 HTTP/1.0 May 1996 - - -10.3 Content-Encoding - - The Content-Encoding entity-header field is used as a modifier to the - media-type. When present, its value indicates what additional content - coding has been applied to the resource, and thus what decoding - mechanism must be applied in order to obtain the media-type - referenced by the Content-Type header field. The Content-Encoding is - primarily used to allow a document to be compressed without losing - the identity of its underlying media type. - - Content-Encoding = "Content-Encoding" ":" content-coding - - Content codings are defined in Section 3.5. An example of its use is - - Content-Encoding: x-gzip - - The Content-Encoding is a characteristic of the resource identified - by the Request-URI. Typically, the resource is stored with this - encoding and is only decoded before rendering or analogous usage. - -10.4 Content-Length - - The Content-Length entity-header field indicates the size of the - Entity-Body, in decimal number of octets, sent to the recipient or, - in the case of the HEAD method, the size of the Entity-Body that - would have been sent had the request been a GET. - - Content-Length = "Content-Length" ":" 1*DIGIT - - An example is - - Content-Length: 3495 - - Applications should use this field to indicate the size of the - Entity-Body to be transferred, regardless of the media type of the - entity. A valid Content-Length field value is required on all - HTTP/1.0 request messages containing an entity body. - - Any Content-Length greater than or equal to zero is a valid value. - Section 7.2.2 describes how to determine the length of a response - entity body if a Content-Length is not given. - - Note: The meaning of this field is significantly different from - the corresponding definition in MIME, where it is an optional - field used within the "message/external-body" content-type. In - HTTP, it should be used whenever the entity's length can be - determined prior to being transferred. - - - - -Berners-Lee, et al Informational [Page 39] - -RFC 1945 HTTP/1.0 May 1996 - - -10.5 Content-Type - - The Content-Type entity-header field indicates the media type of the - Entity-Body sent to the recipient or, in the case of the HEAD method, - the media type that would have been sent had the request been a GET. - - Content-Type = "Content-Type" ":" media-type - - Media types are defined in Section 3.6. An example of the field is - - Content-Type: text/html - - Further discussion of methods for identifying the media type of an - entity is provided in Section 7.2.1. - -10.6 Date - - The Date general-header field represents the date and time at which - the message was originated, having the same semantics as orig-date in - RFC 822. The field value is an HTTP-date, as described in Section - 3.3. - - Date = "Date" ":" HTTP-date - - An example is - - Date: Tue, 15 Nov 1994 08:12:31 GMT - - If a message is received via direct connection with the user agent - (in the case of requests) or the origin server (in the case of - responses), then the date can be assumed to be the current date at - the receiving end. However, since the date--as it is believed by the - origin--is important for evaluating cached responses, origin servers - should always include a Date header. Clients should only send a Date - header field in messages that include an entity body, as in the case - of the POST request, and even then it is optional. A received message - which does not have a Date header field should be assigned one by the - recipient if the message will be cached by that recipient or - gatewayed via a protocol which requires a Date. - - In theory, the date should represent the moment just before the - entity is generated. In practice, the date can be generated at any - time during the message origination without affecting its semantic - value. - - Note: An earlier version of this document incorrectly specified - that this field should contain the creation date of the enclosed - Entity-Body. This has been changed to reflect actual (and proper) - - - -Berners-Lee, et al Informational [Page 40] - -RFC 1945 HTTP/1.0 May 1996 - - - usage. - -10.7 Expires - - The Expires entity-header field gives the date/time after which the - entity should be considered stale. This allows information providers - to suggest the volatility of the resource, or a date after which the - information may no longer be valid. Applications must not cache this - entity beyond the date given. The presence of an Expires field does - not imply that the original resource will change or cease to exist - at, before, or after that time. However, information providers that - know or even suspect that a resource will change by a certain date - should include an Expires header with that date. The format is an - absolute date and time as defined by HTTP-date in Section 3.3. - - Expires = "Expires" ":" HTTP-date - - An example of its use is - - Expires: Thu, 01 Dec 1994 16:00:00 GMT - - If the date given is equal to or earlier than the value of the Date - header, the recipient must not cache the enclosed entity. If a - resource is dynamic by nature, as is the case with many data- - producing processes, entities from that resource should be given an - appropriate Expires value which reflects that dynamism. - - The Expires field cannot be used to force a user agent to refresh its - display or reload a resource; its semantics apply only to caching - mechanisms, and such mechanisms need only check a resource's - expiration status when a new request for that resource is initiated. - - User agents often have history mechanisms, such as "Back" buttons and - history lists, which can be used to redisplay an entity retrieved - earlier in a session. By default, the Expires field does not apply to - history mechanisms. If the entity is still in storage, a history - mechanism should display it even if the entity has expired, unless - the user has specifically configured the agent to refresh expired - history documents. - - Note: Applications are encouraged to be tolerant of bad or - misinformed implementations of the Expires header. A value of zero - (0) or an invalid date format should be considered equivalent to - an "expires immediately." Although these values are not legitimate - for HTTP/1.0, a robust implementation is always desirable. - - - - - - -Berners-Lee, et al Informational [Page 41] - -RFC 1945 HTTP/1.0 May 1996 - - -10.8 From - - The From request-header field, if given, should contain an Internet - e-mail address for the human user who controls the requesting user - agent. The address should be machine-usable, as defined by mailbox in - RFC 822 [7] (as updated by RFC 1123 [6]): - - From = "From" ":" mailbox - - An example is: - - From: webmaster@w3.org - - This header field may be used for logging purposes and as a means for - identifying the source of invalid or unwanted requests. It should not - be used as an insecure form of access protection. The interpretation - of this field is that the request is being performed on behalf of the - person given, who accepts responsibility for the method performed. In - particular, robot agents should include this header so that the - person responsible for running the robot can be contacted if problems - occur on the receiving end. - - The Internet e-mail address in this field may be separate from the - Internet host which issued the request. For example, when a request - is passed through a proxy, the original issuer's address should be - used. - - Note: The client should not send the From header field without the - user's approval, as it may conflict with the user's privacy - interests or their site's security policy. It is strongly - recommended that the user be able to disable, enable, and modify - the value of this field at any time prior to a request. - -10.9 If-Modified-Since - - The If-Modified-Since request-header field is used with the GET - method to make it conditional: if the requested resource has not been - modified since the time specified in this field, a copy of the - resource will not be returned from the server; instead, a 304 (not - modified) response will be returned without any Entity-Body. - - If-Modified-Since = "If-Modified-Since" ":" HTTP-date - - An example of the field is: - - If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT - - - - - -Berners-Lee, et al Informational [Page 42] - -RFC 1945 HTTP/1.0 May 1996 - - - A conditional GET method requests that the identified resource be - transferred only if it has been modified since the date given by the - If-Modified-Since header. The algorithm for determining this includes - the following cases: - - a) If the request would normally result in anything other than - a 200 (ok) status, or if the passed If-Modified-Since date - is invalid, the response is exactly the same as for a - normal GET. A date which is later than the server's current - time is invalid. - - b) If the resource has been modified since the - If-Modified-Since date, the response is exactly the same as - for a normal GET. - - c) If the resource has not been modified since a valid - If-Modified-Since date, the server shall return a 304 (not - modified) response. - - The purpose of this feature is to allow efficient updates of cached - information with a minimum amount of transaction overhead. - -10.10 Last-Modified - - The Last-Modified entity-header field indicates the date and time at - which the sender believes the resource was last modified. The exact - semantics of this field are defined in terms of how the recipient - should interpret it: if the recipient has a copy of this resource - which is older than the date given by the Last-Modified field, that - copy should be considered stale. - - Last-Modified = "Last-Modified" ":" HTTP-date - - An example of its use is - - Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT - - The exact meaning of this header field depends on the implementation - of the sender and the nature of the original resource. For files, it - may be just the file system last-modified time. For entities with - dynamically included parts, it may be the most recent of the set of - last-modify times for its component parts. For database gateways, it - may be the last-update timestamp of the record. For virtual objects, - it may be the last time the internal state changed. - - An origin server must not send a Last-Modified date which is later - than the server's time of message origination. In such cases, where - the resource's last modification would indicate some time in the - - - -Berners-Lee, et al Informational [Page 43] - -RFC 1945 HTTP/1.0 May 1996 - - - future, the server must replace that date with the message - origination date. - -10.11 Location - - The Location response-header field defines the exact location of the - resource that was identified by the Request-URI. For 3xx responses, - the location must indicate the server's preferred URL for automatic - redirection to the resource. Only one absolute URL is allowed. - - Location = "Location" ":" absoluteURI - - An example is - - Location: http://www.w3.org/hypertext/WWW/NewLocation.html - -10.12 Pragma - - The Pragma general-header field is used to include implementation- - specific directives that may apply to any recipient along the - request/response chain. All pragma directives specify optional - behavior from the viewpoint of the protocol; however, some systems - may require that behavior be consistent with the directives. - - Pragma = "Pragma" ":" 1#pragma-directive - - pragma-directive = "no-cache" | extension-pragma - extension-pragma = token [ "=" word ] - - When the "no-cache" directive is present in a request message, an - application should forward the request toward the origin server even - if it has a cached copy of what is being requested. This allows a - client to insist upon receiving an authoritative response to its - request. It also allows a client to refresh a cached copy which is - known to be corrupted or stale. - - Pragma directives must be passed through by a proxy or gateway - application, regardless of their significance to that application, - since the directives may be applicable to all recipients along the - request/response chain. It is not possible to specify a pragma for a - specific recipient; however, any pragma directive not relevant to a - recipient should be ignored by that recipient. - -10.13 Referer - - The Referer request-header field allows the client to specify, for - the server's benefit, the address (URI) of the resource from which - the Request-URI was obtained. This allows a server to generate lists - - - -Berners-Lee, et al Informational [Page 44] - -RFC 1945 HTTP/1.0 May 1996 - - - of back-links to resources for interest, logging, optimized caching, - etc. It also allows obsolete or mistyped links to be traced for - maintenance. The Referer field must not be sent if the Request-URI - was obtained from a source that does not have its own URI, such as - input from the user keyboard. - - Referer = "Referer" ":" ( absoluteURI | relativeURI ) - - Example: - - Referer: http://www.w3.org/hypertext/DataSources/Overview.html - - If a partial URI is given, it should be interpreted relative to the - Request-URI. The URI must not include a fragment. - - Note: Because the source of a link may be private information or - may reveal an otherwise private information source, it is strongly - recommended that the user be able to select whether or not the - Referer field is sent. For example, a browser client could have a - toggle switch for browsing openly/anonymously, which would - respectively enable/disable the sending of Referer and From - information. - -10.14 Server - - The Server response-header field contains information about the - software used by the origin server to handle the request. The field - can contain multiple product tokens (Section 3.7) and comments - identifying the server and any significant subproducts. By - convention, the product tokens are listed in order of their - significance for identifying the application. - - Server = "Server" ":" 1*( product | comment ) - - Example: - - Server: CERN/3.0 libwww/2.17 - - If the response is being forwarded through a proxy, the proxy - application must not add its data to the product list. - - Note: Revealing the specific software version of the server may - allow the server machine to become more vulnerable to attacks - against software that is known to contain security holes. Server - implementors are encouraged to make this field a configurable - option. - - - - - -Berners-Lee, et al Informational [Page 45] - -RFC 1945 HTTP/1.0 May 1996 - - - Note: Some existing servers fail to restrict themselves to the - product token syntax within the Server field. - -10.15 User-Agent - - The User-Agent request-header field contains information about the - user agent originating the request. This is for statistical purposes, - the tracing of protocol violations, and automated recognition of user - agents for the sake of tailoring responses to avoid particular user - agent limitations. Although it is not required, user agents should - include this field with requests. The field can contain multiple - product tokens (Section 3.7) and comments identifying the agent and - any subproducts which form a significant part of the user agent. By - convention, the product tokens are listed in order of their - significance for identifying the application. - - User-Agent = "User-Agent" ":" 1*( product | comment ) - - Example: - - User-Agent: CERN-LineMode/2.15 libwww/2.17b3 - - Note: Some current proxy applications append their product - information to the list in the User-Agent field. This is not - recommended, since it makes machine interpretation of these - fields ambiguous. - - Note: Some existing clients fail to restrict themselves to - the product token syntax within the User-Agent field. - -10.16 WWW-Authenticate - - The WWW-Authenticate response-header field must be included in 401 - (unauthorized) response messages. The field value consists of at - least one challenge that indicates the authentication scheme(s) and - parameters applicable to the Request-URI. - - WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge - - The HTTP access authentication process is described in Section 11. - User agents must take special care in parsing the WWW-Authenticate - field value if it contains more than one challenge, or if more than - one WWW-Authenticate header field is provided, since the contents of - a challenge may itself contain a comma-separated list of - authentication parameters. - - - - - - -Berners-Lee, et al Informational [Page 46] - -RFC 1945 HTTP/1.0 May 1996 - - -11. Access Authentication - - HTTP provides a simple challenge-response authentication mechanism - which may be used by a server to challenge a client request and by a - client to provide authentication information. It uses an extensible, - case-insensitive token to identify the authentication scheme, - followed by a comma-separated list of attribute-value pairs which - carry the parameters necessary for achieving authentication via that - scheme. - - auth-scheme = token - - auth-param = token "=" quoted-string - - The 401 (unauthorized) response message is used by an origin server - to challenge the authorization of a user agent. This response must - include a WWW-Authenticate header field containing at least one - challenge applicable to the requested resource. - - challenge = auth-scheme 1*SP realm *( "," auth-param ) - - realm = "realm" "=" realm-value - realm-value = quoted-string - - The realm attribute (case-insensitive) is required for all - authentication schemes which issue a challenge. The realm value - (case-sensitive), in combination with the canonical root URL of the - server being accessed, defines the protection space. These realms - allow the protected resources on a server to be partitioned into a - set of protection spaces, each with its own authentication scheme - and/or authorization database. The realm value is a string, generally - assigned by the origin server, which may have additional semantics - specific to the authentication scheme. - - A user agent that wishes to authenticate itself with a server-- - usually, but not necessarily, after receiving a 401 response--may do - so by including an Authorization header field with the request. The - Authorization field value consists of credentials containing the - authentication information of the user agent for the realm of the - resource being requested. - - credentials = basic-credentials - | ( auth-scheme #auth-param ) - - The domain over which credentials can be automatically applied by a - user agent is determined by the protection space. If a prior request - has been authorized, the same credentials may be reused for all other - requests within that protection space for a period of time determined - - - -Berners-Lee, et al Informational [Page 47] - -RFC 1945 HTTP/1.0 May 1996 - - - by the authentication scheme, parameters, and/or user preference. - Unless otherwise defined by the authentication scheme, a single - protection space cannot extend outside the scope of its server. - - If the server does not wish to accept the credentials sent with a - request, it should return a 403 (forbidden) response. - - The HTTP protocol does not restrict applications to this simple - challenge-response mechanism for access authentication. Additional - mechanisms may be used, such as encryption at the transport level or - via message encapsulation, and with additional header fields - specifying authentication information. However, these additional - mechanisms are not defined by this specification. - - Proxies must be completely transparent regarding user agent - authentication. That is, they must forward the WWW-Authenticate and - Authorization headers untouched, and must not cache the response to a - request containing Authorization. HTTP/1.0 does not provide a means - for a client to be authenticated with a proxy. - -11.1 Basic Authentication Scheme - - The "basic" authentication scheme is based on the model that the user - agent must authenticate itself with a user-ID and a password for each - realm. The realm value should be considered an opaque string which - can only be compared for equality with other realms on that server. - The server will authorize the request only if it can validate the - user-ID and password for the protection space of the Request-URI. - There are no optional authentication parameters. - - Upon receipt of an unauthorized request for a URI within the - protection space, the server should respond with a challenge like the - following: - - WWW-Authenticate: Basic realm="WallyWorld" - - where "WallyWorld" is the string assigned by the server to identify - the protection space of the Request-URI. - - To receive authorization, the client sends the user-ID and password, - separated by a single colon (":") character, within a base64 [5] - encoded string in the credentials. - - basic-credentials = "Basic" SP basic-cookie - - basic-cookie = <base64 [5] encoding of userid-password, - except not limited to 76 char/line> - - - - -Berners-Lee, et al Informational [Page 48] - -RFC 1945 HTTP/1.0 May 1996 - - - userid-password = [ token ] ":" *TEXT - - If the user agent wishes to send the user-ID "Aladdin" and password - "open sesame", it would use the following header field: - - Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== - - The basic authentication scheme is a non-secure method of filtering - unauthorized access to resources on an HTTP server. It is based on - the assumption that the connection between the client and the server - can be regarded as a trusted carrier. As this is not generally true - on an open network, the basic authentication scheme should be used - accordingly. In spite of this, clients should implement the scheme in - order to communicate with servers that use it. - -12. Security Considerations - - This section is meant to inform application developers, information - providers, and users of the security limitations in HTTP/1.0 as - described by this document. The discussion does not include - definitive solutions to the problems revealed, though it does make - some suggestions for reducing security risks. - -12.1 Authentication of Clients - - As mentioned in Section 11.1, the Basic authentication scheme is not - a secure method of user authentication, nor does it prevent the - Entity-Body from being transmitted in clear text across the physical - network used as the carrier. HTTP/1.0 does not prevent additional - authentication schemes and encryption mechanisms from being employed - to increase security. - -12.2 Safe Methods - - The writers of client software should be aware that the software - represents the user in their interactions over the Internet, and - should be careful to allow the user to be aware of any actions they - may take which may have an unexpected significance to themselves or - others. - - In particular, the convention has been established that the GET and - HEAD methods should never have the significance of taking an action - other than retrieval. These methods should be considered "safe." This - allows user agents to represent other methods, such as POST, in a - special way, so that the user is made aware of the fact that a - possibly unsafe action is being requested. - - - - - -Berners-Lee, et al Informational [Page 49] - -RFC 1945 HTTP/1.0 May 1996 - - - Naturally, it is not possible to ensure that the server does not - generate side-effects as a result of performing a GET request; in - fact, some dynamic resources consider that a feature. The important - distinction here is that the user did not request the side-effects, - so therefore cannot be held accountable for them. - -12.3 Abuse of Server Log Information - - A server is in the position to save personal data about a user's - requests which may identify their reading patterns or subjects of - interest. This information is clearly confidential in nature and its - handling may be constrained by law in certain countries. People using - the HTTP protocol to provide data are responsible for ensuring that - such material is not distributed without the permission of any - individuals that are identifiable by the published results. - -12.4 Transfer of Sensitive Information - - Like any generic data transfer protocol, HTTP cannot regulate the - content of the data that is transferred, nor is there any a priori - method of determining the sensitivity of any particular piece of - information within the context of any given request. Therefore, - applications should supply as much control over this information as - possible to the provider of that information. Three header fields are - worth special mention in this context: Server, Referer and From. - - Revealing the specific software version of the server may allow the - server machine to become more vulnerable to attacks against software - that is known to contain security holes. Implementors should make the - Server header field a configurable option. - - The Referer field allows reading patterns to be studied and reverse - links drawn. Although it can be very useful, its power can be abused - if user details are not separated from the information contained in - the Referer. Even when the personal information has been removed, the - Referer field may indicate a private document's URI whose publication - would be inappropriate. - - The information sent in the From field might conflict with the user's - privacy interests or their site's security policy, and hence it - should not be transmitted without the user being able to disable, - enable, and modify the contents of the field. The user must be able - to set the contents of this field within a user preference or - application defaults configuration. - - We suggest, though do not require, that a convenient toggle interface - be provided for the user to enable or disable the sending of From and - Referer information. - - - -Berners-Lee, et al Informational [Page 50] - -RFC 1945 HTTP/1.0 May 1996 - - -12.5 Attacks Based On File and Path Names - - Implementations of HTTP origin servers should be careful to restrict - the documents returned by HTTP requests to be only those that were - intended by the server administrators. If an HTTP server translates - HTTP URIs directly into file system calls, the server must take - special care not to serve files that were not intended to be - delivered to HTTP clients. For example, Unix, Microsoft Windows, and - other operating systems use ".." as a path component to indicate a - directory level above the current one. On such a system, an HTTP - server must disallow any such construct in the Request-URI if it - would otherwise allow access to a resource outside those intended to - be accessible via the HTTP server. Similarly, files intended for - reference only internally to the server (such as access control - files, configuration files, and script code) must be protected from - inappropriate retrieval, since they might contain sensitive - information. Experience has shown that minor bugs in such HTTP server - implementations have turned into security risks. - -13. Acknowledgments - - This specification makes heavy use of the augmented BNF and generic - constructs defined by David H. Crocker for RFC 822 [7]. Similarly, it - reuses many of the definitions provided by Nathaniel Borenstein and - Ned Freed for MIME [5]. We hope that their inclusion in this - specification will help reduce past confusion over the relationship - between HTTP/1.0 and Internet mail message formats. - - The HTTP protocol has evolved considerably over the past four years. - It has benefited from a large and active developer community--the - many people who have participated on the www-talk mailing list--and - it is that community which has been most responsible for the success - of HTTP and of the World-Wide Web in general. Marc Andreessen, Robert - Cailliau, Daniel W. Connolly, Bob Denny, Jean-Francois Groff, Phillip - M. Hallam-Baker, Hakon W. Lie, Ari Luotonen, Rob McCool, Lou - Montulli, Dave Raggett, Tony Sanders, and Marc VanHeyningen deserve - special recognition for their efforts in defining aspects of the - protocol for early versions of this specification. - - Paul Hoffman contributed sections regarding the informational status - of this document and Appendices C and D. - - - - - - - - - - -Berners-Lee, et al Informational [Page 51] - -RFC 1945 HTTP/1.0 May 1996 - - - This document has benefited greatly from the comments of all those - participating in the HTTP-WG. In addition to those already mentioned, - the following individuals have contributed to this specification: - - Gary Adams Harald Tveit Alvestrand - Keith Ball Brian Behlendorf - Paul Burchard Maurizio Codogno - Mike Cowlishaw Roman Czyborra - Michael A. Dolan John Franks - Jim Gettys Marc Hedlund - Koen Holtman Alex Hopmann - Bob Jernigan Shel Kaphan - Martijn Koster Dave Kristol - Daniel LaLiberte Paul Leach - Albert Lunde John C. Mallery - Larry Masinter Mitra - Jeffrey Mogul Gavin Nicol - Bill Perry Jeffrey Perry - Owen Rees Luigi Rizzo - David Robinson Marc Salomon - Rich Salz Jim Seidman - Chuck Shotton Eric W. Sink - Simon E. Spero Robert S. Thau - Francois Yergeau Mary Ellen Zurko - Jean-Philippe Martin-Flatin - -14. References - - [1] Anklesaria, F., McCahill, M., Lindner, P., Johnson, D., - Torrey, D., and B. Alberti, "The Internet Gopher Protocol: A - Distributed Document Search and Retrieval Protocol", RFC 1436, - University of Minnesota, March 1993. - - [2] Berners-Lee, T., "Universal Resource Identifiers in WWW: A - Unifying Syntax for the Expression of Names and Addresses of - Objects on the Network as used in the World-Wide Web", - RFC 1630, CERN, June 1994. - - [3] Berners-Lee, T., and D. Connolly, "Hypertext Markup Language - - 2.0", RFC 1866, MIT/W3C, November 1995. - - [4] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform - Resource Locators (URL)", RFC 1738, CERN, Xerox PARC, - University of Minnesota, December 1994. - - - - - - - -Berners-Lee, et al Informational [Page 52] - -RFC 1945 HTTP/1.0 May 1996 - - - [5] Borenstein, N., and N. Freed, "MIME (Multipurpose Internet Mail - Extensions) Part One: Mechanisms for Specifying and Describing - the Format of Internet Message Bodies", RFC 1521, Bellcore, - Innosoft, September 1993. - - [6] Braden, R., "Requirements for Internet hosts - Application and - Support", STD 3, RFC 1123, IETF, October 1989. - - [7] Crocker, D., "Standard for the Format of ARPA Internet Text - Messages", STD 11, RFC 822, UDEL, August 1982. - - [8] F. Davis, B. Kahle, H. Morris, J. Salem, T. Shen, R. Wang, - J. Sui, and M. Grinbaum. "WAIS Interface Protocol Prototype - Functional Specification." (v1.5), Thinking Machines - Corporation, April 1990. - - [9] Fielding, R., "Relative Uniform Resource Locators", RFC 1808, - UC Irvine, June 1995. - - [10] Horton, M., and R. Adams, "Standard for interchange of USENET - Messages", RFC 1036 (Obsoletes RFC 850), AT&T Bell - Laboratories, Center for Seismic Studies, December 1987. - - [11] Kantor, B., and P. Lapsley, "Network News Transfer Protocol: - A Proposed Standard for the Stream-Based Transmission of News", - RFC 977, UC San Diego, UC Berkeley, February 1986. - - [12] Postel, J., "Simple Mail Transfer Protocol." STD 10, RFC 821, - USC/ISI, August 1982. - - [13] Postel, J., "Media Type Registration Procedure." RFC 1590, - USC/ISI, March 1994. - - [14] Postel, J., and J. Reynolds, "File Transfer Protocol (FTP)", - STD 9, RFC 959, USC/ISI, October 1985. - - [15] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2, RFC - 1700, USC/ISI, October 1994. - - [16] Sollins, K., and L. Masinter, "Functional Requirements for - Uniform Resource Names", RFC 1737, MIT/LCS, Xerox Corporation, - December 1994. - - [17] US-ASCII. Coded Character Set - 7-Bit American Standard Code - for Information Interchange. Standard ANSI X3.4-1986, ANSI, - 1986. - - - - - -Berners-Lee, et al Informational [Page 53] - -RFC 1945 HTTP/1.0 May 1996 - - - [18] ISO-8859. International Standard -- Information Processing -- - 8-bit Single-Byte Coded Graphic Character Sets -- - Part 1: Latin alphabet No. 1, ISO 8859-1:1987. - Part 2: Latin alphabet No. 2, ISO 8859-2, 1987. - Part 3: Latin alphabet No. 3, ISO 8859-3, 1988. - Part 4: Latin alphabet No. 4, ISO 8859-4, 1988. - Part 5: Latin/Cyrillic alphabet, ISO 8859-5, 1988. - Part 6: Latin/Arabic alphabet, ISO 8859-6, 1987. - Part 7: Latin/Greek alphabet, ISO 8859-7, 1987. - Part 8: Latin/Hebrew alphabet, ISO 8859-8, 1988. - Part 9: Latin alphabet No. 5, ISO 8859-9, 1990. - -15. Authors' Addresses - - Tim Berners-Lee - Director, W3 Consortium - MIT Laboratory for Computer Science - 545 Technology Square - Cambridge, MA 02139, U.S.A. - - Fax: +1 (617) 258 8682 - EMail: timbl@w3.org - - - Roy T. Fielding - Department of Information and Computer Science - University of California - Irvine, CA 92717-3425, U.S.A. - - Fax: +1 (714) 824-4056 - EMail: fielding@ics.uci.edu - - - Henrik Frystyk Nielsen - W3 Consortium - MIT Laboratory for Computer Science - 545 Technology Square - Cambridge, MA 02139, U.S.A. - - Fax: +1 (617) 258 8682 - EMail: frystyk@w3.org - - - - - - - - - - -Berners-Lee, et al Informational [Page 54] - -RFC 1945 HTTP/1.0 May 1996 - - -Appendices - - These appendices are provided for informational reasons only -- they - do not form a part of the HTTP/1.0 specification. - -A. Internet Media Type message/http - - In addition to defining the HTTP/1.0 protocol, this document serves - as the specification for the Internet media type "message/http". The - following is to be registered with IANA [13]. - - Media Type name: message - - Media subtype name: http - - Required parameters: none - - Optional parameters: version, msgtype - - version: The HTTP-Version number of the enclosed message - (e.g., "1.0"). If not present, the version can be - determined from the first line of the body. - - msgtype: The message type -- "request" or "response". If - not present, the type can be determined from the - first line of the body. - - Encoding considerations: only "7bit", "8bit", or "binary" are - permitted - - Security considerations: none - -B. Tolerant Applications - - Although this document specifies the requirements for the generation - of HTTP/1.0 messages, not all applications will be correct in their - implementation. We therefore recommend that operational applications - be tolerant of deviations whenever those deviations can be - interpreted unambiguously. - - Clients should be tolerant in parsing the Status-Line and servers - tolerant when parsing the Request-Line. In particular, they should - accept any amount of SP or HT characters between fields, even though - only a single SP is required. - - The line terminator for HTTP-header fields is the sequence CRLF. - However, we recommend that applications, when parsing such headers, - recognize a single LF as a line terminator and ignore the leading CR. - - - -Berners-Lee, et al Informational [Page 55] - -RFC 1945 HTTP/1.0 May 1996 - - -C. Relationship to MIME - - HTTP/1.0 uses many of the constructs defined for Internet Mail (RFC - 822 [7]) and the Multipurpose Internet Mail Extensions (MIME [5]) to - allow entities to be transmitted in an open variety of - representations and with extensible mechanisms. However, RFC 1521 - discusses mail, and HTTP has a few features that are different than - those described in RFC 1521. These differences were carefully chosen - to optimize performance over binary connections, to allow greater - freedom in the use of new media types, to make date comparisons - easier, and to acknowledge the practice of some early HTTP servers - and clients. - - At the time of this writing, it is expected that RFC 1521 will be - revised. The revisions may include some of the practices found in - HTTP/1.0 but not in RFC 1521. - - This appendix describes specific areas where HTTP differs from RFC - 1521. Proxies and gateways to strict MIME environments should be - aware of these differences and provide the appropriate conversions - where necessary. Proxies and gateways from MIME environments to HTTP - also need to be aware of the differences because some conversions may - be required. - -C.1 Conversion to Canonical Form - - RFC 1521 requires that an Internet mail entity be converted to - canonical form prior to being transferred, as described in Appendix G - of RFC 1521 [5]. Section 3.6.1 of this document describes the forms - allowed for subtypes of the "text" media type when transmitted over - HTTP. - - RFC 1521 requires that content with a Content-Type of "text" - represent line breaks as CRLF and forbids the use of CR or LF outside - of line break sequences. HTTP allows CRLF, bare CR, and bare LF to - indicate a line break within text content when a message is - transmitted over HTTP. - - Where it is possible, a proxy or gateway from HTTP to a strict RFC - 1521 environment should translate all line breaks within the text - media types described in Section 3.6.1 of this document to the RFC - 1521 canonical form of CRLF. Note, however, that this may be - complicated by the presence of a Content-Encoding and by the fact - that HTTP allows the use of some character sets which do not use - octets 13 and 10 to represent CR and LF, as is the case for some - multi-byte character sets. - - - - - -Berners-Lee, et al Informational [Page 56] - -RFC 1945 HTTP/1.0 May 1996 - - -C.2 Conversion of Date Formats - - HTTP/1.0 uses a restricted set of date formats (Section 3.3) to - simplify the process of date comparison. Proxies and gateways from - other protocols should ensure that any Date header field present in a - message conforms to one of the HTTP/1.0 formats and rewrite the date - if necessary. - -C.3 Introduction of Content-Encoding - - RFC 1521 does not include any concept equivalent to HTTP/1.0's - Content-Encoding header field. Since this acts as a modifier on the - media type, proxies and gateways from HTTP to MIME-compliant - protocols must either change the value of the Content-Type header - field or decode the Entity-Body before forwarding the message. (Some - experimental applications of Content-Type for Internet mail have used - a media-type parameter of ";conversions=<content-coding>" to perform - an equivalent function as Content-Encoding. However, this parameter - is not part of RFC 1521.) - -C.4 No Content-Transfer-Encoding - - HTTP does not use the Content-Transfer-Encoding (CTE) field of RFC - 1521. Proxies and gateways from MIME-compliant protocols to HTTP must - remove any non-identity CTE ("quoted-printable" or "base64") encoding - prior to delivering the response message to an HTTP client. - - Proxies and gateways from HTTP to MIME-compliant protocols are - responsible for ensuring that the message is in the correct format - and encoding for safe transport on that protocol, where "safe - transport" is defined by the limitations of the protocol being used. - Such a proxy or gateway should label the data with an appropriate - Content-Transfer-Encoding if doing so will improve the likelihood of - safe transport over the destination protocol. - -C.5 HTTP Header Fields in Multipart Body-Parts - - In RFC 1521, most header fields in multipart body-parts are generally - ignored unless the field name begins with "Content-". In HTTP/1.0, - multipart body-parts may contain any HTTP header fields which are - significant to the meaning of that part. - -D. Additional Features - - This appendix documents protocol elements used by some existing HTTP - implementations, but not consistently and correctly across most - HTTP/1.0 applications. Implementors should be aware of these - features, but cannot rely upon their presence in, or interoperability - - - -Berners-Lee, et al Informational [Page 57] - -RFC 1945 HTTP/1.0 May 1996 - - - with, other HTTP/1.0 applications. - -D.1 Additional Request Methods - -D.1.1 PUT - - The PUT method requests that the enclosed entity be stored under the - supplied Request-URI. If the Request-URI refers to an already - existing resource, the enclosed entity should be considered as a - modified version of the one residing on the origin server. If the - Request-URI does not point to an existing resource, and that URI is - capable of being defined as a new resource by the requesting user - agent, the origin server can create the resource with that URI. - - The fundamental difference between the POST and PUT requests is - reflected in the different meaning of the Request-URI. The URI in a - POST request identifies the resource that will handle the enclosed - entity as data to be processed. That resource may be a data-accepting - process, a gateway to some other protocol, or a separate entity that - accepts annotations. In contrast, the URI in a PUT request identifies - the entity enclosed with the request -- the user agent knows what URI - is intended and the server should not apply the request to some other - resource. - -D.1.2 DELETE - - The DELETE method requests that the origin server delete the resource - identified by the Request-URI. - -D.1.3 LINK - - The LINK method establishes one or more Link relationships between - the existing resource identified by the Request-URI and other - existing resources. - -D.1.4 UNLINK - - The UNLINK method removes one or more Link relationships from the - existing resource identified by the Request-URI. - -D.2 Additional Header Field Definitions - -D.2.1 Accept - - The Accept request-header field can be used to indicate a list of - media ranges which are acceptable as a response to the request. The - asterisk "*" character is used to group media types into ranges, with - "*/*" indicating all media types and "type/*" indicating all subtypes - - - -Berners-Lee, et al Informational [Page 58] - -RFC 1945 HTTP/1.0 May 1996 - - - of that type. The set of ranges given by the client should represent - what types are acceptable given the context of the request. - -D.2.2 Accept-Charset - - The Accept-Charset request-header field can be used to indicate a - list of preferred character sets other than the default US-ASCII and - ISO-8859-1. This field allows clients capable of understanding more - comprehensive or special-purpose character sets to signal that - capability to a server which is capable of representing documents in - those character sets. - -D.2.3 Accept-Encoding - - The Accept-Encoding request-header field is similar to Accept, but - restricts the content-coding values which are acceptable in the - response. - -D.2.4 Accept-Language - - The Accept-Language request-header field is similar to Accept, but - restricts the set of natural languages that are preferred as a - response to the request. - -D.2.5 Content-Language - - The Content-Language entity-header field describes the natural - language(s) of the intended audience for the enclosed entity. Note - that this may not be equivalent to all the languages used within the - entity. - -D.2.6 Link - - The Link entity-header field provides a means for describing a - relationship between the entity and some other resource. An entity - may include multiple Link values. Links at the metainformation level - typically indicate relationships like hierarchical structure and - navigation paths. - -D.2.7 MIME-Version - - HTTP messages may include a single MIME-Version general-header field - to indicate what version of the MIME protocol was used to construct - the message. Use of the MIME-Version header field, as defined by RFC - 1521 [5], should indicate that the message is MIME-conformant. - Unfortunately, some older HTTP/1.0 servers send it indiscriminately, - and thus this field should be ignored. - - - - -Berners-Lee, et al Informational [Page 59] - -RFC 1945 HTTP/1.0 May 1996 - - -D.2.8 Retry-After - - The Retry-After response-header field can be used with a 503 (service - unavailable) response to indicate how long the service is expected to - be unavailable to the requesting client. The value of this field can - be either an HTTP-date or an integer number of seconds (in decimal) - after the time of the response. - -D.2.9 Title - - The Title entity-header field indicates the title of the entity. - -D.2.10 URI - - The URI entity-header field may contain some or all of the Uniform - Resource Identifiers (Section 3.2) by which the Request-URI resource - can be identified. There is no guarantee that the resource can be - accessed using the URI(s) specified. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Berners-Lee, et al Informational [Page 60] - diff --git a/docs/specs/rfc2068.txt b/docs/specs/rfc2068.txt deleted file mode 100644 index e16e4fdf..00000000 --- a/docs/specs/rfc2068.txt +++ /dev/null @@ -1,9075 +0,0 @@ - - - - - - -Network Working Group R. Fielding -Request for Comments: 2068 UC Irvine -Category: Standards Track J. Gettys - J. Mogul - DEC - H. Frystyk - T. Berners-Lee - MIT/LCS - January 1997 - - - Hypertext Transfer Protocol -- HTTP/1.1 - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Abstract - - The Hypertext Transfer Protocol (HTTP) is an application-level - protocol for distributed, collaborative, hypermedia information - systems. It is a generic, stateless, object-oriented protocol which - can be used for many tasks, such as name servers and distributed - object management systems, through extension of its request methods. - A feature of HTTP is the typing and negotiation of data - representation, allowing systems to be built independently of the - data being transferred. - - HTTP has been in use by the World-Wide Web global information - initiative since 1990. This specification defines the protocol - referred to as "HTTP/1.1". - -Table of Contents - - 1 Introduction.............................................7 - 1.1 Purpose ..............................................7 - 1.2 Requirements .........................................7 - 1.3 Terminology ..........................................8 - 1.4 Overall Operation ...................................11 - 2 Notational Conventions and Generic Grammar..............13 - 2.1 Augmented BNF .......................................13 - 2.2 Basic Rules .........................................15 - 3 Protocol Parameters.....................................17 - 3.1 HTTP Version ........................................17 - - - -Fielding, et. al. Standards Track [Page 1] - -RFC 2068 HTTP/1.1 January 1997 - - - 3.2 Uniform Resource Identifiers ........................18 - 3.2.1 General Syntax ...................................18 - 3.2.2 http URL .........................................19 - 3.2.3 URI Comparison ...................................20 - 3.3 Date/Time Formats ...................................21 - 3.3.1 Full Date ........................................21 - 3.3.2 Delta Seconds ....................................22 - 3.4 Character Sets ......................................22 - 3.5 Content Codings .....................................23 - 3.6 Transfer Codings ....................................24 - 3.7 Media Types .........................................25 - 3.7.1 Canonicalization and Text Defaults ...............26 - 3.7.2 Multipart Types ..................................27 - 3.8 Product Tokens ......................................28 - 3.9 Quality Values ......................................28 - 3.10 Language Tags ......................................28 - 3.11 Entity Tags ........................................29 - 3.12 Range Units ........................................30 - 4 HTTP Message............................................30 - 4.1 Message Types .......................................30 - 4.2 Message Headers .....................................31 - 4.3 Message Body ........................................32 - 4.4 Message Length ......................................32 - 4.5 General Header Fields ...............................34 - 5 Request.................................................34 - 5.1 Request-Line ........................................34 - 5.1.1 Method ...........................................35 - 5.1.2 Request-URI ......................................35 - 5.2 The Resource Identified by a Request ................37 - 5.3 Request Header Fields ...............................37 - 6 Response................................................38 - 6.1 Status-Line .........................................38 - 6.1.1 Status Code and Reason Phrase ....................39 - 6.2 Response Header Fields ..............................41 - 7 Entity..................................................41 - 7.1 Entity Header Fields ................................41 - 7.2 Entity Body .........................................42 - 7.2.1 Type .............................................42 - 7.2.2 Length ...........................................43 - 8 Connections.............................................43 - 8.1 Persistent Connections ..............................43 - 8.1.1 Purpose ..........................................43 - 8.1.2 Overall Operation ................................44 - 8.1.3 Proxy Servers ....................................45 - 8.1.4 Practical Considerations .........................45 - 8.2 Message Transmission Requirements ...................46 - 9 Method Definitions......................................48 - 9.1 Safe and Idempotent Methods .........................48 - - - -Fielding, et. al. Standards Track [Page 2] - -RFC 2068 HTTP/1.1 January 1997 - - - 9.1.1 Safe Methods .....................................48 - 9.1.2 Idempotent Methods ...............................49 - 9.2 OPTIONS .............................................49 - 9.3 GET .................................................50 - 9.4 HEAD ................................................50 - 9.5 POST ................................................51 - 9.6 PUT .................................................52 - 9.7 DELETE ..............................................53 - 9.8 TRACE ...............................................53 - 10 Status Code Definitions................................53 - 10.1 Informational 1xx ..................................54 - 10.1.1 100 Continue ....................................54 - 10.1.2 101 Switching Protocols .........................54 - 10.2 Successful 2xx .....................................54 - 10.2.1 200 OK ..........................................54 - 10.2.2 201 Created .....................................55 - 10.2.3 202 Accepted ....................................55 - 10.2.4 203 Non-Authoritative Information ...............55 - 10.2.5 204 No Content ..................................55 - 10.2.6 205 Reset Content ...............................56 - 10.2.7 206 Partial Content .............................56 - 10.3 Redirection 3xx ....................................56 - 10.3.1 300 Multiple Choices ............................57 - 10.3.2 301 Moved Permanently ...........................57 - 10.3.3 302 Moved Temporarily ...........................58 - 10.3.4 303 See Other ...................................58 - 10.3.5 304 Not Modified ................................58 - 10.3.6 305 Use Proxy ...................................59 - 10.4 Client Error 4xx ...................................59 - 10.4.1 400 Bad Request .................................60 - 10.4.2 401 Unauthorized ................................60 - 10.4.3 402 Payment Required ............................60 - 10.4.4 403 Forbidden ...................................60 - 10.4.5 404 Not Found ...................................60 - 10.4.6 405 Method Not Allowed ..........................61 - 10.4.7 406 Not Acceptable ..............................61 - 10.4.8 407 Proxy Authentication Required ...............61 - 10.4.9 408 Request Timeout .............................62 - 10.4.10 409 Conflict ...................................62 - 10.4.11 410 Gone .......................................62 - 10.4.12 411 Length Required ............................63 - 10.4.13 412 Precondition Failed ........................63 - 10.4.14 413 Request Entity Too Large ...................63 - 10.4.15 414 Request-URI Too Long .......................63 - 10.4.16 415 Unsupported Media Type .....................63 - 10.5 Server Error 5xx ...................................64 - 10.5.1 500 Internal Server Error .......................64 - 10.5.2 501 Not Implemented .............................64 - - - -Fielding, et. al. Standards Track [Page 3] - -RFC 2068 HTTP/1.1 January 1997 - - - 10.5.3 502 Bad Gateway .................................64 - 10.5.4 503 Service Unavailable .........................64 - 10.5.5 504 Gateway Timeout .............................64 - 10.5.6 505 HTTP Version Not Supported ..................65 - 11 Access Authentication..................................65 - 11.1 Basic Authentication Scheme ........................66 - 11.2 Digest Authentication Scheme .......................67 - 12 Content Negotiation....................................67 - 12.1 Server-driven Negotiation ..........................68 - 12.2 Agent-driven Negotiation ...........................69 - 12.3 Transparent Negotiation ............................70 - 13 Caching in HTTP........................................70 - 13.1.1 Cache Correctness ...............................72 - 13.1.2 Warnings ........................................73 - 13.1.3 Cache-control Mechanisms ........................74 - 13.1.4 Explicit User Agent Warnings ....................74 - 13.1.5 Exceptions to the Rules and Warnings ............75 - 13.1.6 Client-controlled Behavior ......................75 - 13.2 Expiration Model ...................................75 - 13.2.1 Server-Specified Expiration .....................75 - 13.2.2 Heuristic Expiration ............................76 - 13.2.3 Age Calculations ................................77 - 13.2.4 Expiration Calculations .........................79 - 13.2.5 Disambiguating Expiration Values ................80 - 13.2.6 Disambiguating Multiple Responses ...............80 - 13.3 Validation Model ...................................81 - 13.3.1 Last-modified Dates .............................82 - 13.3.2 Entity Tag Cache Validators .....................82 - 13.3.3 Weak and Strong Validators ......................82 - 13.3.4 Rules for When to Use Entity Tags and Last- - modified Dates..........................................85 - 13.3.5 Non-validating Conditionals .....................86 - 13.4 Response Cachability ...............................86 - 13.5 Constructing Responses From Caches .................87 - 13.5.1 End-to-end and Hop-by-hop Headers ...............88 - 13.5.2 Non-modifiable Headers ..........................88 - 13.5.3 Combining Headers ...............................89 - 13.5.4 Combining Byte Ranges ...........................90 - 13.6 Caching Negotiated Responses .......................90 - 13.7 Shared and Non-Shared Caches .......................91 - 13.8 Errors or Incomplete Response Cache Behavior .......91 - 13.9 Side Effects of GET and HEAD .......................92 - 13.10 Invalidation After Updates or Deletions ...........92 - 13.11 Write-Through Mandatory ...........................93 - 13.12 Cache Replacement .................................93 - 13.13 History Lists .....................................93 - 14 Header Field Definitions...............................94 - 14.1 Accept .............................................95 - - - -Fielding, et. al. Standards Track [Page 4] - -RFC 2068 HTTP/1.1 January 1997 - - - 14.2 Accept-Charset .....................................97 - 14.3 Accept-Encoding ....................................97 - 14.4 Accept-Language ....................................98 - 14.5 Accept-Ranges ......................................99 - 14.6 Age ................................................99 - 14.7 Allow .............................................100 - 14.8 Authorization .....................................100 - 14.9 Cache-Control .....................................101 - 14.9.1 What is Cachable ...............................103 - 14.9.2 What May be Stored by Caches ...................103 - 14.9.3 Modifications of the Basic Expiration Mechanism 104 - 14.9.4 Cache Revalidation and Reload Controls .........105 - 14.9.5 No-Transform Directive .........................107 - 14.9.6 Cache Control Extensions .......................108 - 14.10 Connection .......................................109 - 14.11 Content-Base .....................................109 - 14.12 Content-Encoding .................................110 - 14.13 Content-Language .................................110 - 14.14 Content-Length ...................................111 - 14.15 Content-Location .................................112 - 14.16 Content-MD5 ......................................113 - 14.17 Content-Range ....................................114 - 14.18 Content-Type .....................................116 - 14.19 Date .............................................116 - 14.20 ETag .............................................117 - 14.21 Expires ..........................................117 - 14.22 From .............................................118 - 14.23 Host .............................................119 - 14.24 If-Modified-Since ................................119 - 14.25 If-Match .........................................121 - 14.26 If-None-Match ....................................122 - 14.27 If-Range .........................................123 - 14.28 If-Unmodified-Since ..............................124 - 14.29 Last-Modified ....................................124 - 14.30 Location .........................................125 - 14.31 Max-Forwards .....................................125 - 14.32 Pragma ...........................................126 - 14.33 Proxy-Authenticate ...............................127 - 14.34 Proxy-Authorization ..............................127 - 14.35 Public ...........................................127 - 14.36 Range ............................................128 - 14.36.1 Byte Ranges ...................................128 - 14.36.2 Range Retrieval Requests ......................130 - 14.37 Referer ..........................................131 - 14.38 Retry-After ......................................131 - 14.39 Server ...........................................132 - 14.40 Transfer-Encoding ................................132 - 14.41 Upgrade ..........................................132 - - - -Fielding, et. al. Standards Track [Page 5] - -RFC 2068 HTTP/1.1 January 1997 - - - 14.42 User-Agent .......................................134 - 14.43 Vary .............................................134 - 14.44 Via ..............................................135 - 14.45 Warning ..........................................137 - 14.46 WWW-Authenticate .................................139 - 15 Security Considerations...............................139 - 15.1 Authentication of Clients .........................139 - 15.2 Offering a Choice of Authentication Schemes .......140 - 15.3 Abuse of Server Log Information ...................141 - 15.4 Transfer of Sensitive Information .................141 - 15.5 Attacks Based On File and Path Names ..............142 - 15.6 Personal Information ..............................143 - 15.7 Privacy Issues Connected to Accept Headers ........143 - 15.8 DNS Spoofing ......................................144 - 15.9 Location Headers and Spoofing .....................144 - 16 Acknowledgments.......................................144 - 17 References............................................146 - 18 Authors' Addresses....................................149 - 19 Appendices............................................150 - 19.1 Internet Media Type message/http ..................150 - 19.2 Internet Media Type multipart/byteranges ..........150 - 19.3 Tolerant Applications .............................151 - 19.4 Differences Between HTTP Entities and - MIME Entities...........................................152 - 19.4.1 Conversion to Canonical Form ...................152 - 19.4.2 Conversion of Date Formats .....................153 - 19.4.3 Introduction of Content-Encoding ...............153 - 19.4.4 No Content-Transfer-Encoding ...................153 - 19.4.5 HTTP Header Fields in Multipart Body-Parts .....153 - 19.4.6 Introduction of Transfer-Encoding ..............154 - 19.4.7 MIME-Version ...................................154 - 19.5 Changes from HTTP/1.0 .............................154 - 19.5.1 Changes to Simplify Multi-homed Web Servers and - Conserve IP Addresses .................................155 - 19.6 Additional Features ...............................156 - 19.6.1 Additional Request Methods .....................156 - 19.6.2 Additional Header Field Definitions ............156 - 19.7 Compatibility with Previous Versions ..............160 - 19.7.1 Compatibility with HTTP/1.0 Persistent - Connections............................................161 - - - - - - - - - - - -Fielding, et. al. Standards Track [Page 6] - -RFC 2068 HTTP/1.1 January 1997 - - -1 Introduction - -1.1 Purpose - - The Hypertext Transfer Protocol (HTTP) is an application-level - protocol for distributed, collaborative, hypermedia information - systems. HTTP has been in use by the World-Wide Web global - information initiative since 1990. The first version of HTTP, - referred to as HTTP/0.9, was a simple protocol for raw data transfer - across the Internet. HTTP/1.0, as defined by RFC 1945 [6], improved - the protocol by allowing messages to be in the format of MIME-like - messages, containing metainformation about the data transferred and - modifiers on the request/response semantics. However, HTTP/1.0 does - not sufficiently take into consideration the effects of hierarchical - proxies, caching, the need for persistent connections, and virtual - hosts. In addition, the proliferation of incompletely-implemented - applications calling themselves "HTTP/1.0" has necessitated a - protocol version change in order for two communicating applications - to determine each other's true capabilities. - - This specification defines the protocol referred to as "HTTP/1.1". - This protocol includes more stringent requirements than HTTP/1.0 in - order to ensure reliable implementation of its features. - - Practical information systems require more functionality than simple - retrieval, including search, front-end update, and annotation. HTTP - allows an open-ended set of methods that indicate the purpose of a - request. It builds on the discipline of reference provided by the - Uniform Resource Identifier (URI) [3][20], as a location (URL) [4] or - name (URN) , for indicating the resource to which a method is to be - applied. Messages are passed in a format similar to that used by - Internet mail as defined by the Multipurpose Internet Mail Extensions - (MIME). - - HTTP is also used as a generic protocol for communication between - user agents and proxies/gateways to other Internet systems, including - those supported by the SMTP [16], NNTP [13], FTP [18], Gopher [2], - and WAIS [10] protocols. In this way, HTTP allows basic hypermedia - access to resources available from diverse applications. - -1.2 Requirements - - This specification uses the same words as RFC 1123 [8] for defining - the significance of each particular requirement. These words are: - - MUST - This word or the adjective "required" means that the item is an - absolute requirement of the specification. - - - -Fielding, et. al. Standards Track [Page 7] - -RFC 2068 HTTP/1.1 January 1997 - - - SHOULD - This word or the adjective "recommended" means that there may - exist valid reasons in particular circumstances to ignore this - item, but the full implications should be understood and the case - carefully weighed before choosing a different course. - - MAY - This word or the adjective "optional" means that this item is - truly optional. One vendor may choose to include the item because - a particular marketplace requires it or because it enhances the - product, for example; another vendor may omit the same item. - - An implementation is not compliant if it fails to satisfy one or more - of the MUST requirements for the protocols it implements. An - implementation that satisfies all the MUST and all the SHOULD - requirements for its protocols is said to be "unconditionally - compliant"; one that satisfies all the MUST requirements but not all - the SHOULD requirements for its protocols is said to be - "conditionally compliant." - -1.3 Terminology - - This specification uses a number of terms to refer to the roles - played by participants in, and objects of, the HTTP communication. - - connection - A transport layer virtual circuit established between two programs - for the purpose of communication. - - message - The basic unit of HTTP communication, consisting of a structured - sequence of octets matching the syntax defined in section 4 and - transmitted via the connection. - - request - An HTTP request message, as defined in section 5. - - response - An HTTP response message, as defined in section 6. - - resource - A network data object or service that can be identified by a URI, - as defined in section 3.2. Resources may be available in multiple - representations (e.g. multiple languages, data formats, size, - resolutions) or vary in other ways. - - - - - - -Fielding, et. al. Standards Track [Page 8] - -RFC 2068 HTTP/1.1 January 1997 - - - entity - The information transferred as the payload of a request or - response. An entity consists of metainformation in the form of - entity-header fields and content in the form of an entity-body, as - described in section 7. - - representation - An entity included with a response that is subject to content - negotiation, as described in section 12. There may exist multiple - representations associated with a particular response status. - - content negotiation - The mechanism for selecting the appropriate representation when - servicing a request, as described in section 12. The - representation of entities in any response can be negotiated - (including error responses). - - variant - A resource may have one, or more than one, representation(s) - associated with it at any given instant. Each of these - representations is termed a `variant.' Use of the term `variant' - does not necessarily imply that the resource is subject to content - negotiation. - - client - A program that establishes connections for the purpose of sending - requests. - - user agent - The client which initiates a request. These are often browsers, - editors, spiders (web-traversing robots), or other end user tools. - - server - An application program that accepts connections in order to - service requests by sending back responses. Any given program may - be capable of being both a client and a server; our use of these - terms refers only to the role being performed by the program for a - particular connection, rather than to the program's capabilities - in general. Likewise, any server may act as an origin server, - proxy, gateway, or tunnel, switching behavior based on the nature - of each request. - - origin server - The server on which a given resource resides or is to be created. - - - - - - - -Fielding, et. al. Standards Track [Page 9] - -RFC 2068 HTTP/1.1 January 1997 - - - proxy - An intermediary program which acts as both a server and a client - for the purpose of making requests on behalf of other clients. - Requests are serviced internally or by passing them on, with - possible translation, to other servers. A proxy must implement - both the client and server requirements of this specification. - - gateway - A server which acts as an intermediary for some other server. - Unlike a proxy, a gateway receives requests as if it were the - origin server for the requested resource; the requesting client - may not be aware that it is communicating with a gateway. - - tunnel - An intermediary program which is acting as a blind relay between - two connections. Once active, a tunnel is not considered a party - to the HTTP communication, though the tunnel may have been - initiated by an HTTP request. The tunnel ceases to exist when both - ends of the relayed connections are closed. - - cache - A program's local store of response messages and the subsystem - that controls its message storage, retrieval, and deletion. A - cache stores cachable responses in order to reduce the response - time and network bandwidth consumption on future, equivalent - requests. Any client or server may include a cache, though a cache - cannot be used by a server that is acting as a tunnel. - - cachable - A response is cachable if a cache is allowed to store a copy of - the response message for use in answering subsequent requests. The - rules for determining the cachability of HTTP responses are - defined in section 13. Even if a resource is cachable, there may - be additional constraints on whether a cache can use the cached - copy for a particular request. - - first-hand - A response is first-hand if it comes directly and without - unnecessary delay from the origin server, perhaps via one or more - proxies. A response is also first-hand if its validity has just - been checked directly with the origin server. - - explicit expiration time - The time at which the origin server intends that an entity should - no longer be returned by a cache without further validation. - - - - - - -Fielding, et. al. Standards Track [Page 10] - -RFC 2068 HTTP/1.1 January 1997 - - - heuristic expiration time - An expiration time assigned by a cache when no explicit expiration - time is available. - - age - The age of a response is the time since it was sent by, or - successfully validated with, the origin server. - - freshness lifetime - The length of time between the generation of a response and its - expiration time. - - fresh - A response is fresh if its age has not yet exceeded its freshness - lifetime. - - stale - A response is stale if its age has passed its freshness lifetime. - - semantically transparent - A cache behaves in a "semantically transparent" manner, with - respect to a particular response, when its use affects neither the - requesting client nor the origin server, except to improve - performance. When a cache is semantically transparent, the client - receives exactly the same response (except for hop-by-hop headers) - that it would have received had its request been handled directly - by the origin server. - - validator - A protocol element (e.g., an entity tag or a Last-Modified time) - that is used to find out whether a cache entry is an equivalent - copy of an entity. - -1.4 Overall Operation - - The HTTP protocol is a request/response protocol. A client sends a - request to the server in the form of a request method, URI, and - protocol version, followed by a MIME-like message containing request - modifiers, client information, and possible body content over a - connection with a server. The server responds with a status line, - including the message's protocol version and a success or error code, - followed by a MIME-like message containing server information, entity - metainformation, and possible entity-body content. The relationship - between HTTP and MIME is described in appendix 19.4. - - - - - - - -Fielding, et. al. Standards Track [Page 11] - -RFC 2068 HTTP/1.1 January 1997 - - - Most HTTP communication is initiated by a user agent and consists of - a request to be applied to a resource on some origin server. In the - simplest case, this may be accomplished via a single connection (v) - between the user agent (UA) and the origin server (O). - - request chain ------------------------> - UA -------------------v------------------- O - <----------------------- response chain - - A more complicated situation occurs when one or more intermediaries - are present in the request/response chain. There are three common - forms of intermediary: proxy, gateway, and tunnel. A proxy is a - forwarding agent, receiving requests for a URI in its absolute form, - rewriting all or part of the message, and forwarding the reformatted - request toward the server identified by the URI. A gateway is a - receiving agent, acting as a layer above some other server(s) and, if - necessary, translating the requests to the underlying server's - protocol. A tunnel acts as a relay point between two connections - without changing the messages; tunnels are used when the - communication needs to pass through an intermediary (such as a - firewall) even when the intermediary cannot understand the contents - of the messages. - - request chain --------------------------------------> - UA -----v----- A -----v----- B -----v----- C -----v----- O - <------------------------------------- response chain - - The figure above shows three intermediaries (A, B, and C) between the - user agent and origin server. A request or response message that - travels the whole chain will pass through four separate connections. - This distinction is important because some HTTP communication options - may apply only to the connection with the nearest, non-tunnel - neighbor, only to the end-points of the chain, or to all connections - along the chain. Although the diagram is linear, each participant - may be engaged in multiple, simultaneous communications. For example, - B may be receiving requests from many clients other than A, and/or - forwarding requests to servers other than C, at the same time that it - is handling A's request. - - Any party to the communication which is not acting as a tunnel may - employ an internal cache for handling requests. The effect of a cache - is that the request/response chain is shortened if one of the - participants along the chain has a cached response applicable to that - request. The following illustrates the resulting chain if B has a - cached copy of an earlier response from O (via C) for a request which - has not been cached by UA or A. - - - - - -Fielding, et. al. Standards Track [Page 12] - -RFC 2068 HTTP/1.1 January 1997 - - - request chain ----------> - UA -----v----- A -----v----- B - - - - - - C - - - - - - O - <--------- response chain - - Not all responses are usefully cachable, and some requests may - contain modifiers which place special requirements on cache behavior. - HTTP requirements for cache behavior and cachable responses are - defined in section 13. - - In fact, there are a wide variety of architectures and configurations - of caches and proxies currently being experimented with or deployed - across the World Wide Web; these systems include national hierarchies - of proxy caches to save transoceanic bandwidth, systems that - broadcast or multicast cache entries, organizations that distribute - subsets of cached data via CD-ROM, and so on. HTTP systems are used - in corporate intranets over high-bandwidth links, and for access via - PDAs with low-power radio links and intermittent connectivity. The - goal of HTTP/1.1 is to support the wide diversity of configurations - already deployed while introducing protocol constructs that meet the - needs of those who build web applications that require high - reliability and, failing that, at least reliable indications of - failure. - - HTTP communication usually takes place over TCP/IP connections. The - default port is TCP 80, but other ports can be used. This does not - preclude HTTP from being implemented on top of any other protocol on - the Internet, or on other networks. HTTP only presumes a reliable - transport; any protocol that provides such guarantees can be used; - the mapping of the HTTP/1.1 request and response structures onto the - transport data units of the protocol in question is outside the scope - of this specification. - - In HTTP/1.0, most implementations used a new connection for each - request/response exchange. In HTTP/1.1, a connection may be used for - one or more request/response exchanges, although connections may be - closed for a variety of reasons (see section 8.1). - -2 Notational Conventions and Generic Grammar - -2.1 Augmented BNF - - All of the mechanisms specified in this document are described in - both prose and an augmented Backus-Naur Form (BNF) similar to that - used by RFC 822 [9]. Implementers will need to be familiar with the - notation in order to understand this specification. The augmented BNF - includes the following constructs: - - - - - -Fielding, et. al. Standards Track [Page 13] - -RFC 2068 HTTP/1.1 January 1997 - - -name = definition - The name of a rule is simply the name itself (without any enclosing - "<" and ">") and is separated from its definition by the equal "=" - character. Whitespace is only significant in that indentation of - continuation lines is used to indicate a rule definition that spans - more than one line. Certain basic rules are in uppercase, such as - SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle brackets are used - within definitions whenever their presence will facilitate - discerning the use of rule names. - -"literal" - Quotation marks surround literal text. Unless stated otherwise, the - text is case-insensitive. - -rule1 | rule2 - Elements separated by a bar ("|") are alternatives, e.g., "yes | - no" will accept yes or no. - -(rule1 rule2) - Elements enclosed in parentheses are treated as a single element. - Thus, "(elem (foo | bar) elem)" allows the token sequences "elem - foo elem" and "elem bar elem". - -*rule - The character "*" preceding an element indicates repetition. The - full form is "<n>*<m>element" indicating at least <n> and at most - <m> occurrences of element. Default values are 0 and infinity so - that "*(element)" allows any number, including zero; "1*element" - requires at least one; and "1*2element" allows one or two. - -[rule] - Square brackets enclose optional elements; "[foo bar]" is - equivalent to "*1(foo bar)". - -N rule - Specific repetition: "<n>(element)" is equivalent to - "<n>*<n>(element)"; that is, exactly <n> occurrences of (element). - Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three - alphabetic characters. - -#rule - A construct "#" is defined, similar to "*", for defining lists of - elements. The full form is "<n>#<m>element " indicating at least - <n> and at most <m> elements, each separated by one or more commas - (",") and optional linear whitespace (LWS). This makes the usual - form of lists very easy; a rule such as "( *LWS element *( *LWS "," - *LWS element )) " can be shown as "1#element". Wherever this - construct is used, null elements are allowed, but do not contribute - - - -Fielding, et. al. Standards Track [Page 14] - -RFC 2068 HTTP/1.1 January 1997 - - - to the count of elements present. That is, "(element), , (element) - " is permitted, but counts as only two elements. Therefore, where - at least one element is required, at least one non-null element - must be present. Default values are 0 and infinity so that - "#element" allows any number, including zero; "1#element" requires - at least one; and "1#2element" allows one or two. - -; comment - A semi-colon, set off some distance to the right of rule text, - starts a comment that continues to the end of line. This is a - simple way of including useful notes in parallel with the - specifications. - -implied *LWS - The grammar described by this specification is word-based. Except - where noted otherwise, linear whitespace (LWS) can be included - between any two adjacent words (token or quoted-string), and - between adjacent tokens and delimiters (tspecials), without - changing the interpretation of a field. At least one delimiter - (tspecials) must exist between any two tokens, since they would - otherwise be interpreted as a single token. - -2.2 Basic Rules - - The following rules are used throughout this specification to - describe basic parsing constructs. The US-ASCII coded character set - is defined by ANSI X3.4-1986 [21]. - - OCTET = <any 8-bit sequence of data> - CHAR = <any US-ASCII character (octets 0 - 127)> - UPALPHA = <any US-ASCII uppercase letter "A".."Z"> - LOALPHA = <any US-ASCII lowercase letter "a".."z"> - ALPHA = UPALPHA | LOALPHA - DIGIT = <any US-ASCII digit "0".."9"> - CTL = <any US-ASCII control character - (octets 0 - 31) and DEL (127)> - CR = <US-ASCII CR, carriage return (13)> - LF = <US-ASCII LF, linefeed (10)> - SP = <US-ASCII SP, space (32)> - HT = <US-ASCII HT, horizontal-tab (9)> - <"> = <US-ASCII double-quote mark (34)> - - - - - - - - - - -Fielding, et. al. Standards Track [Page 15] - -RFC 2068 HTTP/1.1 January 1997 - - - HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all - protocol elements except the entity-body (see appendix 19.3 for - tolerant applications). The end-of-line marker within an entity-body - is defined by its associated media type, as described in section 3.7. - - CRLF = CR LF - - HTTP/1.1 headers can be folded onto multiple lines if the - continuation line begins with a space or horizontal tab. All linear - white space, including folding, has the same semantics as SP. - - LWS = [CRLF] 1*( SP | HT ) - - The TEXT rule is only used for descriptive field contents and values - that are not intended to be interpreted by the message parser. Words - of *TEXT may contain characters from character sets other than ISO - 8859-1 [22] only when encoded according to the rules of RFC 1522 - [14]. - - TEXT = <any OCTET except CTLs, - but including LWS> - - Hexadecimal numeric characters are used in several protocol elements. - - HEX = "A" | "B" | "C" | "D" | "E" | "F" - | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT - - Many HTTP/1.1 header field values consist of words separated by LWS - or special characters. These special characters MUST be in a quoted - string to be used within a parameter value. - - token = 1*<any CHAR except CTLs or tspecials> - - tspecials = "(" | ")" | "<" | ">" | "@" - | "," | ";" | ":" | "\" | <"> - | "/" | "[" | "]" | "?" | "=" - | "{" | "}" | SP | HT - - Comments can be included in some HTTP header fields by surrounding - the comment text with parentheses. Comments are only allowed in - fields containing "comment" as part of their field value definition. - In all other fields, parentheses are considered part of the field - value. - - comment = "(" *( ctext | comment ) ")" - ctext = <any TEXT excluding "(" and ")"> - - - - - -Fielding, et. al. Standards Track [Page 16] - -RFC 2068 HTTP/1.1 January 1997 - - - A string of text is parsed as a single word if it is quoted using - double-quote marks. - - quoted-string = ( <"> *(qdtext) <"> ) - - qdtext = <any TEXT except <">> - - The backslash character ("\") may be used as a single-character quoting - mechanism only within quoted-string and comment constructs. - - quoted-pair = "\" CHAR - -3 Protocol Parameters - -3.1 HTTP Version - - HTTP uses a "<major>.<minor>" numbering scheme to indicate versions - of the protocol. The protocol versioning policy is intended to allow - the sender to indicate the format of a message and its capacity for - understanding further HTTP communication, rather than the features - obtained via that communication. No change is made to the version - number for the addition of message components which do not affect - communication behavior or which only add to extensible field values. - The <minor> number is incremented when the changes made to the - protocol add features which do not change the general message parsing - algorithm, but which may add to the message semantics and imply - additional capabilities of the sender. The <major> number is - incremented when the format of a message within the protocol is - changed. - - The version of an HTTP message is indicated by an HTTP-Version field - in the first line of the message. - - HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT - - Note that the major and minor numbers MUST be treated as separate - integers and that each may be incremented higher than a single digit. - Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is - lower than HTTP/12.3. Leading zeros MUST be ignored by recipients and - MUST NOT be sent. - - Applications sending Request or Response messages, as defined by this - specification, MUST include an HTTP-Version of "HTTP/1.1". Use of - this version number indicates that the sending application is at - least conditionally compliant with this specification. - - The HTTP version of an application is the highest HTTP version for - which the application is at least conditionally compliant. - - - -Fielding, et. al. Standards Track [Page 17] - -RFC 2068 HTTP/1.1 January 1997 - - - Proxy and gateway applications must be careful when forwarding - messages in protocol versions different from that of the application. - Since the protocol version indicates the protocol capability of the - sender, a proxy/gateway MUST never send a message with a version - indicator which is greater than its actual version; if a higher - version request is received, the proxy/gateway MUST either downgrade - the request version, respond with an error, or switch to tunnel - behavior. Requests with a version lower than that of the - proxy/gateway's version MAY be upgraded before being forwarded; the - proxy/gateway's response to that request MUST be in the same major - version as the request. - - Note: Converting between versions of HTTP may involve modification - of header fields required or forbidden by the versions involved. - -3.2 Uniform Resource Identifiers - - URIs have been known by many names: WWW addresses, Universal Document - Identifiers, Universal Resource Identifiers , and finally the - combination of Uniform Resource Locators (URL) and Names (URN). As - far as HTTP is concerned, Uniform Resource Identifiers are simply - formatted strings which identify--via name, location, or any other - characteristic--a resource. - -3.2.1 General Syntax - - URIs in HTTP can be represented in absolute form or relative to some - known base URI, depending upon the context of their use. The two - forms are differentiated by the fact that absolute URIs always begin - with a scheme name followed by a colon. - - URI = ( absoluteURI | relativeURI ) [ "#" fragment ] - - absoluteURI = scheme ":" *( uchar | reserved ) - - relativeURI = net_path | abs_path | rel_path - - net_path = "//" net_loc [ abs_path ] - abs_path = "/" rel_path - rel_path = [ path ] [ ";" params ] [ "?" query ] - - path = fsegment *( "/" segment ) - fsegment = 1*pchar - segment = *pchar - - params = param *( ";" param ) - param = *( pchar | "/" ) - - - - -Fielding, et. al. Standards Track [Page 18] - -RFC 2068 HTTP/1.1 January 1997 - - - scheme = 1*( ALPHA | DIGIT | "+" | "-" | "." ) - net_loc = *( pchar | ";" | "?" ) - - query = *( uchar | reserved ) - fragment = *( uchar | reserved ) - - pchar = uchar | ":" | "@" | "&" | "=" | "+" - uchar = unreserved | escape - unreserved = ALPHA | DIGIT | safe | extra | national - - escape = "%" HEX HEX - reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" - extra = "!" | "*" | "'" | "(" | ")" | "," - safe = "$" | "-" | "_" | "." - unsafe = CTL | SP | <"> | "#" | "%" | "<" | ">" - national = <any OCTET excluding ALPHA, DIGIT, - reserved, extra, safe, and unsafe> - - For definitive information on URL syntax and semantics, see RFC 1738 - [4] and RFC 1808 [11]. The BNF above includes national characters not - allowed in valid URLs as specified by RFC 1738, since HTTP servers - are not restricted in the set of unreserved characters allowed to - represent the rel_path part of addresses, and HTTP proxies may - receive requests for URIs not defined by RFC 1738. - - The HTTP protocol does not place any a priori limit on the length of - a URI. Servers MUST be able to handle the URI of any resource they - serve, and SHOULD be able to handle URIs of unbounded length if they - provide GET-based forms that could generate such URIs. A server - SHOULD return 414 (Request-URI Too Long) status if a URI is longer - than the server can handle (see section 10.4.15). - - Note: Servers should be cautious about depending on URI lengths - above 255 bytes, because some older client or proxy implementations - may not properly support these lengths. - -3.2.2 http URL - - The "http" scheme is used to locate network resources via the HTTP - protocol. This section defines the scheme-specific syntax and - semantics for http URLs. - - - - - - - - - - -Fielding, et. al. Standards Track [Page 19] - -RFC 2068 HTTP/1.1 January 1997 - - - http_URL = "http:" "//" host [ ":" port ] [ abs_path ] - - host = <A legal Internet host domain name - or IP address (in dotted-decimal form), - as defined by Section 2.1 of RFC 1123> - - port = *DIGIT - - If the port is empty or not given, port 80 is assumed. The semantics - are that the identified resource is located at the server listening - for TCP connections on that port of that host, and the Request-URI - for the resource is abs_path. The use of IP addresses in URL's SHOULD - be avoided whenever possible (see RFC 1900 [24]). If the abs_path is - not present in the URL, it MUST be given as "/" when used as a - Request-URI for a resource (section 5.1.2). - -3.2.3 URI Comparison - - When comparing two URIs to decide if they match or not, a client - SHOULD use a case-sensitive octet-by-octet comparison of the entire - URIs, with these exceptions: - - o A port that is empty or not given is equivalent to the default - port for that URI; - - o Comparisons of host names MUST be case-insensitive; - - o Comparisons of scheme names MUST be case-insensitive; - - o An empty abs_path is equivalent to an abs_path of "/". - - Characters other than those in the "reserved" and "unsafe" sets (see - section 3.2) are equivalent to their ""%" HEX HEX" encodings. - - For example, the following three URIs are equivalent: - - http://abc.com:80/~smith/home.html - http://ABC.com/%7Esmith/home.html - http://ABC.com:/%7esmith/home.html - - - - - - - - - - - - -Fielding, et. al. Standards Track [Page 20] - -RFC 2068 HTTP/1.1 January 1997 - - -3.3 Date/Time Formats - -3.3.1 Full Date - - HTTP applications have historically allowed three different formats - for the representation of date/time stamps: - - Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 - Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 - Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format - - The first format is preferred as an Internet standard and represents - a fixed-length subset of that defined by RFC 1123 (an update to RFC - 822). The second format is in common use, but is based on the - obsolete RFC 850 [12] date format and lacks a four-digit year. - HTTP/1.1 clients and servers that parse the date value MUST accept - all three formats (for compatibility with HTTP/1.0), though they MUST - only generate the RFC 1123 format for representing HTTP-date values - in header fields. - - Note: Recipients of date values are encouraged to be robust in - accepting date values that may have been sent by non-HTTP - applications, as is sometimes the case when retrieving or posting - messages via proxies/gateways to SMTP or NNTP. - - All HTTP date/time stamps MUST be represented in Greenwich Mean Time - (GMT), without exception. This is indicated in the first two formats - by the inclusion of "GMT" as the three-letter abbreviation for time - zone, and MUST be assumed when reading the asctime format. - - HTTP-date = rfc1123-date | rfc850-date | asctime-date - - rfc1123-date = wkday "," SP date1 SP time SP "GMT" - rfc850-date = weekday "," SP date2 SP time SP "GMT" - asctime-date = wkday SP date3 SP time SP 4DIGIT - - date1 = 2DIGIT SP month SP 4DIGIT - ; day month year (e.g., 02 Jun 1982) - date2 = 2DIGIT "-" month "-" 2DIGIT - ; day-month-year (e.g., 02-Jun-82) - date3 = month SP ( 2DIGIT | ( SP 1DIGIT )) - ; month day (e.g., Jun 2) - - time = 2DIGIT ":" 2DIGIT ":" 2DIGIT - ; 00:00:00 - 23:59:59 - - wkday = "Mon" | "Tue" | "Wed" - | "Thu" | "Fri" | "Sat" | "Sun" - - - -Fielding, et. al. Standards Track [Page 21] - -RFC 2068 HTTP/1.1 January 1997 - - - weekday = "Monday" | "Tuesday" | "Wednesday" - | "Thursday" | "Friday" | "Saturday" | "Sunday" - - month = "Jan" | "Feb" | "Mar" | "Apr" - | "May" | "Jun" | "Jul" | "Aug" - | "Sep" | "Oct" | "Nov" | "Dec" - - Note: HTTP requirements for the date/time stamp format apply only - to their usage within the protocol stream. Clients and servers are - not required to use these formats for user presentation, request - logging, etc. - -3.3.2 Delta Seconds - - Some HTTP header fields allow a time value to be specified as an - integer number of seconds, represented in decimal, after the time - that the message was received. - - delta-seconds = 1*DIGIT - -3.4 Character Sets - - HTTP uses the same definition of the term "character set" as that - described for MIME: - - The term "character set" is used in this document to refer to a - method used with one or more tables to convert a sequence of octets - into a sequence of characters. Note that unconditional conversion - in the other direction is not required, in that not all characters - may be available in a given character set and a character set may - provide more than one sequence of octets to represent a particular - character. This definition is intended to allow various kinds of - character encodings, from simple single-table mappings such as US- - ASCII to complex table switching methods such as those that use ISO - 2022's techniques. However, the definition associated with a MIME - character set name MUST fully specify the mapping to be performed - from octets to characters. In particular, use of external profiling - information to determine the exact mapping is not permitted. - - Note: This use of the term "character set" is more commonly - referred to as a "character encoding." However, since HTTP and MIME - share the same registry, it is important that the terminology also - be shared. - - - - - - - - -Fielding, et. al. Standards Track [Page 22] - -RFC 2068 HTTP/1.1 January 1997 - - - HTTP character sets are identified by case-insensitive tokens. The - complete set of tokens is defined by the IANA Character Set registry - [19]. - - charset = token - - Although HTTP allows an arbitrary token to be used as a charset - value, any token that has a predefined value within the IANA - Character Set registry MUST represent the character set defined by - that registry. Applications SHOULD limit their use of character sets - to those defined by the IANA registry. - -3.5 Content Codings - - Content coding values indicate an encoding transformation that has - been or can be applied to an entity. Content codings are primarily - used to allow a document to be compressed or otherwise usefully - transformed without losing the identity of its underlying media type - and without loss of information. Frequently, the entity is stored in - coded form, transmitted directly, and only decoded by the recipient. - - content-coding = token - - All content-coding values are case-insensitive. HTTP/1.1 uses - content-coding values in the Accept-Encoding (section 14.3) and - Content-Encoding (section 14.12) header fields. Although the value - describes the content-coding, what is more important is that it - indicates what decoding mechanism will be required to remove the - encoding. - - The Internet Assigned Numbers Authority (IANA) acts as a registry for - content-coding value tokens. Initially, the registry contains the - following tokens: - - gzip An encoding format produced by the file compression program "gzip" - (GNU zip) as described in RFC 1952 [25]. This format is a Lempel- - Ziv coding (LZ77) with a 32 bit CRC. - - compress - The encoding format produced by the common UNIX file compression - program "compress". This format is an adaptive Lempel-Ziv-Welch - coding (LZW). - - - - - - - - - -Fielding, et. al. Standards Track [Page 23] - -RFC 2068 HTTP/1.1 January 1997 - - - Note: Use of program names for the identification of encoding - formats is not desirable and should be discouraged for future - encodings. Their use here is representative of historical practice, - not good design. For compatibility with previous implementations of - HTTP, applications should consider "x-gzip" and "x-compress" to be - equivalent to "gzip" and "compress" respectively. - - deflate The "zlib" format defined in RFC 1950[31] in combination with - the "deflate" compression mechanism described in RFC 1951[29]. - - New content-coding value tokens should be registered; to allow - interoperability between clients and servers, specifications of the - content coding algorithms needed to implement a new value should be - publicly available and adequate for independent implementation, and - conform to the purpose of content coding defined in this section. - -3.6 Transfer Codings - - Transfer coding values are used to indicate an encoding - transformation that has been, can be, or may need to be applied to an - entity-body in order to ensure "safe transport" through the network. - This differs from a content coding in that the transfer coding is a - property of the message, not of the original entity. - - transfer-coding = "chunked" | transfer-extension - - transfer-extension = token - - All transfer-coding values are case-insensitive. HTTP/1.1 uses - transfer coding values in the Transfer-Encoding header field (section - 14.40). - - Transfer codings are analogous to the Content-Transfer-Encoding - values of MIME , which were designed to enable safe transport of - binary data over a 7-bit transport service. However, safe transport - has a different focus for an 8bit-clean transfer protocol. In HTTP, - the only unsafe characteristic of message-bodies is the difficulty in - determining the exact body length (section 7.2.2), or the desire to - encrypt data over a shared transport. - - The chunked encoding modifies the body of a message in order to - transfer it as a series of chunks, each with its own size indicator, - followed by an optional footer containing entity-header fields. This - allows dynamically-produced content to be transferred along with the - information necessary for the recipient to verify that it has - received the full message. - - - - - -Fielding, et. al. Standards Track [Page 24] - -RFC 2068 HTTP/1.1 January 1997 - - - Chunked-Body = *chunk - "0" CRLF - footer - CRLF - - chunk = chunk-size [ chunk-ext ] CRLF - chunk-data CRLF - - hex-no-zero = <HEX excluding "0"> - - chunk-size = hex-no-zero *HEX - chunk-ext = *( ";" chunk-ext-name [ "=" chunk-ext-value ] ) - chunk-ext-name = token - chunk-ext-val = token | quoted-string - chunk-data = chunk-size(OCTET) - - footer = *entity-header - - The chunked encoding is ended by a zero-sized chunk followed by the - footer, which is terminated by an empty line. The purpose of the - footer is to provide an efficient way to supply information about an - entity that is generated dynamically; applications MUST NOT send - header fields in the footer which are not explicitly defined as being - appropriate for the footer, such as Content-MD5 or future extensions - to HTTP for digital signatures or other facilities. - - An example process for decoding a Chunked-Body is presented in - appendix 19.4.6. - - All HTTP/1.1 applications MUST be able to receive and decode the - "chunked" transfer coding, and MUST ignore transfer coding extensions - they do not understand. A server which receives an entity-body with a - transfer-coding it does not understand SHOULD return 501 - (Unimplemented), and close the connection. A server MUST NOT send - transfer-codings to an HTTP/1.0 client. - -3.7 Media Types - - HTTP uses Internet Media Types in the Content-Type (section 14.18) - and Accept (section 14.1) header fields in order to provide open and - extensible data typing and type negotiation. - - media-type = type "/" subtype *( ";" parameter ) - type = token - subtype = token - - Parameters may follow the type/subtype in the form of attribute/value - pairs. - - - -Fielding, et. al. Standards Track [Page 25] - -RFC 2068 HTTP/1.1 January 1997 - - - parameter = attribute "=" value - attribute = token - value = token | quoted-string - - The type, subtype, and parameter attribute names are case- - insensitive. Parameter values may or may not be case-sensitive, - depending on the semantics of the parameter name. Linear white space - (LWS) MUST NOT be used between the type and subtype, nor between an - attribute and its value. User agents that recognize the media-type - MUST process (or arrange to be processed by any external applications - used to process that type/subtype by the user agent) the parameters - for that MIME type as described by that type/subtype definition to - the and inform the user of any problems discovered. - - Note: some older HTTP applications do not recognize media type - parameters. When sending data to older HTTP applications, - implementations should only use media type parameters when they are - required by that type/subtype definition. - - Media-type values are registered with the Internet Assigned Number - Authority (IANA). The media type registration process is outlined in - RFC 2048 [17]. Use of non-registered media types is discouraged. - -3.7.1 Canonicalization and Text Defaults - - Internet media types are registered with a canonical form. In - general, an entity-body transferred via HTTP messages MUST be - represented in the appropriate canonical form prior to its - transmission; the exception is "text" types, as defined in the next - paragraph. - - When in canonical form, media subtypes of the "text" type use CRLF as - the text line break. HTTP relaxes this requirement and allows the - transport of text media with plain CR or LF alone representing a line - break when it is done consistently for an entire entity-body. HTTP - applications MUST accept CRLF, bare CR, and bare LF as being - representative of a line break in text media received via HTTP. In - addition, if the text is represented in a character set that does not - use octets 13 and 10 for CR and LF respectively, as is the case for - some multi-byte character sets, HTTP allows the use of whatever octet - sequences are defined by that character set to represent the - equivalent of CR and LF for line breaks. This flexibility regarding - line breaks applies only to text media in the entity-body; a bare CR - or LF MUST NOT be substituted for CRLF within any of the HTTP control - structures (such as header fields and multipart boundaries). - - If an entity-body is encoded with a Content-Encoding, the underlying - data MUST be in a form defined above prior to being encoded. - - - -Fielding, et. al. Standards Track [Page 26] - -RFC 2068 HTTP/1.1 January 1997 - - - The "charset" parameter is used with some media types to define the - character set (section 3.4) of the data. When no explicit charset - parameter is provided by the sender, media subtypes of the "text" - type are defined to have a default charset value of "ISO-8859-1" when - received via HTTP. Data in character sets other than "ISO-8859-1" or - its subsets MUST be labeled with an appropriate charset value. - - Some HTTP/1.0 software has interpreted a Content-Type header without - charset parameter incorrectly to mean "recipient should guess." - Senders wishing to defeat this behavior MAY include a charset - parameter even when the charset is ISO-8859-1 and SHOULD do so when - it is known that it will not confuse the recipient. - - Unfortunately, some older HTTP/1.0 clients did not deal properly with - an explicit charset parameter. HTTP/1.1 recipients MUST respect the - charset label provided by the sender; and those user agents that have - a provision to "guess" a charset MUST use the charset from the - content-type field if they support that charset, rather than the - recipient's preference, when initially displaying a document. - -3.7.2 Multipart Types - - MIME provides for a number of "multipart" types -- encapsulations of - one or more entities within a single message-body. All multipart - types share a common syntax, as defined in MIME [7], and MUST - include a boundary parameter as part of the media type value. The - message body is itself a protocol element and MUST therefore use only - CRLF to represent line breaks between body-parts. Unlike in MIME, the - epilogue of any multipart message MUST be empty; HTTP applications - MUST NOT transmit the epilogue (even if the original multipart - contains an epilogue). - - In HTTP, multipart body-parts MAY contain header fields which are - significant to the meaning of that part. A Content-Location header - field (section 14.15) SHOULD be included in the body-part of each - enclosed entity that can be identified by a URL. - - In general, an HTTP user agent SHOULD follow the same or similar - behavior as a MIME user agent would upon receipt of a multipart type. - If an application receives an unrecognized multipart subtype, the - application MUST treat it as being equivalent to "multipart/mixed". - - Note: The "multipart/form-data" type has been specifically defined - for carrying form data suitable for processing via the POST request - method, as described in RFC 1867 [15]. - - - - - - -Fielding, et. al. Standards Track [Page 27] - -RFC 2068 HTTP/1.1 January 1997 - - -3.8 Product Tokens - - Product tokens are used to allow communicating applications to - identify themselves by software name and version. Most fields using - product tokens also allow sub-products which form a significant part - of the application to be listed, separated by whitespace. By - convention, the products are listed in order of their significance - for identifying the application. - - product = token ["/" product-version] - product-version = token - - Examples: - - User-Agent: CERN-LineMode/2.15 libwww/2.17b3 - Server: Apache/0.8.4 - - Product tokens should be short and to the point -- use of them for - advertising or other non-essential information is explicitly - forbidden. Although any token character may appear in a product- - version, this token SHOULD only be used for a version identifier - (i.e., successive versions of the same product SHOULD only differ in - the product-version portion of the product value). - -3.9 Quality Values - - HTTP content negotiation (section 12) uses short "floating point" - numbers to indicate the relative importance ("weight") of various - negotiable parameters. A weight is normalized to a real number in the - range 0 through 1, where 0 is the minimum and 1 the maximum value. - HTTP/1.1 applications MUST NOT generate more than three digits after - the decimal point. User configuration of these values SHOULD also be - limited in this fashion. - - qvalue = ( "0" [ "." 0*3DIGIT ] ) - | ( "1" [ "." 0*3("0") ] ) - - "Quality values" is a misnomer, since these values merely represent - relative degradation in desired quality. - -3.10 Language Tags - - A language tag identifies a natural language spoken, written, or - otherwise conveyed by human beings for communication of information - to other human beings. Computer languages are explicitly excluded. - HTTP uses language tags within the Accept-Language and Content- - Language fields. - - - - -Fielding, et. al. Standards Track [Page 28] - -RFC 2068 HTTP/1.1 January 1997 - - - The syntax and registry of HTTP language tags is the same as that - defined by RFC 1766 [1]. In summary, a language tag is composed of 1 - or more parts: A primary language tag and a possibly empty series of - subtags: - - language-tag = primary-tag *( "-" subtag ) - - primary-tag = 1*8ALPHA - subtag = 1*8ALPHA - - Whitespace is not allowed within the tag and all tags are case- - insensitive. The name space of language tags is administered by the - IANA. Example tags include: - - en, en-US, en-cockney, i-cherokee, x-pig-latin - - where any two-letter primary-tag is an ISO 639 language abbreviation - and any two-letter initial subtag is an ISO 3166 country code. (The - last three tags above are not registered tags; all but the last are - examples of tags which could be registered in future.) - -3.11 Entity Tags - - Entity tags are used for comparing two or more entities from the same - requested resource. HTTP/1.1 uses entity tags in the ETag (section - 14.20), If-Match (section 14.25), If-None-Match (section 14.26), and - If-Range (section 14.27) header fields. The definition of how they - are used and compared as cache validators is in section 13.3.3. An - entity tag consists of an opaque quoted string, possibly prefixed by - a weakness indicator. - - entity-tag = [ weak ] opaque-tag - - weak = "W/" - opaque-tag = quoted-string - - A "strong entity tag" may be shared by two entities of a resource - only if they are equivalent by octet equality. - - A "weak entity tag," indicated by the "W/" prefix, may be shared by - two entities of a resource only if the entities are equivalent and - could be substituted for each other with no significant change in - semantics. A weak entity tag can only be used for weak comparison. - - An entity tag MUST be unique across all versions of all entities - associated with a particular resource. A given entity tag value may - be used for entities obtained by requests on different URIs without - implying anything about the equivalence of those entities. - - - -Fielding, et. al. Standards Track [Page 29] - -RFC 2068 HTTP/1.1 January 1997 - - -3.12 Range Units - - HTTP/1.1 allows a client to request that only part (a range of) the - response entity be included within the response. HTTP/1.1 uses range - units in the Range (section 14.36) and Content-Range (section 14.17) - header fields. An entity may be broken down into subranges according - to various structural units. - - range-unit = bytes-unit | other-range-unit - - bytes-unit = "bytes" - other-range-unit = token - -The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1 - implementations may ignore ranges specified using other units. - HTTP/1.1 has been designed to allow implementations of applications - that do not depend on knowledge of ranges. - -4 HTTP Message - -4.1 Message Types - - HTTP messages consist of requests from client to server and responses - from server to client. - - HTTP-message = Request | Response ; HTTP/1.1 messages - - Request (section 5) and Response (section 6) messages use the generic - message format of RFC 822 [9] for transferring entities (the payload - of the message). Both types of message consist of a start-line, one - or more header fields (also known as "headers"), an empty line (i.e., - a line with nothing preceding the CRLF) indicating the end of the - header fields, and an optional message-body. - - generic-message = start-line - *message-header - CRLF - [ message-body ] - - start-line = Request-Line | Status-Line - - In the interest of robustness, servers SHOULD ignore any empty - line(s) received where a Request-Line is expected. In other words, if - the server is reading the protocol stream at the beginning of a - message and receives a CRLF first, it should ignore the CRLF. - - - - - - -Fielding, et. al. Standards Track [Page 30] - -RFC 2068 HTTP/1.1 January 1997 - - - Note: certain buggy HTTP/1.0 client implementations generate an - extra CRLF's after a POST request. To restate what is explicitly - forbidden by the BNF, an HTTP/1.1 client must not preface or follow - a request with an extra CRLF. - -4.2 Message Headers - - HTTP header fields, which include general-header (section 4.5), - request-header (section 5.3), response-header (section 6.2), and - entity-header (section 7.1) fields, follow the same generic format as - that given in Section 3.1 of RFC 822 [9]. Each header field consists - of a name followed by a colon (":") and the field value. Field names - are case-insensitive. The field value may be preceded by any amount - of LWS, though a single SP is preferred. Header fields can be - extended over multiple lines by preceding each extra line with at - least one SP or HT. Applications SHOULD follow "common form" when - generating HTTP constructs, since there might exist some - implementations that fail to accept anything beyond the common forms. - - message-header = field-name ":" [ field-value ] CRLF - - field-name = token - field-value = *( field-content | LWS ) - - field-content = <the OCTETs making up the field-value - and consisting of either *TEXT or combinations - of token, tspecials, and quoted-string> - - The order in which header fields with differing field names are - received is not significant. However, it is "good practice" to send - general-header fields first, followed by request-header or response- - header fields, and ending with the entity-header fields. - - Multiple message-header fields with the same field-name may be - present in a message if and only if the entire field-value for that - header field is defined as a comma-separated list [i.e., #(values)]. - It MUST be possible to combine the multiple header fields into one - "field-name: field-value" pair, without changing the semantics of the - message, by appending each subsequent field-value to the first, each - separated by a comma. The order in which header fields with the same - field-name are received is therefore significant to the - interpretation of the combined field value, and thus a proxy MUST NOT - change the order of these field values when a message is forwarded. - - - - - - - - -Fielding, et. al. Standards Track [Page 31] - -RFC 2068 HTTP/1.1 January 1997 - - -4.3 Message Body - - The message-body (if any) of an HTTP message is used to carry the - entity-body associated with the request or response. The message-body - differs from the entity-body only when a transfer coding has been - applied, as indicated by the Transfer-Encoding header field (section - 14.40). - - message-body = entity-body - | <entity-body encoded as per Transfer-Encoding> - - Transfer-Encoding MUST be used to indicate any transfer codings - applied by an application to ensure safe and proper transfer of the - message. Transfer-Encoding is a property of the message, not of the - entity, and thus can be added or removed by any application along the - request/response chain. - - The rules for when a message-body is allowed in a message differ for - requests and responses. - - The presence of a message-body in a request is signaled by the - inclusion of a Content-Length or Transfer-Encoding header field in - the request's message-headers. A message-body MAY be included in a - request only when the request method (section 5.1.1) allows an - entity-body. - - For response messages, whether or not a message-body is included with - a message is dependent on both the request method and the response - status code (section 6.1.1). All responses to the HEAD request method - MUST NOT include a message-body, even though the presence of entity- - header fields might lead one to believe they do. All 1xx - (informational), 204 (no content), and 304 (not modified) responses - MUST NOT include a message-body. All other responses do include a - message-body, although it may be of zero length. - -4.4 Message Length - - When a message-body is included with a message, the length of that - body is determined by one of the following (in order of precedence): - - 1. Any response message which MUST NOT include a message-body - (such as the 1xx, 204, and 304 responses and any response to a HEAD - request) is always terminated by the first empty line after the - header fields, regardless of the entity-header fields present in the - message. - - 2. If a Transfer-Encoding header field (section 14.40) is present and - indicates that the "chunked" transfer coding has been applied, then - - - -Fielding, et. al. Standards Track [Page 32] - -RFC 2068 HTTP/1.1 January 1997 - - - the length is defined by the chunked encoding (section 3.6). - - 3. If a Content-Length header field (section 14.14) is present, its - value in bytes represents the length of the message-body. - - 4. If the message uses the media type "multipart/byteranges", which is - self-delimiting, then that defines the length. This media type MUST - NOT be used unless the sender knows that the recipient can parse it; - the presence in a request of a Range header with multiple byte-range - specifiers implies that the client can parse multipart/byteranges - responses. - - 5. By the server closing the connection. (Closing the connection - cannot be used to indicate the end of a request body, since that - would leave no possibility for the server to send back a response.) - - For compatibility with HTTP/1.0 applications, HTTP/1.1 requests - containing a message-body MUST include a valid Content-Length header - field unless the server is known to be HTTP/1.1 compliant. If a - request contains a message-body and a Content-Length is not given, - the server SHOULD respond with 400 (bad request) if it cannot - determine the length of the message, or with 411 (length required) if - it wishes to insist on receiving a valid Content-Length. - - All HTTP/1.1 applications that receive entities MUST accept the - "chunked" transfer coding (section 3.6), thus allowing this mechanism - to be used for messages when the message length cannot be determined - in advance. - - Messages MUST NOT include both a Content-Length header field and the - "chunked" transfer coding. If both are received, the Content-Length - MUST be ignored. - - When a Content-Length is given in a message where a message-body is - allowed, its field value MUST exactly match the number of OCTETs in - the message-body. HTTP/1.1 user agents MUST notify the user when an - invalid length is received and detected. - - - - - - - - - - - - - - -Fielding, et. al. Standards Track [Page 33] - -RFC 2068 HTTP/1.1 January 1997 - - -4.5 General Header Fields - - There are a few header fields which have general applicability for - both request and response messages, but which do not apply to the - entity being transferred. These header fields apply only to the - message being transmitted. - - general-header = Cache-Control ; Section 14.9 - | Connection ; Section 14.10 - | Date ; Section 14.19 - | Pragma ; Section 14.32 - | Transfer-Encoding ; Section 14.40 - | Upgrade ; Section 14.41 - | Via ; Section 14.44 - - General-header field names can be extended reliably only in - combination with a change in the protocol version. However, new or - experimental header fields may be given the semantics of general - header fields if all parties in the communication recognize them to - be general-header fields. Unrecognized header fields are treated as - entity-header fields. - -5 Request - - A request message from a client to a server includes, within the - first line of that message, the method to be applied to the resource, - the identifier of the resource, and the protocol version in use. - - Request = Request-Line ; Section 5.1 - *( general-header ; Section 4.5 - | request-header ; Section 5.3 - | entity-header ) ; Section 7.1 - CRLF - [ message-body ] ; Section 7.2 - -5.1 Request-Line - - The Request-Line begins with a method token, followed by the - Request-URI and the protocol version, and ending with CRLF. The - elements are separated by SP characters. No CR or LF are allowed - except in the final CRLF sequence. - - Request-Line = Method SP Request-URI SP HTTP-Version CRLF - - - - - - - - -Fielding, et. al. Standards Track [Page 34] - -RFC 2068 HTTP/1.1 January 1997 - - -5.1.1 Method - - The Method token indicates the method to be performed on the resource - identified by the Request-URI. The method is case-sensitive. - - Method = "OPTIONS" ; Section 9.2 - | "GET" ; Section 9.3 - | "HEAD" ; Section 9.4 - | "POST" ; Section 9.5 - | "PUT" ; Section 9.6 - | "DELETE" ; Section 9.7 - | "TRACE" ; Section 9.8 - | extension-method - - extension-method = token - - The list of methods allowed by a resource can be specified in an - Allow header field (section 14.7). The return code of the response - always notifies the client whether a method is currently allowed on a - resource, since the set of allowed methods can change dynamically. - Servers SHOULD return the status code 405 (Method Not Allowed) if the - method is known by the server but not allowed for the requested - resource, and 501 (Not Implemented) if the method is unrecognized or - not implemented by the server. The list of methods known by a server - can be listed in a Public response-header field (section 14.35). - - The methods GET and HEAD MUST be supported by all general-purpose - servers. All other methods are optional; however, if the above - methods are implemented, they MUST be implemented with the same - semantics as those specified in section 9. - -5.1.2 Request-URI - - The Request-URI is a Uniform Resource Identifier (section 3.2) and - identifies the resource upon which to apply the request. - - Request-URI = "*" | absoluteURI | abs_path - - The three options for Request-URI are dependent on the nature of the - request. The asterisk "*" means that the request does not apply to a - particular resource, but to the server itself, and is only allowed - when the method used does not necessarily apply to a resource. One - example would be - - OPTIONS * HTTP/1.1 - - The absoluteURI form is required when the request is being made to a - proxy. The proxy is requested to forward the request or service it - - - -Fielding, et. al. Standards Track [Page 35] - -RFC 2068 HTTP/1.1 January 1997 - - - from a valid cache, and return the response. Note that the proxy MAY - forward the request on to another proxy or directly to the server - specified by the absoluteURI. In order to avoid request loops, a - proxy MUST be able to recognize all of its server names, including - any aliases, local variations, and the numeric IP address. An example - Request-Line would be: - - GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.1 - - To allow for transition to absoluteURIs in all requests in future - versions of HTTP, all HTTP/1.1 servers MUST accept the absoluteURI - form in requests, even though HTTP/1.1 clients will only generate - them in requests to proxies. - - The most common form of Request-URI is that used to identify a - resource on an origin server or gateway. In this case the absolute - path of the URI MUST be transmitted (see section 3.2.1, abs_path) as - the Request-URI, and the network location of the URI (net_loc) MUST - be transmitted in a Host header field. For example, a client wishing - to retrieve the resource above directly from the origin server would - create a TCP connection to port 80 of the host "www.w3.org" and send - the lines: - - GET /pub/WWW/TheProject.html HTTP/1.1 - Host: www.w3.org - - followed by the remainder of the Request. Note that the absolute path - cannot be empty; if none is present in the original URI, it MUST be - given as "/" (the server root). - - If a proxy receives a request without any path in the Request-URI and - the method specified is capable of supporting the asterisk form of - request, then the last proxy on the request chain MUST forward the - request with "*" as the final Request-URI. For example, the request - - OPTIONS http://www.ics.uci.edu:8001 HTTP/1.1 - - would be forwarded by the proxy as - - OPTIONS * HTTP/1.1 - Host: www.ics.uci.edu:8001 - - after connecting to port 8001 of host "www.ics.uci.edu". - - The Request-URI is transmitted in the format specified in section - 3.2.1. The origin server MUST decode the Request-URI in order to - properly interpret the request. Servers SHOULD respond to invalid - Request-URIs with an appropriate status code. - - - -Fielding, et. al. Standards Track [Page 36] - -RFC 2068 HTTP/1.1 January 1997 - - - In requests that they forward, proxies MUST NOT rewrite the - "abs_path" part of a Request-URI in any way except as noted above to - replace a null abs_path with "*", no matter what the proxy does in - its internal implementation. - - Note: The "no rewrite" rule prevents the proxy from changing the - meaning of the request when the origin server is improperly using a - non-reserved URL character for a reserved purpose. Implementers - should be aware that some pre-HTTP/1.1 proxies have been known to - rewrite the Request-URI. - -5.2 The Resource Identified by a Request - - HTTP/1.1 origin servers SHOULD be aware that the exact resource - identified by an Internet request is determined by examining both the - Request-URI and the Host header field. - - An origin server that does not allow resources to differ by the - requested host MAY ignore the Host header field value. (But see - section 19.5.1 for other requirements on Host support in HTTP/1.1.) - - An origin server that does differentiate resources based on the host - requested (sometimes referred to as virtual hosts or vanity - hostnames) MUST use the following rules for determining the requested - resource on an HTTP/1.1 request: - - 1. If Request-URI is an absoluteURI, the host is part of the - Request-URI. Any Host header field value in the request MUST be - ignored. - - 2. If the Request-URI is not an absoluteURI, and the request - includes a Host header field, the host is determined by the Host - header field value. - - 3. If the host as determined by rule 1 or 2 is not a valid host on - the server, the response MUST be a 400 (Bad Request) error - message. - - Recipients of an HTTP/1.0 request that lacks a Host header field MAY - attempt to use heuristics (e.g., examination of the URI path for - something unique to a particular host) in order to determine what - exact resource is being requested. - -5.3 Request Header Fields - - The request-header fields allow the client to pass additional - information about the request, and about the client itself, to the - server. These fields act as request modifiers, with semantics - - - -Fielding, et. al. Standards Track [Page 37] - -RFC 2068 HTTP/1.1 January 1997 - - - equivalent to the parameters on a programming language method - invocation. - - request-header = Accept ; Section 14.1 - | Accept-Charset ; Section 14.2 - | Accept-Encoding ; Section 14.3 - | Accept-Language ; Section 14.4 - | Authorization ; Section 14.8 - | From ; Section 14.22 - | Host ; Section 14.23 - | If-Modified-Since ; Section 14.24 - | If-Match ; Section 14.25 - | If-None-Match ; Section 14.26 - | If-Range ; Section 14.27 - | If-Unmodified-Since ; Section 14.28 - | Max-Forwards ; Section 14.31 - | Proxy-Authorization ; Section 14.34 - | Range ; Section 14.36 - | Referer ; Section 14.37 - | User-Agent ; Section 14.42 - - Request-header field names can be extended reliably only in - combination with a change in the protocol version. However, new or - experimental header fields MAY be given the semantics of request- - header fields if all parties in the communication recognize them to - be request-header fields. Unrecognized header fields are treated as - entity-header fields. - -6 Response - - After receiving and interpreting a request message, a server responds - with an HTTP response message. - - Response = Status-Line ; Section 6.1 - *( general-header ; Section 4.5 - | response-header ; Section 6.2 - | entity-header ) ; Section 7.1 - CRLF - [ message-body ] ; Section 7.2 - -6.1 Status-Line - - The first line of a Response message is the Status-Line, consisting - of the protocol version followed by a numeric status code and its - associated textual phrase, with each element separated by SP - characters. No CR or LF is allowed except in the final CRLF - sequence. - - - - -Fielding, et. al. Standards Track [Page 38] - -RFC 2068 HTTP/1.1 January 1997 - - - Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF - -6.1.1 Status Code and Reason Phrase - - The Status-Code element is a 3-digit integer result code of the - attempt to understand and satisfy the request. These codes are fully - defined in section 10. The Reason-Phrase is intended to give a short - textual description of the Status-Code. The Status-Code is intended - for use by automata and the Reason-Phrase is intended for the human - user. The client is not required to examine or display the Reason- - Phrase. - - The first digit of the Status-Code defines the class of response. The - last two digits do not have any categorization role. There are 5 - values for the first digit: - - o 1xx: Informational - Request received, continuing process - - o 2xx: Success - The action was successfully received, understood, - and accepted - - o 3xx: Redirection - Further action must be taken in order to - complete the request - - o 4xx: Client Error - The request contains bad syntax or cannot be - fulfilled - - o 5xx: Server Error - The server failed to fulfill an apparently - valid request - - The individual values of the numeric status codes defined for - HTTP/1.1, and an example set of corresponding Reason-Phrase's, are - presented below. The reason phrases listed here are only recommended - -- they may be replaced by local equivalents without affecting the - protocol. - - Status-Code = "100" ; Continue - | "101" ; Switching Protocols - | "200" ; OK - | "201" ; Created - | "202" ; Accepted - | "203" ; Non-Authoritative Information - | "204" ; No Content - | "205" ; Reset Content - | "206" ; Partial Content - | "300" ; Multiple Choices - | "301" ; Moved Permanently - | "302" ; Moved Temporarily - - - -Fielding, et. al. Standards Track [Page 39] - -RFC 2068 HTTP/1.1 January 1997 - - - | "303" ; See Other - | "304" ; Not Modified - | "305" ; Use Proxy - | "400" ; Bad Request - | "401" ; Unauthorized - | "402" ; Payment Required - | "403" ; Forbidden - | "404" ; Not Found - | "405" ; Method Not Allowed - | "406" ; Not Acceptable - | "407" ; Proxy Authentication Required - | "408" ; Request Time-out - | "409" ; Conflict - | "410" ; Gone - | "411" ; Length Required - | "412" ; Precondition Failed - | "413" ; Request Entity Too Large - | "414" ; Request-URI Too Large - | "415" ; Unsupported Media Type - | "500" ; Internal Server Error - | "501" ; Not Implemented - | "502" ; Bad Gateway - | "503" ; Service Unavailable - | "504" ; Gateway Time-out - | "505" ; HTTP Version not supported - | extension-code - - extension-code = 3DIGIT - - Reason-Phrase = *<TEXT, excluding CR, LF> - - HTTP status codes are extensible. HTTP applications are not required - to understand the meaning of all registered status codes, though such - understanding is obviously desirable. However, applications MUST - understand the class of any status code, as indicated by the first - digit, and treat any unrecognized response as being equivalent to the - x00 status code of that class, with the exception that an - unrecognized response MUST NOT be cached. For example, if an - unrecognized status code of 431 is received by the client, it can - safely assume that there was something wrong with its request and - treat the response as if it had received a 400 status code. In such - cases, user agents SHOULD present to the user the entity returned - with the response, since that entity is likely to include human- - readable information which will explain the unusual status. - - - - - - - -Fielding, et. al. Standards Track [Page 40] - -RFC 2068 HTTP/1.1 January 1997 - - -6.2 Response Header Fields - - The response-header fields allow the server to pass additional - information about the response which cannot be placed in the Status- - Line. These header fields give information about the server and about - further access to the resource identified by the Request-URI. - - response-header = Age ; Section 14.6 - | Location ; Section 14.30 - | Proxy-Authenticate ; Section 14.33 - | Public ; Section 14.35 - | Retry-After ; Section 14.38 - | Server ; Section 14.39 - | Vary ; Section 14.43 - | Warning ; Section 14.45 - | WWW-Authenticate ; Section 14.46 - - Response-header field names can be extended reliably only in - combination with a change in the protocol version. However, new or - experimental header fields MAY be given the semantics of response- - header fields if all parties in the communication recognize them to - be response-header fields. Unrecognized header fields are treated as - entity-header fields. - -7 Entity - - Request and Response messages MAY transfer an entity if not otherwise - restricted by the request method or response status code. An entity - consists of entity-header fields and an entity-body, although some - responses will only include the entity-headers. - - In this section, both sender and recipient refer to either the client - or the server, depending on who sends and who receives the entity. - -7.1 Entity Header Fields - - Entity-header fields define optional metainformation about the - entity-body or, if no body is present, about the resource identified - by the request. - - - - - - - - - - - - -Fielding, et. al. Standards Track [Page 41] - -RFC 2068 HTTP/1.1 January 1997 - - - entity-header = Allow ; Section 14.7 - | Content-Base ; Section 14.11 - | Content-Encoding ; Section 14.12 - | Content-Language ; Section 14.13 - | Content-Length ; Section 14.14 - | Content-Location ; Section 14.15 - | Content-MD5 ; Section 14.16 - | Content-Range ; Section 14.17 - | Content-Type ; Section 14.18 - | ETag ; Section 14.20 - | Expires ; Section 14.21 - | Last-Modified ; Section 14.29 - | extension-header - - extension-header = message-header - - The extension-header mechanism allows additional entity-header fields - to be defined without changing the protocol, but these fields cannot - be assumed to be recognizable by the recipient. Unrecognized header - fields SHOULD be ignored by the recipient and forwarded by proxies. - -7.2 Entity Body - - The entity-body (if any) sent with an HTTP request or response is in - a format and encoding defined by the entity-header fields. - - entity-body = *OCTET - - An entity-body is only present in a message when a message-body is - present, as described in section 4.3. The entity-body is obtained - from the message-body by decoding any Transfer-Encoding that may have - been applied to ensure safe and proper transfer of the message. - -7.2.1 Type - - When an entity-body is included with a message, the data type of that - body is determined via the header fields Content-Type and Content- - Encoding. These define a two-layer, ordered encoding model: - - entity-body := Content-Encoding( Content-Type( data ) ) - - Content-Type specifies the media type of the underlying data. - Content-Encoding may be used to indicate any additional content - codings applied to the data, usually for the purpose of data - compression, that are a property of the requested resource. There is - no default encoding. - - - - - -Fielding, et. al. Standards Track [Page 42] - -RFC 2068 HTTP/1.1 January 1997 - - - Any HTTP/1.1 message containing an entity-body SHOULD include a - Content-Type header field defining the media type of that body. If - and only if the media type is not given by a Content-Type field, the - recipient MAY attempt to guess the media type via inspection of its - content and/or the name extension(s) of the URL used to identify the - resource. If the media type remains unknown, the recipient SHOULD - treat it as type "application/octet-stream". - -7.2.2 Length - - The length of an entity-body is the length of the message-body after - any transfer codings have been removed. Section 4.4 defines how the - length of a message-body is determined. - -8 Connections - -8.1 Persistent Connections - -8.1.1 Purpose - - Prior to persistent connections, a separate TCP connection was - established to fetch each URL, increasing the load on HTTP servers - and causing congestion on the Internet. The use of inline images and - other associated data often requires a client to make multiple - requests of the same server in a short amount of time. Analyses of - these performance problems are available [30][27]; analysis and - results from a prototype implementation are in [26]. - - Persistent HTTP connections have a number of advantages: - - o By opening and closing fewer TCP connections, CPU time is saved, - and memory used for TCP protocol control blocks is also saved. - o HTTP requests and responses can be pipelined on a connection. - Pipelining allows a client to make multiple requests without - waiting for each response, allowing a single TCP connection to be - used much more efficiently, with much lower elapsed time. - o Network congestion is reduced by reducing the number of packets - caused by TCP opens, and by allowing TCP sufficient time to - determine the congestion state of the network. - o HTTP can evolve more gracefully; since errors can be reported - without the penalty of closing the TCP connection. Clients using - future versions of HTTP might optimistically try a new feature, but - if communicating with an older server, retry with old semantics - after an error is reported. - - HTTP implementations SHOULD implement persistent connections. - - - - - -Fielding, et. al. Standards Track [Page 43] - -RFC 2068 HTTP/1.1 January 1997 - - -8.1.2 Overall Operation - - A significant difference between HTTP/1.1 and earlier versions of - HTTP is that persistent connections are the default behavior of any - HTTP connection. That is, unless otherwise indicated, the client may - assume that the server will maintain a persistent connection. - - Persistent connections provide a mechanism by which a client and a - server can signal the close of a TCP connection. This signaling takes - place using the Connection header field. Once a close has been - signaled, the client MUST not send any more requests on that - connection. - -8.1.2.1 Negotiation - - An HTTP/1.1 server MAY assume that a HTTP/1.1 client intends to - maintain a persistent connection unless a Connection header including - the connection-token "close" was sent in the request. If the server - chooses to close the connection immediately after sending the - response, it SHOULD send a Connection header including the - connection-token close. - - An HTTP/1.1 client MAY expect a connection to remain open, but would - decide to keep it open based on whether the response from a server - contains a Connection header with the connection-token close. In case - the client does not want to maintain a connection for more than that - request, it SHOULD send a Connection header including the - connection-token close. - - If either the client or the server sends the close token in the - Connection header, that request becomes the last one for the - connection. - - Clients and servers SHOULD NOT assume that a persistent connection is - maintained for HTTP versions less than 1.1 unless it is explicitly - signaled. See section 19.7.1 for more information on backwards - compatibility with HTTP/1.0 clients. - - In order to remain persistent, all messages on the connection must - have a self-defined message length (i.e., one not defined by closure - of the connection), as described in section 4.4. - -8.1.2.2 Pipelining - - A client that supports persistent connections MAY "pipeline" its - requests (i.e., send multiple requests without waiting for each - response). A server MUST send its responses to those requests in the - same order that the requests were received. - - - -Fielding, et. al. Standards Track [Page 44] - -RFC 2068 HTTP/1.1 January 1997 - - - Clients which assume persistent connections and pipeline immediately - after connection establishment SHOULD be prepared to retry their - connection if the first pipelined attempt fails. If a client does - such a retry, it MUST NOT pipeline before it knows the connection is - persistent. Clients MUST also be prepared to resend their requests if - the server closes the connection before sending all of the - corresponding responses. - -8.1.3 Proxy Servers - - It is especially important that proxies correctly implement the - properties of the Connection header field as specified in 14.2.1. - - The proxy server MUST signal persistent connections separately with - its clients and the origin servers (or other proxy servers) that it - connects to. Each persistent connection applies to only one transport - link. - - A proxy server MUST NOT establish a persistent connection with an - HTTP/1.0 client. - -8.1.4 Practical Considerations - - Servers will usually have some time-out value beyond which they will - no longer maintain an inactive connection. Proxy servers might make - this a higher value since it is likely that the client will be making - more connections through the same server. The use of persistent - connections places no requirements on the length of this time-out for - either the client or the server. - - When a client or server wishes to time-out it SHOULD issue a graceful - close on the transport connection. Clients and servers SHOULD both - constantly watch for the other side of the transport close, and - respond to it as appropriate. If a client or server does not detect - the other side's close promptly it could cause unnecessary resource - drain on the network. - - A client, server, or proxy MAY close the transport connection at any - time. For example, a client MAY have started to send a new request at - the same time that the server has decided to close the "idle" - connection. From the server's point of view, the connection is being - closed while it was idle, but from the client's point of view, a - request is in progress. - - This means that clients, servers, and proxies MUST be able to recover - from asynchronous close events. Client software SHOULD reopen the - transport connection and retransmit the aborted request without user - interaction so long as the request method is idempotent (see section - - - -Fielding, et. al. Standards Track [Page 45] - -RFC 2068 HTTP/1.1 January 1997 - - - 9.1.2); other methods MUST NOT be automatically retried, although - user agents MAY offer a human operator the choice of retrying the - request. - - However, this automatic retry SHOULD NOT be repeated if the second - request fails. - - Servers SHOULD always respond to at least one request per connection, - if at all possible. Servers SHOULD NOT close a connection in the - middle of transmitting a response, unless a network or client failure - is suspected. - - Clients that use persistent connections SHOULD limit the number of - simultaneous connections that they maintain to a given server. A - single-user client SHOULD maintain AT MOST 2 connections with any - server or proxy. A proxy SHOULD use up to 2*N connections to another - server or proxy, where N is the number of simultaneously active - users. These guidelines are intended to improve HTTP response times - and avoid congestion of the Internet or other networks. - -8.2 Message Transmission Requirements - -General requirements: - -o HTTP/1.1 servers SHOULD maintain persistent connections and use - TCP's flow control mechanisms to resolve temporary overloads, - rather than terminating connections with the expectation that - clients will retry. The latter technique can exacerbate network - congestion. - -o An HTTP/1.1 (or later) client sending a message-body SHOULD monitor - the network connection for an error status while it is transmitting - the request. If the client sees an error status, it SHOULD - immediately cease transmitting the body. If the body is being sent - using a "chunked" encoding (section 3.6), a zero length chunk and - empty footer MAY be used to prematurely mark the end of the - message. If the body was preceded by a Content-Length header, the - client MUST close the connection. - -o An HTTP/1.1 (or later) client MUST be prepared to accept a 100 - (Continue) status followed by a regular response. - -o An HTTP/1.1 (or later) server that receives a request from a - HTTP/1.0 (or earlier) client MUST NOT transmit the 100 (continue) - response; it SHOULD either wait for the request to be completed - normally (thus avoiding an interrupted request) or close the - connection prematurely. - - - - -Fielding, et. al. Standards Track [Page 46] - -RFC 2068 HTTP/1.1 January 1997 - - - Upon receiving a method subject to these requirements from an - HTTP/1.1 (or later) client, an HTTP/1.1 (or later) server MUST either - respond with 100 (Continue) status and continue to read from the - input stream, or respond with an error status. If it responds with an - error status, it MAY close the transport (TCP) connection or it MAY - continue to read and discard the rest of the request. It MUST NOT - perform the requested method if it returns an error status. - - Clients SHOULD remember the version number of at least the most - recently used server; if an HTTP/1.1 client has seen an HTTP/1.1 or - later response from the server, and it sees the connection close - before receiving any status from the server, the client SHOULD retry - the request without user interaction so long as the request method is - idempotent (see section 9.1.2); other methods MUST NOT be - automatically retried, although user agents MAY offer a human - operator the choice of retrying the request.. If the client does - retry the request, the client - - o MUST first send the request header fields, and then - - o MUST wait for the server to respond with either a 100 (Continue) - response, in which case the client should continue, or with an - error status. - - If an HTTP/1.1 client has not seen an HTTP/1.1 or later response from - the server, it should assume that the server implements HTTP/1.0 or - older and will not use the 100 (Continue) response. If in this case - the client sees the connection close before receiving any status from - the server, the client SHOULD retry the request. If the client does - retry the request to this HTTP/1.0 server, it should use the - following "binary exponential backoff" algorithm to be assured of - obtaining a reliable response: - - 1. Initiate a new connection to the server - - 2. Transmit the request-headers - - 3. Initialize a variable R to the estimated round-trip time to the - server (e.g., based on the time it took to establish the - connection), or to a constant value of 5 seconds if the round-trip - time is not available. - - 4. Compute T = R * (2**N), where N is the number of previous retries - of this request. - - 5. Wait either for an error response from the server, or for T seconds - (whichever comes first) - - - - -Fielding, et. al. Standards Track [Page 47] - -RFC 2068 HTTP/1.1 January 1997 - - - 6. If no error response is received, after T seconds transmit the body - of the request. - - 7. If client sees that the connection is closed prematurely, repeat - from step 1 until the request is accepted, an error response is - received, or the user becomes impatient and terminates the retry - process. - - No matter what the server version, if an error status is received, - the client - - o MUST NOT continue and - - o MUST close the connection if it has not completed sending the - message. - - An HTTP/1.1 (or later) client that sees the connection close after - receiving a 100 (Continue) but before receiving any other status - SHOULD retry the request, and need not wait for 100 (Continue) - response (but MAY do so if this simplifies the implementation). - -9 Method Definitions - - The set of common methods for HTTP/1.1 is defined below. Although - this set can be expanded, additional methods cannot be assumed to - share the same semantics for separately extended clients and servers. - - The Host request-header field (section 14.23) MUST accompany all - HTTP/1.1 requests. - -9.1 Safe and Idempotent Methods - -9.1.1 Safe Methods - - Implementers should be aware that the software represents the user in - their interactions over the Internet, and should be careful to allow - the user to be aware of any actions they may take which may have an - unexpected significance to themselves or others. - - In particular, the convention has been established that the GET and - HEAD methods should never have the significance of taking an action - other than retrieval. These methods should be considered "safe." This - allows user agents to represent other methods, such as POST, PUT and - DELETE, in a special way, so that the user is made aware of the fact - that a possibly unsafe action is being requested. - - Naturally, it is not possible to ensure that the server does not - generate side-effects as a result of performing a GET request; in - - - -Fielding, et. al. Standards Track [Page 48] - -RFC 2068 HTTP/1.1 January 1997 - - - fact, some dynamic resources consider that a feature. The important - distinction here is that the user did not request the side-effects, - so therefore cannot be held accountable for them. - -9.1.2 Idempotent Methods - - Methods may also have the property of "idempotence" in that (aside - from error or expiration issues) the side-effects of N > 0 identical - requests is the same as for a single request. The methods GET, HEAD, - PUT and DELETE share this property. - -9.2 OPTIONS - - The OPTIONS method represents a request for information about the - communication options available on the request/response chain - identified by the Request-URI. This method allows the client to - determine the options and/or requirements associated with a resource, - or the capabilities of a server, without implying a resource action - or initiating a resource retrieval. - - Unless the server's response is an error, the response MUST NOT - include entity information other than what can be considered as - communication options (e.g., Allow is appropriate, but Content-Type - is not). Responses to this method are not cachable. - - If the Request-URI is an asterisk ("*"), the OPTIONS request is - intended to apply to the server as a whole. A 200 response SHOULD - include any header fields which indicate optional features - implemented by the server (e.g., Public), including any extensions - not defined by this specification, in addition to any applicable - general or response-header fields. As described in section 5.1.2, an - "OPTIONS *" request can be applied through a proxy by specifying the - destination server in the Request-URI without any path information. - - If the Request-URI is not an asterisk, the OPTIONS request applies - only to the options that are available when communicating with that - resource. A 200 response SHOULD include any header fields which - indicate optional features implemented by the server and applicable - to that resource (e.g., Allow), including any extensions not defined - by this specification, in addition to any applicable general or - response-header fields. If the OPTIONS request passes through a - proxy, the proxy MUST edit the response to exclude those options - which apply to a proxy's capabilities and which are known to be - unavailable through that proxy. - - - - - - - -Fielding, et. al. Standards Track [Page 49] - -RFC 2068 HTTP/1.1 January 1997 - - -9.3 GET - - The GET method means retrieve whatever information (in the form of an - entity) is identified by the Request-URI. If the Request-URI refers - to a data-producing process, it is the produced data which shall be - returned as the entity in the response and not the source text of the - process, unless that text happens to be the output of the process. - - The semantics of the GET method change to a "conditional GET" if the - request message includes an If-Modified-Since, If-Unmodified-Since, - If-Match, If-None-Match, or If-Range header field. A conditional GET - method requests that the entity be transferred only under the - circumstances described by the conditional header field(s). The - conditional GET method is intended to reduce unnecessary network - usage by allowing cached entities to be refreshed without requiring - multiple requests or transferring data already held by the client. - - The semantics of the GET method change to a "partial GET" if the - request message includes a Range header field. A partial GET requests - that only part of the entity be transferred, as described in section - 14.36. The partial GET method is intended to reduce unnecessary - network usage by allowing partially-retrieved entities to be - completed without transferring data already held by the client. - - The response to a GET request is cachable if and only if it meets the - requirements for HTTP caching described in section 13. - -9.4 HEAD - - The HEAD method is identical to GET except that the server MUST NOT - return a message-body in the response. The metainformation contained - in the HTTP headers in response to a HEAD request SHOULD be identical - to the information sent in response to a GET request. This method can - be used for obtaining metainformation about the entity implied by the - request without transferring the entity-body itself. This method is - often used for testing hypertext links for validity, accessibility, - and recent modification. - - The response to a HEAD request may be cachable in the sense that the - information contained in the response may be used to update a - previously cached entity from that resource. If the new field values - indicate that the cached entity differs from the current entity (as - would be indicated by a change in Content-Length, Content-MD5, ETag - or Last-Modified), then the cache MUST treat the cache entry as - stale. - - - - - - -Fielding, et. al. Standards Track [Page 50] - -RFC 2068 HTTP/1.1 January 1997 - - -9.5 POST - - The POST method is used to request that the destination server accept - the entity enclosed in the request as a new subordinate of the - resource identified by the Request-URI in the Request-Line. POST is - designed to allow a uniform method to cover the following functions: - - o Annotation of existing resources; - - o Posting a message to a bulletin board, newsgroup, mailing list, - or similar group of articles; - - o Providing a block of data, such as the result of submitting a - form, to a data-handling process; - - o Extending a database through an append operation. - - The actual function performed by the POST method is determined by the - server and is usually dependent on the Request-URI. The posted entity - is subordinate to that URI in the same way that a file is subordinate - to a directory containing it, a news article is subordinate to a - newsgroup to which it is posted, or a record is subordinate to a - database. - - The action performed by the POST method might not result in a - resource that can be identified by a URI. In this case, either 200 - (OK) or 204 (No Content) is the appropriate response status, - depending on whether or not the response includes an entity that - describes the result. - - If a resource has been created on the origin server, the response - SHOULD be 201 (Created) and contain an entity which describes the - status of the request and refers to the new resource, and a Location - header (see section 14.30). - - Responses to this method are not cachable, unless the response - includes appropriate Cache-Control or Expires header fields. However, - the 303 (See Other) response can be used to direct the user agent to - retrieve a cachable resource. - - POST requests must obey the message transmission requirements set out - in section 8.2. - - - - - - - - - -Fielding, et. al. Standards Track [Page 51] - -RFC 2068 HTTP/1.1 January 1997 - - -9.6 PUT - - The PUT method requests that the enclosed entity be stored under the - supplied Request-URI. If the Request-URI refers to an already - existing resource, the enclosed entity SHOULD be considered as a - modified version of the one residing on the origin server. If the - Request-URI does not point to an existing resource, and that URI is - capable of being defined as a new resource by the requesting user - agent, the origin server can create the resource with that URI. If a - new resource is created, the origin server MUST inform the user agent - via the 201 (Created) response. If an existing resource is modified, - either the 200 (OK) or 204 (No Content) response codes SHOULD be sent - to indicate successful completion of the request. If the resource - could not be created or modified with the Request-URI, an appropriate - error response SHOULD be given that reflects the nature of the - problem. The recipient of the entity MUST NOT ignore any Content-* - (e.g. Content-Range) headers that it does not understand or implement - and MUST return a 501 (Not Implemented) response in such cases. - - If the request passes through a cache and the Request-URI identifies - one or more currently cached entities, those entries should be - treated as stale. Responses to this method are not cachable. - - The fundamental difference between the POST and PUT requests is - reflected in the different meaning of the Request-URI. The URI in a - POST request identifies the resource that will handle the enclosed - entity. That resource may be a data-accepting process, a gateway to - some other protocol, or a separate entity that accepts annotations. - In contrast, the URI in a PUT request identifies the entity enclosed - with the request -- the user agent knows what URI is intended and the - server MUST NOT attempt to apply the request to some other resource. - If the server desires that the request be applied to a different URI, - it MUST send a 301 (Moved Permanently) response; the user agent MAY - then make its own decision regarding whether or not to redirect the - request. - - A single resource MAY be identified by many different URIs. For - example, an article may have a URI for identifying "the current - version" which is separate from the URI identifying each particular - version. In this case, a PUT request on a general URI may result in - several other URIs being defined by the origin server. - - HTTP/1.1 does not define how a PUT method affects the state of an - origin server. - - PUT requests must obey the message transmission requirements set out - in section 8.2. - - - - -Fielding, et. al. Standards Track [Page 52] - -RFC 2068 HTTP/1.1 January 1997 - - -9.7 DELETE - - The DELETE method requests that the origin server delete the resource - identified by the Request-URI. This method MAY be overridden by human - intervention (or other means) on the origin server. The client cannot - be guaranteed that the operation has been carried out, even if the - status code returned from the origin server indicates that the action - has been completed successfully. However, the server SHOULD not - indicate success unless, at the time the response is given, it - intends to delete the resource or move it to an inaccessible - location. - - A successful response SHOULD be 200 (OK) if the response includes an - entity describing the status, 202 (Accepted) if the action has not - yet been enacted, or 204 (No Content) if the response is OK but does - not include an entity. - - If the request passes through a cache and the Request-URI identifies - one or more currently cached entities, those entries should be - treated as stale. Responses to this method are not cachable. - -9.8 TRACE - - The TRACE method is used to invoke a remote, application-layer loop- - back of the request message. The final recipient of the request - SHOULD reflect the message received back to the client as the - entity-body of a 200 (OK) response. The final recipient is either the - origin server or the first proxy or gateway to receive a Max-Forwards - value of zero (0) in the request (see section 14.31). A TRACE request - MUST NOT include an entity. - - TRACE allows the client to see what is being received at the other - end of the request chain and use that data for testing or diagnostic - information. The value of the Via header field (section 14.44) is of - particular interest, since it acts as a trace of the request chain. - Use of the Max-Forwards header field allows the client to limit the - length of the request chain, which is useful for testing a chain of - proxies forwarding messages in an infinite loop. - - If successful, the response SHOULD contain the entire request message - in the entity-body, with a Content-Type of "message/http". Responses - to this method MUST NOT be cached. - -10 Status Code Definitions - - Each Status-Code is described below, including a description of which - method(s) it can follow and any metainformation required in the - response. - - - -Fielding, et. al. Standards Track [Page 53] - -RFC 2068 HTTP/1.1 January 1997 - - -10.1 Informational 1xx - - This class of status code indicates a provisional response, - consisting only of the Status-Line and optional headers, and is - terminated by an empty line. Since HTTP/1.0 did not define any 1xx - status codes, servers MUST NOT send a 1xx response to an HTTP/1.0 - client except under experimental conditions. - -10.1.1 100 Continue - - The client may continue with its request. This interim response is - used to inform the client that the initial part of the request has - been received and has not yet been rejected by the server. The client - SHOULD continue by sending the remainder of the request or, if the - request has already been completed, ignore this response. The server - MUST send a final response after the request has been completed. - -10.1.2 101 Switching Protocols - - The server understands and is willing to comply with the client's - request, via the Upgrade message header field (section 14.41), for a - change in the application protocol being used on this connection. The - server will switch protocols to those defined by the response's - Upgrade header field immediately after the empty line which - terminates the 101 response. - - The protocol should only be switched when it is advantageous to do - so. For example, switching to a newer version of HTTP is - advantageous over older versions, and switching to a real-time, - synchronous protocol may be advantageous when delivering resources - that use such features. - -10.2 Successful 2xx - - This class of status code indicates that the client's request was - successfully received, understood, and accepted. - -10.2.1 200 OK - - The request has succeeded. The information returned with the response - is dependent on the method used in the request, for example: - - GET an entity corresponding to the requested resource is sent in the - response; - - HEAD the entity-header fields corresponding to the requested resource - are sent in the response without any message-body; - - - - -Fielding, et. al. Standards Track [Page 54] - -RFC 2068 HTTP/1.1 January 1997 - - - POST an entity describing or containing the result of the action; - - TRACE an entity containing the request message as received by the end - server. - -10.2.2 201 Created - - The request has been fulfilled and resulted in a new resource being - created. The newly created resource can be referenced by the URI(s) - returned in the entity of the response, with the most specific URL - for the resource given by a Location header field. The origin server - MUST create the resource before returning the 201 status code. If the - action cannot be carried out immediately, the server should respond - with 202 (Accepted) response instead. - -10.2.3 202 Accepted - - The request has been accepted for processing, but the processing has - not been completed. The request MAY or MAY NOT eventually be acted - upon, as it MAY be disallowed when processing actually takes place. - There is no facility for re-sending a status code from an - asynchronous operation such as this. - - The 202 response is intentionally non-committal. Its purpose is to - allow a server to accept a request for some other process (perhaps a - batch-oriented process that is only run once per day) without - requiring that the user agent's connection to the server persist - until the process is completed. The entity returned with this - response SHOULD include an indication of the request's current status - and either a pointer to a status monitor or some estimate of when the - user can expect the request to be fulfilled. - -10.2.4 203 Non-Authoritative Information - - The returned metainformation in the entity-header is not the - definitive set as available from the origin server, but is gathered - from a local or a third-party copy. The set presented MAY be a subset - or superset of the original version. For example, including local - annotation information about the resource MAY result in a superset of - the metainformation known by the origin server. Use of this response - code is not required and is only appropriate when the response would - otherwise be 200 (OK). - -10.2.5 204 No Content - - The server has fulfilled the request but there is no new information - to send back. If the client is a user agent, it SHOULD NOT change its - document view from that which caused the request to be sent. This - - - -Fielding, et. al. Standards Track [Page 55] - -RFC 2068 HTTP/1.1 January 1997 - - - response is primarily intended to allow input for actions to take - place without causing a change to the user agent's active document - view. The response MAY include new metainformation in the form of - entity-headers, which SHOULD apply to the document currently in the - user agent's active view. - - The 204 response MUST NOT include a message-body, and thus is always - terminated by the first empty line after the header fields. - -10.2.6 205 Reset Content - - The server has fulfilled the request and the user agent SHOULD reset - the document view which caused the request to be sent. This response - is primarily intended to allow input for actions to take place via - user input, followed by a clearing of the form in which the input is - given so that the user can easily initiate another input action. The - response MUST NOT include an entity. - -10.2.7 206 Partial Content - - The server has fulfilled the partial GET request for the resource. - The request must have included a Range header field (section 14.36) - indicating the desired range. The response MUST include either a - Content-Range header field (section 14.17) indicating the range - included with this response, or a multipart/byteranges Content-Type - including Content-Range fields for each part. If multipart/byteranges - is not used, the Content-Length header field in the response MUST - match the actual number of OCTETs transmitted in the message-body. - - A cache that does not support the Range and Content-Range headers - MUST NOT cache 206 (Partial) responses. - -10.3 Redirection 3xx - - This class of status code indicates that further action needs to be - taken by the user agent in order to fulfill the request. The action - required MAY be carried out by the user agent without interaction - with the user if and only if the method used in the second request is - GET or HEAD. A user agent SHOULD NOT automatically redirect a request - more than 5 times, since such redirections usually indicate an - infinite loop. - - - - - - - - - - -Fielding, et. al. Standards Track [Page 56] - -RFC 2068 HTTP/1.1 January 1997 - - -10.3.1 300 Multiple Choices - - The requested resource corresponds to any one of a set of - representations, each with its own specific location, and agent- - driven negotiation information (section 12) is being provided so that - the user (or user agent) can select a preferred representation and - redirect its request to that location. - - Unless it was a HEAD request, the response SHOULD include an entity - containing a list of resource characteristics and location(s) from - which the user or user agent can choose the one most appropriate. The - entity format is specified by the media type given in the Content- - Type header field. Depending upon the format and the capabilities of - the user agent, selection of the most appropriate choice may be - performed automatically. However, this specification does not define - any standard for such automatic selection. - - If the server has a preferred choice of representation, it SHOULD - include the specific URL for that representation in the Location - field; user agents MAY use the Location field value for automatic - redirection. This response is cachable unless indicated otherwise. - -10.3.2 301 Moved Permanently - - The requested resource has been assigned a new permanent URI and any - future references to this resource SHOULD be done using one of the - returned URIs. Clients with link editing capabilities SHOULD - automatically re-link references to the Request-URI to one or more of - the new references returned by the server, where possible. This - response is cachable unless indicated otherwise. - - If the new URI is a location, its URL SHOULD be given by the Location - field in the response. Unless the request method was HEAD, the entity - of the response SHOULD contain a short hypertext note with a - hyperlink to the new URI(s). - - If the 301 status code is received in response to a request other - than GET or HEAD, the user agent MUST NOT automatically redirect the - request unless it can be confirmed by the user, since this might - change the conditions under which the request was issued. - - Note: When automatically redirecting a POST request after receiving - a 301 status code, some existing HTTP/1.0 user agents will - erroneously change it into a GET request. - - - - - - - -Fielding, et. al. Standards Track [Page 57] - -RFC 2068 HTTP/1.1 January 1997 - - -10.3.3 302 Moved Temporarily - - The requested resource resides temporarily under a different URI. - Since the redirection may be altered on occasion, the client SHOULD - continue to use the Request-URI for future requests. This response is - only cachable if indicated by a Cache-Control or Expires header - field. - - If the new URI is a location, its URL SHOULD be given by the Location - field in the response. Unless the request method was HEAD, the entity - of the response SHOULD contain a short hypertext note with a - hyperlink to the new URI(s). - - If the 302 status code is received in response to a request other - than GET or HEAD, the user agent MUST NOT automatically redirect the - request unless it can be confirmed by the user, since this might - change the conditions under which the request was issued. - - Note: When automatically redirecting a POST request after receiving - a 302 status code, some existing HTTP/1.0 user agents will - erroneously change it into a GET request. - -10.3.4 303 See Other - - The response to the request can be found under a different URI and - SHOULD be retrieved using a GET method on that resource. This method - exists primarily to allow the output of a POST-activated script to - redirect the user agent to a selected resource. The new URI is not a - substitute reference for the originally requested resource. The 303 - response is not cachable, but the response to the second (redirected) - request MAY be cachable. - - If the new URI is a location, its URL SHOULD be given by the Location - field in the response. Unless the request method was HEAD, the entity - of the response SHOULD contain a short hypertext note with a - hyperlink to the new URI(s). - -10.3.5 304 Not Modified - - If the client has performed a conditional GET request and access is - allowed, but the document has not been modified, the server SHOULD - respond with this status code. The response MUST NOT contain a - message-body. - - - - - - - - -Fielding, et. al. Standards Track [Page 58] - -RFC 2068 HTTP/1.1 January 1997 - - - The response MUST include the following header fields: - - o Date - - o ETag and/or Content-Location, if the header would have been sent in - a 200 response to the same request - - o Expires, Cache-Control, and/or Vary, if the field-value might - differ from that sent in any previous response for the same variant - - If the conditional GET used a strong cache validator (see section - 13.3.3), the response SHOULD NOT include other entity-headers. - Otherwise (i.e., the conditional GET used a weak validator), the - response MUST NOT include other entity-headers; this prevents - inconsistencies between cached entity-bodies and updated headers. - - If a 304 response indicates an entity not currently cached, then the - cache MUST disregard the response and repeat the request without the - conditional. - - If a cache uses a received 304 response to update a cache entry, the - cache MUST update the entry to reflect any new field values given in - the response. - - The 304 response MUST NOT include a message-body, and thus is always - terminated by the first empty line after the header fields. - -10.3.6 305 Use Proxy - - The requested resource MUST be accessed through the proxy given by - the Location field. The Location field gives the URL of the proxy. - The recipient is expected to repeat the request via the proxy. - -10.4 Client Error 4xx - - The 4xx class of status code is intended for cases in which the - client seems to have erred. Except when responding to a HEAD request, - the server SHOULD include an entity containing an explanation of the - error situation, and whether it is a temporary or permanent - condition. These status codes are applicable to any request method. - User agents SHOULD display any included entity to the user. - - Note: If the client is sending data, a server implementation using - TCP should be careful to ensure that the client acknowledges - receipt of the packet(s) containing the response, before the server - closes the input connection. If the client continues sending data - to the server after the close, the server's TCP stack will send a - reset packet to the client, which may erase the client's - - - -Fielding, et. al. Standards Track [Page 59] - -RFC 2068 HTTP/1.1 January 1997 - - - unacknowledged input buffers before they can be read and - interpreted by the HTTP application. - -10.4.1 400 Bad Request - - The request could not be understood by the server due to malformed - syntax. The client SHOULD NOT repeat the request without - modifications. - -10.4.2 401 Unauthorized - - The request requires user authentication. The response MUST include a - WWW-Authenticate header field (section 14.46) containing a challenge - applicable to the requested resource. The client MAY repeat the - request with a suitable Authorization header field (section 14.8). If - the request already included Authorization credentials, then the 401 - response indicates that authorization has been refused for those - credentials. If the 401 response contains the same challenge as the - prior response, and the user agent has already attempted - authentication at least once, then the user SHOULD be presented the - entity that was given in the response, since that entity MAY include - relevant diagnostic information. HTTP access authentication is - explained in section 11. - -10.4.3 402 Payment Required - - This code is reserved for future use. - -10.4.4 403 Forbidden - - The server understood the request, but is refusing to fulfill it. - Authorization will not help and the request SHOULD NOT be repeated. - If the request method was not HEAD and the server wishes to make - public why the request has not been fulfilled, it SHOULD describe the - reason for the refusal in the entity. This status code is commonly - used when the server does not wish to reveal exactly why the request - has been refused, or when no other response is applicable. - -10.4.5 404 Not Found - - The server has not found anything matching the Request-URI. No - indication is given of whether the condition is temporary or - permanent. - - - - - - - - -Fielding, et. al. Standards Track [Page 60] - -RFC 2068 HTTP/1.1 January 1997 - - - If the server does not wish to make this information available to the - client, the status code 403 (Forbidden) can be used instead. The 410 - (Gone) status code SHOULD be used if the server knows, through some - internally configurable mechanism, that an old resource is - permanently unavailable and has no forwarding address. - -10.4.6 405 Method Not Allowed - - The method specified in the Request-Line is not allowed for the - resource identified by the Request-URI. The response MUST include an - Allow header containing a list of valid methods for the requested - resource. - -10.4.7 406 Not Acceptable - - The resource identified by the request is only capable of generating - response entities which have content characteristics not acceptable - according to the accept headers sent in the request. - - Unless it was a HEAD request, the response SHOULD include an entity - containing a list of available entity characteristics and location(s) - from which the user or user agent can choose the one most - appropriate. The entity format is specified by the media type given - in the Content-Type header field. Depending upon the format and the - capabilities of the user agent, selection of the most appropriate - choice may be performed automatically. However, this specification - does not define any standard for such automatic selection. - - Note: HTTP/1.1 servers are allowed to return responses which are - not acceptable according to the accept headers sent in the request. - In some cases, this may even be preferable to sending a 406 - response. User agents are encouraged to inspect the headers of an - incoming response to determine if it is acceptable. If the response - could be unacceptable, a user agent SHOULD temporarily stop receipt - of more data and query the user for a decision on further actions. - -10.4.8 407 Proxy Authentication Required - - This code is similar to 401 (Unauthorized), but indicates that the - client MUST first authenticate itself with the proxy. The proxy MUST - return a Proxy-Authenticate header field (section 14.33) containing a - challenge applicable to the proxy for the requested resource. The - client MAY repeat the request with a suitable Proxy-Authorization - header field (section 14.34). HTTP access authentication is explained - in section 11. - - - - - - -Fielding, et. al. Standards Track [Page 61] - -RFC 2068 HTTP/1.1 January 1997 - - -10.4.9 408 Request Timeout - - The client did not produce a request within the time that the server - was prepared to wait. The client MAY repeat the request without - modifications at any later time. - -10.4.10 409 Conflict - - The request could not be completed due to a conflict with the current - state of the resource. This code is only allowed in situations where - it is expected that the user might be able to resolve the conflict - and resubmit the request. The response body SHOULD include enough - information for the user to recognize the source of the conflict. - Ideally, the response entity would include enough information for the - user or user agent to fix the problem; however, that may not be - possible and is not required. - - Conflicts are most likely to occur in response to a PUT request. If - versioning is being used and the entity being PUT includes changes to - a resource which conflict with those made by an earlier (third-party) - request, the server MAY use the 409 response to indicate that it - can't complete the request. In this case, the response entity SHOULD - contain a list of the differences between the two versions in a - format defined by the response Content-Type. - -10.4.11 410 Gone - - The requested resource is no longer available at the server and no - forwarding address is known. This condition SHOULD be considered - permanent. Clients with link editing capabilities SHOULD delete - references to the Request-URI after user approval. If the server does - not know, or has no facility to determine, whether or not the - condition is permanent, the status code 404 (Not Found) SHOULD be - used instead. This response is cachable unless indicated otherwise. - - The 410 response is primarily intended to assist the task of web - maintenance by notifying the recipient that the resource is - intentionally unavailable and that the server owners desire that - remote links to that resource be removed. Such an event is common for - limited-time, promotional services and for resources belonging to - individuals no longer working at the server's site. It is not - necessary to mark all permanently unavailable resources as "gone" or - to keep the mark for any length of time -- that is left to the - discretion of the server owner. - - - - - - - -Fielding, et. al. Standards Track [Page 62] - -RFC 2068 HTTP/1.1 January 1997 - - -10.4.12 411 Length Required - - The server refuses to accept the request without a defined Content- - Length. The client MAY repeat the request if it adds a valid - Content-Length header field containing the length of the message-body - in the request message. - -10.4.13 412 Precondition Failed - - The precondition given in one or more of the request-header fields - evaluated to false when it was tested on the server. This response - code allows the client to place preconditions on the current resource - metainformation (header field data) and thus prevent the requested - method from being applied to a resource other than the one intended. - -10.4.14 413 Request Entity Too Large - - The server is refusing to process a request because the request - entity is larger than the server is willing or able to process. The - server may close the connection to prevent the client from continuing - the request. - - If the condition is temporary, the server SHOULD include a Retry- - After header field to indicate that it is temporary and after what - time the client may try again. - -10.4.15 414 Request-URI Too Long - - The server is refusing to service the request because the Request-URI - is longer than the server is willing to interpret. This rare - condition is only likely to occur when a client has improperly - converted a POST request to a GET request with long query - information, when the client has descended into a URL "black hole" of - redirection (e.g., a redirected URL prefix that points to a suffix of - itself), or when the server is under attack by a client attempting to - exploit security holes present in some servers using fixed-length - buffers for reading or manipulating the Request-URI. - -10.4.16 415 Unsupported Media Type - - The server is refusing to service the request because the entity of - the request is in a format not supported by the requested resource - for the requested method. - - - - - - - - -Fielding, et. al. Standards Track [Page 63] - -RFC 2068 HTTP/1.1 January 1997 - - -10.5 Server Error 5xx - - Response status codes beginning with the digit "5" indicate cases in - which the server is aware that it has erred or is incapable of - performing the request. Except when responding to a HEAD request, the - server SHOULD include an entity containing an explanation of the - error situation, and whether it is a temporary or permanent - condition. User agents SHOULD display any included entity to the - user. These response codes are applicable to any request method. - -10.5.1 500 Internal Server Error - - The server encountered an unexpected condition which prevented it - from fulfilling the request. - -10.5.2 501 Not Implemented - - The server does not support the functionality required to fulfill the - request. This is the appropriate response when the server does not - recognize the request method and is not capable of supporting it for - any resource. - -10.5.3 502 Bad Gateway - - The server, while acting as a gateway or proxy, received an invalid - response from the upstream server it accessed in attempting to - fulfill the request. - -10.5.4 503 Service Unavailable - - The server is currently unable to handle the request due to a - temporary overloading or maintenance of the server. The implication - is that this is a temporary condition which will be alleviated after - some delay. If known, the length of the delay may be indicated in a - Retry-After header. If no Retry-After is given, the client SHOULD - handle the response as it would for a 500 response. - - Note: The existence of the 503 status code does not imply that a - server must use it when becoming overloaded. Some servers may wish - to simply refuse the connection. - -10.5.5 504 Gateway Timeout - - The server, while acting as a gateway or proxy, did not receive a - timely response from the upstream server it accessed in attempting to - complete the request. - - - - - -Fielding, et. al. Standards Track [Page 64] - -RFC 2068 HTTP/1.1 January 1997 - - -10.5.6 505 HTTP Version Not Supported - - The server does not support, or refuses to support, the HTTP protocol - version that was used in the request message. The server is - indicating that it is unable or unwilling to complete the request - using the same major version as the client, as described in section - 3.1, other than with this error message. The response SHOULD contain - an entity describing why that version is not supported and what other - protocols are supported by that server. - -11 Access Authentication - - HTTP provides a simple challenge-response authentication mechanism - which MAY be used by a server to challenge a client request and by a - client to provide authentication information. It uses an extensible, - case-insensitive token to identify the authentication scheme, - followed by a comma-separated list of attribute-value pairs which - carry the parameters necessary for achieving authentication via that - scheme. - - auth-scheme = token - - auth-param = token "=" quoted-string - - The 401 (Unauthorized) response message is used by an origin server - to challenge the authorization of a user agent. This response MUST - include a WWW-Authenticate header field containing at least one - challenge applicable to the requested resource. - - challenge = auth-scheme 1*SP realm *( "," auth-param ) - - realm = "realm" "=" realm-value - realm-value = quoted-string - - The realm attribute (case-insensitive) is required for all - authentication schemes which issue a challenge. The realm value - (case-sensitive), in combination with the canonical root URL (see - section 5.1.2) of the server being accessed, defines the protection - space. These realms allow the protected resources on a server to be - partitioned into a set of protection spaces, each with its own - authentication scheme and/or authorization database. The realm value - is a string, generally assigned by the origin server, which may have - additional semantics specific to the authentication scheme. - - A user agent that wishes to authenticate itself with a server-- - usually, but not necessarily, after receiving a 401 or 411 response- - -MAY do so by including an Authorization header field with the - request. The Authorization field value consists of credentials - - - -Fielding, et. al. Standards Track [Page 65] - -RFC 2068 HTTP/1.1 January 1997 - - - containing the authentication information of the user agent for the - realm of the resource being requested. - - credentials = basic-credentials - | auth-scheme #auth-param - - The domain over which credentials can be automatically applied by a - user agent is determined by the protection space. If a prior request - has been authorized, the same credentials MAY be reused for all other - requests within that protection space for a period of time determined - by the authentication scheme, parameters, and/or user preference. - Unless otherwise defined by the authentication scheme, a single - protection space cannot extend outside the scope of its server. - - If the server does not wish to accept the credentials sent with a - request, it SHOULD return a 401 (Unauthorized) response. The response - MUST include a WWW-Authenticate header field containing the (possibly - new) challenge applicable to the requested resource and an entity - explaining the refusal. - - The HTTP protocol does not restrict applications to this simple - challenge-response mechanism for access authentication. Additional - mechanisms MAY be used, such as encryption at the transport level or - via message encapsulation, and with additional header fields - specifying authentication information. However, these additional - mechanisms are not defined by this specification. - - Proxies MUST be completely transparent regarding user agent - authentication. That is, they MUST forward the WWW-Authenticate and - Authorization headers untouched, and follow the rules found in - section 14.8. - - HTTP/1.1 allows a client to pass authentication information to and - from a proxy via the Proxy-Authenticate and Proxy-Authorization - headers. - -11.1 Basic Authentication Scheme - - The "basic" authentication scheme is based on the model that the user - agent must authenticate itself with a user-ID and a password for each - realm. The realm value should be considered an opaque string which - can only be compared for equality with other realms on that server. - The server will service the request only if it can validate the - user-ID and password for the protection space of the Request-URI. - There are no optional authentication parameters. - - - - - - -Fielding, et. al. Standards Track [Page 66] - -RFC 2068 HTTP/1.1 January 1997 - - - Upon receipt of an unauthorized request for a URI within the - protection space, the server MAY respond with a challenge like the - following: - - WWW-Authenticate: Basic realm="WallyWorld" - - where "WallyWorld" is the string assigned by the server to identify - the protection space of the Request-URI. - - To receive authorization, the client sends the userid and password, - separated by a single colon (":") character, within a base64 encoded - string in the credentials. - - basic-credentials = "Basic" SP basic-cookie - - basic-cookie = <base64 [7] encoding of user-pass, - except not limited to 76 char/line> - - user-pass = userid ":" password - - userid = *<TEXT excluding ":"> - - password = *TEXT - - Userids might be case sensitive. - - If the user agent wishes to send the userid "Aladdin" and password - "open sesame", it would use the following header field: - - Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== - - See section 15 for security considerations associated with Basic - authentication. - -11.2 Digest Authentication Scheme - - A digest authentication for HTTP is specified in RFC 2069 [32]. - -12 Content Negotiation - - Most HTTP responses include an entity which contains information for - interpretation by a human user. Naturally, it is desirable to supply - the user with the "best available" entity corresponding to the - request. Unfortunately for servers and caches, not all users have - the same preferences for what is "best," and not all user agents are - equally capable of rendering all entity types. For that reason, HTTP - has provisions for several mechanisms for "content negotiation" -- - the process of selecting the best representation for a given response - - - -Fielding, et. al. Standards Track [Page 67] - -RFC 2068 HTTP/1.1 January 1997 - - - when there are multiple representations available. - - Note: This is not called "format negotiation" because the alternate - representations may be of the same media type, but use different - capabilities of that type, be in different languages, etc. - - Any response containing an entity-body MAY be subject to negotiation, - including error responses. - - There are two kinds of content negotiation which are possible in - HTTP: server-driven and agent-driven negotiation. These two kinds of - negotiation are orthogonal and thus may be used separately or in - combination. One method of combination, referred to as transparent - negotiation, occurs when a cache uses the agent-driven negotiation - information provided by the origin server in order to provide - server-driven negotiation for subsequent requests. - -12.1 Server-driven Negotiation - - If the selection of the best representation for a response is made by - an algorithm located at the server, it is called server-driven - negotiation. Selection is based on the available representations of - the response (the dimensions over which it can vary; e.g. language, - content-coding, etc.) and the contents of particular header fields in - the request message or on other information pertaining to the request - (such as the network address of the client). - - Server-driven negotiation is advantageous when the algorithm for - selecting from among the available representations is difficult to - describe to the user agent, or when the server desires to send its - "best guess" to the client along with the first response (hoping to - avoid the round-trip delay of a subsequent request if the "best - guess" is good enough for the user). In order to improve the server's - guess, the user agent MAY include request header fields (Accept, - Accept-Language, Accept-Encoding, etc.) which describe its - preferences for such a response. - - Server-driven negotiation has disadvantages: - -1. It is impossible for the server to accurately determine what might be - "best" for any given user, since that would require complete - knowledge of both the capabilities of the user agent and the intended - use for the response (e.g., does the user want to view it on screen - or print it on paper?). - -2. Having the user agent describe its capabilities in every request can - be both very inefficient (given that only a small percentage of - responses have multiple representations) and a potential violation of - - - -Fielding, et. al. Standards Track [Page 68] - -RFC 2068 HTTP/1.1 January 1997 - - - the user's privacy. - -3. It complicates the implementation of an origin server and the - algorithms for generating responses to a request. - -4. It may limit a public cache's ability to use the same response for - multiple user's requests. - - HTTP/1.1 includes the following request-header fields for enabling - server-driven negotiation through description of user agent - capabilities and user preferences: Accept (section 14.1), Accept- - Charset (section 14.2), Accept-Encoding (section 14.3), Accept- - Language (section 14.4), and User-Agent (section 14.42). However, an - origin server is not limited to these dimensions and MAY vary the - response based on any aspect of the request, including information - outside the request-header fields or within extension header fields - not defined by this specification. - - HTTP/1.1 origin servers MUST include an appropriate Vary header field - (section 14.43) in any cachable response based on server-driven - negotiation. The Vary header field describes the dimensions over - which the response might vary (i.e. the dimensions over which the - origin server picks its "best guess" response from multiple - representations). - - HTTP/1.1 public caches MUST recognize the Vary header field when it - is included in a response and obey the requirements described in - section 13.6 that describes the interactions between caching and - content negotiation. - -12.2 Agent-driven Negotiation - - With agent-driven negotiation, selection of the best representation - for a response is performed by the user agent after receiving an - initial response from the origin server. Selection is based on a list - of the available representations of the response included within the - header fields (this specification reserves the field-name Alternates, - as described in appendix 19.6.2.1) or entity-body of the initial - response, with each representation identified by its own URI. - Selection from among the representations may be performed - automatically (if the user agent is capable of doing so) or manually - by the user selecting from a generated (possibly hypertext) menu. - - Agent-driven negotiation is advantageous when the response would vary - over commonly-used dimensions (such as type, language, or encoding), - when the origin server is unable to determine a user agent's - capabilities from examining the request, and generally when public - caches are used to distribute server load and reduce network usage. - - - -Fielding, et. al. Standards Track [Page 69] - -RFC 2068 HTTP/1.1 January 1997 - - - Agent-driven negotiation suffers from the disadvantage of needing a - second request to obtain the best alternate representation. This - second request is only efficient when caching is used. In addition, - this specification does not define any mechanism for supporting - automatic selection, though it also does not prevent any such - mechanism from being developed as an extension and used within - HTTP/1.1. - - HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable) - status codes for enabling agent-driven negotiation when the server is - unwilling or unable to provide a varying response using server-driven - negotiation. - -12.3 Transparent Negotiation - - Transparent negotiation is a combination of both server-driven and - agent-driven negotiation. When a cache is supplied with a form of the - list of available representations of the response (as in agent-driven - negotiation) and the dimensions of variance are completely understood - by the cache, then the cache becomes capable of performing server- - driven negotiation on behalf of the origin server for subsequent - requests on that resource. - - Transparent negotiation has the advantage of distributing the - negotiation work that would otherwise be required of the origin - server and also removing the second request delay of agent-driven - negotiation when the cache is able to correctly guess the right - response. - - This specification does not define any mechanism for transparent - negotiation, though it also does not prevent any such mechanism from - being developed as an extension and used within HTTP/1.1. An HTTP/1.1 - cache performing transparent negotiation MUST include a Vary header - field in the response (defining the dimensions of its variance) if it - is cachable to ensure correct interoperation with all HTTP/1.1 - clients. The agent-driven negotiation information supplied by the - origin server SHOULD be included with the transparently negotiated - response. - -13 Caching in HTTP - - HTTP is typically used for distributed information systems, where - performance can be improved by the use of response caches. The - HTTP/1.1 protocol includes a number of elements intended to make - caching work as well as possible. Because these elements are - inextricable from other aspects of the protocol, and because they - interact with each other, it is useful to describe the basic caching - design of HTTP separately from the detailed descriptions of methods, - - - -Fielding, et. al. Standards Track [Page 70] - -RFC 2068 HTTP/1.1 January 1997 - - - headers, response codes, etc. - - Caching would be useless if it did not significantly improve - performance. The goal of caching in HTTP/1.1 is to eliminate the need - to send requests in many cases, and to eliminate the need to send - full responses in many other cases. The former reduces the number of - network round-trips required for many operations; we use an - "expiration" mechanism for this purpose (see section 13.2). The - latter reduces network bandwidth requirements; we use a "validation" - mechanism for this purpose (see section 13.3). - - Requirements for performance, availability, and disconnected - operation require us to be able to relax the goal of semantic - transparency. The HTTP/1.1 protocol allows origin servers, caches, - and clients to explicitly reduce transparency when necessary. - However, because non-transparent operation may confuse non-expert - users, and may be incompatible with certain server applications (such - as those for ordering merchandise), the protocol requires that - transparency be relaxed - - o only by an explicit protocol-level request when relaxed by client - or origin server - - o only with an explicit warning to the end user when relaxed by cache - or client - - - - - - - - - - - - - - - - - - - - - - - - - - -Fielding, et. al. Standards Track [Page 71] - -RFC 2068 HTTP/1.1 January 1997 - - - Therefore, the HTTP/1.1 protocol provides these important elements: - - 1. Protocol features that provide full semantic transparency when this - is required by all parties. - - 2. Protocol features that allow an origin server or user agent to - explicitly request and control non-transparent operation. - - 3. Protocol features that allow a cache to attach warnings to - responses that do not preserve the requested approximation of - semantic transparency. - - A basic principle is that it must be possible for the clients to - detect any potential relaxation of semantic transparency. - - Note: The server, cache, or client implementer may be faced with - design decisions not explicitly discussed in this specification. If - a decision may affect semantic transparency, the implementer ought - to err on the side of maintaining transparency unless a careful and - complete analysis shows significant benefits in breaking - transparency. - -13.1.1 Cache Correctness - - A correct cache MUST respond to a request with the most up-to-date - response held by the cache that is appropriate to the request (see - sections 13.2.5, 13.2.6, and 13.12) which meets one of the following - conditions: - - 1. It has been checked for equivalence with what the origin server - would have returned by revalidating the response with the origin - server (section 13.3); - - 2. It is "fresh enough" (see section 13.2). In the default case, this - means it meets the least restrictive freshness requirement of the - client, server, and cache (see section 14.9); if the origin server - so specifies, it is the freshness requirement of the origin server - alone. - - 3. It includes a warning if the freshness demand of the client or the - origin server is violated (see section 13.1.5 and 14.45). - - 4. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), or - error (4xx or 5xx) response message. - - If the cache can not communicate with the origin server, then a - correct cache SHOULD respond as above if the response can be - correctly served from the cache; if not it MUST return an error or - - - -Fielding, et. al. Standards Track [Page 72] - -RFC 2068 HTTP/1.1 January 1997 - - - warning indicating that there was a communication failure. - - If a cache receives a response (either an entire response, or a 304 - (Not Modified) response) that it would normally forward to the - requesting client, and the received response is no longer fresh, the - cache SHOULD forward it to the requesting client without adding a new - Warning (but without removing any existing Warning headers). A cache - SHOULD NOT attempt to revalidate a response simply because that - response became stale in transit; this might lead to an infinite - loop. An user agent that receives a stale response without a Warning - MAY display a warning indication to the user. - -13.1.2 Warnings - - Whenever a cache returns a response that is neither first-hand nor - "fresh enough" (in the sense of condition 2 in section 13.1.1), it - must attach a warning to that effect, using a Warning response- - header. This warning allows clients to take appropriate action. - - Warnings may be used for other purposes, both cache-related and - otherwise. The use of a warning, rather than an error status code, - distinguish these responses from true failures. - - Warnings are always cachable, because they never weaken the - transparency of a response. This means that warnings can be passed to - HTTP/1.0 caches without danger; such caches will simply pass the - warning along as an entity-header in the response. - - Warnings are assigned numbers between 0 and 99. This specification - defines the code numbers and meanings of each currently assigned - warnings, allowing a client or cache to take automated action in some - (but not all) cases. - - Warnings also carry a warning text. The text may be in any - appropriate natural language (perhaps based on the client's Accept - headers), and include an optional indication of what character set is - used. - - Multiple warnings may be attached to a response (either by the origin - server or by a cache), including multiple warnings with the same code - number. For example, a server may provide the same warning with texts - in both English and Basque. - - When multiple warnings are attached to a response, it may not be - practical or reasonable to display all of them to the user. This - version of HTTP does not specify strict priority rules for deciding - which warnings to display and in what order, but does suggest some - heuristics. - - - -Fielding, et. al. Standards Track [Page 73] - -RFC 2068 HTTP/1.1 January 1997 - - - The Warning header and the currently defined warnings are described - in section 14.45. - -13.1.3 Cache-control Mechanisms - - The basic cache mechanisms in HTTP/1.1 (server-specified expiration - times and validators) are implicit directives to caches. In some - cases, a server or client may need to provide explicit directives to - the HTTP caches. We use the Cache-Control header for this purpose. - - The Cache-Control header allows a client or server to transmit a - variety of directives in either requests or responses. These - directives typically override the default caching algorithms. As a - general rule, if there is any apparent conflict between header - values, the most restrictive interpretation should be applied (that - is, the one that is most likely to preserve semantic transparency). - However, in some cases, Cache-Control directives are explicitly - specified as weakening the approximation of semantic transparency - (for example, "max-stale" or "public"). - - The Cache-Control directives are described in detail in section 14.9. - -13.1.4 Explicit User Agent Warnings - - Many user agents make it possible for users to override the basic - caching mechanisms. For example, the user agent may allow the user to - specify that cached entities (even explicitly stale ones) are never - validated. Or the user agent might habitually add "Cache-Control: - max-stale=3600" to every request. The user should have to explicitly - request either non-transparent behavior, or behavior that results in - abnormally ineffective caching. - - If the user has overridden the basic caching mechanisms, the user - agent should explicitly indicate to the user whenever this results in - the display of information that might not meet the server's - transparency requirements (in particular, if the displayed entity is - known to be stale). Since the protocol normally allows the user agent - to determine if responses are stale or not, this indication need only - be displayed when this actually happens. The indication need not be a - dialog box; it could be an icon (for example, a picture of a rotting - fish) or some other visual indicator. - - If the user has overridden the caching mechanisms in a way that would - abnormally reduce the effectiveness of caches, the user agent should - continually display an indication (for example, a picture of currency - in flames) so that the user does not inadvertently consume excess - resources or suffer from excessive latency. - - - - -Fielding, et. al. Standards Track [Page 74] - -RFC 2068 HTTP/1.1 January 1997 - - -13.1.5 Exceptions to the Rules and Warnings - - In some cases, the operator of a cache may choose to configure it to - return stale responses even when not requested by clients. This - decision should not be made lightly, but may be necessary for reasons - of availability or performance, especially when the cache is poorly - connected to the origin server. Whenever a cache returns a stale - response, it MUST mark it as such (using a Warning header). This - allows the client software to alert the user that there may be a - potential problem. - - It also allows the user agent to take steps to obtain a first-hand or - fresh response. For this reason, a cache SHOULD NOT return a stale - response if the client explicitly requests a first-hand or fresh one, - unless it is impossible to comply for technical or policy reasons. - -13.1.6 Client-controlled Behavior - - While the origin server (and to a lesser extent, intermediate caches, - by their contribution to the age of a response) are the primary - source of expiration information, in some cases the client may need - to control a cache's decision about whether to return a cached - response without validating it. Clients do this using several - directives of the Cache-Control header. - - A client's request may specify the maximum age it is willing to - accept of an unvalidated response; specifying a value of zero forces - the cache(s) to revalidate all responses. A client may also specify - the minimum time remaining before a response expires. Both of these - options increase constraints on the behavior of caches, and so cannot - further relax the cache's approximation of semantic transparency. - - A client may also specify that it will accept stale responses, up to - some maximum amount of staleness. This loosens the constraints on the - caches, and so may violate the origin server's specified constraints - on semantic transparency, but may be necessary to support - disconnected operation, or high availability in the face of poor - connectivity. - -13.2 Expiration Model - -13.2.1 Server-Specified Expiration - - HTTP caching works best when caches can entirely avoid making - requests to the origin server. The primary mechanism for avoiding - requests is for an origin server to provide an explicit expiration - time in the future, indicating that a response may be used to satisfy - subsequent requests. In other words, a cache can return a fresh - - - -Fielding, et. al. Standards Track [Page 75] - -RFC 2068 HTTP/1.1 January 1997 - - - response without first contacting the server. - - Our expectation is that servers will assign future explicit - expiration times to responses in the belief that the entity is not - likely to change, in a semantically significant way, before the - expiration time is reached. This normally preserves semantic - transparency, as long as the server's expiration times are carefully - chosen. - - The expiration mechanism applies only to responses taken from a cache - and not to first-hand responses forwarded immediately to the - requesting client. - - If an origin server wishes to force a semantically transparent cache - to validate every request, it may assign an explicit expiration time - in the past. This means that the response is always stale, and so the - cache SHOULD validate it before using it for subsequent requests. See - section 14.9.4 for a more restrictive way to force revalidation. - - If an origin server wishes to force any HTTP/1.1 cache, no matter how - it is configured, to validate every request, it should use the - "must-revalidate" Cache-Control directive (see section 14.9). - - Servers specify explicit expiration times using either the Expires - header, or the max-age directive of the Cache-Control header. - - An expiration time cannot be used to force a user agent to refresh - its display or reload a resource; its semantics apply only to caching - mechanisms, and such mechanisms need only check a resource's - expiration status when a new request for that resource is initiated. - See section 13.13 for explanation of the difference between caches - and history mechanisms. - -13.2.2 Heuristic Expiration - - Since origin servers do not always provide explicit expiration times, - HTTP caches typically assign heuristic expiration times, employing - algorithms that use other header values (such as the Last-Modified - time) to estimate a plausible expiration time. The HTTP/1.1 - specification does not provide specific algorithms, but does impose - worst-case constraints on their results. Since heuristic expiration - times may compromise semantic transparency, they should be used - cautiously, and we encourage origin servers to provide explicit - expiration times as much as possible. - - - - - - - -Fielding, et. al. Standards Track [Page 76] - -RFC 2068 HTTP/1.1 January 1997 - - -13.2.3 Age Calculations - - In order to know if a cached entry is fresh, a cache needs to know if - its age exceeds its freshness lifetime. We discuss how to calculate - the latter in section 13.2.4; this section describes how to calculate - the age of a response or cache entry. - - In this discussion, we use the term "now" to mean "the current value - of the clock at the host performing the calculation." Hosts that use - HTTP, but especially hosts running origin servers and caches, should - use NTP [28] or some similar protocol to synchronize their clocks to - a globally accurate time standard. - - Also note that HTTP/1.1 requires origin servers to send a Date header - with every response, giving the time at which the response was - generated. We use the term "date_value" to denote the value of the - Date header, in a form appropriate for arithmetic operations. - - HTTP/1.1 uses the Age response-header to help convey age information - between caches. The Age header value is the sender's estimate of the - amount of time since the response was generated at the origin server. - In the case of a cached response that has been revalidated with the - origin server, the Age value is based on the time of revalidation, - not of the original response. - - In essence, the Age value is the sum of the time that the response - has been resident in each of the caches along the path from the - origin server, plus the amount of time it has been in transit along - network paths. - - We use the term "age_value" to denote the value of the Age header, in - a form appropriate for arithmetic operations. - - A response's age can be calculated in two entirely independent ways: - - 1. now minus date_value, if the local clock is reasonably well - synchronized to the origin server's clock. If the result is - negative, the result is replaced by zero. - - 2. age_value, if all of the caches along the response path - implement HTTP/1.1. - - Given that we have two independent ways to compute the age of a - response when it is received, we can combine these as - - corrected_received_age = max(now - date_value, age_value) - - and as long as we have either nearly synchronized clocks or all- - - - -Fielding, et. al. Standards Track [Page 77] - -RFC 2068 HTTP/1.1 January 1997 - - - HTTP/1.1 paths, one gets a reliable (conservative) result. - - Note that this correction is applied at each HTTP/1.1 cache along the - path, so that if there is an HTTP/1.0 cache in the path, the correct - received age is computed as long as the receiving cache's clock is - nearly in sync. We don't need end-to-end clock synchronization - (although it is good to have), and there is no explicit clock - synchronization step. - - Because of network-imposed delays, some significant interval may pass - from the time that a server generates a response and the time it is - received at the next outbound cache or client. If uncorrected, this - delay could result in improperly low ages. - - Because the request that resulted in the returned Age value must have - been initiated prior to that Age value's generation, we can correct - for delays imposed by the network by recording the time at which the - request was initiated. Then, when an Age value is received, it MUST - be interpreted relative to the time the request was initiated, not - the time that the response was received. This algorithm results in - conservative behavior no matter how much delay is experienced. So, we - compute: - - corrected_initial_age = corrected_received_age - + (now - request_time) - - where "request_time" is the time (according to the local clock) when - the request that elicited this response was sent. - - Summary of age calculation algorithm, when a cache receives a - response: - - /* - * age_value - * is the value of Age: header received by the cache with - * this response. - * date_value - * is the value of the origin server's Date: header - * request_time - * is the (local) time when the cache made the request - * that resulted in this cached response - * response_time - * is the (local) time when the cache received the - * response - * now - * is the current (local) time - */ - apparent_age = max(0, response_time - date_value); - - - -Fielding, et. al. Standards Track [Page 78] - -RFC 2068 HTTP/1.1 January 1997 - - - corrected_received_age = max(apparent_age, age_value); - response_delay = response_time - request_time; - corrected_initial_age = corrected_received_age + response_delay; - resident_time = now - response_time; - current_age = corrected_initial_age + resident_time; - - When a cache sends a response, it must add to the - corrected_initial_age the amount of time that the response was - resident locally. It must then transmit this total age, using the Age - header, to the next recipient cache. - - Note that a client cannot reliably tell that a response is first- - hand, but the presence of an Age header indicates that a response - is definitely not first-hand. Also, if the Date in a response is - earlier than the client's local request time, the response is - probably not first-hand (in the absence of serious clock skew). - -13.2.4 Expiration Calculations - - In order to decide whether a response is fresh or stale, we need to - compare its freshness lifetime to its age. The age is calculated as - described in section 13.2.3; this section describes how to calculate - the freshness lifetime, and to determine if a response has expired. - In the discussion below, the values can be represented in any form - appropriate for arithmetic operations. - - We use the term "expires_value" to denote the value of the Expires - header. We use the term "max_age_value" to denote an appropriate - value of the number of seconds carried by the max-age directive of - the Cache-Control header in a response (see section 14.10. - - The max-age directive takes priority over Expires, so if max-age is - present in a response, the calculation is simply: - - freshness_lifetime = max_age_value - - Otherwise, if Expires is present in the response, the calculation is: - - freshness_lifetime = expires_value - date_value - - Note that neither of these calculations is vulnerable to clock skew, - since all of the information comes from the origin server. - - If neither Expires nor Cache-Control: max-age appears in the - response, and the response does not include other restrictions on - caching, the cache MAY compute a freshness lifetime using a - heuristic. If the value is greater than 24 hours, the cache must - attach Warning 13 to any response whose age is more than 24 hours if - - - -Fielding, et. al. Standards Track [Page 79] - -RFC 2068 HTTP/1.1 January 1997 - - - such warning has not already been added. - - Also, if the response does have a Last-Modified time, the heuristic - expiration value SHOULD be no more than some fraction of the interval - since that time. A typical setting of this fraction might be 10%. - - The calculation to determine if a response has expired is quite - simple: - - response_is_fresh = (freshness_lifetime > current_age) - -13.2.5 Disambiguating Expiration Values - - Because expiration values are assigned optimistically, it is possible - for two caches to contain fresh values for the same resource that are - different. - - If a client performing a retrieval receives a non-first-hand response - for a request that was already fresh in its own cache, and the Date - header in its existing cache entry is newer than the Date on the new - response, then the client MAY ignore the response. If so, it MAY - retry the request with a "Cache-Control: max-age=0" directive (see - section 14.9), to force a check with the origin server. - - If a cache has two fresh responses for the same representation with - different validators, it MUST use the one with the more recent Date - header. This situation may arise because the cache is pooling - responses from other caches, or because a client has asked for a - reload or a revalidation of an apparently fresh cache entry. - -13.2.6 Disambiguating Multiple Responses - - Because a client may be receiving responses via multiple paths, so - that some responses flow through one set of caches and other - responses flow through a different set of caches, a client may - receive responses in an order different from that in which the origin - server sent them. We would like the client to use the most recently - generated response, even if older responses are still apparently - fresh. - - Neither the entity tag nor the expiration value can impose an - ordering on responses, since it is possible that a later response - intentionally carries an earlier expiration time. However, the - HTTP/1.1 specification requires the transmission of Date headers on - every response, and the Date values are ordered to a granularity of - one second. - - - - - -Fielding, et. al. Standards Track [Page 80] - -RFC 2068 HTTP/1.1 January 1997 - - - When a client tries to revalidate a cache entry, and the response it - receives contains a Date header that appears to be older than the one - for the existing entry, then the client SHOULD repeat the request - unconditionally, and include - - Cache-Control: max-age=0 - - to force any intermediate caches to validate their copies directly - with the origin server, or - - Cache-Control: no-cache - - to force any intermediate caches to obtain a new copy from the origin - server. - - If the Date values are equal, then the client may use either response - (or may, if it is being extremely prudent, request a new response). - Servers MUST NOT depend on clients being able to choose - deterministically between responses generated during the same second, - if their expiration times overlap. - -13.3 Validation Model - - When a cache has a stale entry that it would like to use as a - response to a client's request, it first has to check with the origin - server (or possibly an intermediate cache with a fresh response) to - see if its cached entry is still usable. We call this "validating" - the cache entry. Since we do not want to have to pay the overhead of - retransmitting the full response if the cached entry is good, and we - do not want to pay the overhead of an extra round trip if the cached - entry is invalid, the HTTP/1.1 protocol supports the use of - conditional methods. - - The key protocol features for supporting conditional methods are - those concerned with "cache validators." When an origin server - generates a full response, it attaches some sort of validator to it, - which is kept with the cache entry. When a client (user agent or - proxy cache) makes a conditional request for a resource for which it - has a cache entry, it includes the associated validator in the - request. - - The server then checks that validator against the current validator - for the entity, and, if they match, it responds with a special status - code (usually, 304 (Not Modified)) and no entity-body. Otherwise, it - returns a full response (including entity-body). Thus, we avoid - transmitting the full response if the validator matches, and we avoid - an extra round trip if it does not match. - - - - -Fielding, et. al. Standards Track [Page 81] - -RFC 2068 HTTP/1.1 January 1997 - - - Note: the comparison functions used to decide if validators match - are defined in section 13.3.3. - - In HTTP/1.1, a conditional request looks exactly the same as a normal - request for the same resource, except that it carries a special - header (which includes the validator) that implicitly turns the - method (usually, GET) into a conditional. - - The protocol includes both positive and negative senses of cache- - validating conditions. That is, it is possible to request either that - a method be performed if and only if a validator matches or if and - only if no validators match. - - Note: a response that lacks a validator may still be cached, and - served from cache until it expires, unless this is explicitly - prohibited by a Cache-Control directive. However, a cache cannot do - a conditional retrieval if it does not have a validator for the - entity, which means it will not be refreshable after it expires. - -13.3.1 Last-modified Dates - - The Last-Modified entity-header field value is often used as a cache - validator. In simple terms, a cache entry is considered to be valid - if the entity has not been modified since the Last-Modified value. - -13.3.2 Entity Tag Cache Validators - - The ETag entity-header field value, an entity tag, provides for an - "opaque" cache validator. This may allow more reliable validation in - situations where it is inconvenient to store modification dates, - where the one-second resolution of HTTP date values is not - sufficient, or where the origin server wishes to avoid certain - paradoxes that may arise from the use of modification dates. - - Entity Tags are described in section 3.11. The headers used with - entity tags are described in sections 14.20, 14.25, 14.26 and 14.43. - -13.3.3 Weak and Strong Validators - - Since both origin servers and caches will compare two validators to - decide if they represent the same or different entities, one normally - would expect that if the entity (the entity-body or any entity- - headers) changes in any way, then the associated validator would - change as well. If this is true, then we call this validator a - "strong validator." - - However, there may be cases when a server prefers to change the - validator only on semantically significant changes, and not when - - - -Fielding, et. al. Standards Track [Page 82] - -RFC 2068 HTTP/1.1 January 1997 - - - insignificant aspects of the entity change. A validator that does not - always change when the resource changes is a "weak validator." - - Entity tags are normally "strong validators," but the protocol - provides a mechanism to tag an entity tag as "weak." One can think of - a strong validator as one that changes whenever the bits of an entity - changes, while a weak value changes whenever the meaning of an entity - changes. Alternatively, one can think of a strong validator as part - of an identifier for a specific entity, while a weak validator is - part of an identifier for a set of semantically equivalent entities. - - Note: One example of a strong validator is an integer that is - incremented in stable storage every time an entity is changed. - - An entity's modification time, if represented with one-second - resolution, could be a weak validator, since it is possible that - the resource may be modified twice during a single second. - - Support for weak validators is optional; however, weak validators - allow for more efficient caching of equivalent objects; for - example, a hit counter on a site is probably good enough if it is - updated every few days or weeks, and any value during that period - is likely "good enough" to be equivalent. - - A "use" of a validator is either when a client generates a request - and includes the validator in a validating header field, or when a - server compares two validators. - - Strong validators are usable in any context. Weak validators are only - usable in contexts that do not depend on exact equality of an entity. - For example, either kind is usable for a conditional GET of a full - entity. However, only a strong validator is usable for a sub-range - retrieval, since otherwise the client may end up with an internally - inconsistent entity. - - The only function that the HTTP/1.1 protocol defines on validators is - comparison. There are two validator comparison functions, depending - on whether the comparison context allows the use of weak validators - or not: - - o The strong comparison function: in order to be considered equal, - both validators must be identical in every way, and neither may be - weak. - o The weak comparison function: in order to be considered equal, both - validators must be identical in every way, but either or both of - them may be tagged as "weak" without affecting the result. - - The weak comparison function MAY be used for simple (non-subrange) - - - -Fielding, et. al. Standards Track [Page 83] - -RFC 2068 HTTP/1.1 January 1997 - - - GET requests. The strong comparison function MUST be used in all - other cases. - - An entity tag is strong unless it is explicitly tagged as weak. - Section 3.11 gives the syntax for entity tags. - - A Last-Modified time, when used as a validator in a request, is - implicitly weak unless it is possible to deduce that it is strong, - using the following rules: - - o The validator is being compared by an origin server to the actual - current validator for the entity and, - o That origin server reliably knows that the associated entity did - not change twice during the second covered by the presented - validator. -or - - o The validator is about to be used by a client in an If-Modified- - Since or If-Unmodified-Since header, because the client has a cache - entry for the associated entity, and - o That cache entry includes a Date value, which gives the time when - the origin server sent the original response, and - o The presented Last-Modified time is at least 60 seconds before the - Date value. -or - - o The validator is being compared by an intermediate cache to the - validator stored in its cache entry for the entity, and - o That cache entry includes a Date value, which gives the time when - the origin server sent the original response, and - o The presented Last-Modified time is at least 60 seconds before the - Date value. - - This method relies on the fact that if two different responses were - sent by the origin server during the same second, but both had the - same Last-Modified time, then at least one of those responses would - have a Date value equal to its Last-Modified time. The arbitrary 60- - second limit guards against the possibility that the Date and Last- - Modified values are generated from different clocks, or at somewhat - different times during the preparation of the response. An - implementation may use a value larger than 60 seconds, if it is - believed that 60 seconds is too short. - - If a client wishes to perform a sub-range retrieval on a value for - which it has only a Last-Modified time and no opaque validator, it - may do this only if the Last-Modified time is strong in the sense - described here. - - - - -Fielding, et. al. Standards Track [Page 84] - -RFC 2068 HTTP/1.1 January 1997 - - - A cache or origin server receiving a cache-conditional request, other - than a full-body GET request, MUST use the strong comparison function - to evaluate the condition. - - These rules allow HTTP/1.1 caches and clients to safely perform sub- - range retrievals on values that have been obtained from HTTP/1.0 - servers. - -13.3.4 Rules for When to Use Entity Tags and Last-modified Dates - - We adopt a set of rules and recommendations for origin servers, - clients, and caches regarding when various validator types should be - used, and for what purposes. - - HTTP/1.1 origin servers: - - o SHOULD send an entity tag validator unless it is not feasible to - generate one. - o MAY send a weak entity tag instead of a strong entity tag, if - performance considerations support the use of weak entity tags, or - if it is unfeasible to send a strong entity tag. - o SHOULD send a Last-Modified value if it is feasible to send one, - unless the risk of a breakdown in semantic transparency that could - result from using this date in an If-Modified-Since header would - lead to serious problems. - - In other words, the preferred behavior for an HTTP/1.1 origin server - is to send both a strong entity tag and a Last-Modified value. - - In order to be legal, a strong entity tag MUST change whenever the - associated entity value changes in any way. A weak entity tag SHOULD - change whenever the associated entity changes in a semantically - significant way. - - Note: in order to provide semantically transparent caching, an - origin server must avoid reusing a specific strong entity tag value - for two different entities, or reusing a specific weak entity tag - value for two semantically different entities. Cache entries may - persist for arbitrarily long periods, regardless of expiration - times, so it may be inappropriate to expect that a cache will never - again attempt to validate an entry using a validator that it - obtained at some point in the past. - - HTTP/1.1 clients: - - o If an entity tag has been provided by the origin server, MUST - use that entity tag in any cache-conditional request (using - If-Match or If-None-Match). - - - -Fielding, et. al. Standards Track [Page 85] - -RFC 2068 HTTP/1.1 January 1997 - - - o If only a Last-Modified value has been provided by the origin - server, SHOULD use that value in non-subrange cache-conditional - requests (using If-Modified-Since). - o If only a Last-Modified value has been provided by an HTTP/1.0 - origin server, MAY use that value in subrange cache-conditional - requests (using If-Unmodified-Since:). The user agent should - provide a way to disable this, in case of difficulty. - o If both an entity tag and a Last-Modified value have been - provided by the origin server, SHOULD use both validators in - cache-conditional requests. This allows both HTTP/1.0 and - HTTP/1.1 caches to respond appropriately. - - An HTTP/1.1 cache, upon receiving a request, MUST use the most - restrictive validator when deciding whether the client's cache entry - matches the cache's own cache entry. This is only an issue when the - request contains both an entity tag and a last-modified-date - validator (If-Modified-Since or If-Unmodified-Since). - - A note on rationale: The general principle behind these rules is - that HTTP/1.1 servers and clients should transmit as much non- - redundant information as is available in their responses and - requests. HTTP/1.1 systems receiving this information will make the - most conservative assumptions about the validators they receive. - - HTTP/1.0 clients and caches will ignore entity tags. Generally, - last-modified values received or used by these systems will support - transparent and efficient caching, and so HTTP/1.1 origin servers - should provide Last-Modified values. In those rare cases where the - use of a Last-Modified value as a validator by an HTTP/1.0 system - could result in a serious problem, then HTTP/1.1 origin servers - should not provide one. - -13.3.5 Non-validating Conditionals - - The principle behind entity tags is that only the service author - knows the semantics of a resource well enough to select an - appropriate cache validation mechanism, and the specification of any - validator comparison function more complex than byte-equality would - open up a can of worms. Thus, comparisons of any other headers - (except Last-Modified, for compatibility with HTTP/1.0) are never - used for purposes of validating a cache entry. - -13.4 Response Cachability - - Unless specifically constrained by a Cache-Control (section 14.9) - directive, a caching system may always store a successful response - (see section 13.8) as a cache entry, may return it without validation - if it is fresh, and may return it after successful validation. If - - - -Fielding, et. al. Standards Track [Page 86] - -RFC 2068 HTTP/1.1 January 1997 - - - there is neither a cache validator nor an explicit expiration time - associated with a response, we do not expect it to be cached, but - certain caches may violate this expectation (for example, when little - or no network connectivity is available). A client can usually detect - that such a response was taken from a cache by comparing the Date - header to the current time. - - Note that some HTTP/1.0 caches are known to violate this - expectation without providing any Warning. - - However, in some cases it may be inappropriate for a cache to retain - an entity, or to return it in response to a subsequent request. This - may be because absolute semantic transparency is deemed necessary by - the service author, or because of security or privacy considerations. - Certain Cache-Control directives are therefore provided so that the - server can indicate that certain resource entities, or portions - thereof, may not be cached regardless of other considerations. - - Note that section 14.8 normally prevents a shared cache from saving - and returning a response to a previous request if that request - included an Authorization header. - - A response received with a status code of 200, 203, 206, 300, 301 or - 410 may be stored by a cache and used in reply to a subsequent - request, subject to the expiration mechanism, unless a Cache-Control - directive prohibits caching. However, a cache that does not support - the Range and Content-Range headers MUST NOT cache 206 (Partial - Content) responses. - - A response received with any other status code MUST NOT be returned - in a reply to a subsequent request unless there are Cache-Control - directives or another header(s) that explicitly allow it. For - example, these include the following: an Expires header (section - 14.21); a "max-age", "must-revalidate", "proxy-revalidate", "public" - or "private" Cache-Control directive (section 14.9). - -13.5 Constructing Responses From Caches - - The purpose of an HTTP cache is to store information received in - response to requests, for use in responding to future requests. In - many cases, a cache simply returns the appropriate parts of a - response to the requester. However, if the cache holds a cache entry - based on a previous response, it may have to combine parts of a new - response with what is held in the cache entry. - - - - - - - -Fielding, et. al. Standards Track [Page 87] - -RFC 2068 HTTP/1.1 January 1997 - - -13.5.1 End-to-end and Hop-by-hop Headers - - For the purpose of defining the behavior of caches and non-caching - proxies, we divide HTTP headers into two categories: - - o End-to-end headers, which must be transmitted to the - ultimate recipient of a request or response. End-to-end - headers in responses must be stored as part of a cache entry - and transmitted in any response formed from a cache entry. - o Hop-by-hop headers, which are meaningful only for a single - transport-level connection, and are not stored by caches or - forwarded by proxies. - - The following HTTP/1.1 headers are hop-by-hop headers: - - o Connection - o Keep-Alive - o Public - o Proxy-Authenticate - o Transfer-Encoding - o Upgrade - - All other headers defined by HTTP/1.1 are end-to-end headers. - - Hop-by-hop headers introduced in future versions of HTTP MUST be - listed in a Connection header, as described in section 14.10. - -13.5.2 Non-modifiable Headers - - Some features of the HTTP/1.1 protocol, such as Digest - Authentication, depend on the value of certain end-to-end headers. A - cache or non-caching proxy SHOULD NOT modify an end-to-end header - unless the definition of that header requires or specifically allows - that. - - A cache or non-caching proxy MUST NOT modify any of the following - fields in a request or response, nor may it add any of these fields - if not already present: - - o Content-Location - o ETag - o Expires - o Last-Modified - - - - - - - - -Fielding, et. al. Standards Track [Page 88] - -RFC 2068 HTTP/1.1 January 1997 - - - A cache or non-caching proxy MUST NOT modify or add any of the - following fields in a response that contains the no-transform Cache- - Control directive, or in any request: - - o Content-Encoding - o Content-Length - o Content-Range - o Content-Type - - A cache or non-caching proxy MAY modify or add these fields in a - response that does not include no-transform, but if it does so, it - MUST add a Warning 14 (Transformation applied) if one does not - already appear in the response. - - Warning: unnecessary modification of end-to-end headers may cause - authentication failures if stronger authentication mechanisms are - introduced in later versions of HTTP. Such authentication - mechanisms may rely on the values of header fields not listed here. - -13.5.3 Combining Headers - - When a cache makes a validating request to a server, and the server - provides a 304 (Not Modified) response, the cache must construct a - response to send to the requesting client. The cache uses the - entity-body stored in the cache entry as the entity-body of this - outgoing response. The end-to-end headers stored in the cache entry - are used for the constructed response, except that any end-to-end - headers provided in the 304 response MUST replace the corresponding - headers from the cache entry. Unless the cache decides to remove the - cache entry, it MUST also replace the end-to-end headers stored with - the cache entry with corresponding headers received in the incoming - response. - - In other words, the set of end-to-end headers received in the - incoming response overrides all corresponding end-to-end headers - stored with the cache entry. The cache may add Warning headers (see - section 14.45) to this set. - - If a header field-name in the incoming response matches more than one - header in the cache entry, all such old headers are replaced. - - Note: this rule allows an origin server to use a 304 (Not Modified) - response to update any header associated with a previous response - for the same entity, although it might not always be meaningful or - correct to do so. This rule does not allow an origin server to use - a 304 (not Modified) response to entirely delete a header that it - had provided with a previous response. - - - - -Fielding, et. al. Standards Track [Page 89] - -RFC 2068 HTTP/1.1 January 1997 - - -13.5.4 Combining Byte Ranges - - A response may transfer only a subrange of the bytes of an entity- - body, either because the request included one or more Range - specifications, or because a connection was broken prematurely. After - several such transfers, a cache may have received several ranges of - the same entity-body. - - If a cache has a stored non-empty set of subranges for an entity, and - an incoming response transfers another subrange, the cache MAY - combine the new subrange with the existing set if both the following - conditions are met: - - o Both the incoming response and the cache entry must have a cache - validator. - o The two cache validators must match using the strong comparison - function (see section 13.3.3). - - If either requirement is not meant, the cache must use only the most - recent partial response (based on the Date values transmitted with - every response, and using the incoming response if these values are - equal or missing), and must discard the other partial information. - -13.6 Caching Negotiated Responses - - Use of server-driven content negotiation (section 12), as indicated - by the presence of a Vary header field in a response, alters the - conditions and procedure by which a cache can use the response for - subsequent requests. - - A server MUST use the Vary header field (section 14.43) to inform a - cache of what header field dimensions are used to select among - multiple representations of a cachable response. A cache may use the - selected representation (the entity included with that particular - response) for replying to subsequent requests on that resource only - when the subsequent requests have the same or equivalent values for - all header fields specified in the Vary response-header. Requests - with a different value for one or more of those header fields would - be forwarded toward the origin server. - - If an entity tag was assigned to the representation, the forwarded - request SHOULD be conditional and include the entity tags in an If- - None-Match header field from all its cache entries for the Request- - URI. This conveys to the server the set of entities currently held by - the cache, so that if any one of these entities matches the requested - entity, the server can use the ETag header in its 304 (Not Modified) - response to tell the cache which entry is appropriate. If the - entity-tag of the new response matches that of an existing entry, the - - - -Fielding, et. al. Standards Track [Page 90] - -RFC 2068 HTTP/1.1 January 1997 - - - new response SHOULD be used to update the header fields of the - existing entry, and the result MUST be returned to the client. - - The Vary header field may also inform the cache that the - representation was selected using criteria not limited to the - request-headers; in this case, a cache MUST NOT use the response in a - reply to a subsequent request unless the cache relays the new request - to the origin server in a conditional request and the server responds - with 304 (Not Modified), including an entity tag or Content-Location - that indicates which entity should be used. - - If any of the existing cache entries contains only partial content - for the associated entity, its entity-tag SHOULD NOT be included in - the If-None-Match header unless the request is for a range that would - be fully satisfied by that entry. - - If a cache receives a successful response whose Content-Location - field matches that of an existing cache entry for the same Request- - URI, whose entity-tag differs from that of the existing entry, and - whose Date is more recent than that of the existing entry, the - existing entry SHOULD NOT be returned in response to future requests, - and should be deleted from the cache. - -13.7 Shared and Non-Shared Caches - - For reasons of security and privacy, it is necessary to make a - distinction between "shared" and "non-shared" caches. A non-shared - cache is one that is accessible only to a single user. Accessibility - in this case SHOULD be enforced by appropriate security mechanisms. - All other caches are considered to be "shared." Other sections of - this specification place certain constraints on the operation of - shared caches in order to prevent loss of privacy or failure of - access controls. - -13.8 Errors or Incomplete Response Cache Behavior - - A cache that receives an incomplete response (for example, with fewer - bytes of data than specified in a Content-Length header) may store - the response. However, the cache MUST treat this as a partial - response. Partial responses may be combined as described in section - 13.5.4; the result might be a full response or might still be - partial. A cache MUST NOT return a partial response to a client - without explicitly marking it as such, using the 206 (Partial - Content) status code. A cache MUST NOT return a partial response - using a status code of 200 (OK). - - If a cache receives a 5xx response while attempting to revalidate an - entry, it may either forward this response to the requesting client, - - - -Fielding, et. al. Standards Track [Page 91] - -RFC 2068 HTTP/1.1 January 1997 - - - or act as if the server failed to respond. In the latter case, it MAY - return a previously received response unless the cached entry - includes the "must-revalidate" Cache-Control directive (see section - 14.9). - -13.9 Side Effects of GET and HEAD - - Unless the origin server explicitly prohibits the caching of their - responses, the application of GET and HEAD methods to any resources - SHOULD NOT have side effects that would lead to erroneous behavior if - these responses are taken from a cache. They may still have side - effects, but a cache is not required to consider such side effects in - its caching decisions. Caches are always expected to observe an - origin server's explicit restrictions on caching. - - We note one exception to this rule: since some applications have - traditionally used GETs and HEADs with query URLs (those containing a - "?" in the rel_path part) to perform operations with significant side - effects, caches MUST NOT treat responses to such URLs as fresh unless - the server provides an explicit expiration time. This specifically - means that responses from HTTP/1.0 servers for such URIs should not - be taken from a cache. See section 9.1.1 for related information. - -13.10 Invalidation After Updates or Deletions - - The effect of certain methods at the origin server may cause one or - more existing cache entries to become non-transparently invalid. That - is, although they may continue to be "fresh," they do not accurately - reflect what the origin server would return for a new request. - - There is no way for the HTTP protocol to guarantee that all such - cache entries are marked invalid. For example, the request that - caused the change at the origin server may not have gone through the - proxy where a cache entry is stored. However, several rules help - reduce the likelihood of erroneous behavior. - - In this section, the phrase "invalidate an entity" means that the - cache should either remove all instances of that entity from its - storage, or should mark these as "invalid" and in need of a mandatory - revalidation before they can be returned in response to a subsequent - request. - - - - - - - - - - -Fielding, et. al. Standards Track [Page 92] - -RFC 2068 HTTP/1.1 January 1997 - - - Some HTTP methods may invalidate an entity. This is either the entity - referred to by the Request-URI, or by the Location or Content- - Location response-headers (if present). These methods are: - - o PUT - o DELETE - o POST - - In order to prevent denial of service attacks, an invalidation based - on the URI in a Location or Content-Location header MUST only be - performed if the host part is the same as in the Request-URI. - -13.11 Write-Through Mandatory - - All methods that may be expected to cause modifications to the origin - server's resources MUST be written through to the origin server. This - currently includes all methods except for GET and HEAD. A cache MUST - NOT reply to such a request from a client before having transmitted - the request to the inbound server, and having received a - corresponding response from the inbound server. This does not prevent - a cache from sending a 100 (Continue) response before the inbound - server has replied. - - The alternative (known as "write-back" or "copy-back" caching) is not - allowed in HTTP/1.1, due to the difficulty of providing consistent - updates and the problems arising from server, cache, or network - failure prior to write-back. - -13.12 Cache Replacement - - If a new cachable (see sections 14.9.2, 13.2.5, 13.2.6 and 13.8) - response is received from a resource while any existing responses for - the same resource are cached, the cache SHOULD use the new response - to reply to the current request. It may insert it into cache storage - and may, if it meets all other requirements, use it to respond to any - future requests that would previously have caused the old response to - be returned. If it inserts the new response into cache storage it - should follow the rules in section 13.5.3. - - Note: a new response that has an older Date header value than - existing cached responses is not cachable. - -13.13 History Lists - - User agents often have history mechanisms, such as "Back" buttons and - history lists, which can be used to redisplay an entity retrieved - earlier in a session. - - - - -Fielding, et. al. Standards Track [Page 93] - -RFC 2068 HTTP/1.1 January 1997 - - - History mechanisms and caches are different. In particular history - mechanisms SHOULD NOT try to show a semantically transparent view of - the current state of a resource. Rather, a history mechanism is meant - to show exactly what the user saw at the time when the resource was - retrieved. - - By default, an expiration time does not apply to history mechanisms. - If the entity is still in storage, a history mechanism should display - it even if the entity has expired, unless the user has specifically - configured the agent to refresh expired history documents. - - This should not be construed to prohibit the history mechanism from - telling the user that a view may be stale. - - Note: if history list mechanisms unnecessarily prevent users from - viewing stale resources, this will tend to force service authors to - avoid using HTTP expiration controls and cache controls when they - would otherwise like to. Service authors may consider it important - that users not be presented with error messages or warning messages - when they use navigation controls (such as BACK) to view previously - fetched resources. Even though sometimes such resources ought not - to cached, or ought to expire quickly, user interface - considerations may force service authors to resort to other means - of preventing caching (e.g. "once-only" URLs) in order not to - suffer the effects of improperly functioning history mechanisms. - -14 Header Field Definitions - - This section defines the syntax and semantics of all standard - HTTP/1.1 header fields. For entity-header fields, both sender and - recipient refer to either the client or the server, depending on who - sends and who receives the entity. - - - - - - - - - - - - - - - - - - - -Fielding, et. al. Standards Track [Page 94] - -RFC 2068 HTTP/1.1 January 1997 - - -14.1 Accept - - The Accept request-header field can be used to specify certain media - types which are acceptable for the response. Accept headers can be - used to indicate that the request is specifically limited to a small - set of desired types, as in the case of a request for an in-line - image. - - Accept = "Accept" ":" - #( media-range [ accept-params ] ) - - media-range = ( "*/*" - | ( type "/" "*" ) - | ( type "/" subtype ) - ) *( ";" parameter ) - - accept-params = ";" "q" "=" qvalue *( accept-extension ) - - accept-extension = ";" token [ "=" ( token | quoted-string ) ] - - The asterisk "*" character is used to group media types into ranges, - with "*/*" indicating all media types and "type/*" indicating all - subtypes of that type. The media-range MAY include media type - parameters that are applicable to that range. - - Each media-range MAY be followed by one or more accept-params, - beginning with the "q" parameter for indicating a relative quality - factor. The first "q" parameter (if any) separates the media-range - parameter(s) from the accept-params. Quality factors allow the user - or user agent to indicate the relative degree of preference for that - media-range, using the qvalue scale from 0 to 1 (section 3.9). The - default value is q=1. - - Note: Use of the "q" parameter name to separate media type - parameters from Accept extension parameters is due to historical - practice. Although this prevents any media type parameter named - "q" from being used with a media range, such an event is believed - to be unlikely given the lack of any "q" parameters in the IANA - media type registry and the rare usage of any media type parameters - in Accept. Future media types should be discouraged from - registering any parameter named "q". - - The example - - Accept: audio/*; q=0.2, audio/basic - - SHOULD be interpreted as "I prefer audio/basic, but send me any audio - type if it is the best available after an 80% mark-down in quality." - - - -Fielding, et. al. Standards Track [Page 95] - -RFC 2068 HTTP/1.1 January 1997 - - - If no Accept header field is present, then it is assumed that the - client accepts all media types. If an Accept header field is present, - and if the server cannot send a response which is acceptable - according to the combined Accept field value, then the server SHOULD - send a 406 (not acceptable) response. - - A more elaborate example is - - Accept: text/plain; q=0.5, text/html, - text/x-dvi; q=0.8, text/x-c - - Verbally, this would be interpreted as "text/html and text/x-c are - the preferred media types, but if they do not exist, then send the - text/x-dvi entity, and if that does not exist, send the text/plain - entity." - - Media ranges can be overridden by more specific media ranges or - specific media types. If more than one media range applies to a given - type, the most specific reference has precedence. For example, - - Accept: text/*, text/html, text/html;level=1, */* - - have the following precedence: - - 1) text/html;level=1 - 2) text/html - 3) text/* - 4) */* - - The media type quality factor associated with a given type is - determined by finding the media range with the highest precedence - which matches that type. For example, - - Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, - text/html;level=2;q=0.4, */*;q=0.5 - - would cause the following values to be associated: - - text/html;level=1 = 1 - text/html = 0.7 - text/plain = 0.3 - image/jpeg = 0.5 - text/html;level=2 = 0.4 - text/html;level=3 = 0.7 - - Note: A user agent may be provided with a default set of quality - values for certain media ranges. However, unless the user agent is - a closed system which cannot interact with other rendering agents, - - - -Fielding, et. al. Standards Track [Page 96] - -RFC 2068 HTTP/1.1 January 1997 - - - this default set should be configurable by the user. - -14.2 Accept-Charset - - The Accept-Charset request-header field can be used to indicate what - character sets are acceptable for the response. This field allows - clients capable of understanding more comprehensive or special- - purpose character sets to signal that capability to a server which is - capable of representing documents in those character sets. The ISO- - 8859-1 character set can be assumed to be acceptable to all user - agents. - - Accept-Charset = "Accept-Charset" ":" - 1#( charset [ ";" "q" "=" qvalue ] ) - - Character set values are described in section 3.4. Each charset may - be given an associated quality value which represents the user's - preference for that charset. The default value is q=1. An example is - - Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 - - If no Accept-Charset header is present, the default is that any - character set is acceptable. If an Accept-Charset header is present, - and if the server cannot send a response which is acceptable - according to the Accept-Charset header, then the server SHOULD send - an error response with the 406 (not acceptable) status code, though - the sending of an unacceptable response is also allowed. - -14.3 Accept-Encoding - - The Accept-Encoding request-header field is similar to Accept, but - restricts the content-coding values (section 14.12) which are - acceptable in the response. - - Accept-Encoding = "Accept-Encoding" ":" - #( content-coding ) - - An example of its use is - - Accept-Encoding: compress, gzip - - If no Accept-Encoding header is present in a request, the server MAY - assume that the client will accept any content coding. If an Accept- - Encoding header is present, and if the server cannot send a response - which is acceptable according to the Accept-Encoding header, then the - server SHOULD send an error response with the 406 (Not Acceptable) - status code. - - - - -Fielding, et. al. Standards Track [Page 97] - -RFC 2068 HTTP/1.1 January 1997 - - - An empty Accept-Encoding value indicates none are acceptable. - -14.4 Accept-Language - - The Accept-Language request-header field is similar to Accept, but - restricts the set of natural languages that are preferred as a - response to the request. - - Accept-Language = "Accept-Language" ":" - 1#( language-range [ ";" "q" "=" qvalue ] ) - - language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" ) - - Each language-range MAY be given an associated quality value which - represents an estimate of the user's preference for the languages - specified by that range. The quality value defaults to "q=1". For - example, - - Accept-Language: da, en-gb;q=0.8, en;q=0.7 - - would mean: "I prefer Danish, but will accept British English and - other types of English." A language-range matches a language-tag if - it exactly equals the tag, or if it exactly equals a prefix of the - tag such that the first tag character following the prefix is "-". - The special range "*", if present in the Accept-Language field, - matches every tag not matched by any other range present in the - Accept-Language field. - - Note: This use of a prefix matching rule does not imply that - language tags are assigned to languages in such a way that it is - always true that if a user understands a language with a certain - tag, then this user will also understand all languages with tags - for which this tag is a prefix. The prefix rule simply allows the - use of prefix tags if this is the case. - - The language quality factor assigned to a language-tag by the - Accept-Language field is the quality value of the longest language- - range in the field that matches the language-tag. If no language- - range in the field matches the tag, the language quality factor - assigned is 0. If no Accept-Language header is present in the - request, the server SHOULD assume that all languages are equally - acceptable. If an Accept-Language header is present, then all - languages which are assigned a quality factor greater than 0 are - acceptable. - - It may be contrary to the privacy expectations of the user to send an - Accept-Language header with the complete linguistic preferences of - the user in every request. For a discussion of this issue, see - - - -Fielding, et. al. Standards Track [Page 98] - -RFC 2068 HTTP/1.1 January 1997 - - - section 15.7. - - Note: As intelligibility is highly dependent on the individual - user, it is recommended that client applications make the choice of - linguistic preference available to the user. If the choice is not - made available, then the Accept-Language header field must not be - given in the request. - -14.5 Accept-Ranges - - The Accept-Ranges response-header field allows the server to indicate - its acceptance of range requests for a resource: - - Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges - - acceptable-ranges = 1#range-unit | "none" - - Origin servers that accept byte-range requests MAY send - - Accept-Ranges: bytes - - but are not required to do so. Clients MAY generate byte-range - requests without having received this header for the resource - involved. - - Servers that do not accept any kind of range request for a resource - MAY send - - Accept-Ranges: none - - to advise the client not to attempt a range request. - -14.6 Age - - The Age response-header field conveys the sender's estimate of the - amount of time since the response (or its revalidation) was generated - at the origin server. A cached response is "fresh" if its age does - not exceed its freshness lifetime. Age values are calculated as - specified in section 13.2.3. - - Age = "Age" ":" age-value - - age-value = delta-seconds - - Age values are non-negative decimal integers, representing time in - seconds. - - - - - -Fielding, et. al. Standards Track [Page 99] - -RFC 2068 HTTP/1.1 January 1997 - - - If a cache receives a value larger than the largest positive integer - it can represent, or if any of its age calculations overflows, it - MUST transmit an Age header with a value of 2147483648 (2^31). - HTTP/1.1 caches MUST send an Age header in every response. Caches - SHOULD use an arithmetic type of at least 31 bits of range. - -14.7 Allow - - The Allow entity-header field lists the set of methods supported by - the resource identified by the Request-URI. The purpose of this field - is strictly to inform the recipient of valid methods associated with - the resource. An Allow header field MUST be present in a 405 (Method - Not Allowed) response. - - Allow = "Allow" ":" 1#method - - Example of use: - - Allow: GET, HEAD, PUT - - This field cannot prevent a client from trying other methods. - However, the indications given by the Allow header field value SHOULD - be followed. The actual set of allowed methods is defined by the - origin server at the time of each request. - - The Allow header field MAY be provided with a PUT request to - recommend the methods to be supported by the new or modified - resource. The server is not required to support these methods and - SHOULD include an Allow header in the response giving the actual - supported methods. - - A proxy MUST NOT modify the Allow header field even if it does not - understand all the methods specified, since the user agent MAY have - other means of communicating with the origin server. - - The Allow header field does not indicate what methods are implemented - at the server level. Servers MAY use the Public response-header field - (section 14.35) to describe what methods are implemented on the - server as a whole. - -14.8 Authorization - - A user agent that wishes to authenticate itself with a server-- - usually, but not necessarily, after receiving a 401 response--MAY do - so by including an Authorization request-header field with the - request. The Authorization field value consists of credentials - containing the authentication information of the user agent for the - realm of the resource being requested. - - - -Fielding, et. al. Standards Track [Page 100] - -RFC 2068 HTTP/1.1 January 1997 - - - Authorization = "Authorization" ":" credentials - - HTTP access authentication is described in section 11. If a request - is authenticated and a realm specified, the same credentials SHOULD - be valid for all other requests within this realm. - - When a shared cache (see section 13.7) receives a request containing - an Authorization field, it MUST NOT return the corresponding response - as a reply to any other request, unless one of the following specific - exceptions holds: - - 1. If the response includes the "proxy-revalidate" Cache-Control - directive, the cache MAY use that response in replying to a - subsequent request, but a proxy cache MUST first revalidate it with - the origin server, using the request-headers from the new request - to allow the origin server to authenticate the new request. - 2. If the response includes the "must-revalidate" Cache-Control - directive, the cache MAY use that response in replying to a - subsequent request, but all caches MUST first revalidate it with - the origin server, using the request-headers from the new request - to allow the origin server to authenticate the new request. - 3. If the response includes the "public" Cache-Control directive, it - may be returned in reply to any subsequent request. - -14.9 Cache-Control - - The Cache-Control general-header field is used to specify directives - that MUST be obeyed by all caching mechanisms along the - request/response chain. The directives specify behavior intended to - prevent caches from adversely interfering with the request or - response. These directives typically override the default caching - algorithms. Cache directives are unidirectional in that the presence - of a directive in a request does not imply that the same directive - should be given in the response. - - Note that HTTP/1.0 caches may not implement Cache-Control and may - only implement Pragma: no-cache (see section 14.32). - - Cache directives must be passed through by a proxy or gateway - application, regardless of their significance to that application, - since the directives may be applicable to all recipients along the - request/response chain. It is not possible to specify a cache- - directive for a specific cache. - - Cache-Control = "Cache-Control" ":" 1#cache-directive - - cache-directive = cache-request-directive - | cache-response-directive - - - -Fielding, et. al. Standards Track [Page 101] - -RFC 2068 HTTP/1.1 January 1997 - - - cache-request-directive = - "no-cache" [ "=" <"> 1#field-name <"> ] - | "no-store" - | "max-age" "=" delta-seconds - | "max-stale" [ "=" delta-seconds ] - | "min-fresh" "=" delta-seconds - | "only-if-cached" - | cache-extension - - cache-response-directive = - "public" - | "private" [ "=" <"> 1#field-name <"> ] - | "no-cache" [ "=" <"> 1#field-name <"> ] - | "no-store" - | "no-transform" - | "must-revalidate" - | "proxy-revalidate" - | "max-age" "=" delta-seconds - | cache-extension - - cache-extension = token [ "=" ( token | quoted-string ) ] - - When a directive appears without any 1#field-name parameter, the - directive applies to the entire request or response. When such a - directive appears with a 1#field-name parameter, it applies only to - the named field or fields, and not to the rest of the request or - response. This mechanism supports extensibility; implementations of - future versions of the HTTP protocol may apply these directives to - header fields not defined in HTTP/1.1. - - The cache-control directives can be broken down into these general - categories: - - o Restrictions on what is cachable; these may only be imposed by the - origin server. - o Restrictions on what may be stored by a cache; these may be imposed - by either the origin server or the user agent. - o Modifications of the basic expiration mechanism; these may be - imposed by either the origin server or the user agent. - o Controls over cache revalidation and reload; these may only be - imposed by a user agent. - o Control over transformation of entities. - o Extensions to the caching system. - - - - - - - - -Fielding, et. al. Standards Track [Page 102] - -RFC 2068 HTTP/1.1 January 1997 - - -14.9.1 What is Cachable - - By default, a response is cachable if the requirements of the request - method, request header fields, and the response status indicate that - it is cachable. Section 13.4 summarizes these defaults for - cachability. The following Cache-Control response directives allow an - origin server to override the default cachability of a response: - -public - Indicates that the response is cachable by any cache, even if it - would normally be non-cachable or cachable only within a non-shared - cache. (See also Authorization, section 14.8, for additional - details.) - -private - Indicates that all or part of the response message is intended for a - single user and MUST NOT be cached by a shared cache. This allows an - origin server to state that the specified parts of the response are - intended for only one user and are not a valid response for requests - by other users. A private (non-shared) cache may cache the response. - - Note: This usage of the word private only controls where the - response may be cached, and cannot ensure the privacy of the - message content. - -no-cache - Indicates that all or part of the response message MUST NOT be cached - anywhere. This allows an origin server to prevent caching even by - caches that have been configured to return stale responses to client - requests. - - Note: Most HTTP/1.0 caches will not recognize or obey this - directive. - -14.9.2 What May be Stored by Caches - - The purpose of the no-store directive is to prevent the inadvertent - release or retention of sensitive information (for example, on backup - tapes). The no-store directive applies to the entire message, and may - be sent either in a response or in a request. If sent in a request, a - cache MUST NOT store any part of either this request or any response - to it. If sent in a response, a cache MUST NOT store any part of - either this response or the request that elicited it. This directive - applies to both non-shared and shared caches. "MUST NOT store" in - this context means that the cache MUST NOT intentionally store the - information in non-volatile storage, and MUST make a best-effort - attempt to remove the information from volatile storage as promptly - as possible after forwarding it. - - - -Fielding, et. al. Standards Track [Page 103] - -RFC 2068 HTTP/1.1 January 1997 - - - Even when this directive is associated with a response, users may - explicitly store such a response outside of the caching system (e.g., - with a "Save As" dialog). History buffers may store such responses as - part of their normal operation. - - The purpose of this directive is to meet the stated requirements of - certain users and service authors who are concerned about accidental - releases of information via unanticipated accesses to cache data - structures. While the use of this directive may improve privacy in - some cases, we caution that it is NOT in any way a reliable or - sufficient mechanism for ensuring privacy. In particular, malicious - or compromised caches may not recognize or obey this directive; and - communications networks may be vulnerable to eavesdropping. - -14.9.3 Modifications of the Basic Expiration Mechanism - - The expiration time of an entity may be specified by the origin - server using the Expires header (see section 14.21). Alternatively, - it may be specified using the max-age directive in a response. - - If a response includes both an Expires header and a max-age - directive, the max-age directive overrides the Expires header, even - if the Expires header is more restrictive. This rule allows an origin - server to provide, for a given response, a longer expiration time to - an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This may be - useful if certain HTTP/1.0 caches improperly calculate ages or - expiration times, perhaps due to desynchronized clocks. - - Note: most older caches, not compliant with this specification, do - not implement any Cache-Control directives. An origin server - wishing to use a Cache-Control directive that restricts, but does - not prevent, caching by an HTTP/1.1-compliant cache may exploit the - requirement that the max-age directive overrides the Expires - header, and the fact that non-HTTP/1.1-compliant caches do not - observe the max-age directive. - - Other directives allow an user agent to modify the basic expiration - mechanism. These directives may be specified on a request: - - max-age - Indicates that the client is willing to accept a response whose age - is no greater than the specified time in seconds. Unless max-stale - directive is also included, the client is not willing to accept a - stale response. - - min-fresh - Indicates that the client is willing to accept a response whose - freshness lifetime is no less than its current age plus the - - - -Fielding, et. al. Standards Track [Page 104] - -RFC 2068 HTTP/1.1 January 1997 - - - specified time in seconds. That is, the client wants a response - that will still be fresh for at least the specified number of - seconds. - - max-stale - Indicates that the client is willing to accept a response that has - exceeded its expiration time. If max-stale is assigned a value, - then the client is willing to accept a response that has exceeded - its expiration time by no more than the specified number of - seconds. If no value is assigned to max-stale, then the client is - willing to accept a stale response of any age. - - If a cache returns a stale response, either because of a max-stale - directive on a request, or because the cache is configured to - override the expiration time of a response, the cache MUST attach a - Warning header to the stale response, using Warning 10 (Response is - stale). - -14.9.4 Cache Revalidation and Reload Controls - - Sometimes an user agent may want or need to insist that a cache - revalidate its cache entry with the origin server (and not just with - the next cache along the path to the origin server), or to reload its - cache entry from the origin server. End-to-end revalidation may be - necessary if either the cache or the origin server has overestimated - the expiration time of the cached response. End-to-end reload may be - necessary if the cache entry has become corrupted for some reason. - - End-to-end revalidation may be requested either when the client does - not have its own local cached copy, in which case we call it - "unspecified end-to-end revalidation", or when the client does have a - local cached copy, in which case we call it "specific end-to-end - revalidation." - - The client can specify these three kinds of action using Cache- - Control request directives: - - End-to-end reload - The request includes a "no-cache" Cache-Control directive or, for - compatibility with HTTP/1.0 clients, "Pragma: no-cache". No field - names may be included with the no-cache directive in a request. The - server MUST NOT use a cached copy when responding to such a - request. - - Specific end-to-end revalidation - The request includes a "max-age=0" Cache-Control directive, which - forces each cache along the path to the origin server to revalidate - its own entry, if any, with the next cache or server. The initial - - - -Fielding, et. al. Standards Track [Page 105] - -RFC 2068 HTTP/1.1 January 1997 - - - request includes a cache-validating conditional with the client's - current validator. - - Unspecified end-to-end revalidation - The request includes "max-age=0" Cache-Control directive, which - forces each cache along the path to the origin server to revalidate - its own entry, if any, with the next cache or server. The initial - request does not include a cache-validating conditional; the first - cache along the path (if any) that holds a cache entry for this - resource includes a cache-validating conditional with its current - validator. - - When an intermediate cache is forced, by means of a max-age=0 - directive, to revalidate its own cache entry, and the client has - supplied its own validator in the request, the supplied validator may - differ from the validator currently stored with the cache entry. In - this case, the cache may use either validator in making its own - request without affecting semantic transparency. - - However, the choice of validator may affect performance. The best - approach is for the intermediate cache to use its own validator when - making its request. If the server replies with 304 (Not Modified), - then the cache should return its now validated copy to the client - with a 200 (OK) response. If the server replies with a new entity and - cache validator, however, the intermediate cache should compare the - returned validator with the one provided in the client's request, - using the strong comparison function. If the client's validator is - equal to the origin server's, then the intermediate cache simply - returns 304 (Not Modified). Otherwise, it returns the new entity with - a 200 (OK) response. - - If a request includes the no-cache directive, it should not include - min-fresh, max-stale, or max-age. - - In some cases, such as times of extremely poor network connectivity, - a client may want a cache to return only those responses that it - currently has stored, and not to reload or revalidate with the origin - server. To do this, the client may include the only-if-cached - directive in a request. If it receives this directive, a cache SHOULD - either respond using a cached entry that is consistent with the other - constraints of the request, or respond with a 504 (Gateway Timeout) - status. However, if a group of caches is being operated as a unified - system with good internal connectivity, such a request MAY be - forwarded within that group of caches. - - Because a cache may be configured to ignore a server's specified - expiration time, and because a client request may include a max-stale - directive (which has a similar effect), the protocol also includes a - - - -Fielding, et. al. Standards Track [Page 106] - -RFC 2068 HTTP/1.1 January 1997 - - - mechanism for the origin server to require revalidation of a cache - entry on any subsequent use. When the must-revalidate directive is - present in a response received by a cache, that cache MUST NOT use - the entry after it becomes stale to respond to a subsequent request - without first revalidating it with the origin server. (I.e., the - cache must do an end-to-end revalidation every time, if, based solely - on the origin server's Expires or max-age value, the cached response - is stale.) - - The must-revalidate directive is necessary to support reliable - operation for certain protocol features. In all circumstances an - HTTP/1.1 cache MUST obey the must-revalidate directive; in - particular, if the cache cannot reach the origin server for any - reason, it MUST generate a 504 (Gateway Timeout) response. - - Servers should send the must-revalidate directive if and only if - failure to revalidate a request on the entity could result in - incorrect operation, such as a silently unexecuted financial - transaction. Recipients MUST NOT take any automated action that - violates this directive, and MUST NOT automatically provide an - unvalidated copy of the entity if revalidation fails. - - Although this is not recommended, user agents operating under severe - connectivity constraints may violate this directive but, if so, MUST - explicitly warn the user that an unvalidated response has been - provided. The warning MUST be provided on each unvalidated access, - and SHOULD require explicit user confirmation. - - The proxy-revalidate directive has the same meaning as the must- - revalidate directive, except that it does not apply to non-shared - user agent caches. It can be used on a response to an authenticated - request to permit the user's cache to store and later return the - response without needing to revalidate it (since it has already been - authenticated once by that user), while still requiring proxies that - service many users to revalidate each time (in order to make sure - that each user has been authenticated). Note that such authenticated - responses also need the public cache control directive in order to - allow them to be cached at all. - -14.9.5 No-Transform Directive - - Implementers of intermediate caches (proxies) have found it useful to - convert the media type of certain entity bodies. A proxy might, for - example, convert between image formats in order to save cache space - or to reduce the amount of traffic on a slow link. HTTP has to date - been silent on these transformations. - - - - - -Fielding, et. al. Standards Track [Page 107] - -RFC 2068 HTTP/1.1 January 1997 - - - Serious operational problems have already occurred, however, when - these transformations have been applied to entity bodies intended for - certain kinds of applications. For example, applications for medical - imaging, scientific data analysis and those using end-to-end - authentication, all depend on receiving an entity body that is bit - for bit identical to the original entity-body. - - Therefore, if a response includes the no-transform directive, an - intermediate cache or proxy MUST NOT change those headers that are - listed in section 13.5.2 as being subject to the no-transform - directive. This implies that the cache or proxy must not change any - aspect of the entity-body that is specified by these headers. - -14.9.6 Cache Control Extensions - - The Cache-Control header field can be extended through the use of one - or more cache-extension tokens, each with an optional assigned value. - Informational extensions (those which do not require a change in - cache behavior) may be added without changing the semantics of other - directives. Behavioral extensions are designed to work by acting as - modifiers to the existing base of cache directives. Both the new - directive and the standard directive are supplied, such that - applications which do not understand the new directive will default - to the behavior specified by the standard directive, and those that - understand the new directive will recognize it as modifying the - requirements associated with the standard directive. In this way, - extensions to the Cache-Control directives can be made without - requiring changes to the base protocol. - - This extension mechanism depends on a HTTP cache obeying all of the - cache-control directives defined for its native HTTP-version, obeying - certain extensions, and ignoring all directives that it does not - understand. - - For example, consider a hypothetical new response directive called - "community" which acts as a modifier to the "private" directive. We - define this new directive to mean that, in addition to any non-shared - cache, any cache which is shared only by members of the community - named within its value may cache the response. An origin server - wishing to allow the "UCI" community to use an otherwise private - response in their shared cache(s) may do so by including - - Cache-Control: private, community="UCI" - - A cache seeing this header field will act correctly even if the cache - does not understand the "community" cache-extension, since it will - also see and understand the "private" directive and thus default to - the safe behavior. - - - -Fielding, et. al. Standards Track [Page 108] - -RFC 2068 HTTP/1.1 January 1997 - - - Unrecognized cache-directives MUST be ignored; it is assumed that any - cache-directive likely to be unrecognized by an HTTP/1.1 cache will - be combined with standard directives (or the response's default - cachability) such that the cache behavior will remain minimally - correct even if the cache does not understand the extension(s). - -14.10 Connection - - The Connection general-header field allows the sender to specify - options that are desired for that particular connection and MUST NOT - be communicated by proxies over further connections. - - The Connection header has the following grammar: - - Connection-header = "Connection" ":" 1#(connection-token) - connection-token = token - - HTTP/1.1 proxies MUST parse the Connection header field before a - message is forwarded and, for each connection-token in this field, - remove any header field(s) from the message with the same name as the - connection-token. Connection options are signaled by the presence of - a connection-token in the Connection header field, not by any - corresponding additional header field(s), since the additional header - field may not be sent if there are no parameters associated with that - connection option. HTTP/1.1 defines the "close" connection option - for the sender to signal that the connection will be closed after - completion of the response. For example, - - Connection: close - - in either the request or the response header fields indicates that - the connection should not be considered `persistent' (section 8.1) - after the current request/response is complete. - - HTTP/1.1 applications that do not support persistent connections MUST - include the "close" connection option in every message. - -14.11 Content-Base - - The Content-Base entity-header field may be used to specify the base - URI for resolving relative URLs within the entity. This header field - is described as Base in RFC 1808, which is expected to be revised. - - Content-Base = "Content-Base" ":" absoluteURI - - If no Content-Base field is present, the base URI of an entity is - defined either by its Content-Location (if that Content-Location URI - is an absolute URI) or the URI used to initiate the request, in that - - - -Fielding, et. al. Standards Track [Page 109] - -RFC 2068 HTTP/1.1 January 1997 - - - order of precedence. Note, however, that the base URI of the contents - within the entity-body may be redefined within that entity-body. - -14.12 Content-Encoding - - The Content-Encoding entity-header field is used as a modifier to the - media-type. When present, its value indicates what additional content - codings have been applied to the entity-body, and thus what decoding - mechanisms MUST be applied in order to obtain the media-type - referenced by the Content-Type header field. Content-Encoding is - primarily used to allow a document to be compressed without losing - the identity of its underlying media type. - - Content-Encoding = "Content-Encoding" ":" 1#content-coding - - Content codings are defined in section 3.5. An example of its use is - - Content-Encoding: gzip - - The Content-Encoding is a characteristic of the entity identified by - the Request-URI. Typically, the entity-body is stored with this - encoding and is only decoded before rendering or analogous usage. - - If multiple encodings have been applied to an entity, the content - codings MUST be listed in the order in which they were applied. - - Additional information about the encoding parameters MAY be provided - by other entity-header fields not defined by this specification. - -14.13 Content-Language - - The Content-Language entity-header field describes the natural - language(s) of the intended audience for the enclosed entity. Note - that this may not be equivalent to all the languages used within the - entity-body. - - Content-Language = "Content-Language" ":" 1#language-tag - - Language tags are defined in section 3.10. The primary purpose of - Content-Language is to allow a user to identify and differentiate - entities according to the user's own preferred language. Thus, if the - body content is intended only for a Danish-literate audience, the - appropriate field is - - Content-Language: da - - If no Content-Language is specified, the default is that the content - is intended for all language audiences. This may mean that the sender - - - -Fielding, et. al. Standards Track [Page 110] - -RFC 2068 HTTP/1.1 January 1997 - - - does not consider it to be specific to any natural language, or that - the sender does not know for which language it is intended. - - Multiple languages MAY be listed for content that is intended for - multiple audiences. For example, a rendition of the "Treaty of - Waitangi," presented simultaneously in the original Maori and English - versions, would call for - - Content-Language: mi, en - - However, just because multiple languages are present within an entity - does not mean that it is intended for multiple linguistic audiences. - An example would be a beginner's language primer, such as "A First - Lesson in Latin," which is clearly intended to be used by an - English-literate audience. In this case, the Content-Language should - only include "en". - - Content-Language may be applied to any media type -- it is not - limited to textual documents. - -14.14 Content-Length - - The Content-Length entity-header field indicates the size of the - message-body, in decimal number of octets, sent to the recipient or, - in the case of the HEAD method, the size of the entity-body that - would have been sent had the request been a GET. - - Content-Length = "Content-Length" ":" 1*DIGIT - - An example is - - Content-Length: 3495 - - Applications SHOULD use this field to indicate the size of the - message-body to be transferred, regardless of the media type of the - entity. It must be possible for the recipient to reliably determine - the end of HTTP/1.1 requests containing an entity-body, e.g., because - the request has a valid Content-Length field, uses Transfer-Encoding: - chunked or a multipart body. - - Any Content-Length greater than or equal to zero is a valid value. - Section 4.4 describes how to determine the length of a message-body - if a Content-Length is not given. - - - - - - - - -Fielding, et. al. Standards Track [Page 111] - -RFC 2068 HTTP/1.1 January 1997 - - - Note: The meaning of this field is significantly different from the - corresponding definition in MIME, where it is an optional field - used within the "message/external-body" content-type. In HTTP, it - SHOULD be sent whenever the message's length can be determined - prior to being transferred. - -14.15 Content-Location - - The Content-Location entity-header field may be used to supply the - resource location for the entity enclosed in the message. In the case - where a resource has multiple entities associated with it, and those - entities actually have separate locations by which they might be - individually accessed, the server should provide a Content-Location - for the particular variant which is returned. In addition, a server - SHOULD provide a Content-Location for the resource corresponding to - the response entity. - - Content-Location = "Content-Location" ":" - ( absoluteURI | relativeURI ) - - If no Content-Base header field is present, the value of Content- - Location also defines the base URL for the entity (see section - 14.11). - - The Content-Location value is not a replacement for the original - requested URI; it is only a statement of the location of the resource - corresponding to this particular entity at the time of the request. - Future requests MAY use the Content-Location URI if the desire is to - identify the source of that particular entity. - - A cache cannot assume that an entity with a Content-Location - different from the URI used to retrieve it can be used to respond to - later requests on that Content-Location URI. However, the Content- - Location can be used to differentiate between multiple entities - retrieved from a single requested resource, as described in section - 13.6. - - If the Content-Location is a relative URI, the URI is interpreted - relative to any Content-Base URI provided in the response. If no - Content-Base is provided, the relative URI is interpreted relative to - the Request-URI. - - - - - - - - - - -Fielding, et. al. Standards Track [Page 112] - -RFC 2068 HTTP/1.1 January 1997 - - -14.16 Content-MD5 - - The Content-MD5 entity-header field, as defined in RFC 1864 [23], is - an MD5 digest of the entity-body for the purpose of providing an - end-to-end message integrity check (MIC) of the entity-body. (Note: a - MIC is good for detecting accidental modification of the entity-body - in transit, but is not proof against malicious attacks.) - - Content-MD5 = "Content-MD5" ":" md5-digest - - md5-digest = <base64 of 128 bit MD5 digest as per RFC 1864> - - The Content-MD5 header field may be generated by an origin server to - function as an integrity check of the entity-body. Only origin - servers may generate the Content-MD5 header field; proxies and - gateways MUST NOT generate it, as this would defeat its value as an - end-to-end integrity check. Any recipient of the entity-body, - including gateways and proxies, MAY check that the digest value in - this header field matches that of the entity-body as received. - - The MD5 digest is computed based on the content of the entity-body, - including any Content-Encoding that has been applied, but not - including any Transfer-Encoding that may have been applied to the - message-body. If the message is received with a Transfer-Encoding, - that encoding must be removed prior to checking the Content-MD5 value - against the received entity. - - This has the result that the digest is computed on the octets of the - entity-body exactly as, and in the order that, they would be sent if - no Transfer-Encoding were being applied. - - HTTP extends RFC 1864 to permit the digest to be computed for MIME - composite media-types (e.g., multipart/* and message/rfc822), but - this does not change how the digest is computed as defined in the - preceding paragraph. - - Note: There are several consequences of this. The entity-body for - composite types may contain many body-parts, each with its own MIME - and HTTP headers (including Content-MD5, Content-Transfer-Encoding, - and Content-Encoding headers). If a body-part has a Content- - Transfer-Encoding or Content-Encoding header, it is assumed that - the content of the body-part has had the encoding applied, and the - body-part is included in the Content-MD5 digest as is -- i.e., - after the application. The Transfer-Encoding header field is not - allowed within body-parts. - - Note: while the definition of Content-MD5 is exactly the same for - HTTP as in RFC 1864 for MIME entity-bodies, there are several ways - - - -Fielding, et. al. Standards Track [Page 113] - -RFC 2068 HTTP/1.1 January 1997 - - - in which the application of Content-MD5 to HTTP entity-bodies - differs from its application to MIME entity-bodies. One is that - HTTP, unlike MIME, does not use Content-Transfer-Encoding, and does - use Transfer-Encoding and Content-Encoding. Another is that HTTP - more frequently uses binary content types than MIME, so it is worth - noting that, in such cases, the byte order used to compute the - digest is the transmission byte order defined for the type. Lastly, - HTTP allows transmission of text types with any of several line - break conventions and not just the canonical form using CRLF. - Conversion of all line breaks to CRLF should not be done before - computing or checking the digest: the line break convention used in - the text actually transmitted should be left unaltered when - computing the digest. - -14.17 Content-Range - - The Content-Range entity-header is sent with a partial entity-body to - specify where in the full entity-body the partial body should be - inserted. It also indicates the total size of the full entity-body. - When a server returns a partial response to a client, it must - describe both the extent of the range covered by the response, and - the length of the entire entity-body. - - Content-Range = "Content-Range" ":" content-range-spec - - content-range-spec = byte-content-range-spec - - byte-content-range-spec = bytes-unit SP first-byte-pos "-" - last-byte-pos "/" entity-length - - entity-length = 1*DIGIT - - Unlike byte-ranges-specifier values, a byte-content-range-spec may - only specify one range, and must contain absolute byte positions for - both the first and last byte of the range. - - A byte-content-range-spec whose last-byte-pos value is less than its - first-byte-pos value, or whose entity-length value is less than or - equal to its last-byte-pos value, is invalid. The recipient of an - invalid byte-content-range-spec MUST ignore it and any content - transferred along with it. - - - - - - - - - - -Fielding, et. al. Standards Track [Page 114] - -RFC 2068 HTTP/1.1 January 1997 - - - Examples of byte-content-range-spec values, assuming that the entity - contains a total of 1234 bytes: - - o The first 500 bytes: - - bytes 0-499/1234 - - o The second 500 bytes: - - bytes 500-999/1234 - - o All except for the first 500 bytes: - - bytes 500-1233/1234 - - o The last 500 bytes: - - bytes 734-1233/1234 - - When an HTTP message includes the content of a single range (for - example, a response to a request for a single range, or to a request - for a set of ranges that overlap without any holes), this content is - transmitted with a Content-Range header, and a Content-Length header - showing the number of bytes actually transferred. For example, - - HTTP/1.1 206 Partial content - Date: Wed, 15 Nov 1995 06:25:24 GMT - Last-modified: Wed, 15 Nov 1995 04:58:08 GMT - Content-Range: bytes 21010-47021/47022 - Content-Length: 26012 - Content-Type: image/gif - - When an HTTP message includes the content of multiple ranges (for - example, a response to a request for multiple non-overlapping - ranges), these are transmitted as a multipart MIME message. The - multipart MIME content-type used for this purpose is defined in this - specification to be "multipart/byteranges". See appendix 19.2 for its - definition. - - A client that cannot decode a MIME multipart/byteranges message - should not ask for multiple byte-ranges in a single request. - - When a client requests multiple byte-ranges in one request, the - server SHOULD return them in the order that they appeared in the - request. - - If the server ignores a byte-range-spec because it is invalid, the - server should treat the request as if the invalid Range header field - - - -Fielding, et. al. Standards Track [Page 115] - -RFC 2068 HTTP/1.1 January 1997 - - - did not exist. (Normally, this means return a 200 response containing - the full entity). The reason is that the only time a client will make - such an invalid request is when the entity is smaller than the entity - retrieved by a prior request. - -14.18 Content-Type - - The Content-Type entity-header field indicates the media type of the - entity-body sent to the recipient or, in the case of the HEAD method, - the media type that would have been sent had the request been a GET. - - Content-Type = "Content-Type" ":" media-type - Media types are defined in section 3.7. An example of the field is - - Content-Type: text/html; charset=ISO-8859-4 - - Further discussion of methods for identifying the media type of an - entity is provided in section 7.2.1. - -14.19 Date - - The Date general-header field represents the date and time at which - the message was originated, having the same semantics as orig-date in - RFC 822. The field value is an HTTP-date, as described in section - 3.3.1. - - Date = "Date" ":" HTTP-date - - An example is - - Date: Tue, 15 Nov 1994 08:12:31 GMT - - If a message is received via direct connection with the user agent - (in the case of requests) or the origin server (in the case of - responses), then the date can be assumed to be the current date at - the receiving end. However, since the date--as it is believed by the - origin--is important for evaluating cached responses, origin servers - MUST include a Date header field in all responses. Clients SHOULD - only send a Date header field in messages that include an entity- - body, as in the case of the PUT and POST requests, and even then it - is optional. A received message which does not have a Date header - field SHOULD be assigned one by the recipient if the message will be - cached by that recipient or gatewayed via a protocol which requires a - Date. - - - - - - - -Fielding, et. al. Standards Track [Page 116] - -RFC 2068 HTTP/1.1 January 1997 - - - In theory, the date SHOULD represent the moment just before the - entity is generated. In practice, the date can be generated at any - time during the message origination without affecting its semantic - value. - - The format of the Date is an absolute date and time as defined by - HTTP-date in section 3.3; it MUST be sent in RFC1123 [8]-date format. - -14.20 ETag - - The ETag entity-header field defines the entity tag for the - associated entity. The headers used with entity tags are described in - sections 14.20, 14.25, 14.26 and 14.43. The entity tag may be used - for comparison with other entities from the same resource (see - section 13.3.2). - - ETag = "ETag" ":" entity-tag - - Examples: - - ETag: "xyzzy" - ETag: W/"xyzzy" - ETag: "" - -14.21 Expires - - The Expires entity-header field gives the date/time after which the - response should be considered stale. A stale cache entry may not - normally be returned by a cache (either a proxy cache or an user - agent cache) unless it is first validated with the origin server (or - with an intermediate cache that has a fresh copy of the entity). See - section 13.2 for further discussion of the expiration model. - - The presence of an Expires field does not imply that the original - resource will change or cease to exist at, before, or after that - time. - - The format is an absolute date and time as defined by HTTP-date in - section 3.3; it MUST be in RFC1123-date format: - - Expires = "Expires" ":" HTTP-date - - - - - - - - - - -Fielding, et. al. Standards Track [Page 117] - -RFC 2068 HTTP/1.1 January 1997 - - - An example of its use is - - Expires: Thu, 01 Dec 1994 16:00:00 GMT - - Note: if a response includes a Cache-Control field with the max-age - directive, that directive overrides the Expires field. - - HTTP/1.1 clients and caches MUST treat other invalid date formats, - especially including the value "0", as in the past (i.e., "already - expired"). - - To mark a response as "already expired," an origin server should use - an Expires date that is equal to the Date header value. (See the - rules for expiration calculations in section 13.2.4.) - - To mark a response as "never expires," an origin server should use an - Expires date approximately one year from the time the response is - sent. HTTP/1.1 servers should not send Expires dates more than one - year in the future. - - The presence of an Expires header field with a date value of some - time in the future on an response that otherwise would by default be - non-cacheable indicates that the response is cachable, unless - indicated otherwise by a Cache-Control header field (section 14.9). - -14.22 From - - The From request-header field, if given, SHOULD contain an Internet - e-mail address for the human user who controls the requesting user - agent. The address SHOULD be machine-usable, as defined by mailbox - in RFC 822 (as updated by RFC 1123 ): - - From = "From" ":" mailbox - - An example is: - - From: webmaster@w3.org - - This header field MAY be used for logging purposes and as a means for - identifying the source of invalid or unwanted requests. It SHOULD NOT - be used as an insecure form of access protection. The interpretation - of this field is that the request is being performed on behalf of the - person given, who accepts responsibility for the method performed. In - particular, robot agents SHOULD include this header so that the - person responsible for running the robot can be contacted if problems - occur on the receiving end. - - - - - -Fielding, et. al. Standards Track [Page 118] - -RFC 2068 HTTP/1.1 January 1997 - - - The Internet e-mail address in this field MAY be separate from the - Internet host which issued the request. For example, when a request - is passed through a proxy the original issuer's address SHOULD be - used. - - Note: The client SHOULD not send the From header field without the - user's approval, as it may conflict with the user's privacy - interests or their site's security policy. It is strongly - recommended that the user be able to disable, enable, and modify - the value of this field at any time prior to a request. - -14.23 Host - - The Host request-header field specifies the Internet host and port - number of the resource being requested, as obtained from the original - URL given by the user or referring resource (generally an HTTP URL, - as described in section 3.2.2). The Host field value MUST represent - the network location of the origin server or gateway given by the - original URL. This allows the origin server or gateway to - differentiate between internally-ambiguous URLs, such as the root "/" - URL of a server for multiple host names on a single IP address. - - Host = "Host" ":" host [ ":" port ] ; Section 3.2.2 - - A "host" without any trailing port information implies the default - port for the service requested (e.g., "80" for an HTTP URL). For - example, a request on the origin server for - <http://www.w3.org/pub/WWW/> MUST include: - - GET /pub/WWW/ HTTP/1.1 - Host: www.w3.org - - A client MUST include a Host header field in all HTTP/1.1 request - messages on the Internet (i.e., on any message corresponding to a - request for a URL which includes an Internet host address for the - service being requested). If the Host field is not already present, - an HTTP/1.1 proxy MUST add a Host field to the request message prior - to forwarding it on the Internet. All Internet-based HTTP/1.1 servers - MUST respond with a 400 status code to any HTTP/1.1 request message - which lacks a Host header field. - - See sections 5.2 and 19.5.1 for other requirements relating to Host. - -14.24 If-Modified-Since - - The If-Modified-Since request-header field is used with the GET - method to make it conditional: if the requested variant has not been - modified since the time specified in this field, an entity will not - - - -Fielding, et. al. Standards Track [Page 119] - -RFC 2068 HTTP/1.1 January 1997 - - - be returned from the server; instead, a 304 (not modified) response - will be returned without any message-body. - - If-Modified-Since = "If-Modified-Since" ":" HTTP-date - - An example of the field is: - - If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT - - A GET method with an If-Modified-Since header and no Range header - requests that the identified entity be transferred only if it has - been modified since the date given by the If-Modified-Since header. - The algorithm for determining this includes the following cases: - - a)If the request would normally result in anything other than a 200 - (OK) status, or if the passed If-Modified-Since date is invalid, the - response is exactly the same as for a normal GET. A date which is - later than the server's current time is invalid. - - b)If the variant has been modified since the If-Modified-Since date, - the response is exactly the same as for a normal GET. - - c)If the variant has not been modified since a valid If-Modified-Since - date, the server MUST return a 304 (Not Modified) response. - - The purpose of this feature is to allow efficient updates of cached - information with a minimum amount of transaction overhead. - - Note that the Range request-header field modifies the meaning of - If-Modified-Since; see section 14.36 for full details. - - Note that If-Modified-Since times are interpreted by the server, - whose clock may not be synchronized with the client. - - Note that if a client uses an arbitrary date in the If-Modified-Since - header instead of a date taken from the Last-Modified header for the - same request, the client should be aware of the fact that this date - is interpreted in the server's understanding of time. The client - should consider unsynchronized clocks and rounding problems due to - the different encodings of time between the client and server. This - includes the possibility of race conditions if the document has - changed between the time it was first requested and the If-Modified- - Since date of a subsequent request, and the possibility of clock- - skew-related problems if the If-Modified-Since date is derived from - the client's clock without correction to the server's clock. - Corrections for different time bases between client and server are at - best approximate due to network latency. - - - - -Fielding, et. al. Standards Track [Page 120] - -RFC 2068 HTTP/1.1 January 1997 - - -14.25 If-Match - - The If-Match request-header field is used with a method to make it - conditional. A client that has one or more entities previously - obtained from the resource can verify that one of those entities is - current by including a list of their associated entity tags in the - If-Match header field. The purpose of this feature is to allow - efficient updates of cached information with a minimum amount of - transaction overhead. It is also used, on updating requests, to - prevent inadvertent modification of the wrong version of a resource. - As a special case, the value "*" matches any current entity of the - resource. - - If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) - - If any of the entity tags match the entity tag of the entity that - would have been returned in the response to a similar GET request - (without the If-Match header) on that resource, or if "*" is given - and any current entity exists for that resource, then the server MAY - perform the requested method as if the If-Match header field did not - exist. - - A server MUST use the strong comparison function (see section 3.11) - to compare the entity tags in If-Match. - - If none of the entity tags match, or if "*" is given and no current - entity exists, the server MUST NOT perform the requested method, and - MUST return a 412 (Precondition Failed) response. This behavior is - most useful when the client wants to prevent an updating method, such - as PUT, from modifying a resource that has changed since the client - last retrieved it. - - If the request would, without the If-Match header field, result in - anything other than a 2xx status, then the If-Match header MUST be - ignored. - - The meaning of "If-Match: *" is that the method SHOULD be performed - if the representation selected by the origin server (or by a cache, - possibly using the Vary mechanism, see section 14.43) exists, and - MUST NOT be performed if the representation does not exist. - - - - - - - - - - - -Fielding, et. al. Standards Track [Page 121] - -RFC 2068 HTTP/1.1 January 1997 - - - A request intended to update a resource (e.g., a PUT) MAY include an - If-Match header field to signal that the request method MUST NOT be - applied if the entity corresponding to the If-Match value (a single - entity tag) is no longer a representation of that resource. This - allows the user to indicate that they do not wish the request to be - successful if the resource has been changed without their knowledge. - Examples: - - If-Match: "xyzzy" - If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" - If-Match: * - -14.26 If-None-Match - - The If-None-Match request-header field is used with a method to make - it conditional. A client that has one or more entities previously - obtained from the resource can verify that none of those entities is - current by including a list of their associated entity tags in the - If-None-Match header field. The purpose of this feature is to allow - efficient updates of cached information with a minimum amount of - transaction overhead. It is also used, on updating requests, to - prevent inadvertent modification of a resource which was not known to - exist. - - As a special case, the value "*" matches any current entity of the - resource. - - If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag ) - - If any of the entity tags match the entity tag of the entity that - would have been returned in the response to a similar GET request - (without the If-None-Match header) on that resource, or if "*" is - given and any current entity exists for that resource, then the - server MUST NOT perform the requested method. Instead, if the request - method was GET or HEAD, the server SHOULD respond with a 304 (Not - Modified) response, including the cache-related entity-header fields - (particularly ETag) of one of the entities that matched. For all - other request methods, the server MUST respond with a status of 412 - (Precondition Failed). - - See section 13.3.3 for rules on how to determine if two entity tags - match. The weak comparison function can only be used with GET or HEAD - requests. - - If none of the entity tags match, or if "*" is given and no current - entity exists, then the server MAY perform the requested method as if - the If-None-Match header field did not exist. - - - - -Fielding, et. al. Standards Track [Page 122] - -RFC 2068 HTTP/1.1 January 1997 - - - If the request would, without the If-None-Match header field, result - in anything other than a 2xx status, then the If-None-Match header - MUST be ignored. - - The meaning of "If-None-Match: *" is that the method MUST NOT be - performed if the representation selected by the origin server (or by - a cache, possibly using the Vary mechanism, see section 14.43) - exists, and SHOULD be performed if the representation does not exist. - This feature may be useful in preventing races between PUT - operations. - - Examples: - - If-None-Match: "xyzzy" - If-None-Match: W/"xyzzy" - If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" - If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" - If-None-Match: * - -14.27 If-Range - - If a client has a partial copy of an entity in its cache, and wishes - to have an up-to-date copy of the entire entity in its cache, it - could use the Range request-header with a conditional GET (using - either or both of If-Unmodified-Since and If-Match.) However, if the - condition fails because the entity has been modified, the client - would then have to make a second request to obtain the entire current - entity-body. - - The If-Range header allows a client to "short-circuit" the second - request. Informally, its meaning is `if the entity is unchanged, send - me the part(s) that I am missing; otherwise, send me the entire new - entity.' - - If-Range = "If-Range" ":" ( entity-tag | HTTP-date ) - - If the client has no entity tag for an entity, but does have a Last- - Modified date, it may use that date in a If-Range header. (The server - can distinguish between a valid HTTP-date and any form of entity-tag - by examining no more than two characters.) The If-Range header should - only be used together with a Range header, and must be ignored if the - request does not include a Range header, or if the server does not - support the sub-range operation. - - - - - - - - -Fielding, et. al. Standards Track [Page 123] - -RFC 2068 HTTP/1.1 January 1997 - - - If the entity tag given in the If-Range header matches the current - entity tag for the entity, then the server should provide the - specified sub-range of the entity using a 206 (Partial content) - response. If the entity tag does not match, then the server should - return the entire entity using a 200 (OK) response. - -14.28 If-Unmodified-Since - - The If-Unmodified-Since request-header field is used with a method to - make it conditional. If the requested resource has not been modified - since the time specified in this field, the server should perform the - requested operation as if the If-Unmodified-Since header were not - present. - - If the requested variant has been modified since the specified time, - the server MUST NOT perform the requested operation, and MUST return - a 412 (Precondition Failed). - - If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date - - An example of the field is: - - If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT - - If the request normally (i.e., without the If-Unmodified-Since - header) would result in anything other than a 2xx status, the If- - Unmodified-Since header should be ignored. - - If the specified date is invalid, the header is ignored. - -14.29 Last-Modified - - The Last-Modified entity-header field indicates the date and time at - which the origin server believes the variant was last modified. - - Last-Modified = "Last-Modified" ":" HTTP-date - - An example of its use is - - Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT - - The exact meaning of this header field depends on the implementation - of the origin server and the nature of the original resource. For - files, it may be just the file system last-modified time. For - entities with dynamically included parts, it may be the most recent - of the set of last-modify times for its component parts. For database - gateways, it may be the last-update time stamp of the record. For - virtual objects, it may be the last time the internal state changed. - - - -Fielding, et. al. Standards Track [Page 124] - -RFC 2068 HTTP/1.1 January 1997 - - - An origin server MUST NOT send a Last-Modified date which is later - than the server's time of message origination. In such cases, where - the resource's last modification would indicate some time in the - future, the server MUST replace that date with the message - origination date. - - An origin server should obtain the Last-Modified value of the entity - as close as possible to the time that it generates the Date value of - its response. This allows a recipient to make an accurate assessment - of the entity's modification time, especially if the entity changes - near the time that the response is generated. - - HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. - -14.30 Location - - The Location response-header field is used to redirect the recipient - to a location other than the Request-URI for completion of the - request or identification of a new resource. For 201 (Created) - responses, the Location is that of the new resource which was created - by the request. For 3xx responses, the location SHOULD indicate the - server's preferred URL for automatic redirection to the resource. The - field value consists of a single absolute URL. - - Location = "Location" ":" absoluteURI - - An example is - - Location: http://www.w3.org/pub/WWW/People.html - - Note: The Content-Location header field (section 14.15) differs - from Location in that the Content-Location identifies the original - location of the entity enclosed in the request. It is therefore - possible for a response to contain header fields for both Location - and Content-Location. Also see section 13.10 for cache requirements - of some methods. - -14.31 Max-Forwards - - The Max-Forwards request-header field may be used with the TRACE - method (section 14.31) to limit the number of proxies or gateways - that can forward the request to the next inbound server. This can be - useful when the client is attempting to trace a request chain which - appears to be failing or looping in mid-chain. - - Max-Forwards = "Max-Forwards" ":" 1*DIGIT - - - - - -Fielding, et. al. Standards Track [Page 125] - -RFC 2068 HTTP/1.1 January 1997 - - - The Max-Forwards value is a decimal integer indicating the remaining - number of times this request message may be forwarded. - - Each proxy or gateway recipient of a TRACE request containing a Max- - Forwards header field SHOULD check and update its value prior to - forwarding the request. If the received value is zero (0), the - recipient SHOULD NOT forward the request; instead, it SHOULD respond - as the final recipient with a 200 (OK) response containing the - received request message as the response entity-body (as described in - section 9.8). If the received Max-Forwards value is greater than - zero, then the forwarded message SHOULD contain an updated Max- - Forwards field with a value decremented by one (1). - - The Max-Forwards header field SHOULD be ignored for all other methods - defined by this specification and for any extension methods for which - it is not explicitly referred to as part of that method definition. - -14.32 Pragma - - The Pragma general-header field is used to include implementation- - specific directives that may apply to any recipient along the - request/response chain. All pragma directives specify optional - behavior from the viewpoint of the protocol; however, some systems - MAY require that behavior be consistent with the directives. - - Pragma = "Pragma" ":" 1#pragma-directive - - pragma-directive = "no-cache" | extension-pragma - extension-pragma = token [ "=" ( token | quoted-string ) ] - - When the no-cache directive is present in a request message, an - application SHOULD forward the request toward the origin server even - if it has a cached copy of what is being requested. This pragma - directive has the same semantics as the no-cache cache-directive (see - section 14.9) and is defined here for backwards compatibility with - HTTP/1.0. Clients SHOULD include both header fields when a no-cache - request is sent to a server not known to be HTTP/1.1 compliant. - - Pragma directives MUST be passed through by a proxy or gateway - application, regardless of their significance to that application, - since the directives may be applicable to all recipients along the - request/response chain. It is not possible to specify a pragma for a - specific recipient; however, any pragma directive not relevant to a - recipient SHOULD be ignored by that recipient. - - - - - - - -Fielding, et. al. Standards Track [Page 126] - -RFC 2068 HTTP/1.1 January 1997 - - - HTTP/1.1 clients SHOULD NOT send the Pragma request-header. HTTP/1.1 - caches SHOULD treat "Pragma: no-cache" as if the client had sent - "Cache-Control: no-cache". No new Pragma directives will be defined - in HTTP. - -14.33 Proxy-Authenticate - - The Proxy-Authenticate response-header field MUST be included as part - of a 407 (Proxy Authentication Required) response. The field value - consists of a challenge that indicates the authentication scheme and - parameters applicable to the proxy for this Request-URI. - - Proxy-Authenticate = "Proxy-Authenticate" ":" challenge - - The HTTP access authentication process is described in section 11. - Unlike WWW-Authenticate, the Proxy-Authenticate header field applies - only to the current connection and SHOULD NOT be passed on to - downstream clients. However, an intermediate proxy may need to obtain - its own credentials by requesting them from the downstream client, - which in some circumstances will appear as if the proxy is forwarding - the Proxy-Authenticate header field. - -14.34 Proxy-Authorization - - The Proxy-Authorization request-header field allows the client to - identify itself (or its user) to a proxy which requires - authentication. The Proxy-Authorization field value consists of - credentials containing the authentication information of the user - agent for the proxy and/or realm of the resource being requested. - - Proxy-Authorization = "Proxy-Authorization" ":" credentials - - The HTTP access authentication process is described in section 11. - Unlike Authorization, the Proxy-Authorization header field applies - only to the next outbound proxy that demanded authentication using - the Proxy-Authenticate field. When multiple proxies are used in a - chain, the Proxy-Authorization header field is consumed by the first - outbound proxy that was expecting to receive credentials. A proxy MAY - relay the credentials from the client request to the next proxy if - that is the mechanism by which the proxies cooperatively authenticate - a given request. - -14.35 Public - - The Public response-header field lists the set of methods supported - by the server. The purpose of this field is strictly to inform the - recipient of the capabilities of the server regarding unusual - methods. The methods listed may or may not be applicable to the - - - -Fielding, et. al. Standards Track [Page 127] - -RFC 2068 HTTP/1.1 January 1997 - - - Request-URI; the Allow header field (section 14.7) MAY be used to - indicate methods allowed for a particular URI. - - Public = "Public" ":" 1#method - - Example of use: - - Public: OPTIONS, MGET, MHEAD, GET, HEAD - - This header field applies only to the server directly connected to - the client (i.e., the nearest neighbor in a chain of connections). If - the response passes through a proxy, the proxy MUST either remove the - Public header field or replace it with one applicable to its own - capabilities. - -14.36 Range - -14.36.1 Byte Ranges - - Since all HTTP entities are represented in HTTP messages as sequences - of bytes, the concept of a byte range is meaningful for any HTTP - entity. (However, not all clients and servers need to support byte- - range operations.) - - Byte range specifications in HTTP apply to the sequence of bytes in - the entity-body (not necessarily the same as the message-body). - - A byte range operation may specify a single range of bytes, or a set - of ranges within a single entity. - - ranges-specifier = byte-ranges-specifier - - byte-ranges-specifier = bytes-unit "=" byte-range-set - - byte-range-set = 1#( byte-range-spec | suffix-byte-range-spec ) - - byte-range-spec = first-byte-pos "-" [last-byte-pos] - - first-byte-pos = 1*DIGIT - - last-byte-pos = 1*DIGIT - - The first-byte-pos value in a byte-range-spec gives the byte-offset - of the first byte in a range. The last-byte-pos value gives the - byte-offset of the last byte in the range; that is, the byte - positions specified are inclusive. Byte offsets start at zero. - - - - - -Fielding, et. al. Standards Track [Page 128] - -RFC 2068 HTTP/1.1 January 1997 - - - If the last-byte-pos value is present, it must be greater than or - equal to the first-byte-pos in that byte-range-spec, or the byte- - range-spec is invalid. The recipient of an invalid byte-range-spec - must ignore it. - - If the last-byte-pos value is absent, or if the value is greater than - or equal to the current length of the entity-body, last-byte-pos is - taken to be equal to one less than the current length of the entity- - body in bytes. - - By its choice of last-byte-pos, a client can limit the number of - bytes retrieved without knowing the size of the entity. - - suffix-byte-range-spec = "-" suffix-length - - suffix-length = 1*DIGIT - - A suffix-byte-range-spec is used to specify the suffix of the - entity-body, of a length given by the suffix-length value. (That is, - this form specifies the last N bytes of an entity-body.) If the - entity is shorter than the specified suffix-length, the entire - entity-body is used. - - Examples of byte-ranges-specifier values (assuming an entity-body of - length 10000): - - o The first 500 bytes (byte offsets 0-499, inclusive): - - bytes=0-499 - - o The second 500 bytes (byte offsets 500-999, inclusive): - - bytes=500-999 - - o The final 500 bytes (byte offsets 9500-9999, inclusive): - - bytes=-500 - - o Or - - bytes=9500- - - o The first and last bytes only (bytes 0 and 9999): - - bytes=0-0,-1 - - - - - - -Fielding, et. al. Standards Track [Page 129] - -RFC 2068 HTTP/1.1 January 1997 - - - o Several legal but not canonical specifications of the second - 500 bytes (byte offsets 500-999, inclusive): - - bytes=500-600,601-999 - - bytes=500-700,601-999 - -14.36.2 Range Retrieval Requests - - HTTP retrieval requests using conditional or unconditional GET - methods may request one or more sub-ranges of the entity, instead of - the entire entity, using the Range request header, which applies to - the entity returned as the result of the request: - - Range = "Range" ":" ranges-specifier - - A server MAY ignore the Range header. However, HTTP/1.1 origin - servers and intermediate caches SHOULD support byte ranges when - possible, since Range supports efficient recovery from partially - failed transfers, and supports efficient partial retrieval of large - entities. - - If the server supports the Range header and the specified range or - ranges are appropriate for the entity: - - o The presence of a Range header in an unconditional GET modifies - what is returned if the GET is otherwise successful. In other - words, the response carries a status code of 206 (Partial - Content) instead of 200 (OK). - - o The presence of a Range header in a conditional GET (a request - using one or both of If-Modified-Since and If-None-Match, or - one or both of If-Unmodified-Since and If-Match) modifies what - is returned if the GET is otherwise successful and the condition - is true. It does not affect the 304 (Not Modified) response - returned if the conditional is false. - - In some cases, it may be more appropriate to use the If-Range header - (see section 14.27) in addition to the Range header. - - If a proxy that supports ranges receives a Range request, forwards - the request to an inbound server, and receives an entire entity in - reply, it SHOULD only return the requested range to its client. It - SHOULD store the entire received response in its cache, if that is - consistent with its cache allocation policies. - - - - - - -Fielding, et. al. Standards Track [Page 130] - -RFC 2068 HTTP/1.1 January 1997 - - -14.37 Referer - - The Referer[sic] request-header field allows the client to specify, - for the server's benefit, the address (URI) of the resource from - which the Request-URI was obtained (the "referrer", although the - header field is misspelled.) The Referer request-header allows a - server to generate lists of back-links to resources for interest, - logging, optimized caching, etc. It also allows obsolete or mistyped - links to be traced for maintenance. The Referer field MUST NOT be - sent if the Request-URI was obtained from a source that does not have - its own URI, such as input from the user keyboard. - - Referer = "Referer" ":" ( absoluteURI | relativeURI ) - - Example: - - Referer: http://www.w3.org/hypertext/DataSources/Overview.html - - If the field value is a partial URI, it SHOULD be interpreted - relative to the Request-URI. The URI MUST NOT include a fragment. - - Note: Because the source of a link may be private information or - may reveal an otherwise private information source, it is strongly - recommended that the user be able to select whether or not the - Referer field is sent. For example, a browser client could have a - toggle switch for browsing openly/anonymously, which would - respectively enable/disable the sending of Referer and From - information. - -14.38 Retry-After - - The Retry-After response-header field can be used with a 503 (Service - Unavailable) response to indicate how long the service is expected to - be unavailable to the requesting client. The value of this field can - be either an HTTP-date or an integer number of seconds (in decimal) - after the time of the response. - - Retry-After = "Retry-After" ":" ( HTTP-date | delta-seconds ) - - Two examples of its use are - - Retry-After: Fri, 31 Dec 1999 23:59:59 GMT - Retry-After: 120 - - In the latter example, the delay is 2 minutes. - - - - - - -Fielding, et. al. Standards Track [Page 131] - -RFC 2068 HTTP/1.1 January 1997 - - -14.39 Server - - The Server response-header field contains information about the - software used by the origin server to handle the request. The field - can contain multiple product tokens (section 3.8) and comments - identifying the server and any significant subproducts. The product - tokens are listed in order of their significance for identifying the - application. - - Server = "Server" ":" 1*( product | comment ) - - Example: - - Server: CERN/3.0 libwww/2.17 - - If the response is being forwarded through a proxy, the proxy - application MUST NOT modify the Server response-header. Instead, it - SHOULD include a Via field (as described in section 14.44). - - Note: Revealing the specific software version of the server may - allow the server machine to become more vulnerable to attacks - against software that is known to contain security holes. Server - implementers are encouraged to make this field a configurable - option. - -14.40 Transfer-Encoding - - The Transfer-Encoding general-header field indicates what (if any) - type of transformation has been applied to the message body in order - to safely transfer it between the sender and the recipient. This - differs from the Content-Encoding in that the transfer coding is a - property of the message, not of the entity. - - Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer- - coding - - Transfer codings are defined in section 3.6. An example is: - - Transfer-Encoding: chunked - - Many older HTTP/1.0 applications do not understand the Transfer- - Encoding header. - -14.41 Upgrade - - The Upgrade general-header allows the client to specify what - additional communication protocols it supports and would like to use - if the server finds it appropriate to switch protocols. The server - - - -Fielding, et. al. Standards Track [Page 132] - -RFC 2068 HTTP/1.1 January 1997 - - - MUST use the Upgrade header field within a 101 (Switching Protocols) - response to indicate which protocol(s) are being switched. - - Upgrade = "Upgrade" ":" 1#product - - For example, - - Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11 - - The Upgrade header field is intended to provide a simple mechanism - for transition from HTTP/1.1 to some other, incompatible protocol. It - does so by allowing the client to advertise its desire to use another - protocol, such as a later version of HTTP with a higher major version - number, even though the current request has been made using HTTP/1.1. - This eases the difficult transition between incompatible protocols by - allowing the client to initiate a request in the more commonly - supported protocol while indicating to the server that it would like - to use a "better" protocol if available (where "better" is determined - by the server, possibly according to the nature of the method and/or - resource being requested). - - The Upgrade header field only applies to switching application-layer - protocols upon the existing transport-layer connection. Upgrade - cannot be used to insist on a protocol change; its acceptance and use - by the server is optional. The capabilities and nature of the - application-layer communication after the protocol change is entirely - dependent upon the new protocol chosen, although the first action - after changing the protocol MUST be a response to the initial HTTP - request containing the Upgrade header field. - - The Upgrade header field only applies to the immediate connection. - Therefore, the upgrade keyword MUST be supplied within a Connection - header field (section 14.10) whenever Upgrade is present in an - HTTP/1.1 message. - - The Upgrade header field cannot be used to indicate a switch to a - protocol on a different connection. For that purpose, it is more - appropriate to use a 301, 302, 303, or 305 redirection response. - - This specification only defines the protocol name "HTTP" for use by - the family of Hypertext Transfer Protocols, as defined by the HTTP - version rules of section 3.1 and future updates to this - specification. Any token can be used as a protocol name; however, it - will only be useful if both the client and server associate the name - with the same protocol. - - - - - - -Fielding, et. al. Standards Track [Page 133] - -RFC 2068 HTTP/1.1 January 1997 - - -14.42 User-Agent - - The User-Agent request-header field contains information about the - user agent originating the request. This is for statistical purposes, - the tracing of protocol violations, and automated recognition of user - agents for the sake of tailoring responses to avoid particular user - agent limitations. User agents SHOULD include this field with - requests. The field can contain multiple product tokens (section 3.8) - and comments identifying the agent and any subproducts which form a - significant part of the user agent. By convention, the product tokens - are listed in order of their significance for identifying the - application. - - User-Agent = "User-Agent" ":" 1*( product | comment ) - - Example: - - User-Agent: CERN-LineMode/2.15 libwww/2.17b3 - -14.43 Vary - - The Vary response-header field is used by a server to signal that the - response entity was selected from the available representations of - the response using server-driven negotiation (section 12). Field- - names listed in Vary headers are those of request-headers. The Vary - field value indicates either that the given set of header fields - encompass the dimensions over which the representation might vary, or - that the dimensions of variance are unspecified ("*") and thus may - vary over any aspect of future requests. - - Vary = "Vary" ":" ( "*" | 1#field-name ) - - An HTTP/1.1 server MUST include an appropriate Vary header field with - any cachable response that is subject to server-driven negotiation. - Doing so allows a cache to properly interpret future requests on that - resource and informs the user agent about the presence of negotiation - on that resource. A server SHOULD include an appropriate Vary header - field with a non-cachable response that is subject to server-driven - negotiation, since this might provide the user agent with useful - information about the dimensions over which the response might vary. - - The set of header fields named by the Vary field value is known as - the "selecting" request-headers. - - When the cache receives a subsequent request whose Request-URI - specifies one or more cache entries including a Vary header, the - cache MUST NOT use such a cache entry to construct a response to the - new request unless all of the headers named in the cached Vary header - - - -Fielding, et. al. Standards Track [Page 134] - -RFC 2068 HTTP/1.1 January 1997 - - - are present in the new request, and all of the stored selecting - request-headers from the previous request match the corresponding - headers in the new request. - - The selecting request-headers from two requests are defined to match - if and only if the selecting request-headers in the first request can - be transformed to the selecting request-headers in the second request - by adding or removing linear whitespace (LWS) at places where this is - allowed by the corresponding BNF, and/or combining multiple message- - header fields with the same field name following the rules about - message headers in section 4.2. - - A Vary field value of "*" signals that unspecified parameters, - possibly other than the contents of request-header fields (e.g., the - network address of the client), play a role in the selection of the - response representation. Subsequent requests on that resource can - only be properly interpreted by the origin server, and thus a cache - MUST forward a (possibly conditional) request even when it has a - fresh response cached for the resource. See section 13.6 for use of - the Vary header by caches. - - A Vary field value consisting of a list of field-names signals that - the representation selected for the response is based on a selection - algorithm which considers ONLY the listed request-header field values - in selecting the most appropriate representation. A cache MAY assume - that the same selection will be made for future requests with the - same values for the listed field names, for the duration of time in - which the response is fresh. - - The field-names given are not limited to the set of standard - request-header fields defined by this specification. Field names are - case-insensitive. - -14.44 Via - - The Via general-header field MUST be used by gateways and proxies to - indicate the intermediate protocols and recipients between the user - agent and the server on requests, and between the origin server and - the client on responses. It is analogous to the "Received" field of - RFC 822 and is intended to be used for tracking message forwards, - avoiding request loops, and identifying the protocol capabilities of - all senders along the request/response chain. - - - - - - - - - -Fielding, et. al. Standards Track [Page 135] - -RFC 2068 HTTP/1.1 January 1997 - - - Via = "Via" ":" 1#( received-protocol received-by [ comment ] ) - - received-protocol = [ protocol-name "/" ] protocol-version - protocol-name = token - protocol-version = token - received-by = ( host [ ":" port ] ) | pseudonym - pseudonym = token - - The received-protocol indicates the protocol version of the message - received by the server or client along each segment of the - request/response chain. The received-protocol version is appended to - the Via field value when the message is forwarded so that information - about the protocol capabilities of upstream applications remains - visible to all recipients. - - The protocol-name is optional if and only if it would be "HTTP". The - received-by field is normally the host and optional port number of a - recipient server or client that subsequently forwarded the message. - However, if the real host is considered to be sensitive information, - it MAY be replaced by a pseudonym. If the port is not given, it MAY - be assumed to be the default port of the received-protocol. - - Multiple Via field values represent each proxy or gateway that has - forwarded the message. Each recipient MUST append its information - such that the end result is ordered according to the sequence of - forwarding applications. - - Comments MAY be used in the Via header field to identify the software - of the recipient proxy or gateway, analogous to the User-Agent and - Server header fields. However, all comments in the Via field are - optional and MAY be removed by any recipient prior to forwarding the - message. - - For example, a request message could be sent from an HTTP/1.0 user - agent to an internal proxy code-named "fred", which uses HTTP/1.1 to - forward the request to a public proxy at nowhere.com, which completes - the request by forwarding it to the origin server at www.ics.uci.edu. - The request received by www.ics.uci.edu would then have the following - Via header field: - - Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1) - - Proxies and gateways used as a portal through a network firewall - SHOULD NOT, by default, forward the names and ports of hosts within - the firewall region. This information SHOULD only be propagated if - explicitly enabled. If not enabled, the received-by host of any host - behind the firewall SHOULD be replaced by an appropriate pseudonym - for that host. - - - -Fielding, et. al. Standards Track [Page 136] - -RFC 2068 HTTP/1.1 January 1997 - - - For organizations that have strong privacy requirements for hiding - internal structures, a proxy MAY combine an ordered subsequence of - Via header field entries with identical received-protocol values into - a single such entry. For example, - - Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy - - could be collapsed to - - Via: 1.0 ricky, 1.1 mertz, 1.0 lucy - - Applications SHOULD NOT combine multiple entries unless they are all - under the same organizational control and the hosts have already been - replaced by pseudonyms. Applications MUST NOT combine entries which - have different received-protocol values. - -14.45 Warning - - The Warning response-header field is used to carry additional - information about the status of a response which may not be reflected - by the response status code. This information is typically, though - not exclusively, used to warn about a possible lack of semantic - transparency from caching operations. - - Warning headers are sent with responses using: - - Warning = "Warning" ":" 1#warning-value - - warning-value = warn-code SP warn-agent SP warn-text - warn-code = 2DIGIT - warn-agent = ( host [ ":" port ] ) | pseudonym - ; the name or pseudonym of the server adding - ; the Warning header, for use in debugging - warn-text = quoted-string - - A response may carry more than one Warning header. - - The warn-text should be in a natural language and character set that - is most likely to be intelligible to the human user receiving the - response. This decision may be based on any available knowledge, - such as the location of the cache or user, the Accept-Language field - in a request, the Content-Language field in a response, etc. The - default language is English and the default character set is ISO- - 8859-1. - - If a character set other than ISO-8859-1 is used, it MUST be encoded - in the warn-text using the method described in RFC 1522 [14]. - - - - -Fielding, et. al. Standards Track [Page 137] - -RFC 2068 HTTP/1.1 January 1997 - - - Any server or cache may add Warning headers to a response. New - Warning headers should be added after any existing Warning headers. A - cache MUST NOT delete any Warning header that it received with a - response. However, if a cache successfully validates a cache entry, - it SHOULD remove any Warning headers previously attached to that - entry except as specified for specific Warning codes. It MUST then - add any Warning headers received in the validating response. In other - words, Warning headers are those that would be attached to the most - recent relevant response. - - When multiple Warning headers are attached to a response, the user - agent SHOULD display as many of them as possible, in the order that - they appear in the response. If it is not possible to display all of - the warnings, the user agent should follow these heuristics: - - o Warnings that appear early in the response take priority over those - appearing later in the response. - o Warnings in the user's preferred character set take priority over - warnings in other character sets but with identical warn-codes and - warn-agents. - - Systems that generate multiple Warning headers should order them with - this user agent behavior in mind. - - This is a list of the currently-defined warn-codes, each with a - recommended warn-text in English, and a description of its meaning. - -10 Response is stale - MUST be included whenever the returned response is stale. A cache may - add this warning to any response, but may never remove it until the - response is known to be fresh. - -11 Revalidation failed - MUST be included if a cache returns a stale response because an - attempt to revalidate the response failed, due to an inability to - reach the server. A cache may add this warning to any response, but - may never remove it until the response is successfully revalidated. - -12 Disconnected operation - SHOULD be included if the cache is intentionally disconnected from - the rest of the network for a period of time. - -13 Heuristic expiration - MUST be included if the cache heuristically chose a freshness - lifetime greater than 24 hours and the response's age is greater than - 24 hours. - - - - - -Fielding, et. al. Standards Track [Page 138] - -RFC 2068 HTTP/1.1 January 1997 - - -14 Transformation applied - MUST be added by an intermediate cache or proxy if it applies any - transformation changing the content-coding (as specified in the - Content-Encoding header) or media-type (as specified in the - Content-Type header) of the response, unless this Warning code - already appears in the response. MUST NOT be deleted from a response - even after revalidation. - -99 Miscellaneous warning - The warning text may include arbitrary information to be presented to - a human user, or logged. A system receiving this warning MUST NOT - take any automated action. - -14.46 WWW-Authenticate - - The WWW-Authenticate response-header field MUST be included in 401 - (Unauthorized) response messages. The field value consists of at - least one challenge that indicates the authentication scheme(s) and - parameters applicable to the Request-URI. - - WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge - - The HTTP access authentication process is described in section 11. - User agents MUST take special care in parsing the WWW-Authenticate - field value if it contains more than one challenge, or if more than - one WWW-Authenticate header field is provided, since the contents of - a challenge may itself contain a comma-separated list of - authentication parameters. - -15 Security Considerations - - This section is meant to inform application developers, information - providers, and users of the security limitations in HTTP/1.1 as - described by this document. The discussion does not include - definitive solutions to the problems revealed, though it does make - some suggestions for reducing security risks. - -15.1 Authentication of Clients - - The Basic authentication scheme is not a secure method of user - authentication, nor does it in any way protect the entity, which is - transmitted in clear text across the physical network used as the - carrier. HTTP does not prevent additional authentication schemes and - encryption mechanisms from being employed to increase security or the - addition of enhancements (such as schemes to use one-time passwords) - to Basic authentication. - - - - - -Fielding, et. al. Standards Track [Page 139] - -RFC 2068 HTTP/1.1 January 1997 - - - The most serious flaw in Basic authentication is that it results in - the essentially clear text transmission of the user's password over - the physical network. It is this problem which Digest Authentication - attempts to address. - - Because Basic authentication involves the clear text transmission of - passwords it SHOULD never be used (without enhancements) to protect - sensitive or valuable information. - - A common use of Basic authentication is for identification purposes - -- requiring the user to provide a user name and password as a means - of identification, for example, for purposes of gathering accurate - usage statistics on a server. When used in this way it is tempting to - think that there is no danger in its use if illicit access to the - protected documents is not a major concern. This is only correct if - the server issues both user name and password to the users and in - particular does not allow the user to choose his or her own password. - The danger arises because naive users frequently reuse a single - password to avoid the task of maintaining multiple passwords. - - If a server permits users to select their own passwords, then the - threat is not only illicit access to documents on the server but also - illicit access to the accounts of all users who have chosen to use - their account password. If users are allowed to choose their own - password that also means the server must maintain files containing - the (presumably encrypted) passwords. Many of these may be the - account passwords of users perhaps at distant sites. The owner or - administrator of such a system could conceivably incur liability if - this information is not maintained in a secure fashion. - - Basic Authentication is also vulnerable to spoofing by counterfeit - servers. If a user can be led to believe that he is connecting to a - host containing information protected by basic authentication when in - fact he is connecting to a hostile server or gateway then the - attacker can request a password, store it for later use, and feign an - error. This type of attack is not possible with Digest Authentication - [32]. Server implementers SHOULD guard against the possibility of - this sort of counterfeiting by gateways or CGI scripts. In particular - it is very dangerous for a server to simply turn over a connection to - a gateway since that gateway can then use the persistent connection - mechanism to engage in multiple transactions with the client while - impersonating the original server in a way that is not detectable by - the client. - -15.2 Offering a Choice of Authentication Schemes - - An HTTP/1.1 server may return multiple challenges with a 401 - (Authenticate) response, and each challenge may use a different - - - -Fielding, et. al. Standards Track [Page 140] - -RFC 2068 HTTP/1.1 January 1997 - - - scheme. The order of the challenges returned to the user agent is in - the order that the server would prefer they be chosen. The server - should order its challenges with the "most secure" authentication - scheme first. A user agent should choose as the challenge to be made - to the user the first one that the user agent understands. - - When the server offers choices of authentication schemes using the - WWW-Authenticate header, the "security" of the authentication is only - as malicious user could capture the set of challenges and try to - authenticate him/herself using the weakest of the authentication - schemes. Thus, the ordering serves more to protect the user's - credentials than the server's information. - - A possible man-in-the-middle (MITM) attack would be to add a weak - authentication scheme to the set of choices, hoping that the client - will use one that exposes the user's credentials (e.g. password). For - this reason, the client should always use the strongest scheme that - it understands from the choices accepted. - - An even better MITM attack would be to remove all offered choices, - and to insert a challenge that requests Basic authentication. For - this reason, user agents that are concerned about this kind of attack - could remember the strongest authentication scheme ever requested by - a server and produce a warning message that requires user - confirmation before using a weaker one. A particularly insidious way - to mount such a MITM attack would be to offer a "free" proxy caching - service to gullible users. - -15.3 Abuse of Server Log Information - - A server is in the position to save personal data about a user's - requests which may identify their reading patterns or subjects of - interest. This information is clearly confidential in nature and its - handling may be constrained by law in certain countries. People using - the HTTP protocol to provide data are responsible for ensuring that - such material is not distributed without the permission of any - individuals that are identifiable by the published results. - -15.4 Transfer of Sensitive Information - - Like any generic data transfer protocol, HTTP cannot regulate the - content of the data that is transferred, nor is there any a priori - method of determining the sensitivity of any particular piece of - information within the context of any given request. Therefore, - applications SHOULD supply as much control over this information as - possible to the provider of that information. Four header fields are - worth special mention in this context: Server, Via, Referer and From. - - - - -Fielding, et. al. Standards Track [Page 141] - -RFC 2068 HTTP/1.1 January 1997 - - - Revealing the specific software version of the server may allow the - server machine to become more vulnerable to attacks against software - that is known to contain security holes. Implementers SHOULD make the - Server header field a configurable option. - - Proxies which serve as a portal through a network firewall SHOULD - take special precautions regarding the transfer of header information - that identifies the hosts behind the firewall. In particular, they - SHOULD remove, or replace with sanitized versions, any Via fields - generated behind the firewall. - - The Referer field allows reading patterns to be studied and reverse - links drawn. Although it can be very useful, its power can be abused - if user details are not separated from the information contained in - the Referer. Even when the personal information has been removed, the - Referer field may indicate a private document's URI whose publication - would be inappropriate. - - The information sent in the From field might conflict with the user's - privacy interests or their site's security policy, and hence it - SHOULD NOT be transmitted without the user being able to disable, - enable, and modify the contents of the field. The user MUST be able - to set the contents of this field within a user preference or - application defaults configuration. - - We suggest, though do not require, that a convenient toggle interface - be provided for the user to enable or disable the sending of From and - Referer information. - -15.5 Attacks Based On File and Path Names - - Implementations of HTTP origin servers SHOULD be careful to restrict - the documents returned by HTTP requests to be only those that were - intended by the server administrators. If an HTTP server translates - HTTP URIs directly into file system calls, the server MUST take - special care not to serve files that were not intended to be - delivered to HTTP clients. For example, UNIX, Microsoft Windows, and - other operating systems use ".." as a path component to indicate a - directory level above the current one. On such a system, an HTTP - server MUST disallow any such construct in the Request-URI if it - would otherwise allow access to a resource outside those intended to - be accessible via the HTTP server. Similarly, files intended for - reference only internally to the server (such as access control - files, configuration files, and script code) MUST be protected from - inappropriate retrieval, since they might contain sensitive - information. Experience has shown that minor bugs in such HTTP server - implementations have turned into security risks. - - - - -Fielding, et. al. Standards Track [Page 142] - -RFC 2068 HTTP/1.1 January 1997 - - -15.6 Personal Information - - HTTP clients are often privy to large amounts of personal information - (e.g. the user's name, location, mail address, passwords, encryption - keys, etc.), and SHOULD be very careful to prevent unintentional - leakage of this information via the HTTP protocol to other sources. - We very strongly recommend that a convenient interface be provided - for the user to control dissemination of such information, and that - designers and implementers be particularly careful in this area. - History shows that errors in this area are often both serious - security and/or privacy problems, and often generate highly adverse - publicity for the implementer's company. - -15.7 Privacy Issues Connected to Accept Headers - - Accept request-headers can reveal information about the user to all - servers which are accessed. The Accept-Language header in particular - can reveal information the user would consider to be of a private - nature, because the understanding of particular languages is often - strongly correlated to the membership of a particular ethnic group. - User agents which offer the option to configure the contents of an - Accept-Language header to be sent in every request are strongly - encouraged to let the configuration process include a message which - makes the user aware of the loss of privacy involved. - - An approach that limits the loss of privacy would be for a user agent - to omit the sending of Accept-Language headers by default, and to ask - the user whether it should start sending Accept-Language headers to a - server if it detects, by looking for any Vary response-header fields - generated by the server, that such sending could improve the quality - of service. - - Elaborate user-customized accept header fields sent in every request, - in particular if these include quality values, can be used by servers - as relatively reliable and long-lived user identifiers. Such user - identifiers would allow content providers to do click-trail tracking, - and would allow collaborating content providers to match cross-server - click-trails or form submissions of individual users. Note that for - many users not behind a proxy, the network address of the host - running the user agent will also serve as a long-lived user - identifier. In environments where proxies are used to enhance - privacy, user agents should be conservative in offering accept header - configuration options to end users. As an extreme privacy measure, - proxies could filter the accept headers in relayed requests. General - purpose user agents which provide a high degree of header - configurability should warn users about the loss of privacy which can - be involved. - - - - -Fielding, et. al. Standards Track [Page 143] - -RFC 2068 HTTP/1.1 January 1997 - - -15.8 DNS Spoofing - - Clients using HTTP rely heavily on the Domain Name Service, and are - thus generally prone to security attacks based on the deliberate - mis-association of IP addresses and DNS names. Clients need to be - cautious in assuming the continuing validity of an IP number/DNS name - association. - - In particular, HTTP clients SHOULD rely on their name resolver for - confirmation of an IP number/DNS name association, rather than - caching the result of previous host name lookups. Many platforms - already can cache host name lookups locally when appropriate, and - they SHOULD be configured to do so. These lookups should be cached, - however, only when the TTL (Time To Live) information reported by the - name server makes it likely that the cached information will remain - useful. - - If HTTP clients cache the results of host name lookups in order to - achieve a performance improvement, they MUST observe the TTL - information reported by DNS. - - If HTTP clients do not observe this rule, they could be spoofed when - a previously-accessed server's IP address changes. As network - renumbering is expected to become increasingly common, the - possibility of this form of attack will grow. Observing this - requirement thus reduces this potential security vulnerability. - - This requirement also improves the load-balancing behavior of clients - for replicated servers using the same DNS name and reduces the - likelihood of a user's experiencing failure in accessing sites which - use that strategy. - -15.9 Location Headers and Spoofing - - If a single server supports multiple organizations that do not trust - one another, then it must check the values of Location and Content- - Location headers in responses that are generated under control of - said organizations to make sure that they do not attempt to - invalidate resources over which they have no authority. - -16 Acknowledgments - - This specification makes heavy use of the augmented BNF and generic - constructs defined by David H. Crocker for RFC 822. Similarly, it - reuses many of the definitions provided by Nathaniel Borenstein and - Ned Freed for MIME. We hope that their inclusion in this - specification will help reduce past confusion over the relationship - between HTTP and Internet mail message formats. - - - -Fielding, et. al. Standards Track [Page 144] - -RFC 2068 HTTP/1.1 January 1997 - - - The HTTP protocol has evolved considerably over the past four years. - It has benefited from a large and active developer community--the - many people who have participated on the www-talk mailing list--and - it is that community which has been most responsible for the success - of HTTP and of the World-Wide Web in general. Marc Andreessen, Robert - Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jean-Francois - Groff, Phillip M. Hallam-Baker, Hakon W. Lie, Ari Luotonen, Rob - McCool, Lou Montulli, Dave Raggett, Tony Sanders, and Marc - VanHeyningen deserve special recognition for their efforts in - defining early aspects of the protocol. - - This document has benefited greatly from the comments of all those - participating in the HTTP-WG. In addition to those already mentioned, - the following individuals have contributed to this specification: - - Gary Adams Albert Lunde - Harald Tveit Alvestrand John C. Mallery - Keith Ball Jean-Philippe Martin-Flatin - Brian Behlendorf Larry Masinter - Paul Burchard Mitra - Maurizio Codogno David Morris - Mike Cowlishaw Gavin Nicol - Roman Czyborra Bill Perry - Michael A. Dolan Jeffrey Perry - David J. Fiander Scott Powers - Alan Freier Owen Rees - Marc Hedlund Luigi Rizzo - Greg Herlihy David Robinson - Koen Holtman Marc Salomon - Alex Hopmann Rich Salz - Bob Jernigan Allan M. Schiffman - Shel Kaphan Jim Seidman - Rohit Khare Chuck Shotton - John Klensin Eric W. Sink - Martijn Koster Simon E. Spero - Alexei Kosut Richard N. Taylor - David M. Kristol Robert S. Thau - Daniel LaLiberte Bill (BearHeart) Weinman - Ben Laurie Francois Yergeau - Paul J. Leach Mary Ellen Zurko - Daniel DuBois - - Much of the content and presentation of the caching design is due to - suggestions and comments from individuals including: Shel Kaphan, - Paul Leach, Koen Holtman, David Morris, and Larry Masinter. - - - - - - -Fielding, et. al. Standards Track [Page 145] - -RFC 2068 HTTP/1.1 January 1997 - - - Most of the specification of ranges is based on work originally done - by Ari Luotonen and John Franks, with additional input from Steve - Zilles. - - Thanks to the "cave men" of Palo Alto. You know who you are. - - Jim Gettys (the current editor of this document) wishes particularly - to thank Roy Fielding, the previous editor of this document, along - with John Klensin, Jeff Mogul, Paul Leach, Dave Kristol, Koen - Holtman, John Franks, Alex Hopmann, and Larry Masinter for their - help. - -17 References - - [1] Alvestrand, H., "Tags for the identification of languages", RFC - 1766, UNINETT, March 1995. - - [2] Anklesaria, F., McCahill, M., Lindner, P., Johnson, D., Torrey, - D., and B. Alberti. "The Internet Gopher Protocol: (a distributed - document search and retrieval protocol)", RFC 1436, University of - Minnesota, March 1993. - - [3] Berners-Lee, T., "Universal Resource Identifiers in WWW", A - Unifying Syntax for the Expression of Names and Addresses of Objects - on the Network as used in the World-Wide Web", RFC 1630, CERN, June - 1994. - - [4] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource - Locators (URL)", RFC 1738, CERN, Xerox PARC, University of Minnesota, - December 1994. - - [5] Berners-Lee, T., and D. Connolly, "HyperText Markup Language - Specification - 2.0", RFC 1866, MIT/LCS, November 1995. - - [6] Berners-Lee, T., Fielding, R., and H. Frystyk, "Hypertext - Transfer Protocol -- HTTP/1.0.", RFC 1945 MIT/LCS, UC Irvine, May - 1996. - - [7] Freed, N., and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message Bodies", RFC - 2045, Innosoft, First Virtual, November 1996. - - [8] Braden, R., "Requirements for Internet hosts - application and - support", STD 3, RFC 1123, IETF, October 1989. - - [9] Crocker, D., "Standard for the Format of ARPA Internet Text - Messages", STD 11, RFC 822, UDEL, August 1982. - - - - -Fielding, et. al. Standards Track [Page 146] - -RFC 2068 HTTP/1.1 January 1997 - - - [10] Davis, F., Kahle, B., Morris, H., Salem, J., Shen, T., Wang, R., - Sui, J., and M. Grinbaum. "WAIS Interface Protocol Prototype - Functional Specification", (v1.5), Thinking Machines Corporation, - April 1990. - - [11] Fielding, R., "Relative Uniform Resource Locators", RFC 1808, UC - Irvine, June 1995. - - [12] Horton, M., and R. Adams. "Standard for interchange of USENET - messages", RFC 1036, AT&T Bell Laboratories, Center for Seismic - Studies, December 1987. - - [13] Kantor, B., and P. Lapsley. "Network News Transfer Protocol." A - Proposed Standard for the Stream-Based Transmission of News", RFC - 977, UC San Diego, UC Berkeley, February 1986. - - [14] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part - Three: Message Header Extensions for Non-ASCII Text", RFC 2047, - University of Tennessee, November 1996. - - [15] Nebel, E., and L. Masinter. "Form-based File Upload in HTML", - RFC 1867, Xerox Corporation, November 1995. - - [16] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821, - USC/ISI, August 1982. - - [17] Postel, J., "Media Type Registration Procedure", RFC 2048, - USC/ISI, November 1996. - - [18] Postel, J., and J. Reynolds, "File Transfer Protocol (FTP)", STD - 9, RFC 959, USC/ISI, October 1985. - - [19] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2, RFC - 1700, USC/ISI, October 1994. - - [20] Sollins, K., and L. Masinter, "Functional Requirements for - Uniform Resource Names", RFC 1737, MIT/LCS, Xerox Corporation, - December 1994. - - [21] US-ASCII. Coded Character Set - 7-Bit American Standard Code for - Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986. - - [22] ISO-8859. International Standard -- Information Processing -- - 8-bit Single-Byte Coded Graphic Character Sets -- - Part 1: Latin alphabet No. 1, ISO 8859-1:1987. - Part 2: Latin alphabet No. 2, ISO 8859-2, 1987. - Part 3: Latin alphabet No. 3, ISO 8859-3, 1988. - Part 4: Latin alphabet No. 4, ISO 8859-4, 1988. - - - -Fielding, et. al. Standards Track [Page 147] - -RFC 2068 HTTP/1.1 January 1997 - - - Part 5: Latin/Cyrillic alphabet, ISO 8859-5, 1988. - Part 6: Latin/Arabic alphabet, ISO 8859-6, 1987. - Part 7: Latin/Greek alphabet, ISO 8859-7, 1987. - Part 8: Latin/Hebrew alphabet, ISO 8859-8, 1988. - Part 9: Latin alphabet No. 5, ISO 8859-9, 1990. - - [23] Meyers, J., and M. Rose "The Content-MD5 Header Field", RFC - 1864, Carnegie Mellon, Dover Beach Consulting, October, 1995. - - [24] Carpenter, B., and Y. Rekhter, "Renumbering Needs Work", RFC - 1900, IAB, February 1996. - - [25] Deutsch, P., "GZIP file format specification version 4.3." RFC - 1952, Aladdin Enterprises, May 1996. - - [26] Venkata N. Padmanabhan and Jeffrey C. Mogul. Improving HTTP - Latency. Computer Networks and ISDN Systems, v. 28, pp. 25-35, Dec. - 1995. Slightly revised version of paper in Proc. 2nd International - WWW Conf. '94: Mosaic and the Web, Oct. 1994, which is available at - http://www.ncsa.uiuc.edu/SDG/IT94/Proceedings/DDay/mogul/ - HTTPLatency.html. - - [27] Joe Touch, John Heidemann, and Katia Obraczka, "Analysis of HTTP - Performance", <URL: http://www.isi.edu/lsam/ib/http-perf/>, - USC/Information Sciences Institute, June 1996 - - [28] Mills, D., "Network Time Protocol, Version 3, Specification, - Implementation and Analysis", RFC 1305, University of Delaware, March - 1992. - - [29] Deutsch, P., "DEFLATE Compressed Data Format Specification - version 1.3." RFC 1951, Aladdin Enterprises, May 1996. - - [30] Spero, S., "Analysis of HTTP Performance Problems" - <URL:http://sunsite.unc.edu/mdma-release/http-prob.html>. - - [31] Deutsch, P., and J-L. Gailly, "ZLIB Compressed Data Format - Specification version 3.3", RFC 1950, Aladdin Enterprises, Info-ZIP, - May 1996. - - [32] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P., - Luotonen, A., Sink, E., and L. Stewart, "An Extension to HTTP : - Digest Access Authentication", RFC 2069, January 1997. - - - - - - - - -Fielding, et. al. Standards Track [Page 148] - -RFC 2068 HTTP/1.1 January 1997 - - -18 Authors' Addresses - - Roy T. Fielding - Department of Information and Computer Science - University of California - Irvine, CA 92717-3425, USA - - Fax: +1 (714) 824-4056 - EMail: fielding@ics.uci.edu - - - Jim Gettys - MIT Laboratory for Computer Science - 545 Technology Square - Cambridge, MA 02139, USA - - Fax: +1 (617) 258 8682 - EMail: jg@w3.org - - - Jeffrey C. Mogul - Western Research Laboratory - Digital Equipment Corporation - 250 University Avenue - Palo Alto, California, 94305, USA - - EMail: mogul@wrl.dec.com - - - Henrik Frystyk Nielsen - W3 Consortium - MIT Laboratory for Computer Science - 545 Technology Square - Cambridge, MA 02139, USA - - Fax: +1 (617) 258 8682 - EMail: frystyk@w3.org - - - Tim Berners-Lee - Director, W3 Consortium - MIT Laboratory for Computer Science - 545 Technology Square - Cambridge, MA 02139, USA - - Fax: +1 (617) 258 8682 - EMail: timbl@w3.org - - - - -Fielding, et. al. Standards Track [Page 149] - -RFC 2068 HTTP/1.1 January 1997 - - -19 Appendices - -19.1 Internet Media Type message/http - - In addition to defining the HTTP/1.1 protocol, this document serves - as the specification for the Internet media type "message/http". The - following is to be registered with IANA. - - Media Type name: message - Media subtype name: http - Required parameters: none - Optional parameters: version, msgtype - - version: The HTTP-Version number of the enclosed message - (e.g., "1.1"). If not present, the version can be - determined from the first line of the body. - - msgtype: The message type -- "request" or "response". If not - present, the type can be determined from the first - line of the body. - - Encoding considerations: only "7bit", "8bit", or "binary" are - permitted - - Security considerations: none - -19.2 Internet Media Type multipart/byteranges - - When an HTTP message includes the content of multiple ranges (for - example, a response to a request for multiple non-overlapping - ranges), these are transmitted as a multipart MIME message. The - multipart media type for this purpose is called - "multipart/byteranges". - - The multipart/byteranges media type includes two or more parts, each - with its own Content-Type and Content-Range fields. The parts are - separated using a MIME boundary parameter. - - Media Type name: multipart - Media subtype name: byteranges - Required parameters: boundary - Optional parameters: none - - Encoding considerations: only "7bit", "8bit", or "binary" are - permitted - - Security considerations: none - - - - -Fielding, et. al. Standards Track [Page 150] - -RFC 2068 HTTP/1.1 January 1997 - - -For example: - - HTTP/1.1 206 Partial content - Date: Wed, 15 Nov 1995 06:25:24 GMT - Last-modified: Wed, 15 Nov 1995 04:58:08 GMT - Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES - - --THIS_STRING_SEPARATES - Content-type: application/pdf - Content-range: bytes 500-999/8000 - - ...the first range... - --THIS_STRING_SEPARATES - Content-type: application/pdf - Content-range: bytes 7000-7999/8000 - - ...the second range - --THIS_STRING_SEPARATES-- - -19.3 Tolerant Applications - - Although this document specifies the requirements for the generation - of HTTP/1.1 messages, not all applications will be correct in their - implementation. We therefore recommend that operational applications - be tolerant of deviations whenever those deviations can be - interpreted unambiguously. - - Clients SHOULD be tolerant in parsing the Status-Line and servers - tolerant when parsing the Request-Line. In particular, they SHOULD - accept any amount of SP or HT characters between fields, even though - only a single SP is required. - - The line terminator for message-header fields is the sequence CRLF. - However, we recommend that applications, when parsing such headers, - recognize a single LF as a line terminator and ignore the leading CR. - - The character set of an entity-body should be labeled as the lowest - common denominator of the character codes used within that body, with - the exception that no label is preferred over the labels US-ASCII or - ISO-8859-1. - - Additional rules for requirements on parsing and encoding of dates - and other potential problems with date encodings include: - - o HTTP/1.1 clients and caches should assume that an RFC-850 date - which appears to be more than 50 years in the future is in fact - in the past (this helps solve the "year 2000" problem). - - - - -Fielding, et. al. Standards Track [Page 151] - -RFC 2068 HTTP/1.1 January 1997 - - - o An HTTP/1.1 implementation may internally represent a parsed - Expires date as earlier than the proper value, but MUST NOT - internally represent a parsed Expires date as later than the - proper value. - - o All expiration-related calculations must be done in GMT. The - local time zone MUST NOT influence the calculation or comparison - of an age or expiration time. - - o If an HTTP header incorrectly carries a date value with a time - zone other than GMT, it must be converted into GMT using the most - conservative possible conversion. - -19.4 Differences Between HTTP Entities and MIME Entities - - HTTP/1.1 uses many of the constructs defined for Internet Mail (RFC - 822) and the Multipurpose Internet Mail Extensions (MIME ) to allow - entities to be transmitted in an open variety of representations and - with extensible mechanisms. However, MIME [7] discusses mail, and - HTTP has a few features that are different from those described in - MIME. These differences were carefully chosen to optimize - performance over binary connections, to allow greater freedom in the - use of new media types, to make date comparisons easier, and to - acknowledge the practice of some early HTTP servers and clients. - - This appendix describes specific areas where HTTP differs from MIME. - Proxies and gateways to strict MIME environments SHOULD be aware of - these differences and provide the appropriate conversions where - necessary. Proxies and gateways from MIME environments to HTTP also - need to be aware of the differences because some conversions may be - required. - -19.4.1 Conversion to Canonical Form - - MIME requires that an Internet mail entity be converted to canonical - form prior to being transferred. Section 3.7.1 of this document - describes the forms allowed for subtypes of the "text" media type - when transmitted over HTTP. MIME requires that content with a type of - "text" represent line breaks as CRLF and forbids the use of CR or LF - outside of line break sequences. HTTP allows CRLF, bare CR, and bare - LF to indicate a line break within text content when a message is - transmitted over HTTP. - - Where it is possible, a proxy or gateway from HTTP to a strict MIME - environment SHOULD translate all line breaks within the text media - types described in section 3.7.1 of this document to the MIME - canonical form of CRLF. Note, however, that this may be complicated - by the presence of a Content-Encoding and by the fact that HTTP - - - -Fielding, et. al. Standards Track [Page 152] - -RFC 2068 HTTP/1.1 January 1997 - - - allows the use of some character sets which do not use octets 13 and - 10 to represent CR and LF, as is the case for some multi-byte - character sets. - -19.4.2 Conversion of Date Formats - - HTTP/1.1 uses a restricted set of date formats (section 3.3.1) to - simplify the process of date comparison. Proxies and gateways from - other protocols SHOULD ensure that any Date header field present in a - message conforms to one of the HTTP/1.1 formats and rewrite the date - if necessary. - -19.4.3 Introduction of Content-Encoding - - MIME does not include any concept equivalent to HTTP/1.1's Content- - Encoding header field. Since this acts as a modifier on the media - type, proxies and gateways from HTTP to MIME-compliant protocols MUST - either change the value of the Content-Type header field or decode - the entity-body before forwarding the message. (Some experimental - applications of Content-Type for Internet mail have used a media-type - parameter of ";conversions=<content-coding>" to perform an equivalent - function as Content-Encoding. However, this parameter is not part of - MIME.) - -19.4.4 No Content-Transfer-Encoding - - HTTP does not use the Content-Transfer-Encoding (CTE) field of MIME. - Proxies and gateways from MIME-compliant protocols to HTTP MUST - remove any non-identity CTE ("quoted-printable" or "base64") encoding - prior to delivering the response message to an HTTP client. - - Proxies and gateways from HTTP to MIME-compliant protocols are - responsible for ensuring that the message is in the correct format - and encoding for safe transport on that protocol, where "safe - transport" is defined by the limitations of the protocol being used. - Such a proxy or gateway SHOULD label the data with an appropriate - Content-Transfer-Encoding if doing so will improve the likelihood of - safe transport over the destination protocol. - -19.4.5 HTTP Header Fields in Multipart Body-Parts - - In MIME, most header fields in multipart body-parts are generally - ignored unless the field name begins with "Content-". In HTTP/1.1, - multipart body-parts may contain any HTTP header fields which are - significant to the meaning of that part. - - - - - - -Fielding, et. al. Standards Track [Page 153] - -RFC 2068 HTTP/1.1 January 1997 - - -19.4.6 Introduction of Transfer-Encoding - - HTTP/1.1 introduces the Transfer-Encoding header field (section - 14.40). Proxies/gateways MUST remove any transfer coding prior to - forwarding a message via a MIME-compliant protocol. - - A process for decoding the "chunked" transfer coding (section 3.6) - can be represented in pseudo-code as: - - length := 0 - read chunk-size, chunk-ext (if any) and CRLF - while (chunk-size > 0) { - read chunk-data and CRLF - append chunk-data to entity-body - length := length + chunk-size - read chunk-size and CRLF - } - read entity-header - while (entity-header not empty) { - append entity-header to existing header fields - read entity-header - } - Content-Length := length - Remove "chunked" from Transfer-Encoding - -19.4.7 MIME-Version - - HTTP is not a MIME-compliant protocol (see appendix 19.4). However, - HTTP/1.1 messages may include a single MIME-Version general-header - field to indicate what version of the MIME protocol was used to - construct the message. Use of the MIME-Version header field indicates - that the message is in full compliance with the MIME protocol. - Proxies/gateways are responsible for ensuring full compliance (where - possible) when exporting HTTP messages to strict MIME environments. - - MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT - - MIME version "1.0" is the default for use in HTTP/1.1. However, - HTTP/1.1 message parsing and semantics are defined by this document - and not the MIME specification. - -19.5 Changes from HTTP/1.0 - - This section summarizes major differences between versions HTTP/1.0 - and HTTP/1.1. - - - - - - -Fielding, et. al. Standards Track [Page 154] - -RFC 2068 HTTP/1.1 January 1997 - - -19.5.1 Changes to Simplify Multi-homed Web Servers and Conserve IP - Addresses - - The requirements that clients and servers support the Host request- - header, report an error if the Host request-header (section 14.23) is - missing from an HTTP/1.1 request, and accept absolute URIs (section - 5.1.2) are among the most important changes defined by this - specification. - - Older HTTP/1.0 clients assumed a one-to-one relationship of IP - addresses and servers; there was no other established mechanism for - distinguishing the intended server of a request than the IP address - to which that request was directed. The changes outlined above will - allow the Internet, once older HTTP clients are no longer common, to - support multiple Web sites from a single IP address, greatly - simplifying large operational Web servers, where allocation of many - IP addresses to a single host has created serious problems. The - Internet will also be able to recover the IP addresses that have been - allocated for the sole purpose of allowing special-purpose domain - names to be used in root-level HTTP URLs. Given the rate of growth of - the Web, and the number of servers already deployed, it is extremely - important that all implementations of HTTP (including updates to - existing HTTP/1.0 applications) correctly implement these - requirements: - - o Both clients and servers MUST support the Host request-header. - - o Host request-headers are required in HTTP/1.1 requests. - - o Servers MUST report a 400 (Bad Request) error if an HTTP/1.1 - request does not include a Host request-header. - - o Servers MUST accept absolute URIs. - - - - - - - - - - - - - - - - - - -Fielding, et. al. Standards Track [Page 155] - -RFC 2068 HTTP/1.1 January 1997 - - -19.6 Additional Features - - This appendix documents protocol elements used by some existing HTTP - implementations, but not consistently and correctly across most - HTTP/1.1 applications. Implementers should be aware of these - features, but cannot rely upon their presence in, or interoperability - with, other HTTP/1.1 applications. Some of these describe proposed - experimental features, and some describe features that experimental - deployment found lacking that are now addressed in the base HTTP/1.1 - specification. - -19.6.1 Additional Request Methods - -19.6.1.1 PATCH - - The PATCH method is similar to PUT except that the entity contains a - list of differences between the original version of the resource - identified by the Request-URI and the desired content of the resource - after the PATCH action has been applied. The list of differences is - in a format defined by the media type of the entity (e.g., - "application/diff") and MUST include sufficient information to allow - the server to recreate the changes necessary to convert the original - version of the resource to the desired version. - - If the request passes through a cache and the Request-URI identifies - a currently cached entity, that entity MUST be removed from the - cache. Responses to this method are not cachable. - - The actual method for determining how the patched resource is placed, - and what happens to its predecessor, is defined entirely by the - origin server. If the original version of the resource being patched - included a Content-Version header field, the request entity MUST - include a Derived-From header field corresponding to the value of the - original Content-Version header field. Applications are encouraged to - use these fields for constructing versioning relationships and - resolving version conflicts. - - PATCH requests must obey the message transmission requirements set - out in section 8.2. - - Caches that implement PATCH should invalidate cached responses as - defined in section 13.10 for PUT. - -19.6.1.2 LINK - - The LINK method establishes one or more Link relationships between - the existing resource identified by the Request-URI and other - existing resources. The difference between LINK and other methods - - - -Fielding, et. al. Standards Track [Page 156] - -RFC 2068 HTTP/1.1 January 1997 - - - allowing links to be established between resources is that the LINK - method does not allow any message-body to be sent in the request and - does not directly result in the creation of new resources. - - If the request passes through a cache and the Request-URI identifies - a currently cached entity, that entity MUST be removed from the - cache. Responses to this method are not cachable. - - Caches that implement LINK should invalidate cached responses as - defined in section 13.10 for PUT. - -19.6.1.3 UNLINK - - The UNLINK method removes one or more Link relationships from the - existing resource identified by the Request-URI. These relationships - may have been established using the LINK method or by any other - method supporting the Link header. The removal of a link to a - resource does not imply that the resource ceases to exist or becomes - inaccessible for future references. - - If the request passes through a cache and the Request-URI identifies - a currently cached entity, that entity MUST be removed from the - cache. Responses to this method are not cachable. - - Caches that implement UNLINK should invalidate cached responses as - defined in section 13.10 for PUT. - -19.6.2 Additional Header Field Definitions - -19.6.2.1 Alternates - - The Alternates response-header field has been proposed as a means for - the origin server to inform the client about other available - representations of the requested resource, along with their - distinguishing attributes, and thus providing a more reliable means - for a user agent to perform subsequent selection of another - representation which better fits the desires of its user (described - as agent-driven negotiation in section 12). - - - - - - - - - - - - - -Fielding, et. al. Standards Track [Page 157] - -RFC 2068 HTTP/1.1 January 1997 - - - The Alternates header field is orthogonal to the Vary header field in - that both may coexist in a message without affecting the - interpretation of the response or the available representations. It - is expected that Alternates will provide a significant improvement - over the server-driven negotiation provided by the Vary field for - those resources that vary over common dimensions like type and - language. - - The Alternates header field will be defined in a future - specification. - -19.6.2.2 Content-Version - - The Content-Version entity-header field defines the version tag - associated with a rendition of an evolving entity. Together with the - Derived-From field described in section 19.6.2.3, it allows a group - of people to work simultaneously on the creation of a work as an - iterative process. The field should be used to allow evolution of a - particular work along a single path rather than derived works or - renditions in different representations. - - Content-Version = "Content-Version" ":" quoted-string - - Examples of the Content-Version field include: - - Content-Version: "2.1.2" - Content-Version: "Fred 19950116-12:26:48" - Content-Version: "2.5a4-omega7" - -19.6.2.3 Derived-From - - The Derived-From entity-header field can be used to indicate the - version tag of the resource from which the enclosed entity was - derived before modifications were made by the sender. This field is - used to help manage the process of merging successive changes to a - resource, particularly when such changes are being made in parallel - and from multiple sources. - - Derived-From = "Derived-From" ":" quoted-string - - An example use of the field is: - - Derived-From: "2.1.1" - - The Derived-From field is required for PUT and PATCH requests if the - entity being sent was previously retrieved from the same URI and a - Content-Version header was included with the entity when it was last - retrieved. - - - -Fielding, et. al. Standards Track [Page 158] - -RFC 2068 HTTP/1.1 January 1997 - - -19.6.2.4 Link - - The Link entity-header field provides a means for describing a - relationship between two resources, generally between the requested - resource and some other resource. An entity MAY include multiple Link - values. Links at the metainformation level typically indicate - relationships like hierarchical structure and navigation paths. The - Link field is semantically equivalent to the <LINK> element in - HTML.[5] - - Link = "Link" ":" #("<" URI ">" *( ";" link-param ) - - link-param = ( ( "rel" "=" relationship ) - | ( "rev" "=" relationship ) - | ( "title" "=" quoted-string ) - | ( "anchor" "=" <"> URI <"> ) - | ( link-extension ) ) - - link-extension = token [ "=" ( token | quoted-string ) ] - - relationship = sgml-name - | ( <"> sgml-name *( SP sgml-name) <"> ) - - sgml-name = ALPHA *( ALPHA | DIGIT | "." | "-" ) - - Relationship values are case-insensitive and MAY be extended within - the constraints of the sgml-name syntax. The title parameter MAY be - used to label the destination of a link such that it can be used as - identification within a human-readable menu. The anchor parameter MAY - be used to indicate a source anchor other than the entire current - resource, such as a fragment of this resource or a third resource. - - Examples of usage include: - - Link: <http://www.cern.ch/TheBook/chapter2>; rel="Previous" - - Link: <mailto:timbl@w3.org>; rev="Made"; title="Tim Berners-Lee" - - The first example indicates that chapter2 is previous to this - resource in a logical navigation path. The second indicates that the - person responsible for making the resource available is identified by - the given e-mail address. - -19.6.2.5 URI - - The URI header field has, in past versions of this specification, - been used as a combination of the existing Location, Content- - Location, and Vary header fields as well as the future Alternates - - - -Fielding, et. al. Standards Track [Page 159] - -RFC 2068 HTTP/1.1 January 1997 - - - field (above). Its primary purpose has been to include a list of - additional URIs for the resource, including names and mirror - locations. However, it has become clear that the combination of many - different functions within this single field has been a barrier to - consistently and correctly implementing any of those functions. - Furthermore, we believe that the identification of names and mirror - locations would be better performed via the Link header field. The - URI header field is therefore deprecated in favor of those other - fields. - - URI-header = "URI" ":" 1#( "<" URI ">" ) - -19.7 Compatibility with Previous Versions - - It is beyond the scope of a protocol specification to mandate - compliance with previous versions. HTTP/1.1 was deliberately - designed, however, to make supporting previous versions easy. It is - worth noting that at the time of composing this specification, we - would expect commercial HTTP/1.1 servers to: - - o recognize the format of the Request-Line for HTTP/0.9, 1.0, and 1.1 - requests; - - o understand any valid request in the format of HTTP/0.9, 1.0, or - 1.1; - - o respond appropriately with a message in the same major version used - by the client. - - And we would expect HTTP/1.1 clients to: - - o recognize the format of the Status-Line for HTTP/1.0 and 1.1 - responses; - - o understand any valid response in the format of HTTP/0.9, 1.0, or - 1.1. - - For most implementations of HTTP/1.0, each connection is established - by the client prior to the request and closed by the server after - sending the response. A few implementations implement the Keep-Alive - version of persistent connections described in section 19.7.1.1. - - - - - - - - - - -Fielding, et. al. Standards Track [Page 160] - -RFC 2068 HTTP/1.1 January 1997 - - -19.7.1 Compatibility with HTTP/1.0 Persistent Connections - - Some clients and servers may wish to be compatible with some previous - implementations of persistent connections in HTTP/1.0 clients and - servers. Persistent connections in HTTP/1.0 must be explicitly - negotiated as they are not the default behavior. HTTP/1.0 - experimental implementations of persistent connections are faulty, - and the new facilities in HTTP/1.1 are designed to rectify these - problems. The problem was that some existing 1.0 clients may be - sending Keep-Alive to a proxy server that doesn't understand - Connection, which would then erroneously forward it to the next - inbound server, which would establish the Keep-Alive connection and - result in a hung HTTP/1.0 proxy waiting for the close on the - response. The result is that HTTP/1.0 clients must be prevented from - using Keep-Alive when talking to proxies. - - However, talking to proxies is the most important use of persistent - connections, so that prohibition is clearly unacceptable. Therefore, - we need some other mechanism for indicating a persistent connection - is desired, which is safe to use even when talking to an old proxy - that ignores Connection. Persistent connections are the default for - HTTP/1.1 messages; we introduce a new keyword (Connection: close) for - declaring non-persistence. - - The following describes the original HTTP/1.0 form of persistent - connections. - - When it connects to an origin server, an HTTP client MAY send the - Keep-Alive connection-token in addition to the Persist connection- - token: - - Connection: Keep-Alive - - An HTTP/1.0 server would then respond with the Keep-Alive connection - token and the client may proceed with an HTTP/1.0 (or Keep-Alive) - persistent connection. - - An HTTP/1.1 server may also establish persistent connections with - HTTP/1.0 clients upon receipt of a Keep-Alive connection token. - However, a persistent connection with an HTTP/1.0 client cannot make - use of the chunked transfer-coding, and therefore MUST use a - Content-Length for marking the ending boundary of each message. - - A client MUST NOT send the Keep-Alive connection token to a proxy - server as HTTP/1.0 proxy servers do not obey the rules of HTTP/1.1 - for parsing the Connection header field. - - - - - -Fielding, et. al. Standards Track [Page 161] - -RFC 2068 HTTP/1.1 January 1997 - - -19.7.1.1 The Keep-Alive Header - - When the Keep-Alive connection-token has been transmitted with a - request or a response, a Keep-Alive header field MAY also be - included. The Keep-Alive header field takes the following form: - - Keep-Alive-header = "Keep-Alive" ":" 0# keepalive-param - - keepalive-param = param-name "=" value - - The Keep-Alive header itself is optional, and is used only if a - parameter is being sent. HTTP/1.1 does not define any parameters. - - If the Keep-Alive header is sent, the corresponding connection token - MUST be transmitted. The Keep-Alive header MUST be ignored if - received without the connection token. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Fielding, et. al. Standards Track [Page 162] - diff --git a/docs/specs/rfc2109.txt b/docs/specs/rfc2109.txt deleted file mode 100644 index 432fdcc6..00000000 --- a/docs/specs/rfc2109.txt +++ /dev/null @@ -1,1179 +0,0 @@ - - - - - - -Network Working Group D. Kristol -Request for Comments: 2109 Bell Laboratories, Lucent Technologies -Category: Standards Track L. Montulli - Netscape Communications - February 1997 - - - HTTP State Management Mechanism - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -1. ABSTRACT - - This document specifies a way to create a stateful session with HTTP - requests and responses. It describes two new headers, Cookie and - Set-Cookie, which carry state information between participating - origin servers and user agents. The method described here differs - from Netscape's Cookie proposal, but it can interoperate with - HTTP/1.0 user agents that use Netscape's method. (See the HISTORICAL - section.) - -2. TERMINOLOGY - - The terms user agent, client, server, proxy, and origin server have - the same meaning as in the HTTP/1.0 specification. - - Fully-qualified host name (FQHN) means either the fully-qualified - domain name (FQDN) of a host (i.e., a completely specified domain - name ending in a top-level domain such as .com or .uk), or the - numeric Internet Protocol (IP) address of a host. The fully - qualified domain name is preferred; use of numeric IP addresses is - strongly discouraged. - - The terms request-host and request-URI refer to the values the client - would send to the server as, respectively, the host (but not port) - and abs_path portions of the absoluteURI (http_URL) of the HTTP - request line. Note that request-host must be a FQHN. - - - - - - - - -Kristol & Montulli Standards Track [Page 1] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - Hosts names can be specified either as an IP address or a FQHN - string. Sometimes we compare one host name with another. Host A's - name domain-matches host B's if - - * both host names are IP addresses and their host name strings match - exactly; or - - * both host names are FQDN strings and their host name strings match - exactly; or - - * A is a FQDN string and has the form NB, where N is a non-empty name - string, B has the form .B', and B' is a FQDN string. (So, x.y.com - domain-matches .y.com but not y.com.) - - Note that domain-match is not a commutative operation: a.b.c.com - domain-matches .c.com, but not the reverse. - - Because it was used in Netscape's original implementation of state - management, we will use the term cookie to refer to the state - information that passes between an origin server and user agent, and - that gets stored by the user agent. - -3. STATE AND SESSIONS - - This document describes a way to create stateful sessions with HTTP - requests and responses. Currently, HTTP servers respond to each - client request without relating that request to previous or - subsequent requests; the technique allows clients and servers that - wish to exchange state information to place HTTP requests and - responses within a larger context, which we term a "session". This - context might be used to create, for example, a "shopping cart", in - which user selections can be aggregated before purchase, or a - magazine browsing system, in which a user's previous reading affects - which offerings are presented. - - There are, of course, many different potential contexts and thus many - different potential types of session. The designers' paradigm for - sessions created by the exchange of cookies has these key attributes: - - 1. Each session has a beginning and an end. - - 2. Each session is relatively short-lived. - - 3. Either the user agent or the origin server may terminate a - session. - - 4. The session is implicit in the exchange of state information. - - - - -Kristol & Montulli Standards Track [Page 2] - -RFC 2109 HTTP State Management Mechanism February 1997 - - -4. OUTLINE - - We outline here a way for an origin server to send state information - to the user agent, and for the user agent to return the state - information to the origin server. The goal is to have a minimal - impact on HTTP and user agents. Only origin servers that need to - maintain sessions would suffer any significant impact, and that - impact can largely be confined to Common Gateway Interface (CGI) - programs, unless the server provides more sophisticated state - management support. (See Implementation Considerations, below.) - -4.1 Syntax: General - - The two state management headers, Set-Cookie and Cookie, have common - syntactic properties involving attribute-value pairs. The following - grammar uses the notation, and tokens DIGIT (decimal digits) and - token (informally, a sequence of non-special, non-white space - characters) from the HTTP/1.1 specification [RFC 2068] to describe - their syntax. - - av-pairs = av-pair *(";" av-pair) - av-pair = attr ["=" value] ; optional value - attr = token - value = word - word = token | quoted-string - - Attributes (names) (attr) are case-insensitive. White space is - permitted between tokens. Note that while the above syntax - description shows value as optional, most attrs require them. - - NOTE: The syntax above allows whitespace between the attribute and - the = sign. - -4.2 Origin Server Role - -4.2.1 General - - The origin server initiates a session, if it so desires. (Note that - "session" here does not refer to a persistent network connection but - to a logical session created from HTTP requests and responses. The - presence or absence of a persistent connection should have no effect - on the use of cookie-derived sessions). To initiate a session, the - origin server returns an extra response header to the client, Set- - Cookie. (The details follow later.) - - A user agent returns a Cookie request header (see below) to the - origin server if it chooses to continue a session. The origin server - may ignore it or use it to determine the current state of the - - - -Kristol & Montulli Standards Track [Page 3] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - session. It may send back to the client a Set-Cookie response header - with the same or different information, or it may send no Set-Cookie - header at all. The origin server effectively ends a session by - sending the client a Set-Cookie header with Max-Age=0. - - Servers may return a Set-Cookie response headers with any response. - User agents should send Cookie request headers, subject to other - rules detailed below, with every request. - - An origin server may include multiple Set-Cookie headers in a - response. Note that an intervening gateway could fold multiple such - headers into a single header. - -4.2.2 Set-Cookie Syntax - - The syntax for the Set-Cookie response header is - - set-cookie = "Set-Cookie:" cookies - cookies = 1#cookie - cookie = NAME "=" VALUE *(";" cookie-av) - NAME = attr - VALUE = value - cookie-av = "Comment" "=" value - | "Domain" "=" value - | "Max-Age" "=" value - | "Path" "=" value - | "Secure" - | "Version" "=" 1*DIGIT - - Informally, the Set-Cookie response header comprises the token Set- - Cookie:, followed by a comma-separated list of one or more cookies. - Each cookie begins with a NAME=VALUE pair, followed by zero or more - semi-colon-separated attribute-value pairs. The syntax for - attribute-value pairs was shown earlier. The specific attributes and - the semantics of their values follows. The NAME=VALUE attribute- - value pair must come first in each cookie. The others, if present, - can occur in any order. If an attribute appears more than once in a - cookie, the behavior is undefined. - - NAME=VALUE - Required. The name of the state information ("cookie") is NAME, - and its value is VALUE. NAMEs that begin with $ are reserved for - other uses and must not be used by applications. - - - - - - - - -Kristol & Montulli Standards Track [Page 4] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - The VALUE is opaque to the user agent and may be anything the - origin server chooses to send, possibly in a server-selected - printable ASCII encoding. "Opaque" implies that the content is of - interest and relevance only to the origin server. The content - may, in fact, be readable by anyone that examines the Set-Cookie - header. - - Comment=comment - Optional. Because cookies can contain private information about a - user, the Cookie attribute allows an origin server to document its - intended use of a cookie. The user can inspect the information to - decide whether to initiate or continue a session with this cookie. - - Domain=domain - Optional. The Domain attribute specifies the domain for which the - cookie is valid. An explicitly specified domain must always start - with a dot. - - Max-Age=delta-seconds - Optional. The Max-Age attribute defines the lifetime of the - cookie, in seconds. The delta-seconds value is a decimal non- - negative integer. After delta-seconds seconds elapse, the client - should discard the cookie. A value of zero means the cookie - should be discarded immediately. - - Path=path - Optional. The Path attribute specifies the subset of URLs to - which this cookie applies. - - Secure - Optional. The Secure attribute (with no value) directs the user - agent to use only (unspecified) secure means to contact the origin - server whenever it sends back this cookie. - - The user agent (possibly under the user's control) may determine - what level of security it considers appropriate for "secure" - cookies. The Secure attribute should be considered security - advice from the server to the user agent, indicating that it is in - the session's interest to protect the cookie contents. - - Version=version - Required. The Version attribute, a decimal integer, identifies to - which version of the state management specification the cookie - conforms. For this specification, Version=1 applies. - - - - - - - -Kristol & Montulli Standards Track [Page 5] - -RFC 2109 HTTP State Management Mechanism February 1997 - - -4.2.3 Controlling Caching - - An origin server must be cognizant of the effect of possible caching - of both the returned resource and the Set-Cookie header. Caching - "public" documents is desirable. For example, if the origin server - wants to use a public document such as a "front door" page as a - sentinel to indicate the beginning of a session for which a Set- - Cookie response header must be generated, the page should be stored - in caches "pre-expired" so that the origin server will see further - requests. "Private documents", for example those that contain - information strictly private to a session, should not be cached in - shared caches. - - If the cookie is intended for use by a single user, the Set-cookie - header should not be cached. A Set-cookie header that is intended to - be shared by multiple users may be cached. - - The origin server should send the following additional HTTP/1.1 - response headers, depending on circumstances: - - * To suppress caching of the Set-Cookie header: Cache-control: no- - cache="set-cookie". - - and one of the following: - - * To suppress caching of a private document in shared caches: Cache- - control: private. - - * To allow caching of a document and require that it be validated - before returning it to the client: Cache-control: must-revalidate. - - * To allow caching of a document, but to require that proxy caches - (not user agent caches) validate it before returning it to the - client: Cache-control: proxy-revalidate. - - * To allow caching of a document and request that it be validated - before returning it to the client (by "pre-expiring" it): - Cache-control: max-age=0. Not all caches will revalidate the - document in every case. - - HTTP/1.1 servers must send Expires: old-date (where old-date is a - date long in the past) on responses containing Set-Cookie response - headers unless they know for certain (by out of band means) that - there are no downsteam HTTP/1.0 proxies. HTTP/1.1 servers may send - other Cache-Control directives that permit caching by HTTP/1.1 - proxies in addition to the Expires: old-date directive; the Cache- - Control directive will override the Expires: old-date for HTTP/1.1 - proxies. - - - -Kristol & Montulli Standards Track [Page 6] - -RFC 2109 HTTP State Management Mechanism February 1997 - - -4.3 User Agent Role - -4.3.1 Interpreting Set-Cookie - - The user agent keeps separate track of state information that arrives - via Set-Cookie response headers from each origin server (as - distinguished by name or IP address and port). The user agent - applies these defaults for optional attributes that are missing: - - VersionDefaults to "old cookie" behavior as originally specified by - Netscape. See the HISTORICAL section. - - Domain Defaults to the request-host. (Note that there is no dot at - the beginning of request-host.) - - Max-AgeThe default behavior is to discard the cookie when the user - agent exits. - - Path Defaults to the path of the request URL that generated the - Set-Cookie response, up to, but not including, the - right-most /. - - Secure If absent, the user agent may send the cookie over an - insecure channel. - -4.3.2 Rejecting Cookies - - To prevent possible security or privacy violations, a user agent - rejects a cookie (shall not store its information) if any of the - following is true: - - * The value for the Path attribute is not a prefix of the request- - URI. - - * The value for the Domain attribute contains no embedded dots or - does not start with a dot. - - * The value for the request-host does not domain-match the Domain - attribute. - - * The request-host is a FQDN (not IP address) and has the form HD, - where D is the value of the Domain attribute, and H is a string - that contains one or more dots. - - Examples: - - * A Set-Cookie from request-host y.x.foo.com for Domain=.foo.com - would be rejected, because H is y.x and contains a dot. - - - -Kristol & Montulli Standards Track [Page 7] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - * A Set-Cookie from request-host x.foo.com for Domain=.foo.com would - be accepted. - - * A Set-Cookie with Domain=.com or Domain=.com., will always be - rejected, because there is no embedded dot. - - * A Set-Cookie with Domain=ajax.com will be rejected because the - value for Domain does not begin with a dot. - -4.3.3 Cookie Management - - If a user agent receives a Set-Cookie response header whose NAME is - the same as a pre-existing cookie, and whose Domain and Path - attribute values exactly (string) match those of a pre-existing - cookie, the new cookie supersedes the old. However, if the Set- - Cookie has a value for Max-Age of zero, the (old and new) cookie is - discarded. Otherwise cookies accumulate until they expire (resources - permitting), at which time they are discarded. - - Because user agents have finite space in which to store cookies, they - may also discard older cookies to make space for newer ones, using, - for example, a least-recently-used algorithm, along with constraints - on the maximum number of cookies that each origin server may set. - - If a Set-Cookie response header includes a Comment attribute, the - user agent should store that information in a human-readable form - with the cookie and should display the comment text as part of a - cookie inspection user interface. - - User agents should allow the user to control cookie destruction. An - infrequently-used cookie may function as a "preferences file" for - network applications, and a user may wish to keep it even if it is - the least-recently-used cookie. One possible implementation would be - an interface that allows the permanent storage of a cookie through a - checkbox (or, conversely, its immediate destruction). - - Privacy considerations dictate that the user have considerable - control over cookie management. The PRIVACY section contains more - information. - -4.3.4 Sending Cookies to the Origin Server - - When it sends a request to an origin server, the user agent sends a - Cookie request header to the origin server if it has cookies that are - applicable to the request, based on - - * the request-host; - - - - -Kristol & Montulli Standards Track [Page 8] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - * the request-URI; - - * the cookie's age. - - The syntax for the header is: - - cookie = "Cookie:" cookie-version - 1*((";" | ",") cookie-value) - cookie-value = NAME "=" VALUE [";" path] [";" domain] - cookie-version = "$Version" "=" value - NAME = attr - VALUE = value - path = "$Path" "=" value - domain = "$Domain" "=" value - - The value of the cookie-version attribute must be the value from the - Version attribute, if any, of the corresponding Set-Cookie response - header. Otherwise the value for cookie-version is 0. The value for - the path attribute must be the value from the Path attribute, if any, - of the corresponding Set-Cookie response header. Otherwise the - attribute should be omitted from the Cookie request header. The - value for the domain attribute must be the value from the Domain - attribute, if any, of the corresponding Set-Cookie response header. - Otherwise the attribute should be omitted from the Cookie request - header. - - Note that there is no Comment attribute in the Cookie request header - corresponding to the one in the Set-Cookie response header. The user - agent does not return the comment information to the origin server. - - The following rules apply to choosing applicable cookie-values from - among all the cookies the user agent has. - - Domain Selection - The origin server's fully-qualified host name must domain-match - the Domain attribute of the cookie. - - Path Selection - The Path attribute of the cookie must match a prefix of the - request-URI. - - Max-Age Selection - Cookies that have expired should have been discarded and thus - are not forwarded to an origin server. - - - - - - - -Kristol & Montulli Standards Track [Page 9] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - If multiple cookies satisfy the criteria above, they are ordered in - the Cookie header such that those with more specific Path attributes - precede those with less specific. Ordering with respect to other - attributes (e.g., Domain) is unspecified. - - Note: For backward compatibility, the separator in the Cookie header - is semi-colon (;) everywhere. A server should also accept comma (,) - as the separator between cookie-values for future compatibility. - -4.3.5 Sending Cookies in Unverifiable Transactions - - Users must have control over sessions in order to ensure privacy. - (See PRIVACY section below.) To simplify implementation and to - prevent an additional layer of complexity where adequate safeguards - exist, however, this document distinguishes between transactions that - are verifiable and those that are unverifiable. A transaction is - verifiable if the user has the option to review the request-URI prior - to its use in the transaction. A transaction is unverifiable if the - user does not have that option. Unverifiable transactions typically - arise when a user agent automatically requests inlined or embedded - entities or when it resolves redirection (3xx) responses from an - origin server. Typically the origin transaction, the transaction - that the user initiates, is verifiable, and that transaction may - directly or indirectly induce the user agent to make unverifiable - transactions. - - When it makes an unverifiable transaction, a user agent must enable a - session only if a cookie with a domain attribute D was sent or - received in its origin transaction, such that the host name in the - Request-URI of the unverifiable transaction domain-matches D. - - This restriction prevents a malicious service author from using - unverifiable transactions to induce a user agent to start or continue - a session with a server in a different domain. The starting or - continuation of such sessions could be contrary to the privacy - expectations of the user, and could also be a security problem. - - User agents may offer configurable options that allow the user agent, - or any autonomous programs that the user agent executes, to ignore - the above rule, so long as these override options default to "off". - - Many current user agents already provide a review option that would - render many links verifiable. For instance, some user agents display - the URL that would be referenced for a particular link when the mouse - pointer is placed over that link. The user can therefore determine - whether to visit that site before causing the browser to do so. - (Though not implemented on current user agents, a similar technique - could be used for a button used to submit a form -- the user agent - - - -Kristol & Montulli Standards Track [Page 10] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - could display the action to be taken if the user were to select that - button.) However, even this would not make all links verifiable; for - example, links to automatically loaded images would not normally be - subject to "mouse pointer" verification. - - Many user agents also provide the option for a user to view the HTML - source of a document, or to save the source to an external file where - it can be viewed by another application. While such an option does - provide a crude review mechanism, some users might not consider it - acceptable for this purpose. - -4.4 How an Origin Server Interprets the Cookie Header - - A user agent returns much of the information in the Set-Cookie header - to the origin server when the Path attribute matches that of a new - request. When it receives a Cookie header, the origin server should - treat cookies with NAMEs whose prefix is $ specially, as an attribute - for the adjacent cookie. The value for such a NAME is to be - interpreted as applying to the lexically (left-to-right) most recent - cookie whose name does not have the $ prefix. If there is no - previous cookie, the value applies to the cookie mechanism as a - whole. For example, consider the cookie - - Cookie: $Version="1"; Customer="WILE_E_COYOTE"; - $Path="/acme" - - $Version applies to the cookie mechanism as a whole (and gives the - version number for the cookie mechanism). $Path is an attribute - whose value (/acme) defines the Path attribute that was used when the - Customer cookie was defined in a Set-Cookie response header. - -4.5 Caching Proxy Role - - One reason for separating state information from both a URL and - document content is to facilitate the scaling that caching permits. - To support cookies, a caching proxy must obey these rules already in - the HTTP specification: - - * Honor requests from the cache, if possible, based on cache validity - rules. - - * Pass along a Cookie request header in any request that the proxy - must make of another server. - - * Return the response to the client. Include any Set-Cookie response - header. - - - - - -Kristol & Montulli Standards Track [Page 11] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - * Cache the received response subject to the control of the usual - headers, such as Expires, Cache-control: no-cache, and Cache- - control: private, - - * Cache the Set-Cookie subject to the control of the usual header, - Cache-control: no-cache="set-cookie". (The Set-Cookie header - should usually not be cached.) - - Proxies must not introduce Set-Cookie (Cookie) headers of their own - in proxy responses (requests). - -5. EXAMPLES - -5.1 Example 1 - - Most detail of request and response headers has been omitted. Assume - the user agent has no stored cookies. - - 1. User Agent -> Server - - POST /acme/login HTTP/1.1 - [form data] - - User identifies self via a form. - - 2. Server -> User Agent - - HTTP/1.1 200 OK - Set-Cookie: Customer="WILE_E_COYOTE"; Version="1"; Path="/acme" - - Cookie reflects user's identity. - - 3. User Agent -> Server - - POST /acme/pickitem HTTP/1.1 - Cookie: $Version="1"; Customer="WILE_E_COYOTE"; $Path="/acme" - [form data] - - User selects an item for "shopping basket." - - 4. Server -> User Agent - - HTTP/1.1 200 OK - Set-Cookie: Part_Number="Rocket_Launcher_0001"; Version="1"; - Path="/acme" - - Shopping basket contains an item. - - - - -Kristol & Montulli Standards Track [Page 12] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - 5. User Agent -> Server - - POST /acme/shipping HTTP/1.1 - Cookie: $Version="1"; - Customer="WILE_E_COYOTE"; $Path="/acme"; - Part_Number="Rocket_Launcher_0001"; $Path="/acme" - [form data] - - User selects shipping method from form. - - 6. Server -> User Agent - - HTTP/1.1 200 OK - Set-Cookie: Shipping="FedEx"; Version="1"; Path="/acme" - - New cookie reflects shipping method. - - 7. User Agent -> Server - - POST /acme/process HTTP/1.1 - Cookie: $Version="1"; - Customer="WILE_E_COYOTE"; $Path="/acme"; - Part_Number="Rocket_Launcher_0001"; $Path="/acme"; - Shipping="FedEx"; $Path="/acme" - [form data] - - User chooses to process order. - - 8. Server -> User Agent - - HTTP/1.1 200 OK - - Transaction is complete. - - The user agent makes a series of requests on the origin server, after - each of which it receives a new cookie. All the cookies have the - same Path attribute and (default) domain. Because the request URLs - all have /acme as a prefix, and that matches the Path attribute, each - request contains all the cookies received so far. - -5.2 Example 2 - - This example illustrates the effect of the Path attribute. All - detail of request and response headers has been omitted. Assume the - user agent has no stored cookies. - - Imagine the user agent has received, in response to earlier requests, - the response headers - - - -Kristol & Montulli Standards Track [Page 13] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - Set-Cookie: Part_Number="Rocket_Launcher_0001"; Version="1"; - Path="/acme" - - and - - Set-Cookie: Part_Number="Riding_Rocket_0023"; Version="1"; - Path="/acme/ammo" - - A subsequent request by the user agent to the (same) server for URLs - of the form /acme/ammo/... would include the following request - header: - - Cookie: $Version="1"; - Part_Number="Riding_Rocket_0023"; $Path="/acme/ammo"; - Part_Number="Rocket_Launcher_0001"; $Path="/acme" - - Note that the NAME=VALUE pair for the cookie with the more specific - Path attribute, /acme/ammo, comes before the one with the less - specific Path attribute, /acme. Further note that the same cookie - name appears more than once. - - A subsequent request by the user agent to the (same) server for a URL - of the form /acme/parts/ would include the following request header: - - Cookie: $Version="1"; Part_Number="Rocket_Launcher_0001"; $Path="/acme" - - Here, the second cookie's Path attribute /acme/ammo is not a prefix - of the request URL, /acme/parts/, so the cookie does not get - forwarded to the server. - -6. IMPLEMENTATION CONSIDERATIONS - - Here we speculate on likely or desirable details for an origin server - that implements state management. - -6.1 Set-Cookie Content - - An origin server's content should probably be divided into disjoint - application areas, some of which require the use of state - information. The application areas can be distinguished by their - request URLs. The Set-Cookie header can incorporate information - about the application areas by setting the Path attribute for each - one. - - The session information can obviously be clear or encoded text that - describes state. However, if it grows too large, it can become - unwieldy. Therefore, an implementor might choose for the session - information to be a key to a server-side resource. Of course, using - - - -Kristol & Montulli Standards Track [Page 14] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - a database creates some problems that this state management - specification was meant to avoid, namely: - - 1. keeping real state on the server side; - - 2. how and when to garbage-collect the database entry, in case the - user agent terminates the session by, for example, exiting. - -6.2 Stateless Pages - - Caching benefits the scalability of WWW. Therefore it is important - to reduce the number of documents that have state embedded in them - inherently. For example, if a shopping-basket-style application - always displays a user's current basket contents on each page, those - pages cannot be cached, because each user's basket's contents would - be different. On the other hand, if each page contains just a link - that allows the user to "Look at My Shopping Basket", the page can be - cached. - -6.3 Implementation Limits - - Practical user agent implementations have limits on the number and - size of cookies that they can store. In general, user agents' cookie - support should have no fixed limits. They should strive to store as - many frequently-used cookies as possible. Furthermore, general-use - user agents should provide each of the following minimum capabilities - individually, although not necessarily simultaneously: - - * at least 300 cookies - - * at least 4096 bytes per cookie (as measured by the size of the - characters that comprise the cookie non-terminal in the syntax - description of the Set-Cookie header) - - * at least 20 cookies per unique host or domain name - - User agents created for specific purposes or for limited-capacity - devices should provide at least 20 cookies of 4096 bytes, to ensure - that the user can interact with a session-based origin server. - - The information in a Set-Cookie response header must be retained in - its entirety. If for some reason there is inadequate space to store - the cookie, it must be discarded, not truncated. - - Applications should use as few and as small cookies as possible, and - they should cope gracefully with the loss of a cookie. - - - - - -Kristol & Montulli Standards Track [Page 15] - -RFC 2109 HTTP State Management Mechanism February 1997 - - -6.3.1 Denial of Service Attacks - - User agents may choose to set an upper bound on the number of cookies - to be stored from a given host or domain name or on the size of the - cookie information. Otherwise a malicious server could attempt to - flood a user agent with many cookies, or large cookies, on successive - responses, which would force out cookies the user agent had received - from other servers. However, the minima specified above should still - be supported. - -7. PRIVACY - -7.1 User Agent Control - - An origin server could create a Set-Cookie header to track the path - of a user through the server. Users may object to this behavior as - an intrusive accumulation of information, even if their identity is - not evident. (Identity might become evident if a user subsequently - fills out a form that contains identifying information.) This state - management specification therefore requires that a user agent give - the user control over such a possible intrusion, although the - interface through which the user is given this control is left - unspecified. However, the control mechanisms provided shall at least - allow the user - - * to completely disable the sending and saving of cookies. - - * to determine whether a stateful session is in progress. - - * to control the saving of a cookie on the basis of the cookie's - Domain attribute. - - Such control could be provided by, for example, mechanisms - - * to notify the user when the user agent is about to send a cookie - to the origin server, offering the option not to begin a session. - - * to display a visual indication that a stateful session is in - progress. - - * to let the user decide which cookies, if any, should be saved - when the user concludes a window or user agent session. - - * to let the user examine the contents of a cookie at any time. - - A user agent usually begins execution with no remembered state - information. It should be possible to configure a user agent never - to send Cookie headers, in which case it can never sustain state with - - - -Kristol & Montulli Standards Track [Page 16] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - an origin server. (The user agent would then behave like one that is - unaware of how to handle Set-Cookie response headers.) - - When the user agent terminates execution, it should let the user - discard all state information. Alternatively, the user agent may ask - the user whether state information should be retained; the default - should be "no". If the user chooses to retain state information, it - would be restored the next time the user agent runs. - - NOTE: User agents should probably be cautious about using files to - store cookies long-term. If a user runs more than one instance of - the user agent, the cookies could be commingled or otherwise messed - up. - -7.2 Protocol Design - - The restrictions on the value of the Domain attribute, and the rules - concerning unverifiable transactions, are meant to reduce the ways - that cookies can "leak" to the "wrong" site. The intent is to - restrict cookies to one, or a closely related set of hosts. - Therefore a request-host is limited as to what values it can set for - Domain. We consider it acceptable for hosts host1.foo.com and - host2.foo.com to share cookies, but not a.com and b.com. - - Similarly, a server can only set a Path for cookies that are related - to the request-URI. - -8. SECURITY CONSIDERATIONS - -8.1 Clear Text - - The information in the Set-Cookie and Cookie headers is unprotected. - Two consequences are: - - 1. Any sensitive information that is conveyed in them is exposed - to intruders. - - 2. A malicious intermediary could alter the headers as they travel - in either direction, with unpredictable results. - - These facts imply that information of a personal and/or financial - nature should only be sent over a secure channel. For less sensitive - information, or when the content of the header is a database key, an - origin server should be vigilant to prevent a bad Cookie value from - causing failures. - - - - - - -Kristol & Montulli Standards Track [Page 17] - -RFC 2109 HTTP State Management Mechanism February 1997 - - -8.2 Cookie Spoofing - - Proper application design can avoid spoofing attacks from related - domains. Consider: - - 1. User agent makes request to victim.cracker.edu, gets back - cookie session_id="1234" and sets the default domain - victim.cracker.edu. - - 2. User agent makes request to spoof.cracker.edu, gets back - cookie session-id="1111", with Domain=".cracker.edu". - - 3. User agent makes request to victim.cracker.edu again, and - passes - - Cookie: $Version="1"; - session_id="1234"; - session_id="1111"; $Domain=".cracker.edu" - - The server at victim.cracker.edu should detect that the second - cookie was not one it originated by noticing that the Domain - attribute is not for itself and ignore it. - -8.3 Unexpected Cookie Sharing - - A user agent should make every attempt to prevent the sharing of - session information between hosts that are in different domains. - Embedded or inlined objects may cause particularly severe privacy - problems if they can be used to share cookies between disparate - hosts. For example, a malicious server could embed cookie - information for host a.com in a URI for a CGI on host b.com. User - agent implementors are strongly encouraged to prevent this sort of - exchange whenever possible. - -9. OTHER, SIMILAR, PROPOSALS - - Three other proposals have been made to accomplish similar goals. - This specification is an amalgam of Kristol's State-Info proposal and - Netscape's Cookie proposal. - - Brian Behlendorf proposed a Session-ID header that would be user- - agent-initiated and could be used by an origin server to track - "clicktrails". It would not carry any origin-server-defined state, - however. Phillip Hallam-Baker has proposed another client-defined - session ID mechanism for similar purposes. - - - - - - -Kristol & Montulli Standards Track [Page 18] - -RFC 2109 HTTP State Management Mechanism February 1997 - - - While both session IDs and cookies can provide a way to sustain - stateful sessions, their intended purpose is different, and, - consequently, the privacy requirements for them are different. A - user initiates session IDs to allow servers to track progress through - them, or to distinguish multiple users on a shared machine. Cookies - are server-initiated, so the cookie mechanism described here gives - users control over something that would otherwise take place without - the users' awareness. Furthermore, cookies convey rich, server- - selected information, whereas session IDs comprise user-selected, - simple information. - -10. HISTORICAL - -10.1 Compatibility With Netscape's Implementation - - HTTP/1.0 clients and servers may use Set-Cookie and Cookie headers - that reflect Netscape's original cookie proposal. These notes cover - inter-operation between "old" and "new" cookies. - -10.1.1 Extended Cookie Header - - This proposal adds attribute-value pairs to the Cookie request header - in a compatible way. An "old" client that receives a "new" cookie - will ignore attributes it does not understand; it returns what it - does understand to the origin server. A "new" client always sends - cookies in the new form. - - An "old" server that receives a "new" cookie will see what it thinks - are many cookies with names that begin with a $, and it will ignore - them. (The "old" server expects these cookies to be separated by - semi-colon, not comma.) A "new" server can detect cookies that have - passed through an "old" client, because they lack a $Version - attribute. - -10.1.2 Expires and Max-Age - - Netscape's original proposal defined an Expires header that took a - date value in a fixed-length variant format in place of Max-Age: - - Wdy, DD-Mon-YY HH:MM:SS GMT - - Note that the Expires date format contains embedded spaces, and that - "old" cookies did not have quotes around values. Clients that - implement to this specification should be aware of "old" cookies and - Expires. - - - - - - -Kristol & Montulli Standards Track [Page 19] - -RFC 2109 HTTP State Management Mechanism February 1997 - - -10.1.3 Punctuation - - In Netscape's original proposal, the values in attribute-value pairs - did not accept "-quoted strings. Origin servers should be cautious - about sending values that require quotes unless they know the - receiving user agent understands them (i.e., "new" cookies). A - ("new") user agent should only use quotes around values in Cookie - headers when the cookie's version(s) is (are) all compliant with this - specification or later. - - In Netscape's original proposal, no whitespace was permitted around - the = that separates attribute-value pairs. Therefore such - whitespace should be used with caution in new implementations. - -10.2 Caching and HTTP/1.0 - - Some caches, such as those conforming to HTTP/1.0, will inevitably - cache the Set-Cookie header, because there was no mechanism to - suppress caching of headers prior to HTTP/1.1. This caching can lead - to security problems. Documents transmitted by an origin server - along with Set-Cookie headers will usually either be uncachable, or - will be "pre-expired". As long as caches obey instructions not to - cache documents (following Expires: <a date in the past> or Pragma: - no-cache (HTTP/1.0), or Cache-control: no-cache (HTTP/1.1)) - uncachable documents present no problem. However, pre-expired - documents may be stored in caches. They require validation (a - conditional GET) on each new request, but some cache operators loosen - the rules for their caches, and sometimes serve expired documents - without first validating them. This combination of factors can lead - to cookies meant for one user later being sent to another user. The - Set-Cookie header is stored in the cache, and, although the document - is stale (expired), the cache returns the document in response to - later requests, including cached headers. - -11. ACKNOWLEDGEMENTS - - This document really represents the collective efforts of the - following people, in addition to the authors: Roy Fielding, Marc - Hedlund, Ted Hardie, Koen Holtman, Shel Kaphan, Rohit Khare. - - - - - - - - - - - - -Kristol & Montulli Standards Track [Page 20] - -RFC 2109 HTTP State Management Mechanism February 1997 - - -12. AUTHORS' ADDRESSES - - David M. Kristol - Bell Laboratories, Lucent Technologies - 600 Mountain Ave. Room 2A-227 - Murray Hill, NJ 07974 - - Phone: (908) 582-2250 - Fax: (908) 582-5809 - EMail: dmk@bell-labs.com - - - Lou Montulli - Netscape Communications Corp. - 501 E. Middlefield Rd. - Mountain View, CA 94043 - - Phone: (415) 528-2600 - EMail: montulli@netscape.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Kristol & Montulli Standards Track [Page 21] - diff --git a/docs/specs/rfc2145.txt b/docs/specs/rfc2145.txt deleted file mode 100644 index b6db4d58..00000000 --- a/docs/specs/rfc2145.txt +++ /dev/null @@ -1,395 +0,0 @@ - - - - - - -Network Working Group J. C. Mogul -Request for Comments: 2145 DEC -Category: Informational R. Fielding - UC Irvine - J. Gettys - DEC - H. Frystyk - MIT/LCS - May 1997 - - Use and Interpretation of - HTTP Version Numbers - -Status of this Memo - - This memo provides information for the Internet community. This memo - does not specify an Internet standard of any kind. Distribution of - this memo is unlimited. - - Distribution of this document is unlimited. Please send comments to - the HTTP working group at <http-wg@cuckoo.hpl.hp.com>. Discussions - of the working group are archived at - <URL:http://www.ics.uci.edu/pub/ietf/http/>. General discussions - about HTTP and the applications which use HTTP should take place on - the <www-talk@w3.org> mailing list. - -Abstract - - HTTP request and response messages include an HTTP protocol version - number. Some confusion exists concerning the proper use and - interpretation of HTTP version numbers, and concerning - interoperability of HTTP implementations of different protocol - versions. This document is an attempt to clarify the situation. It - is not a modification of the intended meaning of the existing - HTTP/1.0 and HTTP/1.1 documents, but it does describe the intention - of the authors of those documents, and can be considered definitive - when there is any ambiguity in those documents concerning HTTP - version numbers, for all versions of HTTP. - - - - - - - - - - - - - -Mogul, et. al. Informational [Page 1] - -RFC 2145 HTTP Version Numbers May 1997 - - -TABLE OF CONTENTS - - 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 1.1 Robustness Principle . . . . . . . . . . . . . . . . . . 3 - 2 HTTP version numbers. . . . . . . . . . . . . . . . . . . . . . 3 - 2.1 Proxy behavior. . . . . . . . . . . . . . . . . . . . . . . . 4 - 2.2 Compatibility between minor versions of the same major - version. . . . . . . . . . . . . . . . . . . . . . . . 4 - 2.3 Which version number to send in a message. . . . . . . . 5 - 3 Security Considerations . . . . . . . . . . . . . . . . . . . . 6 - 4 References. . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 5 Authors' addresses. . . . . . . . . . . . . . . . . . . . . . . 6 - -1 Introduction - - HTTP request and response messages include an HTTP protocol version - number. According to section 3.1 of the HTTP/1.1 specification [2], - - HTTP uses a "<major>.<minor>" numbering scheme to indicate - versions of the protocol. The protocol versioning policy is - intended to allow the sender to indicate the format of a message - and its capacity for understanding further HTTP communication, - rather than the features obtained via that communication. No - change is made to the version number for the addition of message - components which do not affect communication behavior or which - only add to extensible field values. The <minor> number is - incremented when the changes made to the protocol add features - which do not change the general message parsing algorithm, but - which may add to the message semantics and imply additional - capabilities of the sender. The <major> number is incremented when - the format of a message within the protocol is changed. - - The same language appears in the description of HTTP/1.0 [1]. - - Many readers of these documents have expressed some confusion about - the intended meaning of this policy. Also, some people who wrote - HTTP implementations before RFC1945 [1] was issued were not aware of - the intentions behind the introduction of version numbers in - HTTP/1.0. This has led to debate and inconsistency regarding the use - and interpretation of HTTP version numbers, and has led to - interoperability problems in certain cases. - - - - - - - - - - -Mogul, et. al. Informational [Page 2] - -RFC 2145 HTTP Version Numbers May 1997 - - - This document is an attempt to clarify the situation. It is not a - modification of the intended meaning of the existing HTTP/1.0 and - HTTP/1.1 documents, but it does describe the intention of the authors - of those documents. In any case where either of those two documents - is ambiguous regarding the use and interpretation of HTTP version - numbers, this document should be considered the definitive as to the - intentions of the designers of HTTP. - - The specification described in this document is not part of the - specification of any individual version of HTTP, such as HTTP/1.0 or - HTTP/1.1. Rather, this document describes the use of HTTP version - numbers in any version of HTTP (except for HTTP/0.9, which did not - include version numbers). - - No vendor or other provider of an HTTP implementation should claim - any compliance with any IETF HTTP specification unless the - implementation conditionally complies with the rules in this - document. - -1.1 Robustness Principle - - RFC791 [4] defines the "robustness principle" in section 3.2: - - an implementation must be conservative in its sending - behavior, and liberal in its receiving behavior. - - This principle applies to HTTP, as well. It is the fundamental basis - for interpreting any part of the HTTP specification that might still - be ambiguous. In particular, implementations of HTTP SHOULD NOT - reject messages or generate errors unnecessarily. - -2 HTTP version numbers - - We start by restating the language quoted above from section 3.1 of - the HTTP/1.1 specification [2]: - - It is, and has always been, the explicit intent of the - HTTP specification that the interpretation of an HTTP message - header does not change between minor versions of the same major - version. - - It is, and has always been, the explicit intent of the - HTTP specification that an implementation receiving a message - header that it does not understand MUST ignore that header. (The - word "ignore" has a special meaning for proxies; see section 2.1 - below.) - - - - - -Mogul, et. al. Informational [Page 3] - -RFC 2145 HTTP Version Numbers May 1997 - - - To make this as clear as possible: The major version sent in a - message MAY indicate the interpretation of other header fields. The - minor version sent in a message MUST NOT indicate the interpretation - of other header fields. This reflects the principle that the minor - version labels the capability of the sender, not the interpretation - of the message. - - Note: In a future version of HTTP, we may introduce a mechanism - that explicitly requires a receiving implementation to reject a - message if it does not understand certain headers. For example, - this might be implemented by means of a header that lists a set of - other message headers that must be understood by the recipient. - Any implementation claiming at least conditional compliance with - this future version of HTTP would have to implement this - mechanism. However, no implementation claiming compliance with a - lower HTTP version (in particular, HTTP/1.1) will have to - implement this mechanism. - - This future change may be required to support the Protocol - Extension Protocol (PEP) [3]. - - One consequence of these rules is that an HTTP/1.1 message sent to an - HTTP/1.0 recipient (or a recipient whose version is unknown) MUST be - constructed so that it remains a valid HTTP/1.0 message when all - headers not defined in the HTTP/1.0 specification [1] are removed. - -2.1 Proxy behavior - - A proxy MUST forward an unknown header, unless it is protected by a - Connection header. A proxy implementing an HTTP version >= 1.1 MUST - NOT forward unknown headers that are protected by a Connection - header, as described in section 14.10 of the HTTP/1.1 specification - [2]. - - We remind the reader that that HTTP version numbers are hop-by-hop - components of HTTP messages, and are not end-to-end. That is, an - HTTP proxy never "forwards" an HTTP version number in either a - request or response. - -2.2 Compatibility between minor versions of the same major version - - An implementation of HTTP/x.b sending a message to a recipient whose - version is known to be HTTP/x.a, a < b, MAY send a header that is not - defined in the specification for HTTP/x.a. For example, an HTTP/1.1 - server may send a "Cache-control" header to an HTTP/1.0 client; this - may be useful if the immediate recipient is an HTTP/1.0 proxy, but - the ultimate recipient is an HTTP/1.1 client. - - - - -Mogul, et. al. Informational [Page 4] - -RFC 2145 HTTP Version Numbers May 1997 - - - An implementation of HTTP/x.b sending a message to a recipient whose - version is known to be HTTP/x.a, a < b, MUST NOT depend on the - recipient understanding a header not defined in the specification for - HTTP/x.a. For example, HTTP/1.0 clients cannot be expected to - understand chunked encodings, and so an HTTP/1.1 server must never - send "Transfer-Encoding: chunked" in response to an HTTP/1.0 request. - -2.3 Which version number to send in a message - - The most strenuous debate over the use of HTTP version numbers has - centered on the problem of implementations that do not follow the - robustness principle, and which fail to produce useful results when - they receive a message with an HTTP minor version higher than the - minor version they implement. We consider these implementations - buggy, but we recognize that the robustness principle also implies - that message senders should make concessions to buggy implementations - when this is truly necessary for interoperation. - - An HTTP client SHOULD send a request version equal to the highest - version for which the client is at least conditionally compliant, and - whose major version is no higher than the highest version supported - by the server, if this is known. An HTTP client MUST NOT send a - version for which it is not at least conditionally compliant. - - An HTTP client MAY send a lower request version, if it is known that - the server incorrectly implements the HTTP specification, but only - after the client has determined that the server is actually buggy. - - An HTTP server SHOULD send a response version equal to the highest - version for which the server is at least conditionally compliant, and - whose major version is less than or equal to the one received in the - request. An HTTP server MUST NOT send a version for which it is not - at least conditionally compliant. A server MAY send a 505 (HTTP - Version Not Supported) response if cannot send a response using the - major version used in the client's request. - - An HTTP server MAY send a lower response version, if it is known or - suspected that the client incorrectly implements the HTTP - specification, but this should not be the default, and this SHOULD - NOT be done if the request version is HTTP/1.1 or greater. - - - - - - - - - - - -Mogul, et. al. Informational [Page 5] - -RFC 2145 HTTP Version Numbers May 1997 - - -3 Security Considerations - - None, except to the extent that security mechanisms introduced in one - version of HTTP might depend on the proper interpretation of HTTP - version numbers in older implementations. - -4 References - - 1. Berners-Lee, T., R. Fielding, and H. Frystyk. Hypertext - Transfer Protocol -- HTTP/1.0. RFC 1945, HTTP Working Group, May, - 1996. - - 2. Fielding, Roy T., Jim Gettys, Jeffrey C. Mogul, Henrik Frystyk - Nielsen, and Tim Berners-Lee. Hypertext Transfer Protocol -- - HTTP/1.1. RFC 2068, HTTP Working Group, January, 1997. - - 3. Khare, Rohit. HTTP/1.2 Extension Protocol (PEP). HTTP Working - Group, Work in Progress. - - 4. Postel, Jon. Internet Protocol. RFC 791, NIC, September, 1981. - -5 Authors' addresses - - Jeffrey C. Mogul - Western Research Laboratory - Digital Equipment Corporation - 250 University Avenue - Palo Alto, California, 94305, USA - Email: mogul@wrl.dec.com - - Roy T. Fielding - Department of Information and Computer Science - University of California - Irvine, CA 92717-3425, USA - Fax: +1 (714) 824-4056 - Email: fielding@ics.uci.edu - - Jim Gettys - MIT Laboratory for Computer Science - 545 Technology Square - Cambridge, MA 02139, USA - Fax: +1 (617) 258 8682 - Email: jg@w3.org - - - - - - - - -Mogul, et. al. Informational [Page 6] - -RFC 2145 HTTP Version Numbers May 1997 - - - Henrik Frystyk Nielsen - W3 Consortium - MIT Laboratory for Computer Science - 545 Technology Square - Cambridge, MA 02139, USA - Fax: +1 (617) 258 8682 - Email: frystyk@w3.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Mogul, et. al. Informational [Page 7] - diff --git a/docs/specs/rfc2324.txt b/docs/specs/rfc2324.txt deleted file mode 100644 index a85921a9..00000000 --- a/docs/specs/rfc2324.txt +++ /dev/null @@ -1,563 +0,0 @@ - - - - - - -Network Working Group L. Masinter -Request for Comments: 2324 1 April 1998 -Category: Informational - - - Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0) - -Status of this Memo - - This memo provides information for the Internet community. It does - not specify an Internet standard of any kind. Distribution of this - memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (1998). All Rights Reserved. - -Abstract - - This document describes HTCPCP, a protocol for controlling, - monitoring, and diagnosing coffee pots. - -1. Rationale and Scope - - There is coffee all over the world. Increasingly, in a world in which - computing is ubiquitous, the computists want to make coffee. Coffee - brewing is an art, but the distributed intelligence of the web- - connected world transcends art. Thus, there is a strong, dark, rich - requirement for a protocol designed espressoly for the brewing of - coffee. Coffee is brewed using coffee pots. Networked coffee pots - require a control protocol if they are to be controlled. - - Increasingly, home and consumer devices are being connected to the - Internet. Early networking experiments demonstrated vending devices - connected to the Internet for status monitoring [COKE]. One of the - first remotely _operated_ machine to be hooked up to the Internet, - the Internet Toaster, (controlled via SNMP) was debuted in 1990 - [RFC2235]. - - The demand for ubiquitous appliance connectivity that is causing the - consumption of the IPv4 address space. Consumers want remote control - of devices such as coffee pots so that they may wake up to freshly - brewed coffee, or cause coffee to be prepared at a precise time after - the completion of dinner preparations. - - - - - - - -Masinter Informational [Page 1] - -RFC 2324 HTCPCP/1.0 1 April 1998 - - - This document specifies a Hyper Text Coffee Pot Control Protocol - (HTCPCP), which permits the full request and responses necessary to - control all devices capable of making the popular caffeinated hot - beverages. - - HTTP 1.1 ([RFC2068]) permits the transfer of web objects from origin - servers to clients. The web is world-wide. HTCPCP is based on HTTP. - This is because HTTP is everywhere. It could not be so pervasive - without being good. Therefore, HTTP is good. If you want good coffee, - HTCPCP needs to be good. To make HTCPCP good, it is good to base - HTCPCP on HTTP. - - Future versions of this protocol may include extensions for espresso - machines and similar devices. - -2. HTCPCP Protocol - - The HTCPCP protocol is built on top of HTTP, with the addition of a - few new methods, header fields and return codes. All HTCPCP servers - should be referred to with the "coffee:" URI scheme (Section 4). - -2.1 HTCPCP Added Methods - -2.1.1 The BREW method, and the use of POST - - Commands to control a coffee pot are sent from client to coffee - server using either the BREW or POST method, and a message body with - Content-Type set to "application/coffee-pot-command". - - A coffee pot server MUST accept both the BREW and POST method - equivalently. However, the use of POST for causing actions to happen - is deprecated. - - Coffee pots heat water using electronic mechanisms, so there is no - fire. Thus, no firewalls are necessary, and firewall control policy - is irrelevant. However, POST may be a trademark for coffee, and so - the BREW method has been added. The BREW method may be used with - other HTTP-based protocols (e.g., the Hyper Text Brewery Control - Protocol). - -2.1.2 GET method - - In HTTP, the GET method is used to mean "retrieve whatever - information (in the form of an entity) identified by the Request- - URI." If the Request-URI refers to a data-producing process, it is - the produced data which shall be returned as the entity in the - response and not the source text of the process, unless that text - happens to be the output of the process. - - - -Masinter Informational [Page 2] - -RFC 2324 HTCPCP/1.0 1 April 1998 - - - In HTCPCP, the resources associated with a coffee pot are physical, - and not information resources. The "data" for most coffee URIs - contain no caffeine. - -2.1.3 PROPFIND method - - If a cup of coffee is data, metadata about the brewed resource is - discovered using the PROPFIND method [WEBDAV]. - -2.1.4 WHEN method - - When coffee is poured, and milk is offered, it is necessary for the - holder of the recipient of milk to say "when" at the time when - sufficient milk has been introduced into the coffee. For this - purpose, the "WHEN" method has been added to HTCPCP. Enough? Say - WHEN. - -2.2 Coffee Pot Header fields - - HTCPCP recommends several HTTP header fields and defines some new - ones. - -2.2.1 Recommended header fields - -2.2.1.1 The "safe" response header field. - - [SAFE] defines a HTTP response header field, "Safe", which can be - used to indicate that repeating a HTTP request is safe. The inclusion - of a "Safe: Yes" header field allows a client to repeat a previous - request if the result of the request might be repeated. - - The actual safety of devices for brewing coffee varies widely, and - may depend, in fact, on conditions in the client rather than just in - the server. Thus, this protocol includes an extension to the "Safe" - response header: - - Safe = "Safe" ":" safe-nature - safe-nature = "yes" | "no" | conditionally-safe - conditionally-safe = "if-" safe-condition - safe-condition = "user-awake" | token - - indication will allow user agents to handle retries of some safe - requests, in particular safe POST requests, in a more user-friendly - way. - - - - - - - -Masinter Informational [Page 3] - -RFC 2324 HTCPCP/1.0 1 April 1998 - - -2.2.2 New header fields - -2.2.2.1 The Accept-Additions header field - - In HTTP, the "Accept" request-header field is used to specify media - types which are acceptable for the response. However, in HTCPCP, the - response may result in additional actions on the part of the - automated pot. For this reason, HTCPCP adds a new header field, - "Accept-Additions": - - - Accept-Additions = "Accept-Additions" ":" - #( addition-range [ accept-params ] ) - - addition-type = ( "*" - | milk-type - | syrup-type - | sweetener-type - | spice-type - | alcohol-type - ) *( ";" parameter ) - milk-type = ( "Cream" | "Half-and-half" | "Whole-milk" - | "Part-Skim" | "Skim" | "Non-Dairy" ) - syrup-type = ( "Vanilla" | "Almond" | "Raspberry" - | "Chocolate" ) - alcohol-type = ( "Whisky" | "Rum" | "Kahlua" | "Aquavit" ) - -2.2.3 Omitted Header Fields - - No options were given for decaffeinated coffee. What's the point? - -2.3 HTCPCP return codes - - Normal HTTP return codes are used to indicate difficulties of the - HTCPCP server. This section identifies special interpretations and - new return codes. - -2.3.1 406 Not Acceptable - - This return code is normally interpreted as "The resource identified - by the request is only capable of generating response entities which - have content characteristics not acceptable according to the accept - headers sent in the request. In HTCPCP, this response code MAY be - returned if the operator of the coffee pot cannot comply with the - Accept-Addition request. Unless the request was a HEAD request, the - response SHOULD include an entity containing a list of available - coffee additions. - - - - -Masinter Informational [Page 4] - -RFC 2324 HTCPCP/1.0 1 April 1998 - - - In practice, most automated coffee pots cannot currently provide - additions. - -2.3.2 418 I'm a teapot - - Any attempt to brew coffee with a teapot should result in the error - code "418 I'm a teapot". The resulting entity body MAY be short and - stout. - -3. The "coffee" URI scheme - - Because coffee is international, there are international coffee URI - schemes. All coffee URL schemes are written with URL encoding of the - UTF-8 encoding of the characters that spell the word for "coffee" in - any of 29 languages, following the conventions for - internationalization in URIs [URLI18N]. - -coffee-url = coffee-scheme ":" [ "//" host ] - ["/" pot-designator ] ["?" additions-list ] - -coffee-scheme = ( "koffie" ; Afrikaans, Dutch - | "q%C3%A6hv%C3%A6" ; Azerbaijani - | "%D9%82%D9%87%D9%88%D8%A9" ; Arabic - | "akeita" ; Basque - | "koffee" ; Bengali - | "kahva" ; Bosnian - | "kafe" ; Bulgarian, Czech - | "caf%C3%E8" ; Catalan, French, Galician - | "%E5%92%96%E5%95%A1" ; Chinese - | "kava" ; Croatian - | "k%C3%A1va ; Czech - | "kaffe" ; Danish, Norwegian, Swedish - | "coffee" ; English - | "kafo" ; Esperanto - | "kohv" ; Estonian - | "kahvi" ; Finnish - | "%4Baffee" ; German - | "%CE%BA%CE%B1%CF%86%CE%AD" ; Greek - | "%E0%A4%95%E0%A5%8C%E0%A4%AB%E0%A5%80" ; Hindi - | "%E3%82%B3%E3%83%BC%E3%83%92%E3%83%BC" ; Japanese - | "%EC%BB%A4%ED%94%BC" ; Korean - | "%D0%BA%D0%BE%D1%84%D0%B5" ; Russian - | "%E0%B8%81%E0%B8%B2%E0%B9%81%E0%B8%9F" ; Thai - ) - - pot-designator = "pot-" integer ; for machines with multiple pots - additions-list = #( addition ) - - - - -Masinter Informational [Page 5] - -RFC 2324 HTCPCP/1.0 1 April 1998 - - - All alternative coffee-scheme forms are equivalent. However, the use - of coffee-scheme in various languages MAY be interpreted as an - indication of the kind of coffee produced by the coffee pot. Note - that while URL scheme names are case-independent, capitalization is - important for German and thus the initial "K" must be encoded. - -4. The "message/coffeepot" media type - - The entity body of a POST or BREW request MUST be of Content-Type - "message/coffeepot". Since most of the information for controlling - the coffee pot is conveyed by the additional headers, the content of - "message/coffeepot" contains only a coffee-message-body: - - coffee-message-body = "start" | "stop" - -5. Operational constraints - - This section lays out some of the operational issues with deployment - of HTCPCP ubiquitously. - -5.1 Timing Considerations - - A robust quality of service is required between the coffee pot user - and the coffee pot service. Coffee pots SHOULD use the Network Time - Protocol [NTP] to synchronize their clocks to a globally accurate - time standard. - - Telerobotics has been an expensive technology. However, with the - advent of the Cambridge Coffee Pot [CAM], the use of the web (rather - than SNMP) for remote system monitoring and management has been - proven. Additional coffee pot maintenance tasks might be - accomplished by remote robotics. - - Web data is normally static. Therefore to save data transmission and - time, Web browser programs store each Web page retrieved by a user on - the user's computer. Thus, if the user wants to return to that page, - it is now stored locally and does not need to be requested again from - the server. An image used for robot control or for monitoring a - changing scene is dynamic. A fresh version needs to be retrieved from - the server each time it is accessed. - -5.2 Crossing firewalls - - In most organizations HTTP traffic crosses firewalls fairly easily. - Modern coffee pots do not use fire. However, a "firewall" is useful - for protection of any source from any manner of heat, and not just - fire. Every home computer network SHOULD be protected by a firewall - from sources of heat. However, remote control of coffee pots is - - - -Masinter Informational [Page 6] - -RFC 2324 HTCPCP/1.0 1 April 1998 - - - important from outside the home. Thus, it is important that HTCPCP - cross firewalls easily. - - By basing HTCPCP on HTTP and using port 80, it will get all of HTTP's - firewall-crossing virtues. Of course, the home firewalls will require - reconfiguration or new versions in order to accommodate HTCPCP- - specific methods, headers and trailers, but such upgrades will be - easily accommodated. Most home network system administrators drink - coffee, and are willing to accommodate the needs of tunnelling - HTCPCP. - -6. System management considerations - - Coffee pot monitoring using HTTP protocols has been an early - application of the web. In the earliest instance, coffee pot - monitoring was an early (and appropriate) use of ATM networks [CAM]. - - The traditional technique [CAM] was to attach a frame-grabber to a - video camera, and feed the images to a web server. This was an - appropriate application of ATM networks. In this coffee pot - installation, the Trojan Room of Cambridge University laboratories - was used to give a web interface to monitor a common coffee pot. of - us involved in related research and, being poor, impoverished - academics, we only had one coffee filter machine between us, which - lived in the corridor just outside the Trojan Room. However, being - highly dedicated and hard-working academics, we got through a lot of - coffee, and when a fresh pot was brewed, it often didn't last long. - - This service was created as the first application to use a new RPC - mechanism designed in the Cambridge Computer Laboratory - MSRPC2. It - runs over MSNL (Multi-Service Network Layer) - a network layer - protocol designed for ATM networks. - - Coffee pots on the Internet may be managed using the Coffee Pot MIB - [CPMIB]. - -7. Security Considerations - - Anyone who gets in between me and my morning coffee should be - insecure. - - Unmoderated access to unprotected coffee pots from Internet users - might lead to several kinds of "denial of coffee service" attacks. - The improper use of filtration devices might admit trojan grounds. - Filtration is not a good virus protection method. - - - - - - -Masinter Informational [Page 7] - -RFC 2324 HTCPCP/1.0 1 April 1998 - - - Putting coffee grounds into Internet plumbing may result in clogged - plumbing, which would entail the services of an Internet Plumber - [PLUMB], who would, in turn, require an Internet Plumber's Helper. - - Access authentication will be discussed in a separate memo. - -8. Acknowledgements - - Many thanks to the many contributors to this standard, including Roy - Fielding, Mark Day, Keith Moore, Carl Uno-Manros, Michael Slavitch, - and Martin Duerst. The inspiration of the Prancing Pony, the CMU - Coke Machine, the Cambridge Coffee Pot, the Internet Toaster, and - other computer controlled remote devices have led to this valuable - creation. - -9. References - - [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T. - Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, - January 1997. - - [RFC2186] Wessels, D., and K. Claffy, "Internet Cache Protocol (ICP), - version 2," RFC 2186, September 1997 - - [CPMIB] Slavitch, M., "Definitions of Managed Objects for Drip-Type - Heated Beverage Hardware Devices using SMIv2", RFC 2325, 1 April - 1998. - - [HTSVMP] Q. Stafford-Fraser, "Hyper Text Sandwich Van Monitoring - Protocol, Version 3.2". In preparation. - - [RFC2295] Holtman, K., and A. Mutz, "Transparent Content Negotiation - in HTTP", RFC 2295, March 1998. - - [SAFE] K. Holtman. "The Safe Response Header Field", September 1997. - - [CAM] "The Trojan Room Coffee Machine", D. Gordon and M. Johnson, - University of Cambridge Computer Lab, - <http://www.cl.cam.ac.uk/coffee/coffee.html> - - [CBIO] "The Trojan Room Coffee Pot, a (non-technical) biography", Q. - Stafford-Fraser, University of Cambridge Computer Lab, - <http://www.cl.cam.ac.uk/coffee/qsf/coffee.html>. - - [RFC2235] Zakon, R., "Hobbes' Internet Timeline", FYI 32, RFC 2230, - November 1997. See also - <http://www.internode.com.au/images/toaster2.jpg> - - - - -Masinter Informational [Page 8] - -RFC 2324 HTCPCP/1.0 1 April 1998 - - - [NTP] Mills, D., "Network Time Protocol (Version 3) Specification, - Implementation and Analysis", RFC 1305, March 1992. - - [URLI18N] Masinter, L., "Using UTF8 for non-ASCII Characters in - Extended URIs" Work in Progress. - - [PLUMB] B. Metcalfe, "Internet Plumber of the Year: Jim Gettys", - Infoworld, February 2, 1998. - - [COKE] D. Nichols, "Coke machine history", C. Everhart, "Interesting - uses of networking", <http://www- - cse.ucsd.edu/users/bsy/coke.history.txt>. - -10. Author's Address - - Larry Masinter - Xerox Palo Alto Research Center - 3333 Coyote Hill Road - Palo Alto, CA 94304 - - EMail: masinter@parc.xerox.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Masinter Informational [Page 9] - -RFC 2324 HTCPCP/1.0 1 April 1998 - - -11. Full Copyright Statement - - Copyright (C) The Internet Society (1998). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - - - - - - - - - - - - - -Masinter Informational [Page 10] - diff --git a/docs/specs/rfc2388.txt b/docs/specs/rfc2388.txt deleted file mode 100644 index ffb9b6c9..00000000 --- a/docs/specs/rfc2388.txt +++ /dev/null @@ -1,507 +0,0 @@ - - - - - - -Network Working Group L. Masinter -Request for Comments: 2388 Xerox Corporation -Category: Standards Track August 1998 - - - Returning Values from Forms: multipart/form-data - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (1998). All Rights Reserved. - -1. Abstract - - This specification defines an Internet Media Type, multipart/form- - data, which can be used by a wide variety of applications and - transported by a wide variety of protocols as a way of returning a - set of values as the result of a user filling out a form. - -2. Introduction - - In many applications, it is possible for a user to be presented with - a form. The user will fill out the form, including information that - is typed, generated by user input, or included from files that the - user has selected. When the form is filled out, the data from the - form is sent from the user to the receiving application. - - The definition of MultiPart/Form-Data is derived from one of those - applications, originally set out in [RFC1867] and subsequently - incorporated into [HTML40], where forms are expressed in HTML, and in - which the form values are sent via HTTP or electronic mail. This - representation is widely implemented in numerous web browsers and web - servers. - - However, multipart/form-data can be used for forms that are presented - using representations other than HTML (spreadsheets, Portable - Document Format, etc), and for transport using other means than - electronic mail or HTTP. This document defines the representation of - form values independently of the application for which it is used. - - - - - -Masinter Standards Track [Page 1] - -RFC 2388 multipart/form-data August 1998 - - -3. Definition of multipart/form-data - - The media-type multipart/form-data follows the rules of all multipart - MIME data streams as outlined in [RFC 2046]. In forms, there are a - series of fields to be supplied by the user who fills out the form. - Each field has a name. Within a given form, the names are unique. - - "multipart/form-data" contains a series of parts. Each part is - expected to contain a content-disposition header [RFC 2183] where the - disposition type is "form-data", and where the disposition contains - an (additional) parameter of "name", where the value of that - parameter is the original field name in the form. For example, a part - might contain a header: - - Content-Disposition: form-data; name="user" - - with the value corresponding to the entry of the "user" field. - - Field names originally in non-ASCII character sets may be encoded - within the value of the "name" parameter using the standard method - described in RFC 2047. - - As with all multipart MIME types, each part has an optional - "Content-Type", which defaults to text/plain. If the contents of a - file are returned via filling out a form, then the file input is - identified as the appropriate media type, if known, or - "application/octet-stream". If multiple files are to be returned as - the result of a single form entry, they should be represented as a - "multipart/mixed" part embedded within the "multipart/form-data". - - Each part may be encoded and the "content-transfer-encoding" header - supplied if the value of that part does not conform to the default - encoding. - -4. Use of multipart/form-data - -4.1 Boundary - - As with other multipart types, a boundary is selected that does not - occur in any of the data. Each field of the form is sent, in the - order defined by the sending appliction and form, as a part of the - multipart stream. Each part identifies the INPUT name within the - original form. Each part should be labelled with an appropriate - content-type if the media type is known (e.g., inferred from the file - extension or operating system typing information) or as - "application/octet-stream". - - - - - -Masinter Standards Track [Page 2] - -RFC 2388 multipart/form-data August 1998 - - -4.2 Sets of files - - If the value of a form field is a set of files rather than a single - file, that value can be transferred together using the - "multipart/mixed" format. - -4.3 Encoding - - While the HTTP protocol can transport arbitrary binary data, the - default for mail transport is the 7BIT encoding. The value supplied - for a part may need to be encoded and the "content-transfer-encoding" - header supplied if the value does not conform to the default - encoding. [See section 5 of RFC 2046 for more details.] - -4.4 Other attributes - - Forms may request file inputs from the user; the form software may - include the file name and other file attributes, as specified in [RFC - 2184]. - - The original local file name may be supplied as well, either as a - "filename" parameter either of the "content-disposition: form-data" - header or, in the case of multiple files, in a "content-disposition: - file" header of the subpart. The sending application MAY supply a - file name; if the file name of the sender's operating system is not - in US-ASCII, the file name might be approximated, or encoded using - the method of RFC 2231. - - This is a convenience for those cases where the files supplied by the - form might contain references to each other, e.g., a TeX file and its - .sty auxiliary style description. - -4.5 Charset of text in form data - - Each part of a multipart/form-data is supposed to have a content- - type. In the case where a field element is text, the charset - parameter for the text indicates the character encoding used. - - For example, a form with a text field in which a user typed 'Joe owes - <eu>100' where <eu> is the Euro symbol might have form data returned - as: - - --AaB03x - content-disposition: form-data; name="field1" - content-type: text/plain;charset=windows-1250 - content-transfer-encoding: quoted-printable - - - - - -Masinter Standards Track [Page 3] - -RFC 2388 multipart/form-data August 1998 - - - Joe owes =80100. - --AaB03x - -5. Operability considerations - -5.1 Compression, encryption - - Some of the data in forms may be compressed or encrypted, using other - MIME mechanisms. This is a function of the application that is - generating the form-data. - -5.2 Other data encodings rather than multipart - - Various people have suggested using new mime top-level type - "aggregate", e.g., aggregate/mixed or a content-transfer-encoding of - "packet" to express indeterminate-length binary data, rather than - relying on the multipart-style boundaries. While this would be - useful, the "multipart" mechanisms are well established, simple to - implement on both the sending client and receiving server, and as - efficient as other methods of dealing with multiple combinations of - binary data. - - The multipart/form-data encoding has a high overhead and performance - impact if there are many fields with short values. However, in - practice, for the forms in use, for example, in HTML, the average - overhead is not significant. - -5.3 Remote files with third-party transfer - - In some scenarios, the user operating the form software might want to - specify a URL for remote data rather than a local file. In this case, - is there a way to allow the browser to send to the client a pointer - to the external data rather than the entire contents? This capability - could be implemented, for example, by having the client send to the - server data of type "message/external-body" with "access-type" set - to, say, "uri", and the URL of the remote data in the body of the - message. - -5.4 Non-ASCII field names - - Note that MIME headers are generally required to consist only of 7- - bit data in the US-ASCII character set. Hence field names should be - encoded according to the method in RFC 2047 if they contain - characters outside of that set. - - - - - - - -Masinter Standards Track [Page 4] - -RFC 2388 multipart/form-data August 1998 - - -5.5 Ordered fields and duplicated field names - - The relationship of the ordering of fields within a form and the - ordering of returned values within "multipart/form-data" is not - defined by this specification, nor is the handling of the case where - a form has multiple fields with the same name. While HTML-based forms - may send back results in the order received, and intermediaries - should not reorder the results, there are some systems which might - not define a natural order for form fields. - -5.6 Interoperability with web applications - - Many web applications use the "application/x-url-encoded" method for - returning data from forms. This format is quite compact, e.g.: - - name=Xavier+Xantico&verdict=Yes&colour=Blue&happy=sad&Utf%F6r=Send - - however, there is no opportunity to label the enclosed data with - content type, apply a charset, or use other encoding mechanisms. - - Many form-interpreting programs (primarly web browsers) now implement - and generate multipart/form-data, but an existing application might - need to optionally support both the application/x-url-encoded format - as well. - -5.7 Correlating form data with the original form - - This specification provides no specific mechanism by which - multipart/form-data can be associated with the form that caused it to - be transmitted. This separation is intentional; many different forms - might be used for transmitting the same data. In practice, - applications may supply a specific form processing resource (in HTML, - the ACTION attribute in a FORM tag) for each different form. - Alternatively, data about the form might be encoded in a "hidden - field" (a field which is part of the form but which has a fixed value - to be transmitted back to the form-data processor.) - -6. Security Considerations - - The data format described in this document introduces no new security - considerations outside of those introduced by the protocols that use - it and of the component elements. It is important when interpreting - content-disposition to not overwrite files in the recipients address - space inadvertently. - - User applications that request form information from users must be - careful not to cause a user to send information to the requestor or a - third party unwillingly or unwittingly. For example, a form might - - - -Masinter Standards Track [Page 5] - -RFC 2388 multipart/form-data August 1998 - - - request 'spam' information to be sent to an unintended third party, - or private information to be sent to someone that the user might not - actually intend. While this is primarily an issue for the - representation and interpretation of forms themselves, rather than - the data representation of the result of form transmission, the - transportation of private information must be done in a way that does - not expose it to unwanted prying. - - With the introduction of form-data that can reasonably send back the - content of files from user's file space, the possibility that a user - might be sent an automated script that fills out a form and then - sends the user's local file to another address arises. Thus, - additional caution is required when executing automated scripting - where form-data might include user's files. - -7. Author's Address - - Larry Masinter - Xerox Palo Alto Research Center - 3333 Coyote Hill Road - Palo Alto, CA 94304 - - Fax: +1 650 812 4333 - EMail: masinter@parc.xerox.com - - - - - - - - - - - - - - - - - - - - - - - - - - - -Masinter Standards Track [Page 6] - -RFC 2388 multipart/form-data August 1998 - - -Appendix A. Media type registration for multipart/form-data - - Media Type name: - multipart - - Media subtype name: - form-data - - Required parameters: - none - - Optional parameters: - none - - Encoding considerations: - No additional considerations other than as for other multipart - types. - - Security Considerations - Applications which receive forms and process them must be careful - not to supply data back to the requesting form processing site that - was not intended to be sent by the recipient. This is a - consideration for any application that generates a multipart/form- - data. - - The multipart/form-data type introduces no new security - considerations for recipients beyond what might occur with any of - the enclosed parts. - - - - - - - - - - - - - - - - - - - - - - - -Masinter Standards Track [Page 7] - -RFC 2388 multipart/form-data August 1998 - - -References - - [RFC 2046] Freed, N., and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part Two: Media Types", RFC 2046, - November 1996. - - [RFC 2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) - Part Three: Message Header Extensions for Non-ASCII Text", - RFC 2047, November 1996. - - [RFC 2231] Freed, N., and K. Moore, "MIME Parameter Value and Encoded - Word Extensions: Character Sets, Languages, and - Continuations", RFC 2231, November 1997. - - [RFC 1806] Troost, R., and S. Dorner, "Communicating Presentation - Information in Internet Messages: The Content-Disposition - Header", RFC 1806, June 1995. - - [RFC 1867] Nebel, E., and L. Masinter, "Form-based File Upload in - HTML", RFC 1867, November 1995. - - [RFC 2183] Troost, R., Dorner, S., and K. Moore, "Communicating - Presentation Information in Internet Messages: The - Content-Disposition Header Field", RFC 2183, August 1997. - - [RFC 2184] Freed, N., and K. Moore, "MIME Parameter Value and Encoded - Word Extensions: Character Sets, Languages, and - Continuations", RFC 2184, August 1997. - - [HTML40] D. Raggett, A. Le Hors, I. Jacobs. "HTML 4.0 - Specification", World Wide Web Consortium Technical Report - "REC-html40", December, 1997. <http://www.w3.org/TR/REC- - html40/> - - - - - - - - - - - - - - - - - - -Masinter Standards Track [Page 8] - -RFC 2388 multipart/form-data August 1998 - - -Full Copyright Statement - - Copyright (C) The Internet Society (1998). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - - - - - - - - - - - - - -Masinter Standards Track [Page 9] - diff --git a/docs/specs/rfc2518.txt b/docs/specs/rfc2518.txt deleted file mode 100644 index 81d40387..00000000 --- a/docs/specs/rfc2518.txt +++ /dev/null @@ -1,5267 +0,0 @@ - - - - - - -Network Working Group Y. Goland -Request for Comments: 2518 Microsoft -Category: Standards Track E. Whitehead - UC Irvine - A. Faizi - Netscape - S. Carter - Novell - D. Jensen - Novell - February 1999 - - - HTTP Extensions for Distributed Authoring -- WEBDAV - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (1999). All Rights Reserved. - -Abstract - - This document specifies a set of methods, headers, and content-types - ancillary to HTTP/1.1 for the management of resource properties, - creation and management of resource collections, namespace - manipulation, and resource locking (collision avoidance). - -Table of Contents - - ABSTRACT............................................................1 - 1 INTRODUCTION .....................................................5 - 2 NOTATIONAL CONVENTIONS ...........................................7 - 3 TERMINOLOGY ......................................................7 - 4 DATA MODEL FOR RESOURCE PROPERTIES ...............................8 - 4.1 The Resource Property Model ...................................8 - 4.2 Existing Metadata Proposals ...................................8 - 4.3 Properties and HTTP Headers ...................................9 - 4.4 Property Values ...............................................9 - 4.5 Property Names ...............................................10 - 4.6 Media Independent Links ......................................10 - 5 COLLECTIONS OF WEB RESOURCES ....................................11 - - - -Goland, et al. Standards Track [Page 1] - -RFC 2518 WEBDAV February 1999 - - - 5.1 HTTP URL Namespace Model .....................................11 - 5.2 Collection Resources .........................................11 - 5.3 Creation and Retrieval of Collection Resources ...............12 - 5.4 Source Resources and Output Resources ........................13 - 6 LOCKING .........................................................14 - 6.1 Exclusive Vs. Shared Locks ...................................14 - 6.2 Required Support .............................................16 - 6.3 Lock Tokens ..................................................16 - 6.4 opaquelocktoken Lock Token URI Scheme ........................16 - 6.4.1 Node Field Generation Without the IEEE 802 Address ........17 - 6.5 Lock Capability Discovery ....................................19 - 6.6 Active Lock Discovery ........................................19 - 6.7 Usage Considerations .........................................19 - 7 WRITE LOCK ......................................................20 - 7.1 Methods Restricted by Write Locks ............................20 - 7.2 Write Locks and Lock Tokens ..................................20 - 7.3 Write Locks and Properties ...................................20 - 7.4 Write Locks and Null Resources ...............................21 - 7.5 Write Locks and Collections ..................................21 - 7.6 Write Locks and the If Request Header ........................22 - 7.6.1 Example - Write Lock ......................................22 - 7.7 Write Locks and COPY/MOVE ....................................23 - 7.8 Refreshing Write Locks .......................................23 - 8 HTTP METHODS FOR DISTRIBUTED AUTHORING ..........................23 - 8.1 PROPFIND .....................................................24 - 8.1.1 Example - Retrieving Named Properties .....................25 - 8.1.2 Example - Using allprop to Retrieve All Properties ........26 - 8.1.3 Example - Using propname to Retrieve all Property Names ...29 - 8.2 PROPPATCH ....................................................31 - 8.2.1 Status Codes for use with 207 (Multi-Status) ..............31 - 8.2.2 Example - PROPPATCH .......................................32 - 8.3 MKCOL Method .................................................33 - 8.3.1 Request ...................................................33 - 8.3.2 Status Codes ..............................................33 - 8.3.3 Example - MKCOL ...........................................34 - 8.4 GET, HEAD for Collections ....................................34 - 8.5 POST for Collections .........................................35 - 8.6 DELETE .......................................................35 - 8.6.1 DELETE for Non-Collection Resources .......................35 - 8.6.2 DELETE for Collections ....................................36 - 8.7 PUT ..........................................................36 - 8.7.1 PUT for Non-Collection Resources ..........................36 - 8.7.2 PUT for Collections .......................................37 - 8.8 COPY Method ..................................................37 - 8.8.1 COPY for HTTP/1.1 resources ...............................37 - 8.8.2 COPY for Properties .......................................38 - 8.8.3 COPY for Collections ......................................38 - 8.8.4 COPY and the Overwrite Header .............................39 - - - -Goland, et al. Standards Track [Page 2] - -RFC 2518 WEBDAV February 1999 - - - 8.8.5 Status Codes ..............................................39 - 8.8.6 Example - COPY with Overwrite .............................40 - 8.8.7 Example - COPY with No Overwrite ..........................40 - 8.8.8 Example - COPY of a Collection ............................41 - 8.9 MOVE Method ..................................................42 - 8.9.1 MOVE for Properties .......................................42 - 8.9.2 MOVE for Collections ......................................42 - 8.9.3 MOVE and the Overwrite Header .............................43 - 8.9.4 Status Codes ..............................................43 - 8.9.5 Example - MOVE of a Non-Collection ........................44 - 8.9.6 Example - MOVE of a Collection ............................44 - 8.10 LOCK Method ..................................................45 - 8.10.1 Operation .................................................46 - 8.10.2 The Effect of Locks on Properties and Collections .........46 - 8.10.3 Locking Replicated Resources ..............................46 - 8.10.4 Depth and Locking .........................................46 - 8.10.5 Interaction with other Methods ............................47 - 8.10.6 Lock Compatibility Table ..................................47 - 8.10.7 Status Codes ..............................................48 - 8.10.8 Example - Simple Lock Request .............................48 - 8.10.9 Example - Refreshing a Write Lock .........................49 - 8.10.10 Example - Multi-Resource Lock Request ....................50 - 8.11 UNLOCK Method ................................................51 - 8.11.1 Example - UNLOCK ..........................................52 - 9 HTTP HEADERS FOR DISTRIBUTED AUTHORING ..........................52 - 9.1 DAV Header ...................................................52 - 9.2 Depth Header .................................................52 - 9.3 Destination Header ...........................................54 - 9.4 If Header ....................................................54 - 9.4.1 No-tag-list Production ....................................55 - 9.4.2 Tagged-list Production ....................................55 - 9.4.3 not Production ............................................56 - 9.4.4 Matching Function .........................................56 - 9.4.5 If Header and Non-DAV Compliant Proxies ...................57 - 9.5 Lock-Token Header ............................................57 - 9.6 Overwrite Header .............................................57 - 9.7 Status-URI Response Header ...................................57 - 9.8 Timeout Request Header .......................................58 - 10 STATUS CODE EXTENSIONS TO HTTP/1.1 ............................59 - 10.1 102 Processing ...............................................59 - 10.2 207 Multi-Status .............................................59 - 10.3 422 Unprocessable Entity .....................................60 - 10.4 423 Locked ...................................................60 - 10.5 424 Failed Dependency ........................................60 - 10.6 507 Insufficient Storage .....................................60 - 11 MULTI-STATUS RESPONSE .........................................60 - 12 XML ELEMENT DEFINITIONS .......................................61 - 12.1 activelock XML Element .......................................61 - - - -Goland, et al. Standards Track [Page 3] - -RFC 2518 WEBDAV February 1999 - - - 12.1.1 depth XML Element .........................................61 - 12.1.2 locktoken XML Element .....................................61 - 12.1.3 timeout XML Element .......................................61 - 12.2 collection XML Element .......................................62 - 12.3 href XML Element .............................................62 - 12.4 link XML Element .............................................62 - 12.4.1 dst XML Element ...........................................62 - 12.4.2 src XML Element ...........................................62 - 12.5 lockentry XML Element ........................................63 - 12.6 lockinfo XML Element .........................................63 - 12.7 lockscope XML Element ........................................63 - 12.7.1 exclusive XML Element .....................................63 - 12.7.2 shared XML Element ........................................63 - 12.8 locktype XML Element .........................................64 - 12.8.1 write XML Element .........................................64 - 12.9 multistatus XML Element ......................................64 - 12.9.1 response XML Element ......................................64 - 12.9.2 responsedescription XML Element ...........................65 - 12.10 owner XML Element ...........................................65 - 12.11 prop XML element ............................................66 - 12.12 propertybehavior XML element ................................66 - 12.12.1 keepalive XML element ....................................66 - 12.12.2 omit XML element .........................................67 - 12.13 propertyupdate XML element ..................................67 - 12.13.1 remove XML element .......................................67 - 12.13.2 set XML element ..........................................67 - 12.14 propfind XML Element ........................................68 - 12.14.1 allprop XML Element ......................................68 - 12.14.2 propname XML Element .....................................68 - 13 DAV PROPERTIES ................................................68 - 13.1 creationdate Property ........................................69 - 13.2 displayname Property .........................................69 - 13.3 getcontentlanguage Property ..................................69 - 13.4 getcontentlength Property ....................................69 - 13.5 getcontenttype Property ......................................70 - 13.6 getetag Property .............................................70 - 13.7 getlastmodified Property .....................................70 - 13.8 lockdiscovery Property .......................................71 - 13.8.1 Example - Retrieving the lockdiscovery Property ...........71 - 13.9 resourcetype Property ........................................72 - 13.10 source Property .............................................72 - 13.10.1 Example - A source Property ..............................72 - 13.11 supportedlock Property ......................................73 - 13.11.1 Example - Retrieving the supportedlock Property ..........73 - 14 INSTRUCTIONS FOR PROCESSING XML IN DAV ........................74 - 15 DAV COMPLIANCE CLASSES ........................................75 - 15.1 Class 1 ......................................................75 - 15.2 Class 2 ......................................................75 - - - -Goland, et al. Standards Track [Page 4] - -RFC 2518 WEBDAV February 1999 - - - 16 INTERNATIONALIZATION CONSIDERATIONS ...........................76 - 17 SECURITY CONSIDERATIONS .......................................77 - 17.1 Authentication of Clients ....................................77 - 17.2 Denial of Service ............................................78 - 17.3 Security through Obscurity ...................................78 - 17.4 Privacy Issues Connected to Locks ............................78 - 17.5 Privacy Issues Connected to Properties .......................79 - 17.6 Reduction of Security due to Source Link .....................79 - 17.7 Implications of XML External Entities ........................79 - 17.8 Risks Connected with Lock Tokens .............................80 - 18 IANA CONSIDERATIONS ...........................................80 - 19 INTELLECTUAL PROPERTY .........................................81 - 20 ACKNOWLEDGEMENTS ..............................................82 - 21 REFERENCES ....................................................82 - 21.1 Normative References .........................................82 - 21.2 Informational References .....................................83 - 22 AUTHORS' ADDRESSES ............................................84 - 23 APPENDICES ....................................................86 - 23.1 Appendix 1 - WebDAV Document Type Definition .................86 - 23.2 Appendix 2 - ISO 8601 Date and Time Profile ..................88 - 23.3 Appendix 3 - Notes on Processing XML Elements ................89 - 23.3.1 Notes on Empty XML Elements ...............................89 - 23.3.2 Notes on Illegal XML Processing ...........................89 - 23.4 Appendix 4 -- XML Namespaces for WebDAV ......................92 - 23.4.1 Introduction ..............................................92 - 23.4.2 Meaning of Qualified Names ................................92 - 24 FULL COPYRIGHT STATEMENT ......................................94 - - - -1 Introduction - - This document describes an extension to the HTTP/1.1 protocol that - allows clients to perform remote web content authoring operations. - This extension provides a coherent set of methods, headers, request - entity body formats, and response entity body formats that provide - operations for: - - Properties: The ability to create, remove, and query information - about Web pages, such as their authors, creation dates, etc. Also, - the ability to link pages of any media type to related pages. - - Collections: The ability to create sets of documents and to retrieve - a hierarchical membership listing (like a directory listing in a file - system). - - - - - - -Goland, et al. Standards Track [Page 5] - -RFC 2518 WEBDAV February 1999 - - - Locking: The ability to keep more than one person from working on a - document at the same time. This prevents the "lost update problem," - in which modifications are lost as first one author then another - writes changes without merging the other author's changes. - - Namespace Operations: The ability to instruct the server to copy and - move Web resources. - - Requirements and rationale for these operations are described in a - companion document, "Requirements for a Distributed Authoring and - Versioning Protocol for the World Wide Web" [RFC2291]. - - The sections below provide a detailed introduction to resource - properties (section 4), collections of resources (section 5), and - locking operations (section 6). These sections introduce the - abstractions manipulated by the WebDAV-specific HTTP methods - described in section 8, "HTTP Methods for Distributed Authoring". - - In HTTP/1.1, method parameter information was exclusively encoded in - HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter - information either in an Extensible Markup Language (XML) [REC-XML] - request entity body, or in an HTTP header. The use of XML to encode - method parameters was motivated by the ability to add extra XML - elements to existing structures, providing extensibility; and by - XML's ability to encode information in ISO 10646 character sets, - providing internationalization support. As a rule of thumb, - parameters are encoded in XML entity bodies when they have unbounded - length, or when they may be shown to a human user and hence require - encoding in an ISO 10646 character set. Otherwise, parameters are - encoded within HTTP headers. Section 9 describes the new HTTP - headers used with WebDAV methods. - - In addition to encoding method parameters, XML is used in WebDAV to - encode the responses from methods, providing the extensibility and - internationalization advantages of XML for method output, as well as - input. - - XML elements used in this specification are defined in section 12. - - The XML namespace extension (Appendix 4) is also used in this - specification in order to allow for new XML elements to be added - without fear of colliding with other element names. - - While the status codes provided by HTTP/1.1 are sufficient to - describe most error conditions encountered by WebDAV methods, there - are some errors that do not fall neatly into the existing categories. - New status codes developed for the WebDAV methods are defined in - section 10. Since some WebDAV methods may operate over many - - - -Goland, et al. Standards Track [Page 6] - -RFC 2518 WEBDAV February 1999 - - - resources, the Multi-Status response has been introduced to return - status information for multiple resources. The Multi-Status response - is described in section 11. - - WebDAV employs the property mechanism to store information about the - current state of the resource. For example, when a lock is taken out - on a resource, a lock information property describes the current - state of the lock. Section 13 defines the properties used within the - WebDAV specification. - - Finishing off the specification are sections on what it means to be - compliant with this specification (section 15), on - internationalization support (section 16), and on security (section - 17). - -2 Notational Conventions - - Since this document describes a set of extensions to the HTTP/1.1 - protocol, the augmented BNF used herein to describe protocol elements - is exactly the same as described in section 2.1 of [RFC2068]. Since - this augmented BNF uses the basic production rules provided in - section 2.2 of [RFC2068], these rules apply to this document as well. - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in RFC 2119 [RFC2119]. - -3 Terminology - - URI/URL - A Uniform Resource Identifier and Uniform Resource Locator, - respectively. These terms (and the distinction between them) are - defined in [RFC2396]. - - Collection - A resource that contains a set of URIs, termed member - URIs, which identify member resources and meets the requirements in - section 5 of this specification. - - Member URI - A URI which is a member of the set of URIs contained by - a collection. - - Internal Member URI - A Member URI that is immediately relative to - the URI of the collection (the definition of immediately relative is - given in section 5.2). - - Property - A name/value pair that contains descriptive information - about a resource. - - - - - -Goland, et al. Standards Track [Page 7] - -RFC 2518 WEBDAV February 1999 - - - Live Property - A property whose semantics and syntax are enforced by - the server. For example, the live "getcontentlength" property has - its value, the length of the entity returned by a GET request, - automatically calculated by the server. - - Dead Property - A property whose semantics and syntax are not - enforced by the server. The server only records the value of a dead - property; the client is responsible for maintaining the consistency - of the syntax and semantics of a dead property. - - Null Resource - A resource which responds with a 404 (Not Found) to - any HTTP/1.1 or DAV method except for PUT, MKCOL, OPTIONS and LOCK. - A NULL resource MUST NOT appear as a member of its parent collection. - -4 Data Model for Resource Properties - -4.1 The Resource Property Model - - Properties are pieces of data that describe the state of a resource. - Properties are data about data. - - Properties are used in distributed authoring environments to provide - for efficient discovery and management of resources. For example, a - 'subject' property might allow for the indexing of all resources by - their subject, and an 'author' property might allow for the discovery - of what authors have written which documents. - - The DAV property model consists of name/value pairs. The name of a - property identifies the property's syntax and semantics, and provides - an address by which to refer to its syntax and semantics. - - There are two categories of properties: "live" and "dead". A live - property has its syntax and semantics enforced by the server. Live - properties include cases where a) the value of a property is read- - only, maintained by the server, and b) the value of the property is - maintained by the client, but the server performs syntax checking on - submitted values. All instances of a given live property MUST comply - with the definition associated with that property name. A dead - property has its syntax and semantics enforced by the client; the - server merely records the value of the property verbatim. - -4.2 Existing Metadata Proposals - - Properties have long played an essential role in the maintenance of - large document repositories, and many current proposals contain some - notion of a property, or discuss web metadata more generally. These - include PICS [REC-PICS], PICS-NG, XML, Web Collections, and several - proposals on representing relationships within HTML. Work on PICS-NG - - - -Goland, et al. Standards Track [Page 8] - -RFC 2518 WEBDAV February 1999 - - - and Web Collections has been subsumed by the Resource Description - Framework (RDF) metadata activity of the World Wide Web Consortium. - RDF consists of a network-based data model and an XML representation - of that model. - - Some proposals come from a digital library perspective. These - include the Dublin Core [RFC2413] metadata set and the Warwick - Framework [WF], a container architecture for different metadata - schemas. The literature includes many examples of metadata, - including MARC [USMARC], a bibliographic metadata format, and a - technical report bibliographic format employed by the Dienst system - [RFC1807]. Additionally, the proceedings from the first IEEE Metadata - conference describe many community-specific metadata sets. - - Participants of the 1996 Metadata II Workshop in Warwick, UK [WF], - noted that "new metadata sets will develop as the networked - infrastructure matures" and "different communities will propose, - design, and be responsible for different types of metadata." These - observations can be corroborated by noting that many community- - specific sets of metadata already exist, and there is significant - motivation for the development of new forms of metadata as many - communities increasingly make their data available in digital form, - requiring a metadata format to assist data location and cataloging. - -4.3 Properties and HTTP Headers - - Properties already exist, in a limited sense, in HTTP message - headers. However, in distributed authoring environments a relatively - large number of properties are needed to describe the state of a - resource, and setting/returning them all through HTTP headers is - inefficient. Thus a mechanism is needed which allows a principal to - identify a set of properties in which the principal is interested and - to set or retrieve just those properties. - -4.4 Property Values - - The value of a property when expressed in XML MUST be well formed. - - XML has been chosen because it is a flexible, self-describing, - structured data format that supports rich schema definitions, and - because of its support for multiple character sets. XML's self- - describing nature allows any property's value to be extended by - adding new elements. Older clients will not break when they - encounter extensions because they will still have the data specified - in the original schema and will ignore elements they do not - understand. XML's support for multiple character sets allows any - human-readable property to be encoded and read in a character set - familiar to the user. XML's support for multiple human languages, - - - -Goland, et al. Standards Track [Page 9] - -RFC 2518 WEBDAV February 1999 - - - using the "xml:lang" attribute, handles cases where the same - character set is employed by multiple human languages. - -4.5 Property Names - - A property name is a universally unique identifier that is associated - with a schema that provides information about the syntax and - semantics of the property. - - Because a property's name is universally unique, clients can depend - upon consistent behavior for a particular property across multiple - resources, on the same and across different servers, so long as that - property is "live" on the resources in question, and the - implementation of the live property is faithful to its definition. - - The XML namespace mechanism, which is based on URIs [RFC2396], is - used to name properties because it prevents namespace collisions and - provides for varying degrees of administrative control. - - The property namespace is flat; that is, no hierarchy of properties - is explicitly recognized. Thus, if a property A and a property A/B - exist on a resource, there is no recognition of any relationship - between the two properties. It is expected that a separate - specification will eventually be produced which will address issues - relating to hierarchical properties. - - Finally, it is not possible to define the same property twice on a - single resource, as this would cause a collision in the resource's - property namespace. - -4.6 Media Independent Links - - Although HTML resources support links to other resources, the Web - needs more general support for links between resources of any media - type (media types are also known as MIME types, or content types). - WebDAV provides such links. A WebDAV link is a special type of - property value, formally defined in section 12.4, that allows typed - connections to be established between resources of any media type. - The property value consists of source and destination Uniform - Resource Identifiers (URIs); the property name identifies the link - type. - - - - - - - - - - -Goland, et al. Standards Track [Page 10] - -RFC 2518 WEBDAV February 1999 - - -5 Collections of Web Resources - - This section provides a description of a new type of Web resource, - the collection, and discusses its interactions with the HTTP URL - namespace. The purpose of a collection resource is to model - collection-like objects (e.g., file system directories) within a - server's namespace. - - All DAV compliant resources MUST support the HTTP URL namespace model - specified herein. - -5.1 HTTP URL Namespace Model - - The HTTP URL namespace is a hierarchical namespace where the - hierarchy is delimited with the "/" character. - - An HTTP URL namespace is said to be consistent if it meets the - following conditions: for every URL in the HTTP hierarchy there - exists a collection that contains that URL as an internal member. - The root, or top-level collection of the namespace under - consideration is exempt from the previous rule. - - Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL - namespace be consistent. However, certain WebDAV methods are - prohibited from producing results that cause namespace - inconsistencies. - - Although implicit in [RFC2068] and [RFC2396], any resource, including - collection resources, MAY be identified by more than one URI. For - example, a resource could be identified by multiple HTTP URLs. - -5.2 Collection Resources - - A collection is a resource whose state consists of at least a list of - internal member URIs and a set of properties, but which may have - additional state such as entity bodies returned by GET. An internal - member URI MUST be immediately relative to a base URI of the - collection. That is, the internal member URI is equal to a - containing collection's URI plus an additional segment for non- - collection resources, or additional segment plus trailing slash "/" - for collection resources, where segment is defined in section 3.3 of - [RFC2396]. - - Any given internal member URI MUST only belong to the collection - once, i.e., it is illegal to have multiple instances of the same URI - in a collection. Properties defined on collections behave exactly as - do properties on non-collection resources. - - - - -Goland, et al. Standards Track [Page 11] - -RFC 2518 WEBDAV February 1999 - - - For all WebDAV compliant resources A and B, identified by URIs U and - V, for which U is immediately relative to V, B MUST be a collection - that has U as an internal member URI. So, if the resource with URL - http://foo.com/bar/blah is WebDAV compliant and if the resource with - URL http://foo.com/bar/ is WebDAV compliant then the resource with - URL http://foo.com/bar/ must be a collection and must contain URL - http://foo.com/bar/blah as an internal member. - - Collection resources MAY list the URLs of non-WebDAV compliant - children in the HTTP URL namespace hierarchy as internal members but - are not required to do so. For example, if the resource with URL - http://foo.com/bar/blah is not WebDAV compliant and the URL - http://foo.com/bar/ identifies a collection then URL - http://foo.com/bar/blah may or may not be an internal member of the - collection with URL http://foo.com/bar/. - - If a WebDAV compliant resource has no WebDAV compliant children in - the HTTP URL namespace hierarchy then the WebDAV compliant resource - is not required to be a collection. - - There is a standing convention that when a collection is referred to - by its name without a trailing slash, the trailing slash is - automatically appended. Due to this, a resource may accept a URI - without a trailing "/" to point to a collection. In this case it - SHOULD return a content-location header in the response pointing to - the URI ending with the "/". For example, if a client invokes a - method on http://foo.bar/blah (no trailing slash), the resource - http://foo.bar/blah/ (trailing slash) may respond as if the operation - were invoked on it, and should return a content-location header with - http://foo.bar/blah/ in it. In general clients SHOULD use the "/" - form of collection names. - - A resource MAY be a collection but not be WebDAV compliant. That is, - the resource may comply with all the rules set out in this - specification regarding how a collection is to behave without - necessarily supporting all methods that a WebDAV compliant resource - is required to support. In such a case the resource may return the - DAV:resourcetype property with the value DAV:collection but MUST NOT - return a DAV header containing the value "1" on an OPTIONS response. - -5.3 Creation and Retrieval of Collection Resources - - This document specifies the MKCOL method to create new collection - resources, rather than using the existing HTTP/1.1 PUT or POST - method, for the following reasons: - - - - - - -Goland, et al. Standards Track [Page 12] - -RFC 2518 WEBDAV February 1999 - - - In HTTP/1.1, the PUT method is defined to store the request body at - the location specified by the Request-URI. While a description - format for a collection can readily be constructed for use with PUT, - the implications of sending such a description to the server are - undesirable. For example, if a description of a collection that - omitted some existing resources were PUT to a server, this might be - interpreted as a command to remove those members. This would extend - PUT to perform DELETE functionality, which is undesirable since it - changes the semantics of PUT, and makes it difficult to control - DELETE functionality with an access control scheme based on methods. - - While the POST method is sufficiently open-ended that a "create a - collection" POST command could be constructed, this is undesirable - because it would be difficult to separate access control for - collection creation from other uses of POST. - - The exact definition of the behavior of GET and PUT on collections is - defined later in this document. - -5.4 Source Resources and Output Resources - - For many resources, the entity returned by a GET method exactly - matches the persistent state of the resource, for example, a GIF file - stored on a disk. For this simple case, the URI at which a resource - is accessed is identical to the URI at which the source (the - persistent state) of the resource is accessed. This is also the case - for HTML source files that are not processed by the server prior to - transmission. - - However, the server can sometimes process HTML resources before they - are transmitted as a return entity body. For example, a server- - side-include directive within an HTML file might instruct a server to - replace the directive with another value, such as the current date. - In this case, what is returned by GET (HTML plus date) differs from - the persistent state of the resource (HTML plus directive). - Typically there is no way to access the HTML resource containing the - unprocessed directive. - - Sometimes the entity returned by GET is the output of a data- - producing process that is described by one or more source resources - (that may not even have a location in the URI namespace). A single - data-producing process may dynamically generate the state of a - potentially large number of output resources. An example of this is - a CGI script that describes a "finger" gateway process that maps part - of the namespace of a server into finger requests, such as - http://www.foo.bar.org/finger_gateway/user@host. - - - - - -Goland, et al. Standards Track [Page 13] - -RFC 2518 WEBDAV February 1999 - - - In the absence of distributed authoring capabilities, it is - acceptable to have no mapping of source resource(s) to the URI - namespace. In fact, preventing access to the source resource(s) has - desirable security benefits. However, if remote editing of the - source resource(s) is desired, the source resource(s) should be given - a location in the URI namespace. This source location should not be - one of the locations at which the generated output is retrievable, - since in general it is impossible for the server to differentiate - requests for source resources from requests for process output - resources. There is often a many-to-many relationship between source - resources and output resources. - - On WebDAV compliant servers the URI of the source resource(s) may be - stored in a link on the output resource with type DAV:source (see - section 13.10 for a description of the source link property). - Storing the source URIs in links on the output resources places the - burden of discovering the source on the authoring client. Note that - the value of a source link is not guaranteed to point to the correct - source. Source links may break or incorrect values may be entered. - Also note that not all servers will allow the client to set the - source link value. For example a server which generates source links - on the fly for its CGI files will most likely not allow a client to - set the source link value. - -6 Locking - - The ability to lock a resource provides a mechanism for serializing - access to that resource. Using a lock, an authoring client can - provide a reasonable guarantee that another principal will not modify - a resource while it is being edited. In this way, a client can - prevent the "lost update" problem. - - This specification allows locks to vary over two client-specified - parameters, the number of principals involved (exclusive vs. shared) - and the type of access to be granted. This document defines locking - for only one access type, write. However, the syntax is extensible, - and permits the eventual specification of locking for other access - types. - -6.1 Exclusive Vs. Shared Locks - - The most basic form of lock is an exclusive lock. This is a lock - where the access right in question is only granted to a single - principal. The need for this arbitration results from a desire to - avoid having to merge results. - - - - - - -Goland, et al. Standards Track [Page 14] - -RFC 2518 WEBDAV February 1999 - - - However, there are times when the goal of a lock is not to exclude - others from exercising an access right but rather to provide a - mechanism for principals to indicate that they intend to exercise - their access rights. Shared locks are provided for this case. A - shared lock allows multiple principals to receive a lock. Hence any - principal with appropriate access can get the lock. - - With shared locks there are two trust sets that affect a resource. - The first trust set is created by access permissions. Principals who - are trusted, for example, may have permission to write to the - resource. Among those who have access permission to write to the - resource, the set of principals who have taken out a shared lock also - must trust each other, creating a (typically) smaller trust set - within the access permission write set. - - Starting with every possible principal on the Internet, in most - situations the vast majority of these principals will not have write - access to a given resource. Of the small number who do have write - access, some principals may decide to guarantee their edits are free - from overwrite conflicts by using exclusive write locks. Others may - decide they trust their collaborators will not overwrite their work - (the potential set of collaborators being the set of principals who - have write permission) and use a shared lock, which informs their - collaborators that a principal may be working on the resource. - - The WebDAV extensions to HTTP do not need to provide all of the - communications paths necessary for principals to coordinate their - activities. When using shared locks, principals may use any out of - band communication channel to coordinate their work (e.g., face-to- - face interaction, written notes, post-it notes on the screen, - telephone conversation, Email, etc.) The intent of a shared lock is - to let collaborators know who else may be working on a resource. - - Shared locks are included because experience from web distributed - authoring systems has indicated that exclusive locks are often too - rigid. An exclusive lock is used to enforce a particular editing - process: take out an exclusive lock, read the resource, perform - edits, write the resource, release the lock. This editing process - has the problem that locks are not always properly released, for - example when a program crashes, or when a lock owner leaves without - unlocking a resource. While both timeouts and administrative action - can be used to remove an offending lock, neither mechanism may be - available when needed; the timeout may be long or the administrator - may not be available. - - - - - - - -Goland, et al. Standards Track [Page 15] - -RFC 2518 WEBDAV February 1999 - - -6.2 Required Support - - A WebDAV compliant server is not required to support locking in any - form. If the server does support locking it may choose to support - any combination of exclusive and shared locks for any access types. - - The reason for this flexibility is that locking policy strikes to the - very heart of the resource management and versioning systems employed - by various storage repositories. These repositories require control - over what sort of locking will be made available. For example, some - repositories only support shared write locks while others only - provide support for exclusive write locks while yet others use no - locking at all. As each system is sufficiently different to merit - exclusion of certain locking features, this specification leaves - locking as the sole axis of negotiation within WebDAV. - -6.3 Lock Tokens - - A lock token is a type of state token, represented as a URI, which - identifies a particular lock. A lock token is returned by every - successful LOCK operation in the lockdiscovery property in the - response body, and can also be found through lock discovery on a - resource. - - Lock token URIs MUST be unique across all resources for all time. - This uniqueness constraint allows lock tokens to be submitted across - resources and servers without fear of confusion. - - This specification provides a lock token URI scheme called - opaquelocktoken that meets the uniqueness requirements. However - resources are free to return any URI scheme so long as it meets the - uniqueness requirements. - - Having a lock token provides no special access rights. Anyone can - find out anyone else's lock token by performing lock discovery. - Locks MUST be enforced based upon whatever authentication mechanism - is used by the server, not based on the secrecy of the token values. - -6.4 opaquelocktoken Lock Token URI Scheme - - The opaquelocktoken URI scheme is designed to be unique across all - resources for all time. Due to this uniqueness quality, a client may - submit an opaque lock token in an If header on a resource other than - the one that returned it. - - All resources MUST recognize the opaquelocktoken scheme and, at - minimum, recognize that the lock token does not refer to an - outstanding lock on the resource. - - - -Goland, et al. Standards Track [Page 16] - -RFC 2518 WEBDAV February 1999 - - - In order to guarantee uniqueness across all resources for all time - the opaquelocktoken requires the use of the Universal Unique - Identifier (UUID) mechanism, as described in [ISO-11578]. - - Opaquelocktoken generators, however, have a choice of how they create - these tokens. They can either generate a new UUID for every lock - token they create or they can create a single UUID and then add - extension characters. If the second method is selected then the - program generating the extensions MUST guarantee that the same - extension will never be used twice with the associated UUID. - - OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension] ; The UUID - production is the string representation of a UUID, as defined in - [ISO-11578]. Note that white space (LWS) is not allowed between - elements of this production. - - Extension = path ; path is defined in section 3.2.1 of RFC 2068 - [RFC2068] - -6.4.1 Node Field Generation Without the IEEE 802 Address - - UUIDs, as defined in [ISO-11578], contain a "node" field that - contains one of the IEEE 802 addresses for the server machine. As - noted in section 17.8, there are several security risks associated - with exposing a machine's IEEE 802 address. This section provides an - alternate mechanism for generating the "node" field of a UUID which - does not employ an IEEE 802 address. WebDAV servers MAY use this - algorithm for creating the node field when generating UUIDs. The - text in this section is originally from an Internet-Draft by Paul - Leach and Rich Salz, who are noted here to properly attribute their - work. - - The ideal solution is to obtain a 47 bit cryptographic quality random - number, and use it as the low 47 bits of the node ID, with the most - significant bit of the first octet of the node ID set to 1. This bit - is the unicast/multicast bit, which will never be set in IEEE 802 - addresses obtained from network cards; hence, there can never be a - conflict between UUIDs generated by machines with and without network - cards. - - If a system does not have a primitive to generate cryptographic - quality random numbers, then in most systems there are usually a - fairly large number of sources of randomness available from which one - can be generated. Such sources are system specific, but often - include: - - - - - - -Goland, et al. Standards Track [Page 17] - -RFC 2518 WEBDAV February 1999 - - - - the percent of memory in use - - the size of main memory in bytes - - the amount of free main memory in bytes - - the size of the paging or swap file in bytes - - free bytes of paging or swap file - - the total size of user virtual address space in bytes - - the total available user address space bytes - - the size of boot disk drive in bytes - - the free disk space on boot drive in bytes - - the current time - - the amount of time since the system booted - - the individual sizes of files in various system directories - - the creation, last read, and modification times of files in - various system directories - - the utilization factors of various system resources (heap, etc.) - - current mouse cursor position - - current caret position - - current number of running processes, threads - - handles or IDs of the desktop window and the active window - - the value of stack pointer of the caller - - the process and thread ID of caller - - various processor architecture specific performance counters - (instructions executed, cache misses, TLB misses) - - (Note that it is precisely the above kinds of sources of randomness - that are used to seed cryptographic quality random number generators - on systems without special hardware for their construction.) - - In addition, items such as the computer's name and the name of the - operating system, while not strictly speaking random, will help - differentiate the results from those obtained by other systems. - - The exact algorithm to generate a node ID using these data is system - specific, because both the data available and the functions to obtain - them are often very system specific. However, assuming that one can - concatenate all the values from the randomness sources into a buffer, - and that a cryptographic hash function such as MD5 is available, then - any 6 bytes of the MD5 hash of the buffer, with the multicast bit - (the high bit of the first byte) set will be an appropriately random - node ID. - - Other hash functions, such as SHA-1, can also be used. The only - requirement is that the result be suitably random _ in the sense that - the outputs from a set uniformly distributed inputs are themselves - uniformly distributed, and that a single bit change in the input can - be expected to cause half of the output bits to change. - - - - - -Goland, et al. Standards Track [Page 18] - -RFC 2518 WEBDAV February 1999 - - -6.5 Lock Capability Discovery - - Since server lock support is optional, a client trying to lock a - resource on a server can either try the lock and hope for the best, - or perform some form of discovery to determine what lock capabilities - the server supports. This is known as lock capability discovery. - Lock capability discovery differs from discovery of supported access - control types, since there may be access control types without - corresponding lock types. A client can determine what lock types the - server supports by retrieving the supportedlock property. - - Any DAV compliant resource that supports the LOCK method MUST support - the supportedlock property. - -6.6 Active Lock Discovery - - If another principal locks a resource that a principal wishes to - access, it is useful for the second principal to be able to find out - who the first principal is. For this purpose the lockdiscovery - property is provided. This property lists all outstanding locks, - describes their type, and where available, provides their lock token. - - Any DAV compliant resource that supports the LOCK method MUST support - the lockdiscovery property. - -6.7 Usage Considerations - - Although the locking mechanisms specified here provide some help in - preventing lost updates, they cannot guarantee that updates will - never be lost. Consider the following scenario: - - Two clients A and B are interested in editing the resource ' - index.html'. Client A is an HTTP client rather than a WebDAV client, - and so does not know how to perform locking. - Client A doesn't lock the document, but does a GET and begins - editing. - Client B does LOCK, performs a GET and begins editing. - Client B finishes editing, performs a PUT, then an UNLOCK. - Client A performs a PUT, overwriting and losing all of B's changes. - - There are several reasons why the WebDAV protocol itself cannot - prevent this situation. First, it cannot force all clients to use - locking because it must be compatible with HTTP clients that do not - comprehend locking. Second, it cannot require servers to support - locking because of the variety of repository implementations, some of - which rely on reservations and merging rather than on locking. - Finally, being stateless, it cannot enforce a sequence of operations - like LOCK / GET / PUT / UNLOCK. - - - -Goland, et al. Standards Track [Page 19] - -RFC 2518 WEBDAV February 1999 - - - WebDAV servers that support locking can reduce the likelihood that - clients will accidentally overwrite each other's changes by requiring - clients to lock resources before modifying them. Such servers would - effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying - resources. - - WebDAV clients can be good citizens by using a lock / retrieve / - write /unlock sequence of operations (at least by default) whenever - they interact with a WebDAV server that supports locking. - - HTTP 1.1 clients can be good citizens, avoiding overwriting other - clients' changes, by using entity tags in If-Match headers with any - requests that would modify resources. - - Information managers may attempt to prevent overwrites by - implementing client-side procedures requiring locking before - modifying WebDAV resources. - -7 Write Lock - - This section describes the semantics specific to the write lock type. - The write lock is a specific instance of a lock type, and is the only - lock type described in this specification. - -7.1 Methods Restricted by Write Locks - - A write lock MUST prevent a principal without the lock from - successfully executing a PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE, - DELETE, or MKCOL on the locked resource. All other current methods, - GET in particular, function independently of the lock. - - Note, however, that as new methods are created it will be necessary - to specify how they interact with a write lock. - -7.2 Write Locks and Lock Tokens - - A successful request for an exclusive or shared write lock MUST - result in the generation of a unique lock token associated with the - requesting principal. Thus if five principals have a shared write - lock on the same resource there will be five lock tokens, one for - each principal. - -7.3 Write Locks and Properties - - While those without a write lock may not alter a property on a - resource it is still possible for the values of live properties to - change, even while locked, due to the requirements of their schemas. - - - - -Goland, et al. Standards Track [Page 20] - -RFC 2518 WEBDAV February 1999 - - - Only dead properties and live properties defined to respect locks are - guaranteed not to change while write locked. - -7.4 Write Locks and Null Resources - - It is possible to assert a write lock on a null resource in order to - lock the name. - - A write locked null resource, referred to as a lock-null resource, - MUST respond with a 404 (Not Found) or 405 (Method Not Allowed) to - any HTTP/1.1 or DAV methods except for PUT, MKCOL, OPTIONS, PROPFIND, - LOCK, and UNLOCK. A lock-null resource MUST appear as a member of - its parent collection. Additionally the lock-null resource MUST have - defined on it all mandatory DAV properties. Most of these - properties, such as all the get* properties, will have no value as a - lock-null resource does not support the GET method. Lock-Null - resources MUST have defined values for lockdiscovery and - supportedlock properties. - - Until a method such as PUT or MKCOL is successfully executed on the - lock-null resource the resource MUST stay in the lock-null state. - However, once a PUT or MKCOL is successfully executed on a lock-null - resource the resource ceases to be in the lock-null state. - - If the resource is unlocked, for any reason, without a PUT, MKCOL, or - similar method having been successfully executed upon it then the - resource MUST return to the null state. - -7.5 Write Locks and Collections - - A write lock on a collection, whether created by a "Depth: 0" or - "Depth: infinity" lock request, prevents the addition or removal of - member URIs of the collection by non-lock owners. As a consequence, - when a principal issues a PUT or POST request to create a new - resource under a URI which needs to be an internal member of a write - locked collection to maintain HTTP namespace consistency, or issues a - DELETE to remove a resource which has a URI which is an existing - internal member URI of a write locked collection, this request MUST - fail if the principal does not have a write lock on the collection. - - However, if a write lock request is issued to a collection containing - member URIs identifying resources that are currently locked in a - manner which conflicts with the write lock, the request MUST fail - with a 423 (Locked) status code. - - If a lock owner causes the URI of a resource to be added as an - internal member URI of a locked collection then the new resource MUST - be automatically added to the lock. This is the only mechanism that - - - -Goland, et al. Standards Track [Page 21] - -RFC 2518 WEBDAV February 1999 - - - allows a resource to be added to a write lock. Thus, for example, if - the collection /a/b/ is write locked and the resource /c is moved to - /a/b/c then resource /a/b/c will be added to the write lock. - -7.6 Write Locks and the If Request Header - - If a user agent is not required to have knowledge about a lock when - requesting an operation on a locked resource, the following scenario - might occur. Program A, run by User A, takes out a write lock on a - resource. Program B, also run by User A, has no knowledge of the - lock taken out by Program A, yet performs a PUT to the locked - resource. In this scenario, the PUT succeeds because locks are - associated with a principal, not a program, and thus program B, - because it is acting with principal A's credential, is allowed to - perform the PUT. However, had program B known about the lock, it - would not have overwritten the resource, preferring instead to - present a dialog box describing the conflict to the user. Due to - this scenario, a mechanism is needed to prevent different programs - from accidentally ignoring locks taken out by other programs with the - same authorization. - - In order to prevent these collisions a lock token MUST be submitted - by an authorized principal in the If header for all locked resources - that a method may interact with or the method MUST fail. For - example, if a resource is to be moved and both the source and - destination are locked then two lock tokens must be submitted, one - for the source and the other for the destination. - -7.6.1 Example - Write Lock - - >>Request - - COPY /~fielding/index.html HTTP/1.1 - Host: www.ics.uci.edu - Destination: http://www.ics.uci.edu/users/f/fielding/index.html - If: <http://www.ics.uci.edu/users/f/fielding/index.html> - (<opaquelocktoken:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>) - - >>Response - - HTTP/1.1 204 No Content - - In this example, even though both the source and destination are - locked, only one lock token must be submitted, for the lock on the - destination. This is because the source resource is not modified by - a COPY, and hence unaffected by the write lock. In this example, user - agent authentication has previously occurred via a mechanism outside - the scope of the HTTP protocol, in the underlying transport layer. - - - -Goland, et al. Standards Track [Page 22] - -RFC 2518 WEBDAV February 1999 - - -7.7 Write Locks and COPY/MOVE - - A COPY method invocation MUST NOT duplicate any write locks active on - the source. However, as previously noted, if the COPY copies the - resource into a collection that is locked with "Depth: infinity", - then the resource will be added to the lock. - - A successful MOVE request on a write locked resource MUST NOT move - the write lock with the resource. However, the resource is subject to - being added to an existing lock at the destination, as specified in - section 7.5. For example, if the MOVE makes the resource a child of a - collection that is locked with "Depth: infinity", then the resource - will be added to that collection's lock. Additionally, if a resource - locked with "Depth: infinity" is moved to a destination that is - within the scope of the same lock (e.g., within the namespace tree - covered by the lock), the moved resource will again be a added to the - lock. In both these examples, as specified in section 7.6, an If - header must be submitted containing a lock token for both the source - and destination. - -7.8 Refreshing Write Locks - - A client MUST NOT submit the same write lock request twice. Note - that a client is always aware it is resubmitting the same lock - request because it must include the lock token in the If header in - order to make the request for a resource that is already locked. - - However, a client may submit a LOCK method with an If header but - without a body. This form of LOCK MUST only be used to "refresh" a - lock. Meaning, at minimum, that any timers associated with the lock - MUST be re-set. - - A server may return a Timeout header with a lock refresh that is - different than the Timeout header returned when the lock was - originally requested. Additionally clients may submit Timeout - headers of arbitrary value with their lock refresh requests. - Servers, as always, may ignore Timeout headers submitted by the - client. - - If an error is received in response to a refresh LOCK request the - client SHOULD assume that the lock was not refreshed. - -8 HTTP Methods for Distributed Authoring - - The following new HTTP methods use XML as a request and response - format. All DAV compliant clients and resources MUST use XML parsers - that are compliant with [REC-XML]. All XML used in either requests - or responses MUST be, at minimum, well formed. If a server receives - - - -Goland, et al. Standards Track [Page 23] - -RFC 2518 WEBDAV February 1999 - - - ill-formed XML in a request it MUST reject the entire request with a - 400 (Bad Request). If a client receives ill-formed XML in a response - then it MUST NOT assume anything about the outcome of the executed - method and SHOULD treat the server as malfunctioning. - -8.1 PROPFIND - - The PROPFIND method retrieves properties defined on the resource - identified by the Request-URI, if the resource does not have any - internal members, or on the resource identified by the Request-URI - and potentially its member resources, if the resource is a collection - that has internal member URIs. All DAV compliant resources MUST - support the PROPFIND method and the propfind XML element (section - 12.14) along with all XML elements defined for use with that element. - - A client may submit a Depth header with a value of "0", "1", or - "infinity" with a PROPFIND on a collection resource with internal - member URIs. DAV compliant servers MUST support the "0", "1" and - "infinity" behaviors. By default, the PROPFIND method without a Depth - header MUST act as if a "Depth: infinity" header was included. - - A client may submit a propfind XML element in the body of the request - method describing what information is being requested. It is - possible to request particular property values, all property values, - or a list of the names of the resource's properties. A client may - choose not to submit a request body. An empty PROPFIND request body - MUST be treated as a request for the names and values of all - properties. - - All servers MUST support returning a response of content type - text/xml or application/xml that contains a multistatus XML element - that describes the results of the attempts to retrieve the various - properties. - - If there is an error retrieving a property then a proper error result - MUST be included in the response. A request to retrieve the value of - a property which does not exist is an error and MUST be noted, if the - response uses a multistatus XML element, with a response XML element - which contains a 404 (Not Found) status value. - - Consequently, the multistatus XML element for a collection resource - with member URIs MUST include a response XML element for each member - URI of the collection, to whatever depth was requested. Each response - XML element MUST contain an href XML element that gives the URI of - the resource on which the properties in the prop XML element are - defined. Results for a PROPFIND on a collection resource with - internal member URIs are returned as a flat list whose order of - entries is not significant. - - - -Goland, et al. Standards Track [Page 24] - -RFC 2518 WEBDAV February 1999 - - - In the case of allprop and propname, if a principal does not have the - right to know whether a particular property exists then the property - should be silently excluded from the response. - - The results of this method SHOULD NOT be cached. - -8.1.1 Example - Retrieving Named Properties - - >>Request - - PROPFIND /file HTTP/1.1 - Host: www.foo.bar - Content-type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:propfind xmlns:D="DAV:"> - <D:prop xmlns:R="http://www.foo.bar/boxschema/"> - <R:bigbox/> - <R:author/> - <R:DingALing/> - <R:Random/> - </D:prop> - </D:propfind> - - >>Response - - HTTP/1.1 207 Multi-Status - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:"> - <D:response> - <D:href>http://www.foo.bar/file</D:href> - <D:propstat> - <D:prop xmlns:R="http://www.foo.bar/boxschema/"> - <R:bigbox> - <R:BoxType>Box type A</R:BoxType> - </R:bigbox> - <R:author> - <R:Name>J.J. Johnson</R:Name> - </R:author> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - <D:propstat> - <D:prop><R:DingALing/><R:Random/></D:prop> - - - -Goland, et al. Standards Track [Page 25] - -RFC 2518 WEBDAV February 1999 - - - <D:status>HTTP/1.1 403 Forbidden</D:status> - <D:responsedescription> The user does not have access to - the DingALing property. - </D:responsedescription> - </D:propstat> - </D:response> - <D:responsedescription> There has been an access violation error. - </D:responsedescription> - </D:multistatus> - - In this example, PROPFIND is executed on a non-collection resource - http://www.foo.bar/file. The propfind XML element specifies the name - of four properties whose values are being requested. In this case - only two properties were returned, since the principal issuing the - request did not have sufficient access rights to see the third and - fourth properties. - -8.1.2 Example - Using allprop to Retrieve All Properties - - >>Request - - PROPFIND /container/ HTTP/1.1 - Host: www.foo.bar - Depth: 1 - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:propfind xmlns:D="DAV:"> - <D:allprop/> - </D:propfind> - - >>Response - - HTTP/1.1 207 Multi-Status - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:"> - <D:response> - <D:href>http://www.foo.bar/container/</D:href> - <D:propstat> - <D:prop xmlns:R="http://www.foo.bar/boxschema/"> - <R:bigbox> - <R:BoxType>Box type A</R:BoxType> - </R:bigbox> - <R:author> - - - -Goland, et al. Standards Track [Page 26] - -RFC 2518 WEBDAV February 1999 - - - <R:Name>Hadrian</R:Name> - </R:author> - <D:creationdate> - 1997-12-01T17:42:21-08:00 - </D:creationdate> - <D:displayname> - Example collection - </D:displayname> - <D:resourcetype><D:collection/></D:resourcetype> - <D:supportedlock> - <D:lockentry> - <D:lockscope><D:exclusive/></D:lockscope> - <D:locktype><D:write/></D:locktype> - </D:lockentry> - <D:lockentry> - <D:lockscope><D:shared/></D:lockscope> - <D:locktype><D:write/></D:locktype> - </D:lockentry> - </D:supportedlock> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - <D:response> - <D:href>http://www.foo.bar/container/front.html</D:href> - <D:propstat> - <D:prop xmlns:R="http://www.foo.bar/boxschema/"> - <R:bigbox> - <R:BoxType>Box type B</R:BoxType> - </R:bigbox> - <D:creationdate> - 1997-12-01T18:27:21-08:00 - </D:creationdate> - <D:displayname> - Example HTML resource - </D:displayname> - <D:getcontentlength> - 4525 - </D:getcontentlength> - <D:getcontenttype> - text/html - </D:getcontenttype> - <D:getetag> - zzyzx - </D:getetag> - <D:getlastmodified> - Monday, 12-Jan-98 09:25:56 GMT - </D:getlastmodified> - - - -Goland, et al. Standards Track [Page 27] - -RFC 2518 WEBDAV February 1999 - - - <D:resourcetype/> - <D:supportedlock> - <D:lockentry> - <D:lockscope><D:exclusive/></D:lockscope> - <D:locktype><D:write/></D:locktype> - </D:lockentry> - <D:lockentry> - <D:lockscope><D:shared/></D:lockscope> - <D:locktype><D:write/></D:locktype> - </D:lockentry> - </D:supportedlock> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - </D:multistatus> - - In this example, PROPFIND was invoked on the resource - http://www.foo.bar/container/ with a Depth header of 1, meaning the - request applies to the resource and its children, and a propfind XML - element containing the allprop XML element, meaning the request - should return the name and value of all properties defined on each - resource. - - The resource http://www.foo.bar/container/ has six properties defined - on it: - - http://www.foo.bar/boxschema/bigbox, - http://www.foo.bar/boxschema/author, DAV:creationdate, - DAV:displayname, DAV:resourcetype, and DAV:supportedlock. - - The last four properties are WebDAV-specific, defined in section 13. - Since GET is not supported on this resource, the get* properties - (e.g., getcontentlength) are not defined on this resource. The DAV- - specific properties assert that "container" was created on December - 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT - (creationdate), has a name of "Example collection" (displayname), a - collection resource type (resourcetype), and supports exclusive write - and shared write locks (supportedlock). - - The resource http://www.foo.bar/container/front.html has nine - properties defined on it: - - http://www.foo.bar/boxschema/bigbox (another instance of the "bigbox" - property type), DAV:creationdate, DAV:displayname, - DAV:getcontentlength, DAV:getcontenttype, DAV:getetag, - DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock. - - - - -Goland, et al. Standards Track [Page 28] - -RFC 2518 WEBDAV February 1999 - - - The DAV-specific properties assert that "front.html" was created on - December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT - (creationdate), has a name of "Example HTML resource" (displayname), - a content length of 4525 bytes (getcontentlength), a MIME type of - "text/html" (getcontenttype), an entity tag of "zzyzx" (getetag), was - last modified on Monday, January 12, 1998, at 09:25:56 GMT - (getlastmodified), has an empty resource type, meaning that it is not - a collection (resourcetype), and supports both exclusive write and - shared write locks (supportedlock). - -8.1.3 Example - Using propname to Retrieve all Property Names - - >>Request - - PROPFIND /container/ HTTP/1.1 - Host: www.foo.bar - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <propfind xmlns="DAV:"> - <propname/> - </propfind> - - >>Response - - HTTP/1.1 207 Multi-Status - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <multistatus xmlns="DAV:"> - <response> - <href>http://www.foo.bar/container/</href> - <propstat> - <prop xmlns:R="http://www.foo.bar/boxschema/"> - <R:bigbox/> - <R:author/> - <creationdate/> - <displayname/> - <resourcetype/> - <supportedlock/> - </prop> - <status>HTTP/1.1 200 OK</status> - </propstat> - </response> - <response> - <href>http://www.foo.bar/container/front.html</href> - - - -Goland, et al. Standards Track [Page 29] - -RFC 2518 WEBDAV February 1999 - - - <propstat> - <prop xmlns:R="http://www.foo.bar/boxschema/"> - <R:bigbox/> - <creationdate/> - <displayname/> - <getcontentlength/> - <getcontenttype/> - <getetag/> - <getlastmodified/> - <resourcetype/> - <supportedlock/> - </prop> - <status>HTTP/1.1 200 OK</status> - </propstat> - </response> - </multistatus> - - - In this example, PROPFIND is invoked on the collection resource - http://www.foo.bar/container/, with a propfind XML element containing - the propname XML element, meaning the name of all properties should - be returned. Since no Depth header is present, it assumes its - default value of "infinity", meaning the name of the properties on - the collection and all its progeny should be returned. - - Consistent with the previous example, resource - http://www.foo.bar/container/ has six properties defined on it, - http://www.foo.bar/boxschema/bigbox, - http://www.foo.bar/boxschema/author, DAV:creationdate, - DAV:displayname, DAV:resourcetype, and DAV:supportedlock. - - The resource http://www.foo.bar/container/index.html, a member of the - "container" collection, has nine properties defined on it, - http://www.foo.bar/boxschema/bigbox, DAV:creationdate, - DAV:displayname, DAV:getcontentlength, DAV:getcontenttype, - DAV:getetag, DAV:getlastmodified, DAV:resourcetype, and - DAV:supportedlock. - - This example also demonstrates the use of XML namespace scoping, and - the default namespace. Since the "xmlns" attribute does not contain - an explicit "shorthand name" (prefix) letter, the namespace applies - by default to all enclosed elements. Hence, all elements which do - not explicitly state the namespace to which they belong are members - of the "DAV:" namespace schema. - - - - - - - -Goland, et al. Standards Track [Page 30] - -RFC 2518 WEBDAV February 1999 - - -8.2 PROPPATCH - - The PROPPATCH method processes instructions specified in the request - body to set and/or remove properties defined on the resource - identified by the Request-URI. - - All DAV compliant resources MUST support the PROPPATCH method and - MUST process instructions that are specified using the - propertyupdate, set, and remove XML elements of the DAV schema. - Execution of the directives in this method is, of course, subject to - access control constraints. DAV compliant resources SHOULD support - the setting of arbitrary dead properties. - - The request message body of a PROPPATCH method MUST contain the - propertyupdate XML element. Instruction processing MUST occur in the - order instructions are received (i.e., from top to bottom). - Instructions MUST either all be executed or none executed. Thus if - any error occurs during processing all executed instructions MUST be - undone and a proper error result returned. Instruction processing - details can be found in the definition of the set and remove - instructions in section 12.13. - -8.2.1 Status Codes for use with 207 (Multi-Status) - - The following are examples of response codes one would expect to be - used in a 207 (Multi-Status) response for this method. Note, - however, that unless explicitly prohibited any 2/3/4/5xx series - response code may be used in a 207 (Multi-Status) response. - - 200 (OK) - The command succeeded. As there can be a mixture of sets - and removes in a body, a 201 (Created) seems inappropriate. - - 403 (Forbidden) - The client, for reasons the server chooses not to - specify, cannot alter one of the properties. - - 409 (Conflict) - The client has provided a value whose semantics are - not appropriate for the property. This includes trying to set read- - only properties. - - 423 (Locked) - The specified resource is locked and the client either - is not a lock owner or the lock type requires a lock token to be - submitted and the client did not submit it. - - 507 (Insufficient Storage) - The server did not have sufficient space - to record the property. - - - - - - -Goland, et al. Standards Track [Page 31] - -RFC 2518 WEBDAV February 1999 - - -8.2.2 Example - PROPPATCH - - >>Request - - PROPPATCH /bar.html HTTP/1.1 - Host: www.foo.com - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:propertyupdate xmlns:D="DAV:" - xmlns:Z="http://www.w3.com/standards/z39.50/"> - <D:set> - <D:prop> - <Z:authors> - <Z:Author>Jim Whitehead</Z:Author> - <Z:Author>Roy Fielding</Z:Author> - </Z:authors> - </D:prop> - </D:set> - <D:remove> - <D:prop><Z:Copyright-Owner/></D:prop> - </D:remove> - </D:propertyupdate> - - >>Response - - HTTP/1.1 207 Multi-Status - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:" - xmlns:Z="http://www.w3.com/standards/z39.50"> - <D:response> - <D:href>http://www.foo.com/bar.html</D:href> - <D:propstat> - <D:prop><Z:Authors/></D:prop> - <D:status>HTTP/1.1 424 Failed Dependency</D:status> - </D:propstat> - <D:propstat> - <D:prop><Z:Copyright-Owner/></D:prop> - <D:status>HTTP/1.1 409 Conflict</D:status> - </D:propstat> - <D:responsedescription> Copyright Owner can not be deleted or - altered.</D:responsedescription> - </D:response> - </D:multistatus> - - - -Goland, et al. Standards Track [Page 32] - -RFC 2518 WEBDAV February 1999 - - - In this example, the client requests the server to set the value of - the http://www.w3.com/standards/z39.50/Authors property, and to - remove the property http://www.w3.com/standards/z39.50/Copyright- - Owner. Since the Copyright-Owner property could not be removed, no - property modifications occur. The 424 (Failed Dependency) status - code for the Authors property indicates this action would have - succeeded if it were not for the conflict with removing the - Copyright-Owner property. - -8.3 MKCOL Method - - The MKCOL method is used to create a new collection. All DAV - compliant resources MUST support the MKCOL method. - -8.3.1 Request - - MKCOL creates a new collection resource at the location specified by - the Request-URI. If the resource identified by the Request-URI is - non-null then the MKCOL MUST fail. During MKCOL processing, a server - MUST make the Request-URI a member of its parent collection, unless - the Request-URI is "/". If no such ancestor exists, the method MUST - fail. When the MKCOL operation creates a new collection resource, - all ancestors MUST already exist, or the method MUST fail with a 409 - (Conflict) status code. For example, if a request to create - collection /a/b/c/d/ is made, and neither /a/b/ nor /a/b/c/ exists, - the request must fail. - - When MKCOL is invoked without a request body, the newly created - collection SHOULD have no members. - - A MKCOL request message may contain a message body. The behavior of - a MKCOL request when the body is present is limited to creating - collections, members of a collection, bodies of members and - properties on the collections or members. If the server receives a - MKCOL request entity type it does not support or understand it MUST - respond with a 415 (Unsupported Media Type) status code. The exact - behavior of MKCOL for various request media types is undefined in - this document, and will be specified in separate documents. - -8.3.2 Status Codes - - Responses from a MKCOL request MUST NOT be cached as MKCOL has non- - idempotent semantics. - - 201 (Created) - The collection or structured resource was created in - its entirety. - - - - - -Goland, et al. Standards Track [Page 33] - -RFC 2518 WEBDAV February 1999 - - - 403 (Forbidden) - This indicates at least one of two conditions: 1) - the server does not allow the creation of collections at the given - location in its namespace, or 2) the parent collection of the - Request-URI exists but cannot accept members. - - 405 (Method Not Allowed) - MKCOL can only be executed on a - deleted/non-existent resource. - - 409 (Conflict) - A collection cannot be made at the Request-URI until - one or more intermediate collections have been created. - - 415 (Unsupported Media Type)- The server does not support the request - type of the body. - - 507 (Insufficient Storage) - The resource does not have sufficient - space to record the state of the resource after the execution of this - method. - -8.3.3 Example - MKCOL - - This example creates a collection called /webdisc/xfiles/ on the - server www.server.org. - - >>Request - - MKCOL /webdisc/xfiles/ HTTP/1.1 - Host: www.server.org - - >>Response - - HTTP/1.1 201 Created - -8.4 GET, HEAD for Collections - - The semantics of GET are unchanged when applied to a collection, - since GET is defined as, "retrieve whatever information (in the form - of an entity) is identified by the Request-URI" [RFC2068]. GET when - applied to a collection may return the contents of an "index.html" - resource, a human-readable view of the contents of the collection, or - something else altogether. Hence it is possible that the result of a - GET on a collection will bear no correlation to the membership of the - collection. - - Similarly, since the definition of HEAD is a GET without a response - message body, the semantics of HEAD are unmodified when applied to - collection resources. - - - - - -Goland, et al. Standards Track [Page 34] - -RFC 2518 WEBDAV February 1999 - - -8.5 POST for Collections - - Since by definition the actual function performed by POST is - determined by the server and often depends on the particular - resource, the behavior of POST when applied to collections cannot be - meaningfully modified because it is largely undefined. Thus the - semantics of POST are unmodified when applied to a collection. - -8.6 DELETE - - 8.6.1 DELETE for Non-Collection Resources - - If the DELETE method is issued to a non-collection resource whose - URIs are an internal member of one or more collections, then during - DELETE processing a server MUST remove any URI for the resource - identified by the Request-URI from collections which contain it as a - member. - -8.6.2 DELETE for Collections - - The DELETE method on a collection MUST act as if a "Depth: infinity" - header was used on it. A client MUST NOT submit a Depth header with - a DELETE on a collection with any value but infinity. - - DELETE instructs that the collection specified in the Request-URI and - all resources identified by its internal member URIs are to be - deleted. - - If any resource identified by a member URI cannot be deleted then all - of the member's ancestors MUST NOT be deleted, so as to maintain - namespace consistency. - - Any headers included with DELETE MUST be applied in processing every - resource to be deleted. - - When the DELETE method has completed processing it MUST result in a - consistent namespace. - - If an error occurs with a resource other than the resource identified - in the Request-URI then the response MUST be a 207 (Multi-Status). - 424 (Failed Dependency) errors SHOULD NOT be in the 207 (Multi- - Status). They can be safely left out because the client will know - that the ancestors of a resource could not be deleted when the client - receives an error for the ancestor's progeny. Additionally 204 (No - Content) errors SHOULD NOT be returned in the 207 (Multi-Status). - The reason for this prohibition is that 204 (No Content) is the - default success code. - - - - -Goland, et al. Standards Track [Page 35] - -RFC 2518 WEBDAV February 1999 - - -8.6.2.1 Example - DELETE - - >>Request - - DELETE /container/ HTTP/1.1 - Host: www.foo.bar - - >>Response - - HTTP/1.1 207 Multi-Status - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <d:multistatus xmlns:d="DAV:"> - <d:response> - <d:href>http://www.foo.bar/container/resource3</d:href> - <d:status>HTTP/1.1 423 Locked</d:status> - </d:response> - </d:multistatus> - - In this example the attempt to delete - http://www.foo.bar/container/resource3 failed because it is locked, - and no lock token was submitted with the request. Consequently, the - attempt to delete http://www.foo.bar/container/ also failed. Thus the - client knows that the attempt to delete http://www.foo.bar/container/ - must have also failed since the parent can not be deleted unless its - child has also been deleted. Even though a Depth header has not been - included, a depth of infinity is assumed because the method is on a - collection. - -8.7 PUT - -8.7.1 PUT for Non-Collection Resources - - A PUT performed on an existing resource replaces the GET response - entity of the resource. Properties defined on the resource may be - recomputed during PUT processing but are not otherwise affected. For - example, if a server recognizes the content type of the request body, - it may be able to automatically extract information that could be - profitably exposed as properties. - - A PUT that would result in the creation of a resource without an - appropriately scoped parent collection MUST fail with a 409 - (Conflict). - - - - - - -Goland, et al. Standards Track [Page 36] - -RFC 2518 WEBDAV February 1999 - - -8.7.2 PUT for Collections - - As defined in the HTTP/1.1 specification [RFC2068], the "PUT method - requests that the enclosed entity be stored under the supplied - Request-URI." Since submission of an entity representing a - collection would implicitly encode creation and deletion of - resources, this specification intentionally does not define a - transmission format for creating a collection using PUT. Instead, - the MKCOL method is defined to create collections. - - When the PUT operation creates a new non-collection resource all - ancestors MUST already exist. If all ancestors do not exist, the - method MUST fail with a 409 (Conflict) status code. For example, if - resource /a/b/c/d.html is to be created and /a/b/c/ does not exist, - then the request must fail. - -8.8 COPY Method - - The COPY method creates a duplicate of the source resource, - identified by the Request-URI, in the destination resource, - identified by the URI in the Destination header. The Destination - header MUST be present. The exact behavior of the COPY method - depends on the type of the source resource. - - All WebDAV compliant resources MUST support the COPY method. - However, support for the COPY method does not guarantee the ability - to copy a resource. For example, separate programs may control - resources on the same server. As a result, it may not be possible to - copy a resource to a location that appears to be on the same server. - -8.8.1 COPY for HTTP/1.1 resources - - When the source resource is not a collection the result of the COPY - method is the creation of a new resource at the destination whose - state and behavior match that of the source resource as closely as - possible. After a successful COPY invocation, all properties on the - source resource MUST be duplicated on the destination resource, - subject to modifying headers and XML elements, following the - definition for copying properties. Since the environment at the - destination may be different than at the source due to factors - outside the scope of control of the server, such as the absence of - resources required for correct operation, it may not be possible to - completely duplicate the behavior of the resource at the destination. - Subsequent alterations to the destination resource will not modify - the source resource. Subsequent alterations to the source resource - will not modify the destination resource. - - - - - -Goland, et al. Standards Track [Page 37] - -RFC 2518 WEBDAV February 1999 - - -8.8.2. COPY for Properties - - The following section defines how properties on a resource are - handled during a COPY operation. - - Live properties SHOULD be duplicated as identically behaving live - properties at the destination resource. If a property cannot be - copied live, then its value MUST be duplicated, octet-for-octet, in - an identically named, dead property on the destination resource - subject to the effects of the propertybehavior XML element. - - The propertybehavior XML element can specify that properties are - copied on best effort, that all live properties must be successfully - copied or the method must fail, or that a specified list of live - properties must be successfully copied or the method must fail. The - propertybehavior XML element is defined in section 12.12. - -8.8.3 COPY for Collections - - The COPY method on a collection without a Depth header MUST act as if - a Depth header with value "infinity" was included. A client may - submit a Depth header on a COPY on a collection with a value of "0" - or "infinity". DAV compliant servers MUST support the "0" and - "infinity" Depth header behaviors. - - A COPY of depth infinity instructs that the collection resource - identified by the Request-URI is to be copied to the location - identified by the URI in the Destination header, and all its internal - member resources are to be copied to a location relative to it, - recursively through all levels of the collection hierarchy. - - A COPY of "Depth: 0" only instructs that the collection and its - properties but not resources identified by its internal member URIs, - are to be copied. - - Any headers included with a COPY MUST be applied in processing every - resource to be copied with the exception of the Destination header. - - The Destination header only specifies the destination URI for the - Request-URI. When applied to members of the collection identified by - the Request-URI the value of Destination is to be modified to reflect - the current location in the hierarchy. So, if the Request- URI is - /a/ with Host header value http://fun.com/ and the Destination is - http://fun.com/b/ then when http://fun.com/a/c/d is processed it must - use a Destination of http://fun.com/b/c/d. - - - - - - -Goland, et al. Standards Track [Page 38] - -RFC 2518 WEBDAV February 1999 - - - When the COPY method has completed processing it MUST have created a - consistent namespace at the destination (see section 5.1 for the - definition of namespace consistency). However, if an error occurs - while copying an internal collection, the server MUST NOT copy any - resources identified by members of this collection (i.e., the server - must skip this subtree), as this would create an inconsistent - namespace. After detecting an error, the COPY operation SHOULD try to - finish as much of the original copy operation as possible (i.e., the - server should still attempt to copy other subtrees and their members, - that are not descendents of an error-causing collection). So, for - example, if an infinite depth copy operation is performed on - collection /a/, which contains collections /a/b/ and /a/c/, and an - error occurs copying /a/b/, an attempt should still be made to copy - /a/c/. Similarly, after encountering an error copying a non- - collection resource as part of an infinite depth copy, the server - SHOULD try to finish as much of the original copy operation as - possible. - - If an error in executing the COPY method occurs with a resource other - than the resource identified in the Request-URI then the response - MUST be a 207 (Multi-Status). - - The 424 (Failed Dependency) status code SHOULD NOT be returned in the - 207 (Multi-Status) response from a COPY method. These responses can - be safely omitted because the client will know that the progeny of a - resource could not be copied when the client receives an error for - the parent. Additionally 201 (Created)/204 (No Content) status codes - SHOULD NOT be returned as values in 207 (Multi-Status) responses from - COPY methods. They, too, can be safely omitted because they are the - default success codes. - -8.8.4 COPY and the Overwrite Header - - If a resource exists at the destination and the Overwrite header is - "T" then prior to performing the copy the server MUST perform a - DELETE with "Depth: infinity" on the destination resource. If the - Overwrite header is set to "F" then the operation will fail. - -8.8.5 Status Codes - - 201 (Created) - The source resource was successfully copied. The - copy operation resulted in the creation of a new resource. - - 204 (No Content) - The source resource was successfully copied to a - pre-existing destination resource. - - 403 (Forbidden) _ The source and destination URIs are the same. - - - - -Goland, et al. Standards Track [Page 39] - -RFC 2518 WEBDAV February 1999 - - - 409 (Conflict) _ A resource cannot be created at the destination - until one or more intermediate collections have been created. - - 412 (Precondition Failed) - The server was unable to maintain the - liveness of the properties listed in the propertybehavior XML element - or the Overwrite header is "F" and the state of the destination - resource is non-null. - - 423 (Locked) - The destination resource was locked. - - 502 (Bad Gateway) - This may occur when the destination is on another - server and the destination server refuses to accept the resource. - - 507 (Insufficient Storage) - The destination resource does not have - sufficient space to record the state of the resource after the - execution of this method. - -8.8.6 Example - COPY with Overwrite - - This example shows resource - http://www.ics.uci.edu/~fielding/index.html being copied to the - location http://www.ics.uci.edu/users/f/fielding/index.html. The 204 - (No Content) status code indicates the existing resource at the - destination was overwritten. - - >>Request - - COPY /~fielding/index.html HTTP/1.1 - Host: www.ics.uci.edu - Destination: http://www.ics.uci.edu/users/f/fielding/index.html - - >>Response - - HTTP/1.1 204 No Content - -8.8.7 Example - COPY with No Overwrite - - The following example shows the same copy operation being performed, - but with the Overwrite header set to "F." A response of 412 - (Precondition Failed) is returned because the destination resource - has a non-null state. - - >>Request - - COPY /~fielding/index.html HTTP/1.1 - Host: www.ics.uci.edu - Destination: http://www.ics.uci.edu/users/f/fielding/index.html - Overwrite: F - - - -Goland, et al. Standards Track [Page 40] - -RFC 2518 WEBDAV February 1999 - - - >>Response - - HTTP/1.1 412 Precondition Failed - -8.8.8 Example - COPY of a Collection - - >>Request - - COPY /container/ HTTP/1.1 - Host: www.foo.bar - Destination: http://www.foo.bar/othercontainer/ - Depth: infinity - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <d:propertybehavior xmlns:d="DAV:"> - <d:keepalive>*</d:keepalive> - </d:propertybehavior> - - >>Response - - HTTP/1.1 207 Multi-Status - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <d:multistatus xmlns:d="DAV:"> - <d:response> - <d:href>http://www.foo.bar/othercontainer/R2/</d:href> - <d:status>HTTP/1.1 412 Precondition Failed</d:status> - </d:response> - </d:multistatus> - - The Depth header is unnecessary as the default behavior of COPY on a - collection is to act as if a "Depth: infinity" header had been - submitted. In this example most of the resources, along with the - collection, were copied successfully. However the collection R2 - failed, most likely due to a problem with maintaining the liveness of - properties (this is specified by the propertybehavior XML element). - Because there was an error copying R2, none of R2's members were - copied. However no errors were listed for those members due to the - error minimization rules given in section 8.8.3. - - - - - - - - -Goland, et al. Standards Track [Page 41] - -RFC 2518 WEBDAV February 1999 - - -8.9 MOVE Method - - The MOVE operation on a non-collection resource is the logical - equivalent of a copy (COPY), followed by consistency maintenance - processing, followed by a delete of the source, where all three - actions are performed atomically. The consistency maintenance step - allows the server to perform updates caused by the move, such as - updating all URIs other than the Request-URI which identify the - source resource, to point to the new destination resource. - Consequently, the Destination header MUST be present on all MOVE - methods and MUST follow all COPY requirements for the COPY part of - the MOVE method. All DAV compliant resources MUST support the MOVE - method. However, support for the MOVE method does not guarantee the - ability to move a resource to a particular destination. - - For example, separate programs may actually control different sets of - resources on the same server. Therefore, it may not be possible to - move a resource within a namespace that appears to belong to the same - server. - - If a resource exists at the destination, the destination resource - will be DELETEd as a side-effect of the MOVE operation, subject to - the restrictions of the Overwrite header. - -8.9.1 MOVE for Properties - - The behavior of properties on a MOVE, including the effects of the - propertybehavior XML element, MUST be the same as specified in - section 8.8.2. - -8.9.2 MOVE for Collections - - A MOVE with "Depth: infinity" instructs that the collection - identified by the Request-URI be moved to the URI specified in the - Destination header, and all resources identified by its internal - member URIs are to be moved to locations relative to it, recursively - through all levels of the collection hierarchy. - - The MOVE method on a collection MUST act as if a "Depth: infinity" - header was used on it. A client MUST NOT submit a Depth header on a - MOVE on a collection with any value but "infinity". - - Any headers included with MOVE MUST be applied in processing every - resource to be moved with the exception of the Destination header. - - The behavior of the Destination header is the same as given for COPY - on collections. - - - - -Goland, et al. Standards Track [Page 42] - -RFC 2518 WEBDAV February 1999 - - - When the MOVE method has completed processing it MUST have created a - consistent namespace at both the source and destination (see section - 5.1 for the definition of namespace consistency). However, if an - error occurs while moving an internal collection, the server MUST NOT - move any resources identified by members of the failed collection - (i.e., the server must skip the error-causing subtree), as this would - create an inconsistent namespace. In this case, after detecting the - error, the move operation SHOULD try to finish as much of the - original move as possible (i.e., the server should still attempt to - move other subtrees and the resources identified by their members, - that are not descendents of an error-causing collection). So, for - example, if an infinite depth move is performed on collection /a/, - which contains collections /a/b/ and /a/c/, and an error occurs - moving /a/b/, an attempt should still be made to try moving /a/c/. - Similarly, after encountering an error moving a non-collection - resource as part of an infinite depth move, the server SHOULD try to - finish as much of the original move operation as possible. - - If an error occurs with a resource other than the resource identified - in the Request-URI then the response MUST be a 207 (Multi-Status). - - The 424 (Failed Dependency) status code SHOULD NOT be returned in the - 207 (Multi-Status) response from a MOVE method. These errors can be - safely omitted because the client will know that the progeny of a - resource could not be moved when the client receives an error for the - parent. Additionally 201 (Created)/204 (No Content) responses SHOULD - NOT be returned as values in 207 (Multi-Status) responses from a - MOVE. These responses can be safely omitted because they are the - default success codes. - -8.9.3 MOVE and the Overwrite Header - - If a resource exists at the destination and the Overwrite header is - "T" then prior to performing the move the server MUST perform a - DELETE with "Depth: infinity" on the destination resource. If the - Overwrite header is set to "F" then the operation will fail. - -8.9.4 Status Codes - - 201 (Created) - The source resource was successfully moved, and a new - resource was created at the destination. - - 204 (No Content) - The source resource was successfully moved to a - pre-existing destination resource. - - 403 (Forbidden) _ The source and destination URIs are the same. - - - - - -Goland, et al. Standards Track [Page 43] - -RFC 2518 WEBDAV February 1999 - - - 409 (Conflict) _ A resource cannot be created at the destination - until one or more intermediate collections have been created. - - 412 (Precondition Failed) - The server was unable to maintain the - liveness of the properties listed in the propertybehavior XML element - or the Overwrite header is "F" and the state of the destination - resource is non-null. - - 423 (Locked) - The source or the destination resource was locked. - - 502 (Bad Gateway) - This may occur when the destination is on another - server and the destination server refuses to accept the resource. - -8.9.5 Example - MOVE of a Non-Collection - - This example shows resource - http://www.ics.uci.edu/~fielding/index.html being moved to the - location http://www.ics.uci.edu/users/f/fielding/index.html. The - contents of the destination resource would have been overwritten if - the destination resource had been non-null. In this case, since - there was nothing at the destination resource, the response code is - 201 (Created). - - >>Request - - MOVE /~fielding/index.html HTTP/1.1 - Host: www.ics.uci.edu - Destination: http://www.ics.uci.edu/users/f/fielding/index.html - - >>Response - - HTTP/1.1 201 Created - Location: http://www.ics.uci.edu/users/f/fielding/index.html - - -8.9.6 Example - MOVE of a Collection - - >>Request - - MOVE /container/ HTTP/1.1 - Host: www.foo.bar - Destination: http://www.foo.bar/othercontainer/ - Overwrite: F - If: (<opaquelocktoken:fe184f2e-6eec-41d0-c765-01adc56e6bb4>) - (<opaquelocktoken:e454f3f3-acdc-452a-56c7-00a5c91e4b77>) - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - - - -Goland, et al. Standards Track [Page 44] - -RFC 2518 WEBDAV February 1999 - - - <?xml version="1.0" encoding="utf-8" ?> - <d:propertybehavior xmlns:d='DAV:'> - <d:keepalive>*</d:keepalive> - </d:propertybehavior> - - >>Response - - HTTP/1.1 207 Multi-Status - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <d:multistatus xmlns:d='DAV:'> - <d:response> - <d:href>http://www.foo.bar/othercontainer/C2/</d:href> - <d:status>HTTP/1.1 423 Locked</d:status> - </d:response> - </d:multistatus> - - In this example the client has submitted a number of lock tokens with - the request. A lock token will need to be submitted for every - resource, both source and destination, anywhere in the scope of the - method, that is locked. In this case the proper lock token was not - submitted for the destination http://www.foo.bar/othercontainer/C2/. - This means that the resource /container/C2/ could not be moved. - Because there was an error copying /container/C2/, none of - /container/C2's members were copied. However no errors were listed - for those members due to the error minimization rules given in - section 8.8.3. User agent authentication has previously occurred via - a mechanism outside the scope of the HTTP protocol, in an underlying - transport layer. - -8.10 LOCK Method - - The following sections describe the LOCK method, which is used to - take out a lock of any access type. These sections on the LOCK - method describe only those semantics that are specific to the LOCK - method and are independent of the access type of the lock being - requested. - - Any resource which supports the LOCK method MUST, at minimum, support - the XML request and response formats defined herein. - - - - - - - - - -Goland, et al. Standards Track [Page 45] - -RFC 2518 WEBDAV February 1999 - - -8.10.1 Operation - - A LOCK method invocation creates the lock specified by the lockinfo - XML element on the Request-URI. Lock method requests SHOULD have a - XML request body which contains an owner XML element for this lock - request, unless this is a refresh request. The LOCK request may have - a Timeout header. - - Clients MUST assume that locks may arbitrarily disappear at any time, - regardless of the value given in the Timeout header. The Timeout - header only indicates the behavior of the server if "extraordinary" - circumstances do not occur. For example, an administrator may remove - a lock at any time or the system may crash in such a way that it - loses the record of the lock's existence. The response MUST contain - the value of the lockdiscovery property in a prop XML element. - - In order to indicate the lock token associated with a newly created - lock, a Lock-Token response header MUST be included in the response - for every successful LOCK request for a new lock. Note that the - Lock-Token header would not be returned in the response for a - successful refresh LOCK request because a new lock was not created. - -8.10.2 The Effect of Locks on Properties and Collections - - The scope of a lock is the entire state of the resource, including - its body and associated properties. As a result, a lock on a - resource MUST also lock the resource's properties. - - For collections, a lock also affects the ability to add or remove - members. The nature of the effect depends upon the type of access - control involved. - -8.10.3 Locking Replicated Resources - - A resource may be made available through more than one URI. However - locks apply to resources, not URIs. Therefore a LOCK request on a - resource MUST NOT succeed if can not be honored by all the URIs - through which the resource is addressable. - -8.10.4 Depth and Locking - - The Depth header may be used with the LOCK method. Values other than - 0 or infinity MUST NOT be used with the Depth header on a LOCK - method. All resources that support the LOCK method MUST support the - Depth header. - - A Depth header of value 0 means to just lock the resource specified - by the Request-URI. - - - -Goland, et al. Standards Track [Page 46] - -RFC 2518 WEBDAV February 1999 - - - If the Depth header is set to infinity then the resource specified in - the Request-URI along with all its internal members, all the way down - the hierarchy, are to be locked. A successful result MUST return a - single lock token which represents all the resources that have been - locked. If an UNLOCK is successfully executed on this token, all - associated resources are unlocked. If the lock cannot be granted to - all resources, a 409 (Conflict) status code MUST be returned with a - response entity body containing a multistatus XML element describing - which resource(s) prevented the lock from being granted. Hence, - partial success is not an option. Either the entire hierarchy is - locked or no resources are locked. - - If no Depth header is submitted on a LOCK request then the request - MUST act as if a "Depth:infinity" had been submitted. - -8.10.5 Interaction with other Methods - - The interaction of a LOCK with various methods is dependent upon the - lock type. However, independent of lock type, a successful DELETE of - a resource MUST cause all of its locks to be removed. - -8.10.6 Lock Compatibility Table - - The table below describes the behavior that occurs when a lock - request is made on a resource. - - Current lock state/ | Shared Lock | Exclusive - Lock request | | Lock - =====================+=================+============== - None | True | True - ---------------------+-----------------+-------------- - Shared Lock | True | False - ---------------------+-----------------+-------------- - Exclusive Lock | False | False* - ------------------------------------------------------ - - Legend: True = lock may be granted. False = lock MUST NOT be - granted. *=It is illegal for a principal to request the same lock - twice. - - The current lock state of a resource is given in the leftmost column, - and lock requests are listed in the first row. The intersection of a - row and column gives the result of a lock request. For example, if a - shared lock is held on a resource, and an exclusive lock is - requested, the table entry is "false", indicating the lock must not - be granted. - - - - - -Goland, et al. Standards Track [Page 47] - -RFC 2518 WEBDAV February 1999 - - -8.10.7 Status Codes - - 200 (OK) - The lock request succeeded and the value of the - lockdiscovery property is included in the body. - - 412 (Precondition Failed) - The included lock token was not - enforceable on this resource or the server could not satisfy the - request in the lockinfo XML element. - - 423 (Locked) - The resource is locked, so the method has been - rejected. - -8.10.8 Example - Simple Lock Request - - >>Request - - LOCK /workspace/webdav/proposal.doc HTTP/1.1 - Host: webdav.sb.aol.com - Timeout: Infinite, Second-4100000000 - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - Authorization: Digest username="ejw", - realm="ejw@webdav.sb.aol.com", nonce="...", - uri="/workspace/webdav/proposal.doc", - response="...", opaque="..." - - <?xml version="1.0" encoding="utf-8" ?> - <D:lockinfo xmlns:D='DAV:'> - <D:lockscope><D:exclusive/></D:lockscope> - <D:locktype><D:write/></D:locktype> - <D:owner> - <D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href> - </D:owner> - </D:lockinfo> - - >>Response - - HTTP/1.1 200 OK - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:prop xmlns:D="DAV:"> - <D:lockdiscovery> - <D:activelock> - <D:locktype><D:write/></D:locktype> - <D:lockscope><D:exclusive/></D:lockscope> - <D:depth>Infinity</D:depth> - - - -Goland, et al. Standards Track [Page 48] - -RFC 2518 WEBDAV February 1999 - - - <D:owner> - <D:href> - http://www.ics.uci.edu/~ejw/contact.html - </D:href> - </D:owner> - <D:timeout>Second-604800</D:timeout> - <D:locktoken> - <D:href> - opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 - </D:href> - </D:locktoken> - </D:activelock> - </D:lockdiscovery> - </D:prop> - - This example shows the successful creation of an exclusive write lock - on resource http://webdav.sb.aol.com/workspace/webdav/proposal.doc. - The resource http://www.ics.uci.edu/~ejw/contact.html contains - contact information for the owner of the lock. The server has an - activity-based timeout policy in place on this resource, which causes - the lock to automatically be removed after 1 week (604800 seconds). - Note that the nonce, response, and opaque fields have not been - calculated in the Authorization request header. - -8.10.9 Example - Refreshing a Write Lock - - >>Request - - LOCK /workspace/webdav/proposal.doc HTTP/1.1 - Host: webdav.sb.aol.com - Timeout: Infinite, Second-4100000000 - If: (<opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>) - Authorization: Digest username="ejw", - realm="ejw@webdav.sb.aol.com", nonce="...", - uri="/workspace/webdav/proposal.doc", - response="...", opaque="..." - - >>Response - - HTTP/1.1 200 OK - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:prop xmlns:D="DAV:"> - <D:lockdiscovery> - <D:activelock> - <D:locktype><D:write/></D:locktype> - - - -Goland, et al. Standards Track [Page 49] - -RFC 2518 WEBDAV February 1999 - - - <D:lockscope><D:exclusive/></D:lockscope> - <D:depth>Infinity</D:depth> - <D:owner> - <D:href> - http://www.ics.uci.edu/~ejw/contact.html - </D:href> - </D:owner> - <D:timeout>Second-604800</D:timeout> - <D:locktoken> - <D:href> - opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4 - </D:href> - </D:locktoken> - </D:activelock> - </D:lockdiscovery> - </D:prop> - - This request would refresh the lock, resetting any time outs. Notice - that the client asked for an infinite time out but the server choose - to ignore the request. In this example, the nonce, response, and - opaque fields have not been calculated in the Authorization request - header. - -8.10.10 Example - Multi-Resource Lock Request - - >>Request - - LOCK /webdav/ HTTP/1.1 - Host: webdav.sb.aol.com - Timeout: Infinite, Second-4100000000 - Depth: infinity - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - Authorization: Digest username="ejw", - realm="ejw@webdav.sb.aol.com", nonce="...", - uri="/workspace/webdav/proposal.doc", - response="...", opaque="..." - - <?xml version="1.0" encoding="utf-8" ?> - <D:lockinfo xmlns:D="DAV:"> - <D:locktype><D:write/></D:locktype> - <D:lockscope><D:exclusive/></D:lockscope> - <D:owner> - <D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href> - </D:owner> - </D:lockinfo> - - >>Response - - - -Goland, et al. Standards Track [Page 50] - -RFC 2518 WEBDAV February 1999 - - - HTTP/1.1 207 Multi-Status - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:"> - <D:response> - <D:href>http://webdav.sb.aol.com/webdav/secret</D:href> - <D:status>HTTP/1.1 403 Forbidden</D:status> - </D:response> - <D:response> - <D:href>http://webdav.sb.aol.com/webdav/</D:href> - <D:propstat> - <D:prop><D:lockdiscovery/></D:prop> - <D:status>HTTP/1.1 424 Failed Dependency</D:status> - </D:propstat> - </D:response> - </D:multistatus> - - This example shows a request for an exclusive write lock on a - collection and all its children. In this request, the client has - specified that it desires an infinite length lock, if available, - otherwise a timeout of 4.1 billion seconds, if available. The request - entity body contains the contact information for the principal taking - out the lock, in this case a web page URL. - - The error is a 403 (Forbidden) response on the resource - http://webdav.sb.aol.com/webdav/secret. Because this resource could - not be locked, none of the resources were locked. Note also that the - lockdiscovery property for the Request-URI has been included as - required. In this example the lockdiscovery property is empty which - means that there are no outstanding locks on the resource. - - In this example, the nonce, response, and opaque fields have not been - calculated in the Authorization request header. - -8.11 UNLOCK Method - - The UNLOCK method removes the lock identified by the lock token in - the Lock-Token request header from the Request-URI, and all other - resources included in the lock. If all resources which have been - locked under the submitted lock token can not be unlocked then the - UNLOCK request MUST fail. - - Any DAV compliant resource which supports the LOCK method MUST - support the UNLOCK method. - - - - - -Goland, et al. Standards Track [Page 51] - -RFC 2518 WEBDAV February 1999 - - -8.11.1 Example - UNLOCK - - >>Request - - UNLOCK /workspace/webdav/info.doc HTTP/1.1 - Host: webdav.sb.aol.com - Lock-Token: <opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7> - Authorization: Digest username="ejw", - realm="ejw@webdav.sb.aol.com", nonce="...", - uri="/workspace/webdav/proposal.doc", - response="...", opaque="..." - - >>Response - - HTTP/1.1 204 No Content - - In this example, the lock identified by the lock token - "opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is - successfully removed from the resource - http://webdav.sb.aol.com/workspace/webdav/info.doc. If this lock - included more than just one resource, the lock is removed from all - resources included in the lock. The 204 (No Content) status code is - used instead of 200 (OK) because there is no response entity body. - - In this example, the nonce, response, and opaque fields have not been - calculated in the Authorization request header. - -9 HTTP Headers for Distributed Authoring - -9.1 DAV Header - - DAV = "DAV" ":" "1" ["," "2"] ["," 1#extend] - - This header indicates that the resource supports the DAV schema and - protocol as specified. All DAV compliant resources MUST return the - DAV header on all OPTIONS responses. - - The value is a list of all compliance classes that the resource - supports. Note that above a comma has already been added to the 2. - This is because a resource can not be level 2 compliant unless it is - also level 1 compliant. Please refer to section 15 for more details. - In general, however, support for one compliance class does not entail - support for any other. - -9.2 Depth Header - - Depth = "Depth" ":" ("0" | "1" | "infinity") - - - - -Goland, et al. Standards Track [Page 52] - -RFC 2518 WEBDAV February 1999 - - - The Depth header is used with methods executed on resources which - could potentially have internal members to indicate whether the - method is to be applied only to the resource ("Depth: 0"), to the - resource and its immediate children, ("Depth: 1"), or the resource - and all its progeny ("Depth: infinity"). - - The Depth header is only supported if a method's definition - explicitly provides for such support. - - The following rules are the default behavior for any method that - supports the Depth header. A method may override these defaults by - defining different behavior in its definition. - - Methods which support the Depth header may choose not to support all - of the header's values and may define, on a case by case basis, the - behavior of the method if a Depth header is not present. For example, - the MOVE method only supports "Depth: infinity" and if a Depth header - is not present will act as if a "Depth: infinity" header had been - applied. - - Clients MUST NOT rely upon methods executing on members of their - hierarchies in any particular order or on the execution being atomic - unless the particular method explicitly provides such guarantees. - - Upon execution, a method with a Depth header will perform as much of - its assigned task as possible and then return a response specifying - what it was able to accomplish and what it failed to do. - - So, for example, an attempt to COPY a hierarchy may result in some of - the members being copied and some not. - - Any headers on a method that has a defined interaction with the Depth - header MUST be applied to all resources in the scope of the method - except where alternative behavior is explicitly defined. For example, - an If-Match header will have its value applied against every resource - in the method's scope and will cause the method to fail if the header - fails to match. - - If a resource, source or destination, within the scope of the method - with a Depth header is locked in such a way as to prevent the - successful execution of the method, then the lock token for that - resource MUST be submitted with the request in the If request header. - - The Depth header only specifies the behavior of the method with - regards to internal children. If a resource does not have internal - children then the Depth header MUST be ignored. - - - - - -Goland, et al. Standards Track [Page 53] - -RFC 2518 WEBDAV February 1999 - - - Please note, however, that it is always an error to submit a value - for the Depth header that is not allowed by the method's definition. - Thus submitting a "Depth: 1" on a COPY, even if the resource does not - have internal members, will result in a 400 (Bad Request). The method - should fail not because the resource doesn't have internal members, - but because of the illegal value in the header. - -9.3 Destination Header - - Destination = "Destination" ":" absoluteURI - - The Destination header specifies the URI which identifies a - destination resource for methods such as COPY and MOVE, which take - two URIs as parameters. Note that the absoluteURI production is - defined in [RFC2396]. - -9.4 If Header - - If = "If" ":" ( 1*No-tag-list | 1*Tagged-list) - No-tag-list = List - Tagged-list = Resource 1*List - Resource = Coded-URL - List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")" - State-token = Coded-URL - Coded-URL = "<" absoluteURI ">" - - The If header is intended to have similar functionality to the If- - Match header defined in section 14.25 of [RFC2068]. However the If - header is intended for use with any URI which represents state - information, referred to as a state token, about a resource as well - as ETags. A typical example of a state token is a lock token, and - lock tokens are the only state tokens defined in this specification. - - All DAV compliant resources MUST honor the If header. - - The If header's purpose is to describe a series of state lists. If - the state of the resource to which the header is applied does not - match any of the specified state lists then the request MUST fail - with a 412 (Precondition Failed). If one of the described state - lists matches the state of the resource then the request may succeed. - - Note that the absoluteURI production is defined in [RFC2396]. - - - - - - - - - -Goland, et al. Standards Track [Page 54] - -RFC 2518 WEBDAV February 1999 - - -9.4.1 No-tag-list Production - - The No-tag-list production describes a series of state tokens and - ETags. If multiple No-tag-list productions are used then one only - needs to match the state of the resource for the method to be allowed - to continue. - - If a method, due to the presence of a Depth or Destination header, is - applied to multiple resources then the No-tag-list production MUST be - applied to each resource the method is applied to. - -9.4.1.1 Example - No-tag-list If Header - - If: (<locktoken:a-write-lock-token> ["I am an ETag"]) (["I am another - ETag"]) - - The previous header would require that any resources within the scope - of the method must either be locked with the specified lock token and - in the state identified by the "I am an ETag" ETag or in the state - identified by the second ETag "I am another ETag". To put the matter - more plainly one can think of the previous If header as being in the - form (or (and <locktoken:a-write-lock-token> ["I am an ETag"]) (and - ["I am another ETag"])). - -9.4.2 Tagged-list Production - - The tagged-list production scopes a list production. That is, it - specifies that the lists following the resource specification only - apply to the specified resource. The scope of the resource - production begins with the list production immediately following the - resource production and ends with the next resource production, if - any. - - When the If header is applied to a particular resource, the Tagged- - list productions MUST be searched to determine if any of the listed - resources match the operand resource(s) for the current method. If - none of the resource productions match the current resource then the - header MUST be ignored. If one of the resource productions does - match the name of the resource under consideration then the list - productions following the resource production MUST be applied to the - resource in the manner specified in the previous section. - - The same URI MUST NOT appear more than once in a resource production - in an If header. - - - - - - - -Goland, et al. Standards Track [Page 55] - -RFC 2518 WEBDAV February 1999 - - -9.4.2.1 Example - Tagged List If header - - COPY /resource1 HTTP/1.1 - Host: www.foo.bar - Destination: http://www.foo.bar/resource2 - If: <http://www.foo.bar/resource1> (<locktoken:a-write-lock-token> - [W/"A weak ETag"]) (["strong ETag"]) - <http://www.bar.bar/random>(["another strong ETag"]) - - In this example http://www.foo.bar/resource1 is being copied to - http://www.foo.bar/resource2. When the method is first applied to - http://www.foo.bar/resource1, resource1 must be in the state - specified by "(<locktoken:a-write-lock-token> [W/"A weak ETag"]) - (["strong ETag"])", that is, it either must be locked with a lock - token of "locktoken:a-write-lock-token" and have a weak entity tag - W/"A weak ETag" or it must have a strong entity tag "strong ETag". - - That is the only success condition since the resource - http://www.bar.bar/random never has the method applied to it (the - only other resource listed in the If header) and - http://www.foo.bar/resource2 is not listed in the If header. - -9.4.3 not Production - - Every state token or ETag is either current, and hence describes the - state of a resource, or is not current, and does not describe the - state of a resource. The boolean operation of matching a state token - or ETag to the current state of a resource thus resolves to a true or - false value. The not production is used to reverse that value. The - scope of the not production is the state-token or entity-tag - immediately following it. - - If: (Not <locktoken:write1> <locktoken:write2>) - - When submitted with a request, this If header requires that all - operand resources must not be locked with locktoken:write1 and must - be locked with locktoken:write2. - -9.4.4 Matching Function - - When performing If header processing, the definition of a matching - state token or entity tag is as follows. - - Matching entity tag: Where the entity tag matches an entity tag - associated with that resource. - - Matching state token: Where there is an exact match between the state - token in the If header and any state token on the resource. - - - -Goland, et al. Standards Track [Page 56] - -RFC 2518 WEBDAV February 1999 - - -9.4.5 If Header and Non-DAV Compliant Proxies - - Non-DAV compliant proxies will not honor the If header, since they - will not understand the If header, and HTTP requires non-understood - headers to be ignored. When communicating with HTTP/1.1 proxies, the - "Cache-Control: no-cache" request header MUST be used so as to - prevent the proxy from improperly trying to service the request from - its cache. When dealing with HTTP/1.0 proxies the "Pragma: no-cache" - request header MUST be used for the same reason. - -9.5 Lock-Token Header - - Lock-Token = "Lock-Token" ":" Coded-URL - - The Lock-Token request header is used with the UNLOCK method to - identify the lock to be removed. The lock token in the Lock-Token - request header MUST identify a lock that contains the resource - identified by Request-URI as a member. - - The Lock-Token response header is used with the LOCK method to - indicate the lock token created as a result of a successful LOCK - request to create a new lock. - -9.6 Overwrite Header - - Overwrite = "Overwrite" ":" ("T" | "F") - - The Overwrite header specifies whether the server should overwrite - the state of a non-null destination resource during a COPY or MOVE. - A value of "F" states that the server must not perform the COPY or - MOVE operation if the state of the destination resource is non-null. - If the overwrite header is not included in a COPY or MOVE request - then the resource MUST treat the request as if it has an overwrite - header of value "T". While the Overwrite header appears to duplicate - the functionality of the If-Match: * header of HTTP/1.1, If-Match - applies only to the Request-URI, and not to the Destination of a COPY - or MOVE. - - If a COPY or MOVE is not performed due to the value of the Overwrite - header, the method MUST fail with a 412 (Precondition Failed) status - code. - - All DAV compliant resources MUST support the Overwrite header. - -9.7 Status-URI Response Header - - The Status-URI response header may be used with the 102 (Processing) - status code to inform the client as to the status of a method. - - - -Goland, et al. Standards Track [Page 57] - -RFC 2518 WEBDAV February 1999 - - - Status-URI = "Status-URI" ":" *(Status-Code Coded-URL) ; Status-Code - is defined in 6.1.1 of [RFC2068] - - The URIs listed in the header are source resources which have been - affected by the outstanding method. The status code indicates the - resolution of the method on the identified resource. So, for - example, if a MOVE method on a collection is outstanding and a 102 - (Processing) response with a Status-URI response header is returned, - the included URIs will indicate resources that have had move - attempted on them and what the result was. - -9.8 Timeout Request Header - - TimeOut = "Timeout" ":" 1#TimeType - TimeType = ("Second-" DAVTimeOutVal | "Infinite" | Other) - DAVTimeOutVal = 1*digit - Other = "Extend" field-value ; See section 4.2 of [RFC2068] - - Clients may include Timeout headers in their LOCK requests. However, - the server is not required to honor or even consider these requests. - Clients MUST NOT submit a Timeout request header with any method - other than a LOCK method. - - A Timeout request header MUST contain at least one TimeType and may - contain multiple TimeType entries. The purpose of listing multiple - TimeType entries is to indicate multiple different values and value - types that are acceptable to the client. The client lists the - TimeType entries in order of preference. - - Timeout response values MUST use a Second value, Infinite, or a - TimeType the client has indicated familiarity with. The server may - assume a client is familiar with any TimeType submitted in a Timeout - header. - - The "Second" TimeType specifies the number of seconds that will - elapse between granting of the lock at the server, and the automatic - removal of the lock. The timeout value for TimeType "Second" MUST - NOT be greater than 2^32-1. - - The timeout counter SHOULD be restarted any time an owner of the lock - sends a method to any member of the lock, including unsupported - methods, or methods which are unsuccessful. However the lock MUST be - refreshed if a refresh LOCK method is successfully received. - - If the timeout expires then the lock may be lost. Specifically, if - the server wishes to harvest the lock upon time-out, the server - SHOULD act as if an UNLOCK method was executed by the server on the - resource using the lock token of the timed-out lock, performed with - - - -Goland, et al. Standards Track [Page 58] - -RFC 2518 WEBDAV February 1999 - - - its override authority. Thus logs should be updated with the - disposition of the lock, notifications should be sent, etc., just as - they would be for an UNLOCK request. - - Servers are advised to pay close attention to the values submitted by - clients, as they will be indicative of the type of activity the - client intends to perform. For example, an applet running in a - browser may need to lock a resource, but because of the instability - of the environment within which the applet is running, the applet may - be turned off without warning. As a result, the applet is likely to - ask for a relatively small timeout value so that if the applet dies, - the lock can be quickly harvested. However, a document management - system is likely to ask for an extremely long timeout because its - user may be planning on going off-line. - - A client MUST NOT assume that just because the time-out has expired - the lock has been lost. - -10 Status Code Extensions to HTTP/1.1 - - The following status codes are added to those defined in HTTP/1.1 - [RFC2068]. - -10.1 102 Processing - - The 102 (Processing) status code is an interim response used to - inform the client that the server has accepted the complete request, - but has not yet completed it. This status code SHOULD only be sent - when the server has a reasonable expectation that the request will - take significant time to complete. As guidance, if a method is taking - longer than 20 seconds (a reasonable, but arbitrary value) to process - the server SHOULD return a 102 (Processing) response. The server MUST - send a final response after the request has been completed. - - Methods can potentially take a long period of time to process, - especially methods that support the Depth header. In such cases the - client may time-out the connection while waiting for a response. To - prevent this the server may return a 102 (Processing) status code to - indicate to the client that the server is still processing the - method. - -10.2 207 Multi-Status - - The 207 (Multi-Status) status code provides status for multiple - independent operations (see section 11 for more information). - - - - - - -Goland, et al. Standards Track [Page 59] - -RFC 2518 WEBDAV February 1999 - - -10.3 422 Unprocessable Entity - - The 422 (Unprocessable Entity) status code means the server - understands the content type of the request entity (hence a - 415(Unsupported Media Type) status code is inappropriate), and the - syntax of the request entity is correct (thus a 400 (Bad Request) - status code is inappropriate) but was unable to process the contained - instructions. For example, this error condition may occur if an XML - request body contains well-formed (i.e., syntactically correct), but - semantically erroneous XML instructions. - -10.4 423 Locked - - The 423 (Locked) status code means the source or destination resource - of a method is locked. - -10.5 424 Failed Dependency - - The 424 (Failed Dependency) status code means that the method could - not be performed on the resource because the requested action - depended on another action and that action failed. For example, if a - command in a PROPPATCH method fails then, at minimum, the rest of the - commands will also fail with 424 (Failed Dependency). - -10.6 507 Insufficient Storage - - The 507 (Insufficient Storage) status code means the method could not - be performed on the resource because the server is unable to store - the representation needed to successfully complete the request. This - condition is considered to be temporary. If the request which - received this status code was the result of a user action, the - request MUST NOT be repeated until it is requested by a separate user - action. - -11 Multi-Status Response - - The default 207 (Multi-Status) response body is a text/xml or - application/xml HTTP entity that contains a single XML element called - multistatus, which contains a set of XML elements called response - which contain 200, 300, 400, and 500 series status codes generated - during the method invocation. 100 series status codes SHOULD NOT be - recorded in a response XML element. - - - - - - - - - -Goland, et al. Standards Track [Page 60] - -RFC 2518 WEBDAV February 1999 - - -12 XML Element Definitions - - In the section below, the final line of each section gives the - element type declaration using the format defined in [REC-XML]. The - "Value" field, where present, specifies further restrictions on the - allowable contents of the XML element using BNF (i.e., to further - restrict the values of a PCDATA element). - -12.1 activelock XML Element - - Name: activelock - Namespace: DAV: - Purpose: Describes a lock on a resource. - - <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?, - locktoken?) > - -12.1.1 depth XML Element - - Name: depth - Namespace: DAV: - Purpose: The value of the Depth header. - Value: "0" | "1" | "infinity" - - <!ELEMENT depth (#PCDATA) > - -12.1.2 locktoken XML Element - - Name: locktoken - Namespace: DAV: - Purpose: The lock token associated with a lock. - Description: The href contains one or more opaque lock token URIs - which all refer to the same lock (i.e., the OpaqueLockToken-URI - production in section 6.4). - - <!ELEMENT locktoken (href+) > - -12.1.3 timeout XML Element - - Name: timeout - Namespace: DAV: - Purpose: The timeout associated with a lock - Value: TimeType ;Defined in section 9.8 - - <!ELEMENT timeout (#PCDATA) > - - - - - - -Goland, et al. Standards Track [Page 61] - -RFC 2518 WEBDAV February 1999 - - -12.2 collection XML Element - - Name: collection - Namespace: DAV: - Purpose: Identifies the associated resource as a collection. The - resourcetype property of a collection resource MUST have this value. - - <!ELEMENT collection EMPTY > - -12.3 href XML Element - - Name: href - Namespace: DAV: - Purpose: Identifies the content of the element as a URI. - Value: URI ; See section 3.2.1 of [RFC2068] - - <!ELEMENT href (#PCDATA)> - -12.4 link XML Element - - Name: link - Namespace: DAV: - Purpose: Identifies the property as a link and contains the source - and destination of that link. - Description: The link XML element is used to provide the sources and - destinations of a link. The name of the property containing the link - XML element provides the type of the link. Link is a multi-valued - element, so multiple links may be used together to indicate multiple - links with the same type. The values in the href XML elements inside - the src and dst XML elements of the link XML element MUST NOT be - rejected if they point to resources which do not exist. - - <!ELEMENT link (src+, dst+) > - -12.4.1 dst XML Element - - Name: dst - Namespace: DAV: - Purpose: Indicates the destination of a link - Value: URI - - <!ELEMENT dst (#PCDATA) > - -12.4.2 src XML Element - - Name: src - Namespace: DAV: - Purpose: Indicates the source of a link. - - - -Goland, et al. Standards Track [Page 62] - -RFC 2518 WEBDAV February 1999 - - - Value: URI - - <!ELEMENT src (#PCDATA) > - -12.5 lockentry XML Element - - Name: lockentry - Namespace: DAV: - Purpose: Defines the types of locks that can be used with the - resource. - - <!ELEMENT lockentry (lockscope, locktype) > - -12.6 lockinfo XML Element - - Name: lockinfo - Namespace: DAV: - Purpose: The lockinfo XML element is used with a LOCK method to - specify the type of lock the client wishes to have created. - - <!ELEMENT lockinfo (lockscope, locktype, owner?) > - -12.7 lockscope XML Element - - Name: lockscope - Namespace: DAV: - Purpose: Specifies whether a lock is an exclusive lock, or a - shared lock. - - <!ELEMENT lockscope (exclusive | shared) > - -12.7.1 exclusive XML Element - - Name: exclusive - Namespace: DAV: - Purpose: Specifies an exclusive lock - - <!ELEMENT exclusive EMPTY > - -12.7.2 shared XML Element - - Name: shared - Namespace: DAV: - Purpose: Specifies a shared lock - - <!ELEMENT shared EMPTY > - - - - - -Goland, et al. Standards Track [Page 63] - -RFC 2518 WEBDAV February 1999 - - -12.8 locktype XML Element - - Name: locktype - Namespace: DAV: - Purpose: Specifies the access type of a lock. At present, this - specification only defines one lock type, the write lock. - - <!ELEMENT locktype (write) > - -12.8.1 write XML Element - - Name: write - Namespace: DAV: - Purpose: Specifies a write lock. - - <!ELEMENT write EMPTY > - -12.9 multistatus XML Element - - Name: multistatus - Namespace: DAV: - Purpose: Contains multiple response messages. - Description: The responsedescription at the top level is used to - provide a general message describing the overarching nature of the - response. If this value is available an application may use it - instead of presenting the individual response descriptions contained - within the responses. - - <!ELEMENT multistatus (response+, responsedescription?) > - -12.9.1 response XML Element - - Name: response - Namespace: DAV: - Purpose: Holds a single response describing the effect of a - method on resource and/or its properties. - Description: A particular href MUST NOT appear more than once as the - child of a response XML element under a multistatus XML element. - This requirement is necessary in order to keep processing costs for a - response to linear time. Essentially, this prevents having to search - in order to group together all the responses by href. There are, - however, no requirements regarding ordering based on href values. - - <!ELEMENT response (href, ((href*, status)|(propstat+)), - responsedescription?) > - - - - - - -Goland, et al. Standards Track [Page 64] - -RFC 2518 WEBDAV February 1999 - - -12.9.1.1 propstat XML Element - - Name: propstat - Namespace: DAV: - Purpose: Groups together a prop and status element that is - associated with a particular href element. - Description: The propstat XML element MUST contain one prop XML - element and one status XML element. The contents of the prop XML - element MUST only list the names of properties to which the result in - the status element applies. - - <!ELEMENT propstat (prop, status, responsedescription?) > - -12.9.1.2 status XML Element - - Name: status - Namespace: DAV: - Purpose: Holds a single HTTP status-line - Value: status-line ;status-line defined in [RFC2068] - - <!ELEMENT status (#PCDATA) > - -12.9.2 responsedescription XML Element - - Name: responsedescription - Namespace: DAV: - Purpose: Contains a message that can be displayed to the user - explaining the nature of the response. - Description: This XML element provides information suitable to be - presented to a user. - - <!ELEMENT responsedescription (#PCDATA) > - -12.10 owner XML Element - - Name: owner - Namespace: DAV: - Purpose: Provides information about the principal taking out a - lock. - Description: The owner XML element provides information sufficient - for either directly contacting a principal (such as a telephone - number or Email URI), or for discovering the principal (such as the - URL of a homepage) who owns a lock. - - <!ELEMENT owner ANY> - - - - - - -Goland, et al. Standards Track [Page 65] - -RFC 2518 WEBDAV February 1999 - - -12.11 prop XML element - - Name: prop - Namespace: DAV: - Purpose: Contains properties related to a resource. - Description: The prop XML element is a generic container for - properties defined on resources. All elements inside a prop XML - element MUST define properties related to the resource. No other - elements may be used inside of a prop element. - - <!ELEMENT prop ANY> - -12.12 propertybehavior XML element - - Name: propertybehavior Namespace: DAV: Purpose: Specifies - how properties are handled during a COPY or MOVE. - Description: The propertybehavior XML element specifies how - properties are handled during a COPY or MOVE. If this XML element is - not included in the request body then the server is expected to act - as defined by the default property handling behavior of the - associated method. All WebDAV compliant resources MUST support the - propertybehavior XML element. - - <!ELEMENT propertybehavior (omit | keepalive) > - -12.12.1 keepalive XML element - - Name: keepalive - Namespace: DAV: - Purpose: Specifies requirements for the copying/moving of live - properties. - Description: If a list of URIs is included as the value of keepalive - then the named properties MUST be "live" after they are copied - (moved) to the destination resource of a COPY (or MOVE). If the - value "*" is given for the keepalive XML element, this designates - that all live properties on the source resource MUST be live on the - destination. If the requirements specified by the keepalive element - can not be honored then the method MUST fail with a 412 (Precondition - Failed). All DAV compliant resources MUST support the keepalive XML - element for use with the COPY and MOVE methods. - Value: "*" ; #PCDATA value can only be "*" - - <!ELEMENT keepalive (#PCDATA | href+) > - - - - - - - - -Goland, et al. Standards Track [Page 66] - -RFC 2518 WEBDAV February 1999 - - -12.12.2 omit XML element - - Name: omit - Namespace: DAV: - Purpose: The omit XML element instructs the server that it should - use best effort to copy properties but a failure to copy a property - MUST NOT cause the method to fail. Description: The default behavior - for a COPY or MOVE is to copy/move all properties or fail the method. - In certain circumstances, such as when a server copies a resource - over another protocol such as FTP, it may not be possible to - copy/move the properties associated with the resource. Thus any - attempt to copy/move over FTP would always have to fail because - properties could not be moved over, even as dead properties. All DAV - compliant resources MUST support the omit XML element on COPY/MOVE - methods. - - <!ELEMENT omit EMPTY > - -12.13 propertyupdate XML element - - Name: propertyupdate - Namespace: DAV: - Purpose: Contains a request to alter the properties on a - resource. - Description: This XML element is a container for the information - required to modify the properties on the resource. This XML element - is multi-valued. - - <!ELEMENT propertyupdate (remove | set)+ > - -12.13.1 remove XML element - - Name: remove - Namespace: DAV: - Purpose: Lists the DAV properties to be removed from a resource. - Description: Remove instructs that the properties specified in prop - should be removed. Specifying the removal of a property that does - not exist is not an error. All the XML elements in a prop XML - element inside of a remove XML element MUST be empty, as only the - names of properties to be removed are required. - - <!ELEMENT remove (prop) > - -12.13.2 set XML element - - Name: set - Namespace: DAV: - Purpose: Lists the DAV property values to be set for a resource. - - - -Goland, et al. Standards Track [Page 67] - -RFC 2518 WEBDAV February 1999 - - - Description: The set XML element MUST contain only a prop XML - element. The elements contained by the prop XML element inside the - set XML element MUST specify the name and value of properties that - are set on the resource identified by Request-URI. If a property - already exists then its value is replaced. Language tagging - information in the property's value (in the "xml:lang" attribute, if - present) MUST be persistently stored along with the property, and - MUST be subsequently retrievable using PROPFIND. - - <!ELEMENT set (prop) > - -12.14 propfind XML Element - - Name: propfind - Namespace: DAV: - Purpose: Specifies the properties to be returned from a PROPFIND - method. Two special elements are specified for use with propfind, - allprop and propname. If prop is used inside propfind it MUST only - contain property names, not values. - - <!ELEMENT propfind (allprop | propname | prop) > - -12.14.1 allprop XML Element - - Name: allprop Namespace: DAV: Purpose: The allprop XML - element specifies that all property names and values on the resource - are to be returned. - - <!ELEMENT allprop EMPTY > - -12.14.2 propname XML Element - - Name: propname Namespace: DAV: Purpose: The propname XML - element specifies that only a list of property names on the resource - is to be returned. - - <!ELEMENT propname EMPTY > - -13 DAV Properties - - For DAV properties, the name of the property is also the same as the - name of the XML element that contains its value. In the section - below, the final line of each section gives the element type - declaration using the format defined in [REC-XML]. The "Value" field, - where present, specifies further restrictions on the allowable - contents of the XML element using BNF (i.e., to further restrict the - values of a PCDATA element). - - - - -Goland, et al. Standards Track [Page 68] - -RFC 2518 WEBDAV February 1999 - - -13.1 creationdate Property - - Name: creationdate - Namespace: DAV: - Purpose: Records the time and date the resource was created. - Value: date-time ; See Appendix 2 - Description: The creationdate property should be defined on all DAV - compliant resources. If present, it contains a timestamp of the - moment when the resource was created (i.e., the moment it had non- - null state). - - <!ELEMENT creationdate (#PCDATA) > - -13.2 displayname Property - - Name: displayname - Namespace: DAV: - Purpose: Provides a name for the resource that is suitable for - presentation to a user. - Description: The displayname property should be defined on all DAV - compliant resources. If present, the property contains a description - of the resource that is suitable for presentation to a user. - - <!ELEMENT displayname (#PCDATA) > - -13.3 getcontentlanguage Property - - Name: getcontentlanguage - Namespace: DAV: - Purpose: Contains the Content-Language header returned by a GET - without accept headers - Description: The getcontentlanguage property MUST be defined on any - DAV compliant resource that returns the Content-Language header on a - GET. - Value: language-tag ;language-tag is defined in section 14.13 - of [RFC2068] - - <!ELEMENT getcontentlanguage (#PCDATA) > - -13.4 getcontentlength Property - - Name: getcontentlength - Namespace: DAV: - Purpose: Contains the Content-Length header returned by a GET - without accept headers. - Description: The getcontentlength property MUST be defined on any - DAV compliant resource that returns the Content-Length header in - response to a GET. - - - -Goland, et al. Standards Track [Page 69] - -RFC 2518 WEBDAV February 1999 - - - Value: content-length ; see section 14.14 of [RFC2068] - - <!ELEMENT getcontentlength (#PCDATA) > - -13.5 getcontenttype Property - - Name: getcontenttype - Namespace: DAV: - Purpose: Contains the Content-Type header returned by a GET - without accept headers. - Description: This getcontenttype property MUST be defined on any DAV - compliant resource that returns the Content-Type header in response - to a GET. - Value: media-type ; defined in section 3.7 of [RFC2068] - - <!ELEMENT getcontenttype (#PCDATA) > - -13.6 getetag Property - - Name: getetag - Namespace: DAV: - Purpose: Contains the ETag header returned by a GET without - accept headers. - Description: The getetag property MUST be defined on any DAV - compliant resource that returns the Etag header. - Value: entity-tag ; defined in section 3.11 of [RFC2068] - - <!ELEMENT getetag (#PCDATA) > - -13.7 getlastmodified Property - - Name: getlastmodified - Namespace: DAV: - Purpose: Contains the Last-Modified header returned by a GET - method without accept headers. - Description: Note that the last-modified date on a resource may - reflect changes in any part of the state of the resource, not - necessarily just a change to the response to the GET method. For - example, a change in a property may cause the last-modified date to - change. The getlastmodified property MUST be defined on any DAV - compliant resource that returns the Last-Modified header in response - to a GET. - Value: HTTP-date ; defined in section 3.3.1 of [RFC2068] - - <!ELEMENT getlastmodified (#PCDATA) > - - - - - - -Goland, et al. Standards Track [Page 70] - -RFC 2518 WEBDAV February 1999 - - -13.8 lockdiscovery Property - - Name: lockdiscovery - Namespace: DAV: - Purpose: Describes the active locks on a resource - Description: The lockdiscovery property returns a listing of who has - a lock, what type of lock he has, the timeout type and the time - remaining on the timeout, and the associated lock token. The server - is free to withhold any or all of this information if the requesting - principal does not have sufficient access rights to see the requested - data. - - <!ELEMENT lockdiscovery (activelock)* > - -13.8.1 Example - Retrieving the lockdiscovery Property - - >>Request - - PROPFIND /container/ HTTP/1.1 - Host: www.foo.bar - Content-Length: xxxx - Content-Type: text/xml; charset="utf-8" - - <?xml version="1.0" encoding="utf-8" ?> - <D:propfind xmlns:D='DAV:'> - <D:prop><D:lockdiscovery/></D:prop> - </D:propfind> - - >>Response - - HTTP/1.1 207 Multi-Status - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D='DAV:'> - <D:response> - <D:href>http://www.foo.bar/container/</D:href> - <D:propstat> - <D:prop> - <D:lockdiscovery> - <D:activelock> - <D:locktype><D:write/></D:locktype> - <D:lockscope><D:exclusive/></D:lockscope> - <D:depth>0</D:depth> - <D:owner>Jane Smith</D:owner> - <D:timeout>Infinite</D:timeout> - <D:locktoken> - - - -Goland, et al. Standards Track [Page 71] - -RFC 2518 WEBDAV February 1999 - - - <D:href> - opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76 - </D:href> - </D:locktoken> - </D:activelock> - </D:lockdiscovery> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - </D:multistatus> - - This resource has a single exclusive write lock on it, with an - infinite timeout. - -13.9 resourcetype Property - - Name: resourcetype - Namespace: DAV: - Purpose: Specifies the nature of the resource. - Description: The resourcetype property MUST be defined on all DAV - compliant resources. The default value is empty. - - <!ELEMENT resourcetype ANY > - -13.10 source Property - - Name: source - Namespace: DAV: - Purpose: The destination of the source link identifies the - resource that contains the unprocessed source of the link's source. - Description: The source of the link (src) is typically the URI of the - output resource on which the link is defined, and there is typically - only one destination (dst) of the link, which is the URI where the - unprocessed source of the resource may be accessed. When more than - one link destination exists, this specification asserts no policy on - ordering. - - <!ELEMENT source (link)* > - -13.10.1 Example - A source Property - - <?xml version="1.0" encoding="utf-8" ?> - <D:prop xmlns:D="DAV:" xmlns:F="http://www.foocorp.com/Project/"> - <D:source> - <D:link> - <F:projfiles>Source</F:projfiles> - <D:src>http://foo.bar/program</D:src> - - - -Goland, et al. Standards Track [Page 72] - -RFC 2518 WEBDAV February 1999 - - - <D:dst>http://foo.bar/src/main.c</D:dst> - </D:link> - <D:link> - <F:projfiles>Library</F:projfiles> - <D:src>http://foo.bar/program</D:src> - <D:dst>http://foo.bar/src/main.lib</D:dst> - </D:link> - <D:link> - <F:projfiles>Makefile</F:projfiles> - <D:src>http://foo.bar/program</D:src> - <D:dst>http://foo.bar/src/makefile</D:dst> - </D:link> - </D:source> - </D:prop> - - In this example the resource http://foo.bar/program has a source - property that contains three links. Each link contains three - elements, two of which, src and dst, are part of the DAV schema - defined in this document, and one which is defined by the schema - http://www.foocorp.com/project/ (Source, Library, and Makefile). A - client which only implements the elements in the DAV spec will not - understand the foocorp elements and will ignore them, thus seeing the - expected source and destination links. An enhanced client may know - about the foocorp elements and be able to present the user with - additional information about the links. This example demonstrates - the power of XML markup, allowing element values to be enhanced - without breaking older clients. - -13.11 supportedlock Property - - Name: supportedlock - Namespace: DAV: - Purpose: To provide a listing of the lock capabilities supported - by the resource. - Description: The supportedlock property of a resource returns a - listing of the combinations of scope and access types which may be - specified in a lock request on the resource. Note that the actual - contents are themselves controlled by access controls so a server is - not required to provide information the client is not authorized to - see. - - <!ELEMENT supportedlock (lockentry)* > - -13.11.1 Example - Retrieving the supportedlock Property - - >>Request - - PROPFIND /container/ HTTP/1.1 - - - -Goland, et al. Standards Track [Page 73] - -RFC 2518 WEBDAV February 1999 - - - Host: www.foo.bar - Content-Length: xxxx - Content-Type: text/xml; charset="utf-8" - - <?xml version="1.0" encoding="utf-8" ?> - <D:propfind xmlns:D="DAV:"> - <D:prop><D:supportedlock/></D:prop> - </D:propfind> - - >>Response - - HTTP/1.1 207 Multi-Status - Content-Type: text/xml; charset="utf-8" - Content-Length: xxxx - - <?xml version="1.0" encoding="utf-8" ?> - <D:multistatus xmlns:D="DAV:"> - <D:response> - <D:href>http://www.foo.bar/container/</D:href> - <D:propstat> - <D:prop> - <D:supportedlock> - <D:lockentry> - <D:lockscope><D:exclusive/></D:lockscope> - <D:locktype><D:write/></D:locktype> - </D:lockentry> - <D:lockentry> - <D:lockscope><D:shared/></D:lockscope> - <D:locktype><D:write/></D:locktype> - </D:lockentry> - </D:supportedlock> - </D:prop> - <D:status>HTTP/1.1 200 OK</D:status> - </D:propstat> - </D:response> - </D:multistatus> - -14 Instructions for Processing XML in DAV - - All DAV compliant resources MUST ignore any unknown XML element and - all its children encountered while processing a DAV method that uses - XML as its command language. - - This restriction also applies to the processing, by clients, of DAV - property values where unknown XML elements SHOULD be ignored unless - the property's schema declares otherwise. - - - - - -Goland, et al. Standards Track [Page 74] - -RFC 2518 WEBDAV February 1999 - - - This restriction does not apply to setting dead DAV properties on the - server where the server MUST record unknown XML elements. - - Additionally, this restriction does not apply to the use of XML where - XML happens to be the content type of the entity body, for example, - when used as the body of a PUT. - - Since XML can be transported as text/xml or application/xml, a DAV - server MUST accept DAV method requests with XML parameters - transported as either text/xml or application/xml, and DAV client - MUST accept XML responses using either text/xml or application/xml. - -15 DAV Compliance Classes - - A DAV compliant resource can choose from two classes of compliance. - A client can discover the compliance classes of a resource by - executing OPTIONS on the resource, and examining the "DAV" header - which is returned. - - Since this document describes extensions to the HTTP/1.1 protocol, - minimally all DAV compliant resources, clients, and proxies MUST be - compliant with [RFC2068]. - - Compliance classes are not necessarily sequential. A resource that is - class 2 compliant must also be class 1 compliant; but if additional - compliance classes are defined later, a resource that is class 1, 2, - and 4 compliant might not be class 3 compliant. Also note that - identifiers other than numbers may be used as compliance class - identifiers. - -15.1 Class 1 - - A class 1 compliant resource MUST meet all "MUST" requirements in all - sections of this document. - - Class 1 compliant resources MUST return, at minimum, the value "1" in - the DAV header on all responses to the OPTIONS method. - -15.2 Class 2 - - A class 2 compliant resource MUST meet all class 1 requirements and - support the LOCK method, the supportedlock property, the - lockdiscovery property, the Time-Out response header and the Lock- - Token request header. A class "2" compliant resource SHOULD also - support the Time-Out request header and the owner XML element. - - Class 2 compliant resources MUST return, at minimum, the values "1" - and "2" in the DAV header on all responses to the OPTIONS method. - - - -Goland, et al. Standards Track [Page 75] - -RFC 2518 WEBDAV February 1999 - - -16 Internationalization Considerations - - In the realm of internationalization, this specification complies - with the IETF Character Set Policy [RFC2277]. In this specification, - human-readable fields can be found either in the value of a property, - or in an error message returned in a response entity body. In both - cases, the human-readable content is encoded using XML, which has - explicit provisions for character set tagging and encoding, and - requires that XML processors read XML elements encoded, at minimum, - using the UTF-8 [UTF-8] encoding of the ISO 10646 multilingual plane. - XML examples in this specification demonstrate use of the charset - parameter of the Content-Type header, as defined in [RFC2376], as - well as the XML "encoding" attribute, which together provide charset - identification information for MIME and XML processors. - - XML also provides a language tagging capability for specifying the - language of the contents of a particular XML element. XML uses - either IANA registered language tags (see [RFC1766]) or ISO 639 - language tags [ISO-639] in the "xml:lang" attribute of an XML element - to identify the language of its content and attributes. - - WebDAV applications MUST support the character set tagging, character - set encoding, and the language tagging functionality of the XML - specification. Implementors of WebDAV applications are strongly - encouraged to read "XML Media Types" [RFC2376] for instruction on - which MIME media type to use for XML transport, and on use of the - charset parameter of the Content-Type header. - - Names used within this specification fall into three categories: - names of protocol elements such as methods and headers, names of XML - elements, and names of properties. Naming of protocol elements - follows the precedent of HTTP, using English names encoded in USASCII - for methods and headers. Since these protocol elements are not - visible to users, and are in fact simply long token identifiers, they - do not need to support encoding in multiple character sets. - Similarly, though the names of XML elements used in this - specification are English names encoded in UTF-8, these names are not - visible to the user, and hence do not need to support multiple - character set encodings. - - The name of a property defined on a resource is a URI. Although some - applications (e.g., a generic property viewer) will display property - URIs directly to their users, it is expected that the typical - application will use a fixed set of properties, and will provide a - mapping from the property name URI to a human-readable field when - displaying the property name to a user. It is only in the case where - - - - - -Goland, et al. Standards Track [Page 76] - -RFC 2518 WEBDAV February 1999 - - - the set of properties is not known ahead of time that an application - need display a property name URI to a user. We recommend that - applications provide human-readable property names wherever feasible. - - For error reporting, we follow the convention of HTTP/1.1 status - codes, including with each status code a short, English description - of the code (e.g., 423 (Locked)). While the possibility exists that - a poorly crafted user agent would display this message to a user, - internationalized applications will ignore this message, and display - an appropriate message in the user's language and character set. - - Since interoperation of clients and servers does not require locale - information, this specification does not specify any mechanism for - transmission of this information. - -17 Security Considerations - - This section is provided to detail issues concerning security - implications of which WebDAV applications need to be aware. - - All of the security considerations of HTTP/1.1 (discussed in - [RFC2068]) and XML (discussed in [RFC2376]) also apply to WebDAV. In - addition, the security risks inherent in remote authoring require - stronger authentication technology, introduce several new privacy - concerns, and may increase the hazards from poor server design. - These issues are detailed below. - -17.1 Authentication of Clients - - Due to their emphasis on authoring, WebDAV servers need to use - authentication technology to protect not just access to a network - resource, but the integrity of the resource as well. Furthermore, - the introduction of locking functionality requires support for - authentication. - - A password sent in the clear over an insecure channel is an - inadequate means for protecting the accessibility and integrity of a - resource as the password may be intercepted. Since Basic - authentication for HTTP/1.1 performs essentially clear text - transmission of a password, Basic authentication MUST NOT be used to - authenticate a WebDAV client to a server unless the connection is - secure. Furthermore, a WebDAV server MUST NOT send Basic - authentication credentials in a WWW-Authenticate header unless the - connection is secure. Examples of secure connections include a - Transport Layer Security (TLS) connection employing a strong cipher - suite with mutual authentication of client and server, or a - connection over a network which is physically secure, for example, an - isolated network in a building with restricted access. - - - -Goland, et al. Standards Track [Page 77] - -RFC 2518 WEBDAV February 1999 - - - WebDAV applications MUST support the Digest authentication scheme - [RFC2069]. Since Digest authentication verifies that both parties to - a communication know a shared secret, a password, without having to - send that secret in the clear, Digest authentication avoids the - security problems inherent in Basic authentication while providing a - level of authentication which is useful in a wide range of scenarios. - -17.2 Denial of Service - - Denial of service attacks are of special concern to WebDAV servers. - WebDAV plus HTTP enables denial of service attacks on every part of a - system's resources. - - The underlying storage can be attacked by PUTting extremely large - files. - - Asking for recursive operations on large collections can attack - processing time. - - Making multiple pipelined requests on multiple connections can attack - network connections. - - WebDAV servers need to be aware of the possibility of a denial of - service attack at all levels. - -17.3 Security through Obscurity - - WebDAV provides, through the PROPFIND method, a mechanism for listing - the member resources of a collection. This greatly diminishes the - effectiveness of security or privacy techniques that rely only on the - difficulty of discovering the names of network resources. Users of - WebDAV servers are encouraged to use access control techniques to - prevent unwanted access to resources, rather than depending on the - relative obscurity of their resource names. - -17.4 Privacy Issues Connected to Locks - - When submitting a lock request a user agent may also submit an owner - XML field giving contact information for the person taking out the - lock (for those cases where a person, rather than a robot, is taking - out the lock). This contact information is stored in a lockdiscovery - property on the resource, and can be used by other collaborators to - begin negotiation over access to the resource. However, in many - cases this contact information can be very private, and should not be - widely disseminated. Servers SHOULD limit read access to the - lockdiscovery property as appropriate. Furthermore, user agents - - - - - -Goland, et al. Standards Track [Page 78] - -RFC 2518 WEBDAV February 1999 - - - SHOULD provide control over whether contact information is sent at - all, and if contact information is sent, control over exactly what - information is sent. - -17.5 Privacy Issues Connected to Properties - - Since property values are typically used to hold information such as - the author of a document, there is the possibility that privacy - concerns could arise stemming from widespread access to a resource's - property data. To reduce the risk of inadvertent release of private - information via properties, servers are encouraged to develop access - control mechanisms that separate read access to the resource body and - read access to the resource's properties. This allows a user to - control the dissemination of their property data without overly - restricting access to the resource's contents. - -17.6 Reduction of Security due to Source Link - - HTTP/1.1 warns against providing read access to script code because - it may contain sensitive information. Yet WebDAV, via its source - link facility, can potentially provide a URI for script resources so - they may be authored. For HTTP/1.1, a server could reasonably - prevent access to source resources due to the predominance of read- - only access. WebDAV, with its emphasis on authoring, encourages read - and write access to source resources, and provides the source link - facility to identify the source. This reduces the security benefits - of eliminating access to source resources. Users and administrators - of WebDAV servers should be very cautious when allowing remote - authoring of scripts, limiting read and write access to the source - resources to authorized principals. - -17.7 Implications of XML External Entities - - XML supports a facility known as "external entities", defined in - section 4.2.2 of [REC-XML], which instruct an XML processor to - retrieve and perform an inline include of XML located at a particular - URI. An external XML entity can be used to append or modify the - document type declaration (DTD) associated with an XML document. An - external XML entity can also be used to include XML within the - content of an XML document. For non-validating XML, such as the XML - used in this specification, including an external XML entity is not - required by [REC-XML]. However, [REC-XML] does state that an XML - processor may, at its discretion, include the external XML entity. - - External XML entities have no inherent trustworthiness and are - subject to all the attacks that are endemic to any HTTP GET request. - Furthermore, it is possible for an external XML entity to modify the - DTD, and hence affect the final form of an XML document, in the worst - - - -Goland, et al. Standards Track [Page 79] - -RFC 2518 WEBDAV February 1999 - - - case significantly modifying its semantics, or exposing the XML - processor to the security risks discussed in [RFC2376]. Therefore, - implementers must be aware that external XML entities should be - treated as untrustworthy. - - There is also the scalability risk that would accompany a widely - deployed application which made use of external XML entities. In - this situation, it is possible that there would be significant - numbers of requests for one external XML entity, potentially - overloading any server which fields requests for the resource - containing the external XML entity. - -17.8 Risks Connected with Lock Tokens - - This specification, in section 6.4, requires the use of Universal - Unique Identifiers (UUIDs) for lock tokens, in order to guarantee - their uniqueness across space and time. UUIDs, as defined in [ISO- - 11578], contain a "node" field which "consists of the IEEE address, - usually the host address. For systems with multiple IEEE 802 nodes, - any available node address can be used." Since a WebDAV server will - issue many locks over its lifetime, the implication is that it will - also be publicly exposing its IEEE 802 address. - - There are several risks associated with exposure of IEEE 802 - addresses. Using the IEEE 802 address: - - * It is possible to track the movement of hardware from subnet to - subnet. - - * It may be possible to identify the manufacturer of the hardware - running a WebDAV server. - - * It may be possible to determine the number of each type of computer - running WebDAV. - - Section 6.4.1 of this specification details an alternate mechanism - for generating the "node" field of a UUID without using an IEEE 802 - address, which alleviates the risks associated with exposure of IEEE - 802 addresses by using an alternate source of uniqueness. - -18 IANA Considerations - - This document defines two namespaces, the namespace of property - names, and the namespace of WebDAV-specific XML elements used within - property values. - - - - - - -Goland, et al. Standards Track [Page 80] - -RFC 2518 WEBDAV February 1999 - - - URIs are used for both names, for several reasons. Assignment of a - URI does not require a request to a central naming authority, and - hence allow WebDAV property names and XML elements to be quickly - defined by any WebDAV user or application. URIs also provide a - unique address space, ensuring that the distributed users of WebDAV - will not have collisions among the property names and XML elements - they create. - - This specification defines a distinguished set of property names and - XML elements that are understood by all WebDAV applications. The - property names and XML elements in this specification are all derived - from the base URI DAV: by adding a suffix to this URI, for example, - DAV:creationdate for the "creationdate" property. - - This specification also defines a URI scheme for the encoding of lock - tokens, the opaquelocktoken URI scheme described in section 6.4. - - To ensure correct interoperation based on this specification, IANA - must reserve the URI namespaces starting with "DAV:" and with - "opaquelocktoken:" for use by this specification, its revisions, and - related WebDAV specifications. - -19 Intellectual Property - - The following notice is copied from RFC 2026 [RFC2026], section 10.4, - and describes the position of the IETF concerning intellectual - property claims made against this document. - - The IETF takes no position regarding the validity or scope of any - intellectual property or other rights that might be claimed to - pertain to the implementation or use other technology described in - this document or the extent to which any license under such rights - might or might not be available; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication and any assurances of - licenses to be made available, or the result of an attempt made to - obtain a general license or permission for the use of such - proprietary rights by implementors or users of this specification can - be obtained from the IETF Secretariat. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights which may cover technology that may be required to practice - this standard. Please address the information to the IETF Executive - Director. - - - - -Goland, et al. Standards Track [Page 81] - -RFC 2518 WEBDAV February 1999 - - -20 Acknowledgements - - A specification such as this thrives on piercing critical review and - withers from apathetic neglect. The authors gratefully acknowledge - the contributions of the following people, whose insights were so - valuable at every stage of our work. - - Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan - Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners- - Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith - Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee - Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan - Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis - Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van der - Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven - Martin, Larry Masinter, Michael Mealling, Keith Moore, Thomas Narten, - Henrik Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff, - Saveen Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike - Spreitzer, Einar Stefferud, Greg Stein, Ralph Swick, Kenji Takahashi, - Richard N. Taylor, Robert Thau, John Turner, Sankar Virdhagriswaran, - Fabio Vitali, Gregory Woodhouse, and Lauren Wood. - - Two from this list deserve special mention. The contributions by - Larry Masinter have been invaluable, both in helping the formation of - the working group and in patiently coaching the authors along the - way. In so many ways he has set high standards we have toiled to - meet. The contributions of Judith Slein in clarifying the - requirements, and in patiently reviewing draft after draft, both - improved this specification and expanded our minds on document - management. - - We would also like to thank John Turner for developing the XML DTD. - -21 References - -21.1 Normative References - - [RFC1766] Alvestrand, H., "Tags for the Identification of - Languages", RFC 1766, March 1995. - - [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and - Languages", BCP 18, RFC 2277, January 1998. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - - - - - -Goland, et al. Standards Track [Page 82] - -RFC 2518 WEBDAV February 1999 - - - [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, - "Uniform Resource Identifiers (URI): Generic Syntax", - RFC 2396, August 1998. - - [REC-XML] T. Bray, J. Paoli, C. M. Sperberg-McQueen, - "Extensible Markup Language (XML)." World Wide Web - Consortium Recommendation REC-xml-19980210. - http://www.w3.org/TR/1998/REC-xml-19980210. - - [REC-XML-NAMES] T. Bray, D. Hollander, A. Layman, "Namespaces in - XML". World Wide Web Consortium Recommendation REC- - xml-names-19990114. http://www.w3.org/TR/1999/REC- - xml-names-19990114/ - - [RFC2069] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, - P, Luotonen, A., Sink, E. and L. Stewart, "An - Extension to HTTP : Digest Access Authentication", - RFC 2069, January 1997. - - [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and - T. Berners-Lee, "Hypertext Transfer Protocol -- - HTTP/1.1", RFC 2068, January 1997. - - [ISO-639] ISO (International Organization for Standardization). - ISO 639:1988. "Code for the representation of names - of languages." - - [ISO-8601] ISO (International Organization for Standardization). - ISO 8601:1988. "Data elements and interchange formats - - Information interchange - Representation of dates - and times." - - [ISO-11578] ISO (International Organization for Standardization). - ISO/IEC 11578:1996. "Information technology - Open - Systems Interconnection - Remote Procedure Call - (RPC)" - - [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. - - [UTF-8] Yergeau, F., "UTF-8, a transformation format of - Unicode and ISO 10646", RFC 2279, January 1998. - -21.2 Informational References - - [RFC2026] Bradner, S., "The Internet Standards Process - Revision - 3", BCP 9, RFC 2026, October 1996. - - - - - -Goland, et al. Standards Track [Page 83] - -RFC 2518 WEBDAV February 1999 - - - [RFC1807] Lasher, R. and D. Cohen, "A Format for Bibliographic - Records", RFC 1807, June 1995. - - [WF] C. Lagoze, "The Warwick Framework: A Container - Architecture for Diverse Sets of Metadata", D-Lib - Magazine, July/August 1996. - http://www.dlib.org/dlib/july96/lagoze/07lagoze.html - - [USMARC] Network Development and MARC Standards, Office, ed. 1994. - "USMARC Format for Bibliographic Data", 1994. Washington, - DC: Cataloging Distribution Service, Library of Congress. - - [REC-PICS] J. Miller, T. Krauskopf, P. Resnick, W. Treese, "PICS - Label Distribution Label Syntax and Communication - Protocols" Version 1.1, World Wide Web Consortium - Recommendation REC-PICS-labels-961031. - http://www.w3.org/pub/WWW/TR/REC-PICS-labels-961031.html. - - [RFC2291] Slein, J., Vitali, F., Whitehead, E. and D. Durand, - "Requirements for Distributed Authoring and Versioning - Protocol for the World Wide Web", RFC 2291, February 1998. - - [RFC2413] Weibel, S., Kunze, J., Lagoze, C. and M. Wolf, "Dublin - Core Metadata for Resource Discovery", RFC 2413, September - 1998. - - [RFC2376] Whitehead, E. and M. Murata, "XML Media Types", RFC 2376, - July 1998. - -22 Authors' Addresses - - Y. Y. Goland - Microsoft Corporation - One Microsoft Way - Redmond, WA 98052-6399 - - EMail: yarong@microsoft.com - - - E. J. Whitehead, Jr. - Dept. Of Information and Computer Science - University of California, Irvine - Irvine, CA 92697-3425 - - EMail: ejw@ics.uci.edu - - - - - - -Goland, et al. Standards Track [Page 84] - -RFC 2518 WEBDAV February 1999 - - - A. Faizi - Netscape - 685 East Middlefield Road - Mountain View, CA 94043 - - EMail: asad@netscape.com - - - S. R. Carter - Novell - 1555 N. Technology Way - M/S ORM F111 - Orem, UT 84097-2399 - - EMail: srcarter@novell.com - - - D. Jensen - Novell - 1555 N. Technology Way - M/S ORM F111 - Orem, UT 84097-2399 - - EMail: dcjensen@novell.com - - - - - - - - - - - - - - - - - - - - - - - - - - - -Goland, et al. Standards Track [Page 85] - -RFC 2518 WEBDAV February 1999 - - -23 Appendices - -23.1 Appendix 1 - WebDAV Document Type Definition - - This section provides a document type definition, following the rules - in [REC-XML], for the XML elements used in the protocol stream and in - the values of properties. It collects the element definitions given - in sections 12 and 13. - - <!DOCTYPE webdav-1.0 [ - - <!--============ XML Elements from Section 12 ==================--> - - <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?, - locktoken?) > - - <!ELEMENT lockentry (lockscope, locktype) > - <!ELEMENT lockinfo (lockscope, locktype, owner?) > - - <!ELEMENT locktype (write) > - <!ELEMENT write EMPTY > - - <!ELEMENT lockscope (exclusive | shared) > - <!ELEMENT exclusive EMPTY > - <!ELEMENT shared EMPTY > - - <!ELEMENT depth (#PCDATA) > - - <!ELEMENT owner ANY > - - <!ELEMENT timeout (#PCDATA) > - - <!ELEMENT locktoken (href+) > - - <!ELEMENT href (#PCDATA) > - - <!ELEMENT link (src+, dst+) > - <!ELEMENT dst (#PCDATA) > - <!ELEMENT src (#PCDATA) > - - <!ELEMENT multistatus (response+, responsedescription?) > - - <!ELEMENT response (href, ((href*, status)|(propstat+)), - responsedescription?) > - <!ELEMENT status (#PCDATA) > - <!ELEMENT propstat (prop, status, responsedescription?) > - <!ELEMENT responsedescription (#PCDATA) > - - - - -Goland, et al. Standards Track [Page 86] - -RFC 2518 WEBDAV February 1999 - - - <!ELEMENT prop ANY > - - <!ELEMENT propertybehavior (omit | keepalive) > - <!ELEMENT omit EMPTY > - - <!ELEMENT keepalive (#PCDATA | href+) > - - <!ELEMENT propertyupdate (remove | set)+ > - <!ELEMENT remove (prop) > - <!ELEMENT set (prop) > - - <!ELEMENT propfind (allprop | propname | prop) > - <!ELEMENT allprop EMPTY > - <!ELEMENT propname EMPTY > - - <!ELEMENT collection EMPTY > - - <!--=========== Property Elements from Section 13 ===============--> - <!ELEMENT creationdate (#PCDATA) > - <!ELEMENT displayname (#PCDATA) > - <!ELEMENT getcontentlanguage (#PCDATA) > - <!ELEMENT getcontentlength (#PCDATA) > - <!ELEMENT getcontenttype (#PCDATA) > - <!ELEMENT getetag (#PCDATA) > - <!ELEMENT getlastmodified (#PCDATA) > - <!ELEMENT lockdiscovery (activelock)* > - <!ELEMENT resourcetype ANY > - <!ELEMENT source (link)* > - <!ELEMENT supportedlock (lockentry)* > - ]> - - - - - - - - - - - - - - - - - - - - - -Goland, et al. Standards Track [Page 87] - -RFC 2518 WEBDAV February 1999 - - -23.2 Appendix 2 - ISO 8601 Date and Time Profile - - The creationdate property specifies the use of the ISO 8601 date - format [ISO-8601]. This section defines a profile of the ISO 8601 - date format for use with this specification. This profile is quoted - from an Internet-Draft by Chris Newman, and is mentioned here to - properly attribute his work. - - date-time = full-date "T" full-time - - full-date = date-fullyear "-" date-month "-" date-mday - full-time = partial-time time-offset - - date-fullyear = 4DIGIT - date-month = 2DIGIT ; 01-12 - date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on - month/year - time-hour = 2DIGIT ; 00-23 - time-minute = 2DIGIT ; 00-59 - time-second = 2DIGIT ; 00-59, 00-60 based on leap second rules - time-secfrac = "." 1*DIGIT - time-numoffset = ("+" / "-") time-hour ":" time-minute - time-offset = "Z" / time-numoffset - - partial-time = time-hour ":" time-minute ":" time-second - [time-secfrac] - - Numeric offsets are calculated as local time minus UTC (Coordinated - Universal Time). So the equivalent time in UTC can be determined by - subtracting the offset from the local time. For example, 18:50:00- - 04:00 is the same time as 22:58:00Z. - - If the time in UTC is known, but the offset to local time is unknown, - this can be represented with an offset of "-00:00". This differs - from an offset of "Z" which implies that UTC is the preferred - reference point for the specified time. - - - - - - - - - - - - - - - -Goland, et al. Standards Track [Page 88] - -RFC 2518 WEBDAV February 1999 - - -23.3 Appendix 3 - Notes on Processing XML Elements - -23.3.1 Notes on Empty XML Elements - - XML supports two mechanisms for indicating that an XML element does - not have any content. The first is to declare an XML element of the - form <A></A>. The second is to declare an XML element of the form - <A/>. The two XML elements are semantically identical. - - It is a violation of the XML specification to use the <A></A> form if - the associated DTD declares the element to be EMPTY (e.g., <!ELEMENT - A EMPTY>). If such a statement is included, then the empty element - format, <A/> must be used. If the element is not declared to be - EMPTY, then either form <A></A> or <A/> may be used for empty - elements. - - 23.3.2 Notes on Illegal XML Processing - - XML is a flexible data format that makes it easy to submit data that - appears legal but in fact is not. The philosophy of "Be flexible in - what you accept and strict in what you send" still applies, but it - must not be applied inappropriately. XML is extremely flexible in - dealing with issues of white space, element ordering, inserting new - elements, etc. This flexibility does not require extension, - especially not in the area of the meaning of elements. - - There is no kindness in accepting illegal combinations of XML - elements. At best it will cause an unwanted result and at worst it - can cause real damage. - -23.3.2.1 Example - XML Syntax Error - - The following request body for a PROPFIND method is illegal. - - <?xml version="1.0" encoding="utf-8" ?> - <D:propfind xmlns:D="DAV:"> - <D:allprop/> - <D:propname/> - </D:propfind> - - The definition of the propfind element only allows for the allprop or - the propname element, not both. Thus the above is an error and must - be responded to with a 400 (Bad Request). - - - - - - - - -Goland, et al. Standards Track [Page 89] - -RFC 2518 WEBDAV February 1999 - - - Imagine, however, that a server wanted to be "kind" and decided to - pick the allprop element as the true element and respond to it. A - client running over a bandwidth limited line who intended to execute - a propname would be in for a big surprise if the server treated the - command as an allprop. - - Additionally, if a server were lenient and decided to reply to this - request, the results would vary randomly from server to server, with - some servers executing the allprop directive, and others executing - the propname directive. This reduces interoperability rather than - increasing it. - -23.3.2.2 Example - Unknown XML Element - - The previous example was illegal because it contained two elements - that were explicitly banned from appearing together in the propfind - element. However, XML is an extensible language, so one can imagine - new elements being defined for use with propfind. Below is the - request body of a PROPFIND and, like the previous example, must be - rejected with a 400 (Bad Request) by a server that does not - understand the expired-props element. - - <?xml version="1.0" encoding="utf-8" ?> - <D:propfind xmlns:D="DAV:" - xmlns:E="http://www.foo.bar/standards/props/"> - <E:expired-props/> - </D:propfind> - - To understand why a 400 (Bad Request) is returned let us look at the - request body as the server unfamiliar with expired-props sees it. - - <?xml version="1.0" encoding="utf-8" ?> - <D:propfind xmlns:D="DAV:" - xmlns:E="http://www.foo.bar/standards/props/"> - </D:propfind> - - As the server does not understand the expired-props element, - according to the WebDAV-specific XML processing rules specified in - section 14, it must ignore it. Thus the server sees an empty - propfind, which by the definition of the propfind element is illegal. - - Please note that had the extension been additive it would not - necessarily have resulted in a 400 (Bad Request). For example, - imagine the following request body for a PROPFIND: - - <?xml version="1.0" encoding="utf-8" ?> - <D:propfind xmlns:D="DAV:" - xmlns:E="http://www.foo.bar/standards/props/"> - - - -Goland, et al. Standards Track [Page 90] - -RFC 2518 WEBDAV February 1999 - - - <D:propname/> - <E:leave-out>*boss*</E:leave-out> - </D:propfind> - - The previous example contains the fictitious element leave-out. Its - purpose is to prevent the return of any property whose name matches - the submitted pattern. If the previous example were submitted to a - server unfamiliar with leave-out, the only result would be that the - leave-out element would be ignored and a propname would be executed. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Goland, et al. Standards Track [Page 91] - -RFC 2518 WEBDAV February 1999 - - -23.4 Appendix 4 -- XML Namespaces for WebDAV - -23.4.1 Introduction - - All DAV compliant systems MUST support the XML namespace extensions - as specified in [REC-XML-NAMES]. - -23.4.2 Meaning of Qualified Names - - [Note to the reader: This section does not appear in [REC-XML-NAMES], - but is necessary to avoid ambiguity for WebDAV XML processors.] - - WebDAV compliant XML processors MUST interpret a qualified name as a - URI constructed by appending the LocalPart to the namespace name URI. - - Example - - <del:glider xmlns:del="http://www.del.jensen.org/"> - <del:glidername> - Johnny Updraft - </del:glidername> - <del:glideraccidents/> - </del:glider> - - In this example, the qualified element name "del:glider" is - interpreted as the URL "http://www.del.jensen.org/glider". - - <bar:glider xmlns:del="http://www.del.jensen.org/"> - <bar:glidername> - Johnny Updraft - </bar:glidername> - <bar:glideraccidents/> - </bar:glider> - - Even though this example is syntactically different from the previous - example, it is semantically identical. Each instance of the - namespace name "bar" is replaced with "http://www.del.jensen.org/" - and then appended to the local name for each element tag. The - resulting tag names in this example are exactly the same as for the - previous example. - - <foo:r xmlns:foo="http://www.del.jensen.org/glide"> - <foo:rname> - Johnny Updraft - </foo:rname> - <foo:raccidents/> - </foo:r> - - - - -Goland, et al. Standards Track [Page 92] - -RFC 2518 WEBDAV February 1999 - - - This example is semantically identical to the two previous ones. - Each instance of the namespace name "foo" is replaced with - "http://www.del.jensen.org/glide" which is then appended to the local - name for each element tag, the resulting tag names are identical to - those in the previous examples. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Goland, et al. Standards Track [Page 93] - -RFC 2518 WEBDAV February 1999 - - -24. Full Copyright Statement - - Copyright (C) The Internet Society (1999). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - - - - - - - - - - - - - -Goland, et al. Standards Track [Page 94] - diff --git a/docs/specs/rfc2616.txt b/docs/specs/rfc2616.txt deleted file mode 100644 index 32f6f69d..00000000 --- a/docs/specs/rfc2616.txt +++ /dev/null @@ -1,9934 +0,0 @@ - -[[ Text in double brackets is from the unofficial errata at ]] -[[ http://skrb.org/ietf/http_errata.html ]] - - -Network Working Group R. Fielding -Request for Comments: 2616 UC Irvine -Obsoletes: 2068 J. Gettys -Category: Standards Track Compaq/W3C - J. Mogul - Compaq - H. Frystyk - W3C/MIT - L. Masinter - Xerox - P. Leach - Microsoft - T. Berners-Lee - W3C/MIT - June 1999 - - - Hypertext Transfer Protocol -- HTTP/1.1 - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (1999). All Rights Reserved. - -Abstract - - The Hypertext Transfer Protocol (HTTP) is an application-level - protocol for distributed, collaborative, hypermedia information - systems. It is a generic, stateless, protocol which can be used for - many tasks beyond its use for hypertext, such as name servers and - distributed object management systems, through extension of its - request methods, error codes and headers [47]. A feature of HTTP is - the typing and negotiation of data representation, allowing systems - to be built independently of the data being transferred. - - HTTP has been in use by the World-Wide Web global information - initiative since 1990. This specification defines the protocol - referred to as "HTTP/1.1", and is an update to RFC 2068 [33]. - - - - - - -Fielding, et al. Standards Track [Page 1] - -RFC 2616 HTTP/1.1 June 1999 - - -Table of Contents - - 1 Introduction ...................................................7 - 1.1 Purpose......................................................7 - 1.2 Requirements .................................................8 - 1.3 Terminology ..................................................8 - 1.4 Overall Operation ...........................................12 - 2 Notational Conventions and Generic Grammar ....................14 - 2.1 Augmented BNF ...............................................14 - 2.2 Basic Rules .................................................15 - 3 Protocol Parameters ...........................................17 - 3.1 HTTP Version ................................................17 - 3.2 Uniform Resource Identifiers ................................18 - 3.2.1 General Syntax ...........................................19 - 3.2.2 http URL .................................................19 - 3.2.3 URI Comparison ...........................................20 - 3.3 Date/Time Formats ...........................................20 - 3.3.1 Full Date ................................................20 - 3.3.2 Delta Seconds ............................................21 - 3.4 Character Sets ..............................................21 - 3.4.1 Missing Charset ..........................................22 - 3.5 Content Codings .............................................23 - 3.6 Transfer Codings ............................................24 - 3.6.1 Chunked Transfer Coding ..................................25 - 3.7 Media Types .................................................26 - 3.7.1 Canonicalization and Text Defaults .......................27 - 3.7.2 Multipart Types ..........................................27 - 3.8 Product Tokens ..............................................28 - 3.9 Quality Values ..............................................29 - 3.10 Language Tags ...............................................29 - 3.11 Entity Tags .................................................30 - 3.12 Range Units .................................................30 - 4 HTTP Message ..................................................31 - 4.1 Message Types ...............................................31 - 4.2 Message Headers .............................................31 - 4.3 Message Body ................................................32 - 4.4 Message Length ..............................................33 - 4.5 General Header Fields .......................................34 - 5 Request .......................................................35 - 5.1 Request-Line ................................................35 - 5.1.1 Method ...................................................36 - 5.1.2 Request-URI ..............................................36 - 5.2 The Resource Identified by a Request ........................38 - 5.3 Request Header Fields .......................................38 - 6 Response ......................................................39 - 6.1 Status-Line .................................................39 - 6.1.1 Status Code and Reason Phrase ............................39 - 6.2 Response Header Fields ......................................41 - - - -Fielding, et al. Standards Track [Page 2] - -RFC 2616 HTTP/1.1 June 1999 - - - 7 Entity ........................................................42 - 7.1 Entity Header Fields ........................................42 - 7.2 Entity Body .................................................43 - 7.2.1 Type .....................................................43 - 7.2.2 Entity Length ............................................43 - 8 Connections ...................................................44 - 8.1 Persistent Connections ......................................44 - 8.1.1 Purpose ..................................................44 - 8.1.2 Overall Operation ........................................45 - 8.1.3 Proxy Servers ............................................46 - 8.1.4 Practical Considerations .................................46 - 8.2 Message Transmission Requirements ...........................47 - 8.2.1 Persistent Connections and Flow Control ..................47 - 8.2.2 Monitoring Connections for Error Status Messages .........48 - 8.2.3 Use of the 100 (Continue) Status .........................48 - 8.2.4 Client Behavior if Server Prematurely Closes Connection ..50 - 9 Method Definitions ............................................51 - 9.1 Safe and Idempotent Methods .................................51 - 9.1.1 Safe Methods .............................................51 - 9.1.2 Idempotent Methods .......................................51 - 9.2 OPTIONS .....................................................52 - 9.3 GET .........................................................53 - 9.4 HEAD ........................................................54 - 9.5 POST ........................................................54 - 9.6 PUT .........................................................55 - 9.7 DELETE ......................................................56 - 9.8 TRACE .......................................................56 - 9.9 CONNECT .....................................................57 - 10 Status Code Definitions ......................................57 - 10.1 Informational 1xx ...........................................57 - 10.1.1 100 Continue .............................................58 - 10.1.2 101 Switching Protocols ..................................58 - 10.2 Successful 2xx ..............................................58 - 10.2.1 200 OK ...................................................58 - 10.2.2 201 Created ..............................................59 - 10.2.3 202 Accepted .............................................59 - 10.2.4 203 Non-Authoritative Information ........................59 - 10.2.5 204 No Content ...........................................60 - 10.2.6 205 Reset Content ........................................60 - 10.2.7 206 Partial Content ......................................60 - 10.3 Redirection 3xx .............................................61 - 10.3.1 300 Multiple Choices .....................................61 - 10.3.2 301 Moved Permanently ....................................62 - 10.3.3 302 Found ................................................62 - 10.3.4 303 See Other ............................................63 - 10.3.5 304 Not Modified .........................................63 - 10.3.6 305 Use Proxy ............................................64 - 10.3.7 306 (Unused) .............................................64 - - - -Fielding, et al. Standards Track [Page 3] - -RFC 2616 HTTP/1.1 June 1999 - - - 10.3.8 307 Temporary Redirect ...................................65 - 10.4 Client Error 4xx ............................................65 - 10.4.1 400 Bad Request .........................................65 - 10.4.2 401 Unauthorized ........................................66 - 10.4.3 402 Payment Required ....................................66 - 10.4.4 403 Forbidden ...........................................66 - 10.4.5 404 Not Found ...........................................66 - 10.4.6 405 Method Not Allowed ..................................66 - 10.4.7 406 Not Acceptable ......................................67 - 10.4.8 407 Proxy Authentication Required .......................67 - 10.4.9 408 Request Timeout .....................................67 - 10.4.10 409 Conflict ............................................67 - 10.4.11 410 Gone ................................................68 - 10.4.12 411 Length Required .....................................68 - 10.4.13 412 Precondition Failed .................................68 - 10.4.14 413 Request Entity Too Large ............................69 - 10.4.15 414 Request-URI Too Long ................................69 - 10.4.16 415 Unsupported Media Type ..............................69 - 10.4.17 416 Requested Range Not Satisfiable .....................69 - 10.4.18 417 Expectation Failed ..................................70 - 10.5 Server Error 5xx ............................................70 - 10.5.1 500 Internal Server Error ................................70 - 10.5.2 501 Not Implemented ......................................70 - 10.5.3 502 Bad Gateway ..........................................70 - 10.5.4 503 Service Unavailable ..................................70 - 10.5.5 504 Gateway Timeout ......................................71 - 10.5.6 505 HTTP Version Not Supported ...........................71 - 11 Access Authentication ........................................71 - 12 Content Negotiation ..........................................71 - 12.1 Server-driven Negotiation ...................................72 - 12.2 Agent-driven Negotiation ....................................73 - 12.3 Transparent Negotiation .....................................74 - 13 Caching in HTTP ..............................................74 - 13.1.1 Cache Correctness ........................................75 - 13.1.2 Warnings .................................................76 - 13.1.3 Cache-control Mechanisms .................................77 - 13.1.4 Explicit User Agent Warnings .............................78 - 13.1.5 Exceptions to the Rules and Warnings .....................78 - 13.1.6 Client-controlled Behavior ...............................79 - 13.2 Expiration Model ............................................79 - 13.2.1 Server-Specified Expiration ..............................79 - 13.2.2 Heuristic Expiration .....................................80 - 13.2.3 Age Calculations .........................................80 - 13.2.4 Expiration Calculations ..................................83 - 13.2.5 Disambiguating Expiration Values .........................84 - 13.2.6 Disambiguating Multiple Responses ........................84 - 13.3 Validation Model ............................................85 - 13.3.1 Last-Modified Dates ......................................86 - - - -Fielding, et al. Standards Track [Page 4] - -RFC 2616 HTTP/1.1 June 1999 - - - 13.3.2 Entity Tag Cache Validators ..............................86 - 13.3.3 Weak and Strong Validators ...............................86 - 13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates.89 - 13.3.5 Non-validating Conditionals ..............................90 - 13.4 Response Cacheability .......................................91 - 13.5 Constructing Responses From Caches ..........................92 - 13.5.1 End-to-end and Hop-by-hop Headers ........................92 - 13.5.2 Non-modifiable Headers ...................................92 - 13.5.3 Combining Headers ........................................94 - 13.5.4 Combining Byte Ranges ....................................95 - 13.6 Caching Negotiated Responses ................................95 - 13.7 Shared and Non-Shared Caches ................................96 - 13.8 Errors or Incomplete Response Cache Behavior ................97 - 13.9 Side Effects of GET and HEAD ................................97 - 13.10 Invalidation After Updates or Deletions ...................97 - 13.11 Write-Through Mandatory ...................................98 - 13.12 Cache Replacement .........................................99 - 13.13 History Lists .............................................99 - 14 Header Field Definitions ....................................100 - 14.1 Accept .....................................................100 - 14.2 Accept-Charset .............................................102 - 14.3 Accept-Encoding ............................................102 - 14.4 Accept-Language ............................................104 - 14.5 Accept-Ranges ..............................................105 - 14.6 Age ........................................................106 - 14.7 Allow ......................................................106 - 14.8 Authorization ..............................................107 - 14.9 Cache-Control ..............................................108 - 14.9.1 What is Cacheable .......................................109 - 14.9.2 What May be Stored by Caches ............................110 - 14.9.3 Modifications of the Basic Expiration Mechanism .........111 - 14.9.4 Cache Revalidation and Reload Controls ..................113 - 14.9.5 No-Transform Directive ..................................115 - 14.9.6 Cache Control Extensions ................................116 - 14.10 Connection ...............................................117 - 14.11 Content-Encoding .........................................118 - 14.12 Content-Language .........................................118 - 14.13 Content-Length ...........................................119 - 14.14 Content-Location .........................................120 - 14.15 Content-MD5 ..............................................121 - 14.16 Content-Range ............................................122 - 14.17 Content-Type .............................................124 - 14.18 Date .....................................................124 - 14.18.1 Clockless Origin Server Operation ......................125 - 14.19 ETag .....................................................126 - 14.20 Expect ...................................................126 - 14.21 Expires ..................................................127 - 14.22 From .....................................................128 - - - -Fielding, et al. Standards Track [Page 5] - -RFC 2616 HTTP/1.1 June 1999 - - - 14.23 Host .....................................................128 - 14.24 If-Match .................................................129 - 14.25 If-Modified-Since ........................................130 - 14.26 If-None-Match ............................................132 - 14.27 If-Range .................................................133 - 14.28 If-Unmodified-Since ......................................134 - 14.29 Last-Modified ............................................134 - 14.30 Location .................................................135 - 14.31 Max-Forwards .............................................136 - 14.32 Pragma ...................................................136 - 14.33 Proxy-Authenticate .......................................137 - 14.34 Proxy-Authorization ......................................137 - 14.35 Range ....................................................138 - 14.35.1 Byte Ranges ...........................................138 - 14.35.2 Range Retrieval Requests ..............................139 - 14.36 Referer ..................................................140 - 14.37 Retry-After ..............................................141 - 14.38 Server ...................................................141 - 14.39 TE .......................................................142 - 14.40 Trailer ..................................................143 - 14.41 Transfer-Encoding..........................................143 - 14.42 Upgrade ..................................................144 - 14.43 User-Agent ...............................................145 - 14.44 Vary .....................................................145 - 14.45 Via ......................................................146 - 14.46 Warning ..................................................148 - 14.47 WWW-Authenticate .........................................150 - 15 Security Considerations .......................................150 - 15.1 Personal Information....................................151 - 15.1.1 Abuse of Server Log Information .........................151 - 15.1.2 Transfer of Sensitive Information .......................151 - 15.1.3 Encoding Sensitive Information in URI's .................152 - 15.1.4 Privacy Issues Connected to Accept Headers ..............152 - 15.2 Attacks Based On File and Path Names .......................153 - 15.3 DNS Spoofing ...............................................154 - 15.4 Location Headers and Spoofing ..............................154 - 15.5 Content-Disposition Issues .................................154 - 15.6 Authentication Credentials and Idle Clients ................155 - 15.7 Proxies and Caching ........................................155 - 15.7.1 Denial of Service Attacks on Proxies....................156 - 16 Acknowledgments .............................................156 - 17 References ..................................................158 - 18 Authors' Addresses ..........................................162 - 19 Appendices ..................................................164 - 19.1 Internet Media Type message/http and application/http ......164 - 19.2 Internet Media Type multipart/byteranges ...................165 - 19.3 Tolerant Applications ......................................166 - 19.4 Differences Between HTTP Entities and RFC 2045 Entities ....167 - - - -Fielding, et al. Standards Track [Page 6] - -RFC 2616 HTTP/1.1 June 1999 - - - 19.4.1 MIME-Version ............................................167 - 19.4.2 Conversion to Canonical Form ............................167 - 19.4.3 Conversion of Date Formats ..............................168 - 19.4.4 Introduction of Content-Encoding ........................168 - 19.4.5 No Content-Transfer-Encoding ............................168 - 19.4.6 Introduction of Transfer-Encoding .......................169 - 19.4.7 MHTML and Line Length Limitations .......................169 - 19.5 Additional Features ........................................169 - 19.5.1 Content-Disposition .....................................170 - 19.6 Compatibility with Previous Versions .......................170 - 19.6.1 Changes from HTTP/1.0 ...................................171 - 19.6.2 Compatibility with HTTP/1.0 Persistent Connections ......172 - 19.6.3 Changes from RFC 2068 ...................................172 - 20 Index .......................................................175 - 21 Full Copyright Statement ....................................176 - -1 Introduction - -1.1 Purpose - - The Hypertext Transfer Protocol (HTTP) is an application-level - protocol for distributed, collaborative, hypermedia information - systems. HTTP has been in use by the World-Wide Web global - information initiative since 1990. The first version of HTTP, - referred to as HTTP/0.9, was a simple protocol for raw data transfer - across the Internet. HTTP/1.0, as defined by RFC 1945 [6], improved - the protocol by allowing messages to be in the format of MIME-like - messages, containing metainformation about the data transferred and - modifiers on the request/response semantics. However, HTTP/1.0 does - not sufficiently take into consideration the effects of hierarchical - proxies, caching, the need for persistent connections, or virtual - hosts. In addition, the proliferation of incompletely-implemented - applications calling themselves "HTTP/1.0" has necessitated a - protocol version change in order for two communicating applications - to determine each other's true capabilities. - - This specification defines the protocol referred to as "HTTP/1.1". - This protocol includes more stringent requirements than HTTP/1.0 in - order to ensure reliable implementation of its features. - - Practical information systems require more functionality than simple - retrieval, including search, front-end update, and annotation. HTTP - allows an open-ended set of methods and headers that indicate the - purpose of a request [47]. It builds on the discipline of reference - provided by the Uniform Resource Identifier (URI) [3], as a location - (URL) [4] or name (URN) [20], for indicating the resource to which a - - - - - -Fielding, et al. Standards Track [Page 7] - -RFC 2616 HTTP/1.1 June 1999 - - - method is to be applied. Messages are passed in a format similar to - that used by Internet mail [9] as defined by the Multipurpose - Internet Mail Extensions (MIME) [7]. - - HTTP is also used as a generic protocol for communication between - user agents and proxies/gateways to other Internet systems, including - those supported by the SMTP [16], NNTP [13], FTP [18], Gopher [2], - and WAIS [10] protocols. In this way, HTTP allows basic hypermedia - access to resources available from diverse applications. - -1.2 Requirements - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in RFC 2119 [34]. - - An implementation is not compliant if it fails to satisfy one or more - of the MUST or REQUIRED level requirements for the protocols it - implements. An implementation that satisfies all the MUST or REQUIRED - level and all the SHOULD level requirements for its protocols is said - to be "unconditionally compliant"; one that satisfies all the MUST - level requirements but not all the SHOULD level requirements for its - protocols is said to be "conditionally compliant." - -1.3 Terminology - - This specification uses a number of terms to refer to the roles - played by participants in, and objects of, the HTTP communication. - - connection - A transport layer virtual circuit established between two programs - for the purpose of communication. - - message - The basic unit of HTTP communication, consisting of a structured - sequence of octets matching the syntax defined in section 4 and - transmitted via the connection. - - request - An HTTP request message, as defined in section 5. - - response - An HTTP response message, as defined in section 6. - - - - - - - - -Fielding, et al. Standards Track [Page 8] - -RFC 2616 HTTP/1.1 June 1999 - - - resource - A network data object or service that can be identified by a URI, - as defined in section 3.2. Resources may be available in multiple - representations (e.g. multiple languages, data formats, size, and - resolutions) or vary in other ways. - - entity - The information transferred as the payload of a request or - response. An entity consists of metainformation in the form of - entity-header fields and content in the form of an entity-body, as - described in section 7. - - representation - An entity included with a response that is subject to content - negotiation, as described in section 12. There may exist multiple - representations associated with a particular response status. - - content negotiation - The mechanism for selecting the appropriate representation when - servicing a request, as described in section 12. The - representation of entities in any response can be negotiated - (including error responses). - - variant - A resource may have one, or more than one, representation(s) - associated with it at any given instant. Each of these - representations is termed a `varriant'. Use of the term `variant' - does not necessarily imply that the resource is subject to content - negotiation. - - client - A program that establishes connections for the purpose of sending - requests. - - user agent - The client which initiates a request. These are often browsers, - editors, spiders (web-traversing robots), or other end user tools. - - server - An application program that accepts connections in order to - service requests by sending back responses. Any given program may - be capable of being both a client and a server; our use of these - terms refers only to the role being performed by the program for a - particular connection, rather than to the program's capabilities - in general. Likewise, any server may act as an origin server, - proxy, gateway, or tunnel, switching behavior based on the nature - of each request. - - - - -Fielding, et al. Standards Track [Page 9] - -RFC 2616 HTTP/1.1 June 1999 - - - origin server - The server on which a given resource resides or is to be created. - - proxy - An intermediary program which acts as both a server and a client - for the purpose of making requests on behalf of other clients. - Requests are serviced internally or by passing them on, with - possible translation, to other servers. A proxy MUST implement - both the client and server requirements of this specification. A - "transparent proxy" is a proxy that does not modify the request or - response beyond what is required for proxy authentication and - identification. A "non-transparent proxy" is a proxy that modifies - the request or response in order to provide some added service to - the user agent, such as group annotation services, media type - transformation, protocol reduction, or anonymity filtering. Except - where either transparent or non-transparent behavior is explicitly - stated, the HTTP proxy requirements apply to both types of - proxies. - - gateway - A server which acts as an intermediary for some other server. - Unlike a proxy, a gateway receives requests as if it were the - origin server for the requested resource; the requesting client - may not be aware that it is communicating with a gateway. - - tunnel - An intermediary program which is acting as a blind relay between - two connections. Once active, a tunnel is not considered a party - to the HTTP communication, though the tunnel may have been - initiated by an HTTP request. The tunnel ceases to exist when both - ends of the relayed connections are closed. - - cache - A program's local store of response messages and the subsystem - that controls its message storage, retrieval, and deletion. A - cache stores cacheable responses in order to reduce the response - time and network bandwidth consumption on future, equivalent - requests. Any client or server may include a cache, though a cache - cannot be used by a server that is acting as a tunnel. - - cacheable - A response is cacheable if a cache is allowed to store a copy of - the response message for use in answering subsequent requests. The - rules for determining the cacheability of HTTP responses are - defined in section 13. Even if a resource is cacheable, there may - be additional constraints on whether a cache can use the cached - copy for a particular request. - - - - -Fielding, et al. Standards Track [Page 10] - -RFC 2616 HTTP/1.1 June 1999 - - - first-hand - A response is first-hand if it comes directly and without - unnecessary delay from the origin server, perhaps via one or more - proxies. A response is also first-hand if its validity has just - been checked directly with the origin server. - - explicit expiration time - The time at which the origin server intends that an entity should - no longer be returned by a cache without further validation. - - heuristic expiration time - An expiration time assigned by a cache when no explicit expiration - time is available. - - age - The age of a response is the time since it was sent by, or - successfully validated with, the origin server. - - freshness lifetime - The length of time between the generation of a response and its - expiration time. - - fresh - A response is fresh if its age has not yet exceeded its freshness - lifetime. - - stale - A response is stale if its age has passed its freshness lifetime. - - semantically transparent - A cache behaves in a "semantically transparent" manner, with - respect to a particular response, when its use affects neither the - requesting client nor the origin server, except to improve - performance. When a cache is semantically transparent, the client - receives exactly the same response (except for hop-by-hop headers) - that it would have received had its request been handled directly - by the origin server. - - validator - A protocol element (e.g., an entity tag or a Last-Modified time) - that is used to find out whether a cache entry is an equivalent - copy of an entity. - - upstream/downstream - Upstream and downstream describe the flow of a message: all - messages flow from upstream to downstream. - - - - - -Fielding, et al. Standards Track [Page 11] - -RFC 2616 HTTP/1.1 June 1999 - - - inbound/outbound - Inbound and outbound refer to the request and response paths for - messages: "inbound" means "traveling toward the origin server", - and "outbound" means "traveling toward the user agent" - -1.4 Overall Operation - - The HTTP protocol is a request/response protocol. A client sends a - request to the server in the form of a request method, URI, and - protocol version, followed by a MIME-like message containing request - modifiers, client information, and possible body content over a - connection with a server. The server responds with a status line, - including the message's protocol version and a success or error code, - followed by a MIME-like message containing server information, entity - metainformation, and possible entity-body content. The relationship - between HTTP and MIME is described in appendix 19.4. - - Most HTTP communication is initiated by a user agent and consists of - a request to be applied to a resource on some origin server. In the - simplest case, this may be accomplished via a single connection (v) - between the user agent (UA) and the origin server (O). - - request chain ------------------------> - UA -------------------v------------------- O - <----------------------- response chain - - A more complicated situation occurs when one or more intermediaries - are present in the request/response chain. There are three common - forms of intermediary: proxy, gateway, and tunnel. A proxy is a - forwarding agent, receiving requests for a URI in its absolute form, - rewriting all or part of the message, and forwarding the reformatted - request toward the server identified by the URI. A gateway is a - receiving agent, acting as a layer above some other server(s) and, if - necessary, translating the requests to the underlying server's - protocol. A tunnel acts as a relay point between two connections - without changing the messages; tunnels are used when the - communication needs to pass through an intermediary (such as a - firewall) even when the intermediary cannot understand the contents - of the messages. - - request chain --------------------------------------> - UA -----v----- A -----v----- B -----v----- C -----v----- O - <------------------------------------- response chain - - The figure above shows three intermediaries (A, B, and C) between the - user agent and origin server. A request or response message that - travels the whole chain will pass through four separate connections. - This distinction is important because some HTTP communication options - - - -Fielding, et al. Standards Track [Page 12] - -RFC 2616 HTTP/1.1 June 1999 - - - may apply only to the connection with the nearest, non-tunnel - neighbor, only to the end-points of the chain, or to all connections - along the chain. Although the diagram is linear, each participant may - be engaged in multiple, simultaneous communications. For example, B - may be receiving requests from many clients other than A, and/or - forwarding requests to servers other than C, at the same time that it - is handling A's request. - - Any party to the communication which is not acting as a tunnel may - employ an internal cache for handling requests. The effect of a cache - is that the request/response chain is shortened if one of the - participants along the chain has a cached response applicable to that - request. The following illustrates the resulting chain if B has a - cached copy of an earlier response from O (via C) for a request which - has not been cached by UA or A. - - request chain ----------> - UA -----v----- A -----v----- B - - - - - - C - - - - - - O - <--------- response chain - - Not all responses are usefully cacheable, and some requests may - contain modifiers which place special requirements on cache behavior. - HTTP requirements for cache behavior and cacheable responses are - defined in section 13. - - In fact, there are a wide variety of architectures and configurations - of caches and proxies currently being experimented with or deployed - across the World Wide Web. These systems include national hierarchies - of proxy caches to save transoceanic bandwidth, systems that - broadcast or multicast cache entries, organizations that distribute - subsets of cached data via CD-ROM, and so on. HTTP systems are used - in corporate intranets over high-bandwidth links, and for access via - PDAs with low-power radio links and intermittent connectivity. The - goal of HTTP/1.1 is to support the wide diversity of configurations - already deployed while introducing protocol constructs that meet the - needs of those who build web applications that require high - reliability and, failing that, at least reliable indications of - failure. - - HTTP communication usually takes place over TCP/IP connections. The - default port is TCP 80 [19], but other ports can be used. This does - not preclude HTTP from being implemented on top of any other protocol - on the Internet, or on other networks. HTTP only presumes a reliable - transport; any protocol that provides such guarantees can be used; - the mapping of the HTTP/1.1 request and response structures onto the - transport data units of the protocol in question is outside the scope - of this specification. - - - - -Fielding, et al. Standards Track [Page 13] - -RFC 2616 HTTP/1.1 June 1999 - - - In HTTP/1.0, most implementations used a new connection for each - request/response exchange. In HTTP/1.1, a connection may be used for - one or more request/response exchanges, although connections may be - closed for a variety of reasons (see section 8.1). - -2 Notational Conventions and Generic Grammar - -2.1 Augmented BNF - - All of the mechanisms specified in this document are described in - both prose and an augmented Backus-Naur Form (BNF) similar to that - used by RFC 822 [9]. Implementors will need to be familiar with the - notation in order to understand this specification. The augmented BNF - includes the following constructs: - - name = definition - The name of a rule is simply the name itself (without any - enclosing "<" and ">") and is separated from its definition by the - equal "=" character. White space is only significant in that - indentation of continuation lines is used to indicate a rule - definition that spans more than one line. Certain basic rules are - in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle - brackets are used within definitions whenever their presence will - facilitate discerning the use of rule names. - - "literal" - Quotation marks surround literal text. Unless stated otherwise, - the text is case-insensitive. - - rule1 | rule2 - Elements separated by a bar ("|") are alternatives, e.g., "yes | - no" will accept yes or no. - - (rule1 rule2) - Elements enclosed in parentheses are treated as a single element. - Thus, "(elem (foo | bar) elem)" allows the token sequences "elem - foo elem" and "elem bar elem". - - *rule - The character "*" preceding an element indicates repetition. The - full form is "<n>*<m>element" indicating at least <n> and at most - <m> occurrences of element. Default values are 0 and infinity so - that "*(element)" allows any number, including zero; "1*element" - requires at least one; and "1*2element" allows one or two. - - [rule] - Square brackets enclose optional elements; "[foo bar]" is - equivalent to "*1(foo bar)". - - - -Fielding, et al. Standards Track [Page 14] - -RFC 2616 HTTP/1.1 June 1999 - - - N rule - Specific repetition: "<n>(element)" is equivalent to - "<n>*<n>(element)"; that is, exactly <n> occurrences of (element). - Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three - alphabetic characters. - - #rule - A construct "#" is defined, similar to "*", for defining lists of - elements. The full form is "<n>#<m>element" indicating at least - <n> and at most <m> elements, each separated by one or more commas - (",") and OPTIONAL linear white space (LWS). This makes the usual - form of lists very easy; a rule such as - ( *LWS element *( *LWS "," *LWS element )) - can be shown as - 1#element - Wherever this construct is used, null elements are allowed, but do - not contribute to the count of elements present. That is, - "(element), , (element) " is permitted, but counts as only two - elements. Therefore, where at least one element is required, at - least one non-null element MUST be present. Default values are 0 - and infinity so that "#element" allows any number, including zero; - "1#element" requires at least one; and "1#2element" allows one or - two. - - ; comment - A semi-colon, set off some distance to the right of rule text, - starts a comment that continues to the end of line. This is a - simple way of including useful notes in parallel with the - specifications. - - implied *LWS - The grammar described by this specification is word-based. Except - where noted otherwise, linear white space (LWS) can be included - between any two adjacent words (token or quoted-string), and - between adjacent words and separators, without changing the - interpretation of a field. At least one delimiter (LWS and/or - - separators) MUST exist between any two tokens (for the definition - of "token" below), since they would otherwise be interpreted as a - single token. - -2.2 Basic Rules - - The following rules are used throughout this specification to - describe basic parsing constructs. The US-ASCII coded character set - is defined by ANSI X3.4-1986 [21]. - - - - - -Fielding, et al. Standards Track [Page 15] - -RFC 2616 HTTP/1.1 June 1999 - - - OCTET = <any 8-bit sequence of data> - CHAR = <any US-ASCII character (octets 0 - 127)> - UPALPHA = <any US-ASCII uppercase letter "A".."Z"> - LOALPHA = <any US-ASCII lowercase letter "a".."z"> - ALPHA = UPALPHA | LOALPHA - DIGIT = <any US-ASCII digit "0".."9"> - CTL = <any US-ASCII control character - (octets 0 - 31) and DEL (127)> - CR = <US-ASCII CR, carriage return (13)> - LF = <US-ASCII LF, linefeed (10)> - SP = <US-ASCII SP, space (32)> - HT = <US-ASCII HT, horizontal-tab (9)> - <"> = <US-ASCII double-quote mark (34)> - - HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all - protocol elements except the entity-body (see appendix 19.3 for - tolerant applications). The end-of-line marker within an entity-body - is defined by its associated media type, as described in section 3.7. - - CRLF = CR LF - - HTTP/1.1 header field values can be folded onto multiple lines if the - continuation line begins with a space or horizontal tab. All linear - white space, including folding, has the same semantics as SP. A - recipient MAY replace any linear white space with a single SP before - interpreting the field value or forwarding the message downstream. - - LWS = [CRLF] 1*( SP | HT ) - - The TEXT rule is only used for descriptive field contents and values - that are not intended to be interpreted by the message parser. Words - of *TEXT MAY contain characters from character sets other than ISO- - 8859-1 [22] only when encoded according to the rules of RFC 2047 - [14]. - - TEXT = <any OCTET except CTLs, - but including LWS> - - A CRLF is allowed in the definition of TEXT only as part of a header - field continuation. It is expected that the folding LWS will be - replaced with a single SP before interpretation of the TEXT value. - - Hexadecimal numeric characters are used in several protocol elements. - - HEX = "A" | "B" | "C" | "D" | "E" | "F" - | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT - - - - - -Fielding, et al. Standards Track [Page 16] - -RFC 2616 HTTP/1.1 June 1999 - - - Many HTTP/1.1 header field values consist of words separated by LWS - or special characters. These special characters MUST be in a quoted - string to be used within a parameter value (as defined in section - 3.6). - - token = 1*<any CHAR except CTLs or separators> - separators = "(" | ")" | "<" | ">" | "@" - | "," | ";" | ":" | "\" | <"> - | "/" | "[" | "]" | "?" | "=" - | "{" | "}" | SP | HT - - Comments can be included in some HTTP header fields by surrounding - the comment text with parentheses. Comments are only allowed in - fields containing "comment" as part of their field value definition. - In all other fields, parentheses are considered part of the field - value. - - comment = "(" *( ctext | quoted-pair | comment ) ")" - ctext = <any TEXT excluding "(" and ")"> - - A string of text is parsed as a single word if it is quoted using - double-quote marks. - - quoted-string = ( <"> *(qdtext | quoted-pair ) <"> ) - qdtext = <any TEXT except <">> - - The backslash character ("\") MAY be used as a single-character - quoting mechanism only within quoted-string and comment constructs. - - quoted-pair = "\" CHAR - -3 Protocol Parameters - -3.1 HTTP Version - - HTTP uses a "<major>.<minor>" numbering scheme to indicate versions - of the protocol. The protocol versioning policy is intended to allow - the sender to indicate the format of a message and its capacity for - understanding further HTTP communication, rather than the features - obtained via that communication. No change is made to the version - number for the addition of message components which do not affect - communication behavior or which only add to extensible field values. - The <minor> number is incremented when the changes made to the - protocol add features which do not change the general message parsing - algorithm, but which may add to the message semantics and imply - additional capabilities of the sender. The <major> number is - incremented when the format of a message within the protocol is - changed. See RFC 2145 [36] for a fuller explanation. - - - -Fielding, et al. Standards Track [Page 17] - -RFC 2616 HTTP/1.1 June 1999 - - - The version of an HTTP message is indicated by an HTTP-Version field - in the first line of the message. [[HTTP-Version is case-sensitive.]] - - HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT - - Note that the major and minor numbers MUST be treated as separate - integers and that each MAY be incremented higher than a single digit. - Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is - lower than HTTP/12.3. Leading zeros MUST be ignored by recipients and - MUST NOT be sent. - - An application that sends a request or response message that includes - HTTP-Version of "HTTP/1.1" MUST be at least conditionally compliant - with this specification. Applications that are at least conditionally - compliant with this specification SHOULD use an HTTP-Version of - "HTTP/1.1" in their messages, and MUST do so for any message that is - not compatible with HTTP/1.0. For more details on when to send - specific HTTP-Version values, see RFC 2145 [36]. - - The HTTP version of an application is the highest HTTP version for - which the application is at least conditionally compliant. - - Proxy and gateway applications need to be careful when forwarding - messages in protocol versions different from that of the application. - Since the protocol version indicates the protocol capability of the - sender, a proxy/gateway MUST NOT send a message with a version - indicator which is greater than its actual version. If a higher - version request is received, the proxy/gateway MUST either downgrade - the request version, or respond with an error, or switch to tunnel - behavior. - - Due to interoperability problems with HTTP/1.0 proxies discovered - since the publication of RFC 2068[33], caching proxies MUST, gateways - MAY, and tunnels MUST NOT upgrade the request to the highest version - they support. The proxy/gateway's response to that request MUST be in - the same major version as the request. - - Note: Converting between versions of HTTP may involve modification - of header fields required or forbidden by the versions involved. - -3.2 Uniform Resource Identifiers - - URIs have been known by many names: WWW addresses, Universal Document - Identifiers, Universal Resource Identifiers [3], and finally the - combination of Uniform Resource Locators (URL) [4] and Names (URN) - [20]. As far as HTTP is concerned, Uniform Resource Identifiers are - simply formatted strings which identify--via name, location, or any - other characteristic--a resource. - - - -Fielding, et al. Standards Track [Page 18] - -RFC 2616 HTTP/1.1 June 1999 - - -3.2.1 General Syntax - - URIs in HTTP can be represented in absolute form or relative to some - known base URI [11], depending upon the context of their use. The two - forms are differentiated by the fact that absolute URIs always begin - with a scheme name followed by a colon. For definitive information on - URL syntax and semantics, see "Uniform Resource Identifiers (URI): - Generic Syntax and Semantics," RFC 2396 [42] (which replaces RFCs - 1738 [4] and RFC 1808 [11]). This specification adopts the - definitions of "URI-reference", "absoluteURI", "relativeURI", "port", - "host","abs_path", "rel_path", and "authority" from that - specification. - - The HTTP protocol does not place any a priori limit on the length of - a URI. Servers MUST be able to handle the URI of any resource they - serve, and SHOULD be able to handle URIs of unbounded length if they - provide GET-based forms that could generate such URIs. A server - SHOULD return 414 (Request-URI Too Long) status if a URI is longer - than the server can handle (see section 10.4.15). - - Note: Servers ought to be cautious about depending on URI lengths - above 255 bytes, because some older client or proxy - implementations might not properly support these lengths. - -3.2.2 http URL - - The "http" scheme is used to locate network resources via the HTTP - protocol. This section defines the scheme-specific syntax and - semantics for http URLs. - - http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]] - - If the port is empty or not given, port 80 is assumed. The semantics - are that the identified resource is located at the server listening - for TCP connections on that port of that host, and the Request-URI - for the resource is abs_path (section 5.1.2). The use of IP addresses - in URLs SHOULD be avoided whenever possible (see RFC 1900 [24]). If - the abs_path is not present in the URL, it MUST be given as "/" when - used as a Request-URI for a resource (section 5.1.2). If a proxy - receives a host name which is not a fully qualified domain name, it - MAY add its domain to the host name it received. If a proxy receives - a fully qualified domain name, the proxy MUST NOT change the host - name. - - - - - - - - -Fielding, et al. Standards Track [Page 19] - -RFC 2616 HTTP/1.1 June 1999 - - -3.2.3 URI Comparison - - When comparing two URIs to decide if they match or not, a client - SHOULD use a case-sensitive octet-by-octet comparison of the entire - URIs, with these exceptions: - - - A port that is empty or not given is equivalent to the default - port for that URI-reference; - - - Comparisons of host names MUST be case-insensitive; - - - Comparisons of scheme names MUST be case-insensitive; - - - An empty abs_path is equivalent to an abs_path of "/". - - Characters other than those in the "reserved" and "unsafe" sets (see - RFC 2396 [42]) are equivalent to their ""%" HEX HEX" encoding. - [[ Ignore reference to "unsafe" set. ]] - - For example, the following three URIs are equivalent: - - http://abc.com:80/~smith/home.html - http://ABC.com/%7Esmith/home.html - http://ABC.com:/%7esmith/home.html - -3.3 Date/Time Formats - -3.3.1 Full Date - - HTTP applications have historically allowed three different formats - for the representation of date/time stamps: - - Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 - Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 - Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format - - The first format is preferred as an Internet standard and represents - a fixed-length subset of that defined by RFC 1123 [8] (an update to - RFC 822 [9]). The second format is in common use, but is based on the - obsolete RFC 850 [12] date format and lacks a four-digit year. - HTTP/1.1 clients and servers that parse the date value MUST accept - all three formats (for compatibility with HTTP/1.0), though they MUST - only generate the RFC 1123 format for representing HTTP-date values - in header fields. See section 19.3 for further information. - - Note: Recipients of date values are encouraged to be robust in - accepting date values that may have been sent by non-HTTP - applications, as is sometimes the case when retrieving or posting - messages via proxies/gateways to SMTP or NNTP. - - - -Fielding, et al. Standards Track [Page 20] - -RFC 2616 HTTP/1.1 June 1999 - - - All HTTP date/time stamps MUST be represented in Greenwich Mean Time - (GMT), without exception. For the purposes of HTTP, GMT is exactly - equal to UTC (Coordinated Universal Time). This is indicated in the - first two formats by the inclusion of "GMT" as the three-letter - abbreviation for time zone, and MUST be assumed when reading the - asctime format. HTTP-date is case sensitive and MUST NOT include - additional LWS beyond that specifically included as SP in the - grammar. - - HTTP-date = rfc1123-date | rfc850-date | asctime-date - rfc1123-date = wkday "," SP date1 SP time SP "GMT" - rfc850-date = weekday "," SP date2 SP time SP "GMT" - asctime-date = wkday SP date3 SP time SP 4DIGIT - date1 = 2DIGIT SP month SP 4DIGIT - ; day month year (e.g., 02 Jun 1982) - date2 = 2DIGIT "-" month "-" 2DIGIT - ; day-month-year (e.g., 02-Jun-82) - date3 = month SP ( 2DIGIT | ( SP 1DIGIT )) - ; month day (e.g., Jun 2) - time = 2DIGIT ":" 2DIGIT ":" 2DIGIT - ; 00:00:00 - 23:59:59 - wkday = "Mon" | "Tue" | "Wed" - | "Thu" | "Fri" | "Sat" | "Sun" - weekday = "Monday" | "Tuesday" | "Wednesday" - | "Thursday" | "Friday" | "Saturday" | "Sunday" - month = "Jan" | "Feb" | "Mar" | "Apr" - | "May" | "Jun" | "Jul" | "Aug" - | "Sep" | "Oct" | "Nov" | "Dec" - - Note: HTTP requirements for the date/time stamp format apply only - to their usage within the protocol stream. Clients and servers are - not required to use these formats for user presentation, request - logging, etc. - -3.3.2 Delta Seconds - - Some HTTP header fields allow a time value to be specified as an - integer number of seconds, represented in decimal, after the time - that the message was received. - - delta-seconds = 1*DIGIT - -3.4 Character Sets - - HTTP uses the same definition of the term "character set" as that - described for MIME: - - - - - -Fielding, et al. Standards Track [Page 21] - -RFC 2616 HTTP/1.1 June 1999 - - - The term "character set" is used in this document to refer to a - method used with one or more tables to convert a sequence of octets - into a sequence of characters. Note that unconditional conversion in - the other direction is not required, in that not all characters may - be available in a given character set and a character set may provide - more than one sequence of octets to represent a particular character. - This definition is intended to allow various kinds of character - encoding, from simple single-table mappings such as US-ASCII to - complex table switching methods such as those that use ISO-2022's - techniques. However, the definition associated with a MIME character - set name MUST fully specify the mapping to be performed from octets - to characters. In particular, use of external profiling information - to determine the exact mapping is not permitted. - - Note: This use of the term "character set" is more commonly - referred to as a "character encoding." However, since HTTP and - MIME share the same registry, it is important that the terminology - also be shared. - - HTTP character sets are identified by case-insensitive tokens. The - complete set of tokens is defined by the IANA Character Set registry - [19]. - - charset = token - -[[ HTTP uses charset in two contexts: within an Accept-Charset request ]] -[[ header (in which the charset value is an unquoted token) and as the ]] -[[ value of a parameter in a Content-type header (within a request or ]] -[[ response), in which case the parameter value of the charset ]] -[[ parameter may be quoted. ]] - - Although HTTP allows an arbitrary token to be used as a charset - value, any token that has a predefined value within the IANA - Character Set registry [19] MUST represent the character set defined - by that registry. Applications SHOULD limit their use of character - sets to those defined by the IANA registry. - - Implementors should be aware of IETF character set requirements [38] - [41]. - -3.4.1 Missing Charset - - Some HTTP/1.0 software has interpreted a Content-Type header without - charset parameter incorrectly to mean "recipient should guess." - Senders wishing to defeat this behavior MAY include a charset - parameter even when the charset is ISO-8859-1 and SHOULD do so when - it is known that it will not confuse the recipient. - - Unfortunately, some older HTTP/1.0 clients did not deal properly with - an explicit charset parameter. HTTP/1.1 recipients MUST respect the - charset label provided by the sender; and those user agents that have - a provision to "guess" a charset MUST use the charset from the - - - - - -Fielding, et al. Standards Track [Page 22] - -RFC 2616 HTTP/1.1 June 1999 - - - content-type field if they support that charset, rather than the - recipient's preference, when initially displaying a document. See - section 3.7.1. - -3.5 Content Codings - - Content coding values indicate an encoding transformation that has - been or can be applied to an entity. Content codings are primarily - used to allow a document to be compressed or otherwise usefully - transformed without losing the identity of its underlying media type - and without loss of information. Frequently, the entity is stored in - coded form, transmitted directly, and only decoded by the recipient. - - content-coding = token - - All content-coding values are case-insensitive. HTTP/1.1 uses - content-coding values in the Accept-Encoding (section 14.3) and - Content-Encoding (section 14.11) header fields. Although the value - describes the content-coding, what is more important is that it - indicates what decoding mechanism will be required to remove the - encoding. - - The Internet Assigned Numbers Authority (IANA) acts as a registry for - content-coding value tokens. Initially, the registry contains the - following tokens: - - gzip An encoding format produced by the file compression program - "gzip" (GNU zip) as described in RFC 1952 [25]. This format is a - Lempel-Ziv coding (LZ77) with a 32 bit CRC. - - compress - The encoding format produced by the common UNIX file compression - program "compress". This format is an adaptive Lempel-Ziv-Welch - coding (LZW). - - Use of program names for the identification of encoding formats - is not desirable and is discouraged for future encodings. Their - use here is representative of historical practice, not good - design. For compatibility with previous implementations of HTTP, - applications SHOULD consider "x-gzip" and "x-compress" to be - equivalent to "gzip" and "compress" respectively. - - deflate - The "zlib" format defined in RFC 1950 [31] in combination with - the "deflate" compression mechanism described in RFC 1951 [29]. - - - - - - -Fielding, et al. Standards Track [Page 23] - -RFC 2616 HTTP/1.1 June 1999 - - - identity - The default (identity) encoding; the use of no transformation - whatsoever. This content-coding is used only in the Accept- - Encoding header, and SHOULD NOT be used in the Content-Encoding - header. - - New content-coding value tokens SHOULD be registered; to allow - interoperability between clients and servers, specifications of the - content coding algorithms needed to implement a new value SHOULD be - publicly available and adequate for independent implementation, and - conform to the purpose of content coding defined in this section. - -3.6 Transfer Codings - - Transfer-coding values are used to indicate an encoding - transformation that has been, can be, or may need to be applied to an - entity-body in order to ensure "safe transport" through the network. - This differs from a content coding in that the transfer-coding is a - property of the message, not of the original entity. - - transfer-coding = "chunked" | transfer-extension - transfer-extension = token *( ";" parameter ) - - Parameters are in the form of attribute/value pairs. - - parameter = attribute "=" value - attribute = token - value = token | quoted-string - - All transfer-coding values are case-insensitive. HTTP/1.1 uses - transfer-coding values in the TE header field (section 14.39) and in - the Transfer-Encoding header field (section 14.41). - - Whenever a transfer-coding is applied to a message-body, the set of - transfer-codings MUST include "chunked", unless the message is - terminated by closing the connection. When the "chunked" transfer- - coding is used, it MUST be the last transfer-coding applied to the - message-body. The "chunked" transfer-coding MUST NOT be applied more - than once to a message-body. These rules allow the recipient to - determine the transfer-length of the message (section 4.4). - - Transfer-codings are analogous to the Content-Transfer-Encoding - values of MIME [7], which were designed to enable safe transport of - binary data over a 7-bit transport service. However, safe transport - has a different focus for an 8bit-clean transfer protocol. In HTTP, - the only unsafe characteristic of message-bodies is the difficulty in - determining the exact body length (section 7.2.2), or the desire to - encrypt data over a shared transport. - - - -Fielding, et al. Standards Track [Page 24] - -RFC 2616 HTTP/1.1 June 1999 - - - The Internet Assigned Numbers Authority (IANA) acts as a registry for - transfer-coding value tokens. Initially, the registry contains the - following tokens: "chunked" (section 3.6.1), "identity" (section - 3.6.2), "gzip" (section 3.5), "compress" (section 3.5), and "deflate" - (section 3.5). - - [[ Remove reference to "identity" token ]] - - New transfer-coding value tokens SHOULD be registered in the same way - as new content-coding value tokens (section 3.5). - - A server which receives an entity-body with a transfer-coding it does - not understand SHOULD return 501 (Unimplemented), and close the - connection. A server MUST NOT send transfer-codings to an HTTP/1.0 - client. - -3.6.1 Chunked Transfer Coding - - The chunked encoding modifies the body of a message in order to - transfer it as a series of chunks, each with its own size indicator, - followed by an OPTIONAL trailer containing entity-header fields. This - allows dynamically produced content to be transferred along with the - information necessary for the recipient to verify that it has - received the full message. - - Chunked-Body = *chunk - last-chunk - trailer - CRLF - - chunk = chunk-size [ chunk-extension ] CRLF - chunk-data CRLF - chunk-size = 1*HEX - last-chunk = 1*("0") [ chunk-extension ] CRLF - - chunk-extension= *( ";" chunk-ext-name [ "=" chunk-ext-val ] ) - chunk-ext-name = token - chunk-ext-val = token | quoted-string - chunk-data = chunk-size(OCTET) - trailer = *(entity-header CRLF) - - The chunk-size field is a string of hex digits indicating the size of - the chunk. The chunked encoding is ended by any chunk whose size is - zero, followed by the trailer, which is terminated by an empty line. - - [[ "the size of the chunk" means "the size of the chunk-data in ]] - [[ octets" ]] - - The trailer allows the sender to include additional HTTP header - fields at the end of the message. The Trailer header field can be - used to indicate which header fields are included in a trailer (see - section 14.40). - - - - -Fielding, et al. Standards Track [Page 25] - -RFC 2616 HTTP/1.1 June 1999 - - - A server using chunked transfer-coding in a response MUST NOT use the - trailer for any header fields unless at least one of the following is - true: - - a)the request included a TE header field that indicates "trailers" is - acceptable in the transfer-coding of the response, as described in - section 14.39; or, - - b)the server is the origin server for the response, the trailer - fields consist entirely of optional metadata, and the recipient - could use the message (in a manner acceptable to the origin server) - without receiving this metadata. In other words, the origin server - is willing to accept the possibility that the trailer fields might - be silently discarded along the path to the client. - - This requirement prevents an interoperability failure when the - message is being received by an HTTP/1.1 (or later) proxy and - forwarded to an HTTP/1.0 recipient. It avoids a situation where - compliance with the protocol would have necessitated a possibly - infinite buffer on the proxy. - - An example process for decoding a Chunked-Body is presented in - appendix 19.4.6. - - All HTTP/1.1 applications MUST be able to receive and decode the - "chunked" transfer-coding, and MUST ignore chunk-extension extensions - they do not understand. - -3.7 Media Types - - HTTP uses Internet Media Types [17] in the Content-Type (section - 14.17) and Accept (section 14.1) header fields in order to provide - open and extensible data typing and type negotiation. - - media-type = type "/" subtype *( ";" parameter ) - type = token - subtype = token - - Parameters MAY follow the type/subtype in the form of attribute/value - pairs (as defined in section 3.6). - - The type, subtype, and parameter attribute names are case- - insensitive. Parameter values might or might not be case-sensitive, - depending on the semantics of the parameter name. Linear white space - (LWS) MUST NOT be used between the type and subtype, nor between an - attribute and its value. The presence or absence of a parameter might - be significant to the processing of a media-type, depending on its - definition within the media type registry. - - - -Fielding, et al. Standards Track [Page 26] - -RFC 2616 HTTP/1.1 June 1999 - - - Note that some older HTTP applications do not recognize media type - parameters. When sending data to older HTTP applications, - implementations SHOULD only use media type parameters when they are - required by that type/subtype definition. - - Media-type values are registered with the Internet Assigned Number - Authority (IANA [19]). The media type registration process is - outlined in RFC 1590 [17]. Use of non-registered media types is - discouraged. - - [[ "RFC 1590" should be "RFC 2048" ]] - -3.7.1 Canonicalization and Text Defaults - - Internet media types are registered with a canonical form. An - entity-body transferred via HTTP messages MUST be represented in the - appropriate canonical form prior to its transmission except for - "text" types, as defined in the next paragraph. - - When in canonical form, media subtypes of the "text" type use CRLF as - the text line break. HTTP relaxes this requirement and allows the - transport of text media with plain CR or LF alone representing a line - break when it is done consistently for an entire entity-body. HTTP - applications MUST accept CRLF, bare CR, and bare LF as being - representative of a line break in text media received via HTTP. In - addition, if the text is represented in a character set that does not - use octets 13 and 10 for CR and LF respectively, as is the case for - some multi-byte character sets, HTTP allows the use of whatever octet - sequences are defined by that character set to represent the - equivalent of CR and LF for line breaks. This flexibility regarding - line breaks applies only to text media in the entity-body; a bare CR - or LF MUST NOT be substituted for CRLF within any of the HTTP control - structures (such as header fields and multipart boundaries). - - If an entity-body is encoded with a content-coding, the underlying - data MUST be in a form defined above prior to being encoded. - - The "charset" parameter is used with some media types to define the - character set (section 3.4) of the data. When no explicit charset - parameter is provided by the sender, media subtypes of the "text" - type are defined to have a default charset value of "ISO-8859-1" when - received via HTTP. Data in character sets other than "ISO-8859-1" or - its subsets MUST be labeled with an appropriate charset value. See - section 3.4.1 for compatibility problems. - -3.7.2 Multipart Types - - MIME provides for a number of "multipart" types -- encapsulations of - one or more entities within a single message-body. All multipart - types share a common syntax, as defined in section 5.1.1 of RFC 2046 - - - -Fielding, et al. Standards Track [Page 27] - -RFC 2616 HTTP/1.1 June 1999 - - - [40], and MUST include a boundary parameter as part of the media type - value. The message body is itself a protocol element and MUST - therefore use only CRLF to represent line breaks between body-parts. - Unlike in RFC 2046, the epilogue of any multipart message MUST be - empty; HTTP applications MUST NOT transmit the epilogue (even if the - original multipart contains an epilogue). These restrictions exist in - order to preserve the self-delimiting nature of a multipart message- - body, wherein the "end" of the message-body is indicated by the - ending multipart boundary. - - In general, HTTP treats a multipart message-body no differently than - any other media type: strictly as payload. The one exception is the - "multipart/byteranges" type (appendix 19.2) when it appears in a 206 - (Partial Content) response, which will be interpreted by some HTTP - caching mechanisms as described in sections 13.5.4 and 14.16. In all - other cases, an HTTP user agent SHOULD follow the same or similar - behavior as a MIME user agent would upon receipt of a multipart type. - The MIME header fields within each body-part of a multipart message- - body do not have any significance to HTTP beyond that defined by - their MIME semantics. - - In general, an HTTP user agent SHOULD follow the same or similar - behavior as a MIME user agent would upon receipt of a multipart type. - If an application receives an unrecognized multipart subtype, the - application MUST treat it as being equivalent to "multipart/mixed". - - Note: The "multipart/form-data" type has been specifically defined - for carrying form data suitable for processing via the POST - request method, as described in RFC 1867 [15]. - -3.8 Product Tokens - - Product tokens are used to allow communicating applications to - identify themselves by software name and version. Most fields using - product tokens also allow sub-products which form a significant part - of the application to be listed, separated by white space. By - convention, the products are listed in order of their significance - for identifying the application. - - product = token ["/" product-version] - product-version = token - - Examples: - - User-Agent: CERN-LineMode/2.15 libwww/2.17b3 - Server: Apache/0.8.4 - - - - - -Fielding, et al. Standards Track [Page 28] - -RFC 2616 HTTP/1.1 June 1999 - - - Product tokens SHOULD be short and to the point. They MUST NOT be - used for advertising or other non-essential information. Although any - token character MAY appear in a product-version, this token SHOULD - only be used for a version identifier (i.e., successive versions of - the same product SHOULD only differ in the product-version portion of - the product value). - -3.9 Quality Values - - HTTP content negotiation (section 12) uses short "floating point" - numbers to indicate the relative importance ("weight") of various - negotiable parameters. A weight is normalized to a real number in - the range 0 through 1, where 0 is the minimum and 1 the maximum - value. If a parameter has a quality value of 0, then content with - this parameter is `not acceptable' for the client. HTTP/1.1 - applications MUST NOT generate more than three digits after the - decimal point. User configuration of these values SHOULD also be - limited in this fashion. - - qvalue = ( "0" [ "." 0*3DIGIT ] ) - | ( "1" [ "." 0*3("0") ] ) - - "Quality values" is a misnomer, since these values merely represent - relative degradation in desired quality. - -3.10 Language Tags - - A language tag identifies a natural language spoken, written, or - otherwise conveyed by human beings for communication of information - to other human beings. Computer languages are explicitly excluded. - HTTP uses language tags within the Accept-Language and Content- - Language fields. - - The syntax and registry of HTTP language tags is the same as that - defined by RFC 1766 [1]. In summary, a language tag is composed of 1 - or more parts: A primary language tag and a possibly empty series of - subtags: - - language-tag = primary-tag *( "-" subtag ) - primary-tag = 1*8ALPHA - subtag = 1*8ALPHA - - [[ Updated by RFC 3066: subtags may now contain digits ]] - - White space is not allowed within the tag and all tags are case- - insensitive. The name space of language tags is administered by the - IANA. Example tags include: - - en, en-US, en-cockney, i-cherokee, x-pig-latin - - - - -Fielding, et al. Standards Track [Page 29] - -RFC 2616 HTTP/1.1 June 1999 - - - where any two-letter primary-tag is an ISO-639 language abbreviation - and any two-letter initial subtag is an ISO-3166 country code. (The - last three tags above are not registered tags; all but the last are - examples of tags which could be registered in future.) - -3.11 Entity Tags - - Entity tags are used for comparing two or more entities from the same - requested resource. HTTP/1.1 uses entity tags in the ETag (section - 14.19), If-Match (section 14.24), If-None-Match (section 14.26), and - If-Range (section 14.27) header fields. The definition of how they - are used and compared as cache validators is in section 13.3.3. An - entity tag consists of an opaque quoted string, possibly prefixed by - a weakness indicator. - - entity-tag = [ weak ] opaque-tag - weak = "W/" - opaque-tag = quoted-string - - A "strong entity tag" MAY be shared by two entities of a resource - only if they are equivalent by octet equality. - - A "weak entity tag," indicated by the "W/" prefix, MAY be shared by - two entities of a resource only if the entities are equivalent and - could be substituted for each other with no significant change in - semantics. A weak entity tag can only be used for weak comparison. - - An entity tag MUST be unique across all versions of all entities - associated with a particular resource. A given entity tag value MAY - be used for entities obtained by requests on different URIs. The use - of the same entity tag value in conjunction with entities obtained by - requests on different URIs does not imply the equivalence of those - entities. - -3.12 Range Units - - HTTP/1.1 allows a client to request that only part (a range of) the - response entity be included within the response. HTTP/1.1 uses range - units in the Range (section 14.35) and Content-Range (section 14.16) - header fields. An entity can be broken down into subranges according - to various structural units. - - range-unit = bytes-unit | other-range-unit - bytes-unit = "bytes" - other-range-unit = token - - The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1 - implementations MAY ignore ranges specified using other units. - - - -Fielding, et al. Standards Track [Page 30] - -RFC 2616 HTTP/1.1 June 1999 - - - HTTP/1.1 has been designed to allow implementations of applications - that do not depend on knowledge of ranges. - -4 HTTP Message - -4.1 Message Types - - HTTP messages consist of requests from client to server and responses - from server to client. - - HTTP-message = Request | Response ; HTTP/1.1 messages - - Request (section 5) and Response (section 6) messages use the generic - message format of RFC 822 [9] for transferring entities (the payload - of the message). Both types of message consist of a start-line, zero - or more header fields (also known as "headers"), an empty line (i.e., - a line with nothing preceding the CRLF) indicating the end of the - header fields, and possibly a message-body. - - generic-message = start-line - *(message-header CRLF) - CRLF - [ message-body ] - start-line = Request-Line | Status-Line - - In the interest of robustness, servers SHOULD ignore any empty - line(s) received where a Request-Line is expected. In other words, if - the server is reading the protocol stream at the beginning of a - message and receives a CRLF first, it should ignore the CRLF. - - Certain buggy HTTP/1.0 client implementations generate extra CRLF's - after a POST request. To restate what is explicitly forbidden by the - BNF, an HTTP/1.1 client MUST NOT preface or follow a request with an - extra CRLF. - -4.2 Message Headers - - HTTP header fields, which include general-header (section 4.5), - request-header (section 5.3), response-header (section 6.2), and - entity-header (section 7.1) fields, follow the same generic format as - that given in Section 3.1 of RFC 822 [9]. Each header field consists - of a name followed by a colon (":") and the field value. Field names - are case-insensitive. The field value MAY be preceded by any amount - of LWS, though a single SP is preferred. Header fields can be - extended over multiple lines by preceding each extra line with at - least one SP or HT. Applications ought to follow "common form", where - one is known or indicated, when generating HTTP constructs, since - there might exist some implementations that fail to accept anything - - - -Fielding, et al. Standards Track [Page 31] - -RFC 2616 HTTP/1.1 June 1999 - - - beyond the common forms. - - message-header = field-name ":" [ field-value ] - field-name = token - field-value = *( field-content | LWS ) - field-content = <the OCTETs making up the field-value - and consisting of either *TEXT or combinations - of token, separators, and quoted-string> - - The field-content does not include any leading or trailing LWS: - linear white space occurring before the first non-whitespace - character of the field-value or after the last non-whitespace - character of the field-value. Such leading or trailing LWS MAY be - removed without changing the semantics of the field value. Any LWS - that occurs between field-content MAY be replaced with a single SP - before interpreting the field value or forwarding the message - downstream. - - The order in which header fields with differing field names are - received is not significant. However, it is "good practice" to send - general-header fields first, followed by request-header or response- - header fields, and ending with the entity-header fields. - - Multiple message-header fields with the same field-name MAY be - present in a message if and only if the entire field-value for that - header field is defined as a comma-separated list [i.e., #(values)]. - It MUST be possible to combine the multiple header fields into one - "field-name: field-value" pair, without changing the semantics of the - message, by appending each subsequent field-value to the first, each - separated by a comma. The order in which header fields with the same - field-name are received is therefore significant to the - interpretation of the combined field value, and thus a proxy MUST NOT - change the order of these field values when a message is forwarded. - -4.3 Message Body - - The message-body (if any) of an HTTP message is used to carry the - entity-body associated with the request or response. The message-body - differs from the entity-body only when a transfer-coding has been - applied, as indicated by the Transfer-Encoding header field (section - 14.41). - - message-body = entity-body - | <entity-body encoded as per Transfer-Encoding> - - Transfer-Encoding MUST be used to indicate any transfer-codings - applied by an application to ensure safe and proper transfer of the - message. Transfer-Encoding is a property of the message, not of the - - - -Fielding, et al. Standards Track [Page 32] - -RFC 2616 HTTP/1.1 June 1999 - - - entity, and thus MAY be added or removed by any application along the - request/response chain. (However, section 3.6 places restrictions on - when certain transfer-codings may be used.) - - The rules for when a message-body is allowed in a message differ for - requests and responses. - - The presence of a message-body in a request is signaled by the - inclusion of a Content-Length or Transfer-Encoding header field in - the request's message-headers. A message-body MUST NOT be included in - a request if the specification of the request method (section 5.1.1) - does not allow sending an entity-body in requests. A server SHOULD - read and forward a message-body on any request; if the request method - does not include defined semantics for an entity-body, then the - message-body SHOULD be ignored when handling the request. - - For response messages, whether or not a message-body is included with - a message is dependent on both the request method and the response - status code (section 6.1.1). All responses to the HEAD request method - MUST NOT include a message-body, even though the presence of entity- - header fields might lead one to believe they do. All 1xx - (informational), 204 (no content), and 304 (not modified) responses - MUST NOT include a message-body. All other responses do include a - message-body, although it MAY be of zero length. - -4.4 Message Length - - The transfer-length of a message is the length of the message-body as - it appears in the message; that is, after any transfer-codings have - been applied. When a message-body is included with a message, the - transfer-length of that body is determined by one of the following - (in order of precedence): - - 1.Any response message which "MUST NOT" include a message-body (such - as the 1xx, 204, and 304 responses and any response to a HEAD - request) is always terminated by the first empty line after the - header fields, regardless of the entity-header fields present in - the message. - - 2.If a Transfer-Encoding header field (section 14.41) is present and - has any value other than "identity", then the transfer-length is - defined by use of the "chunked" transfer-coding (section 3.6), - unless the message is terminated by closing the connection. - - [[ Remove 'and has any value other than "identity"' ]] - - 3.If a Content-Length header field (section 14.13) is present, its - decimal value in OCTETs represents both the entity-length and the - transfer-length. The Content-Length header field MUST NOT be sent - if these two lengths are different (i.e., if a Transfer-Encoding - - - -Fielding, et al. Standards Track [Page 33] - -RFC 2616 HTTP/1.1 June 1999 - - - header field is present). If a message is received with both a - Transfer-Encoding header field and a Content-Length header field, - the latter MUST be ignored. - - 4.If the message uses the media type "multipart/byteranges", and the - ransfer-length is not otherwise specified, then this self- - elimiting media type defines the transfer-length. This media type - UST NOT be used unless the sender knows that the recipient can arse - it; the presence in a request of a Range header with ultiple byte- - range specifiers from a 1.1 client implies that the lient can parse - multipart/byteranges responses. - - A range header might be forwarded by a 1.0 proxy that does not - understand multipart/byteranges; in this case the server MUST - delimit the message using methods defined in items 1,3 or 5 of - this section. - - 5.By the server closing the connection. (Closing the connection - cannot be used to indicate the end of a request body, since that - would leave no possibility for the server to send back a response.) - - For compatibility with HTTP/1.0 applications, HTTP/1.1 requests - containing a message-body MUST include a valid Content-Length header - field unless the server is known to be HTTP/1.1 compliant. If a - request contains a message-body and a Content-Length is not given, - the server SHOULD respond with 400 (bad request) if it cannot - determine the length of the message, or with 411 (length required) if - it wishes to insist on receiving a valid Content-Length. - - All HTTP/1.1 applications that receive entities MUST accept the - "chunked" transfer-coding (section 3.6), thus allowing this mechanism - to be used for messages when the message length cannot be determined - in advance. - - Messages MUST NOT include both a Content-Length header field and a - non-identity transfer-coding. If the message does include a non- - identity transfer-coding, the Content-Length MUST be ignored. - - [[ Remove "non-identity" both times ]] - - When a Content-Length is given in a message where a message-body is - allowed, its field value MUST exactly match the number of OCTETs in - the message-body. HTTP/1.1 user agents MUST notify the user when an - invalid length is received and detected. - -4.5 General Header Fields - - There are a few header fields which have general applicability for - both request and response messages, but which do not apply to the - entity being transferred. These header fields apply only to the - - - -Fielding, et al. Standards Track [Page 34] - -RFC 2616 HTTP/1.1 June 1999 - - - message being transmitted. - - general-header = Cache-Control ; Section 14.9 - | Connection ; Section 14.10 - | Date ; Section 14.18 - | Pragma ; Section 14.32 - | Trailer ; Section 14.40 - | Transfer-Encoding ; Section 14.41 - | Upgrade ; Section 14.42 - | Via ; Section 14.45 - | Warning ; Section 14.46 - - General-header field names can be extended reliably only in - combination with a change in the protocol version. However, new or - experimental header fields may be given the semantics of general - header fields if all parties in the communication recognize them to - be general-header fields. Unrecognized header fields are treated as - entity-header fields. - -5 Request - - A request message from a client to a server includes, within the - first line of that message, the method to be applied to the resource, - the identifier of the resource, and the protocol version in use. - - Request = Request-Line ; Section 5.1 - *(( general-header ; Section 4.5 - | request-header ; Section 5.3 - | entity-header ) CRLF) ; Section 7.1 - CRLF - [ message-body ] ; Section 4.3 - -5.1 Request-Line - - The Request-Line begins with a method token, followed by the - Request-URI and the protocol version, and ending with CRLF. The - elements are separated by SP characters. No CR or LF is allowed - except in the final CRLF sequence. - - Request-Line = Method SP Request-URI SP HTTP-Version CRLF - - - - - - - - - - - -Fielding, et al. Standards Track [Page 35] - -RFC 2616 HTTP/1.1 June 1999 - - -5.1.1 Method - - The Method token indicates the method to be performed on the - resource identified by the Request-URI. The method is case-sensitive. - - Method = "OPTIONS" ; Section 9.2 - | "GET" ; Section 9.3 - | "HEAD" ; Section 9.4 - | "POST" ; Section 9.5 - | "PUT" ; Section 9.6 - | "DELETE" ; Section 9.7 - | "TRACE" ; Section 9.8 - | "CONNECT" ; Section 9.9 - | extension-method - extension-method = token - - The list of methods allowed by a resource can be specified in an - Allow header field (section 14.7). The return code of the response - always notifies the client whether a method is currently allowed on a - resource, since the set of allowed methods can change dynamically. An - origin server SHOULD return the status code 405 (Method Not Allowed) - if the method is known by the origin server but not allowed for the - requested resource, and 501 (Not Implemented) if the method is - unrecognized or not implemented by the origin server. The methods GET - and HEAD MUST be supported by all general-purpose servers. All other - methods are OPTIONAL; however, if the above methods are implemented, - they MUST be implemented with the same semantics as those specified - in section 9. - -5.1.2 Request-URI - - The Request-URI is a Uniform Resource Identifier (section 3.2) and - identifies the resource upon which to apply the request. - - Request-URI = "*" | absoluteURI | abs_path | authority - [[ Request-URI = "*" | absoluteURI | abs_path [ "?" query ] | authority ]] - - The four options for Request-URI are dependent on the nature of the - request. The asterisk "*" means that the request does not apply to a - particular resource, but to the server itself, and is only allowed - when the method used does not necessarily apply to a resource. One - example would be - - OPTIONS * HTTP/1.1 - - The absoluteURI form is REQUIRED when the request is being made to a - proxy. The proxy is requested to forward the request or service it - from a valid cache, and return the response. Note that the proxy MAY - forward the request on to another proxy or directly to the server - - - -Fielding, et al. Standards Track [Page 36] - -RFC 2616 HTTP/1.1 June 1999 - - - specified by the absoluteURI. In order to avoid request loops, a - proxy MUST be able to recognize all of its server names, including - any aliases, local variations, and the numeric IP address. An example - Request-Line would be: - - GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.1 - - To allow for transition to absoluteURIs in all requests in future - versions of HTTP, all HTTP/1.1 servers MUST accept the absoluteURI - form in requests, even though HTTP/1.1 clients will only generate - them in requests to proxies. - - The authority form is only used by the CONNECT method (section 9.9). - - The most common form of Request-URI is that used to identify a - resource on an origin server or gateway. In this case the absolute - path of the URI MUST be transmitted (see section 3.2.1, abs_path) as - the Request-URI, and the network location of the URI (authority) MUST - be transmitted in a Host header field. For example, a client wishing - to retrieve the resource above directly from the origin server would - create a TCP connection to port 80 of the host "www.w3.org" and send - the lines: - - GET /pub/WWW/TheProject.html HTTP/1.1 - Host: www.w3.org - - followed by the remainder of the Request. Note that the absolute path - cannot be empty; if none is present in the original URI, it MUST be - given as "/" (the server root). - - The Request-URI is transmitted in the format specified in section - 3.2.1. If the Request-URI is encoded using the "% HEX HEX" encoding - [42], the origin server MUST decode the Request-URI in order to - properly interpret the request. Servers SHOULD respond to invalid - Request-URIs with an appropriate status code. - - A transparent proxy MUST NOT rewrite the "abs_path" part of the - received Request-URI when forwarding it to the next inbound server, - except as noted above to replace a null abs_path with "/". - - Note: The "no rewrite" rule prevents the proxy from changing the - meaning of the request when the origin server is improperly using - a non-reserved URI character for a reserved purpose. Implementors - should be aware that some pre-HTTP/1.1 proxies have been known to - rewrite the Request-URI. - - - - - - -Fielding, et al. Standards Track [Page 37] - -RFC 2616 HTTP/1.1 June 1999 - - -5.2 The Resource Identified by a Request - - The exact resource identified by an Internet request is determined by - examining both the Request-URI and the Host header field. - - An origin server that does not allow resources to differ by the - requested host MAY ignore the Host header field value when - determining the resource identified by an HTTP/1.1 request. (But see - section 19.6.1.1 for other requirements on Host support in HTTP/1.1.) - - An origin server that does differentiate resources based on the host - requested (sometimes referred to as virtual hosts or vanity host - names) MUST use the following rules for determining the requested - resource on an HTTP/1.1 request: - - 1. If Request-URI is an absoluteURI, the host is part of the - Request-URI. Any Host header field value in the request MUST be - ignored. - - 2. If the Request-URI is not an absoluteURI, and the request includes - a Host header field, the host is determined by the Host header - field value. - - 3. If the host as determined by rule 1 or 2 is not a valid host on - the server, the response MUST be a 400 (Bad Request) error message. - - Recipients of an HTTP/1.0 request that lacks a Host header field MAY - attempt to use heuristics (e.g., examination of the URI path for - something unique to a particular host) in order to determine what - exact resource is being requested. - -5.3 Request Header Fields - - The request-header fields allow the client to pass additional - information about the request, and about the client itself, to the - server. These fields act as request modifiers, with semantics - equivalent to the parameters on a programming language method - invocation. - - request-header = Accept ; Section 14.1 - | Accept-Charset ; Section 14.2 - | Accept-Encoding ; Section 14.3 - | Accept-Language ; Section 14.4 - | Authorization ; Section 14.8 - | Expect ; Section 14.20 - | From ; Section 14.22 - | Host ; Section 14.23 - | If-Match ; Section 14.24 - - - -Fielding, et al. Standards Track [Page 38] - -RFC 2616 HTTP/1.1 June 1999 - - - | If-Modified-Since ; Section 14.25 - | If-None-Match ; Section 14.26 - | If-Range ; Section 14.27 - | If-Unmodified-Since ; Section 14.28 - | Max-Forwards ; Section 14.31 - | Proxy-Authorization ; Section 14.34 - | Range ; Section 14.35 - | Referer ; Section 14.36 - | TE ; Section 14.39 - | User-Agent ; Section 14.43 - - Request-header field names can be extended reliably only in - combination with a change in the protocol version. However, new or - experimental header fields MAY be given the semantics of request- - header fields if all parties in the communication recognize them to - be request-header fields. Unrecognized header fields are treated as - entity-header fields. - -6 Response - - After receiving and interpreting a request message, a server responds - with an HTTP response message. - - Response = Status-Line ; Section 6.1 - *(( general-header ; Section 4.5 - | response-header ; Section 6.2 - | entity-header ) CRLF) ; Section 7.1 - CRLF - [ message-body ] ; Section 7.2 - -6.1 Status-Line - - The first line of a Response message is the Status-Line, consisting - of the protocol version followed by a numeric status code and its - associated textual phrase, with each element separated by SP - characters. No CR or LF is allowed except in the final CRLF sequence. - - Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF - -6.1.1 Status Code and Reason Phrase - - The Status-Code element is a 3-digit integer result code of the - attempt to understand and satisfy the request. These codes are fully - defined in section 10. The Reason-Phrase is intended to give a short - textual description of the Status-Code. The Status-Code is intended - for use by automata and the Reason-Phrase is intended for the human - user. The client is not required to examine or display the Reason- - Phrase. - - - -Fielding, et al. Standards Track [Page 39] - -RFC 2616 HTTP/1.1 June 1999 - - - The first digit of the Status-Code defines the class of response. The - last two digits do not have any categorization role. There are 5 - values for the first digit: - - - 1xx: Informational - Request received, continuing process - - - 2xx: Success - The action was successfully received, - understood, and accepted - - - 3xx: Redirection - Further action must be taken in order to - complete the request - - - 4xx: Client Error - The request contains bad syntax or cannot - be fulfilled - - - 5xx: Server Error - The server failed to fulfill an apparently - valid request - - The individual values of the numeric status codes defined for - HTTP/1.1, and an example set of corresponding Reason-Phrase's, are - presented below. The reason phrases listed here are only - recommendations -- they MAY be replaced by local equivalents without - affecting the protocol. - - Status-Code = - "100" ; Section 10.1.1: Continue - | "101" ; Section 10.1.2: Switching Protocols - | "200" ; Section 10.2.1: OK - | "201" ; Section 10.2.2: Created - | "202" ; Section 10.2.3: Accepted - | "203" ; Section 10.2.4: Non-Authoritative Information - | "204" ; Section 10.2.5: No Content - | "205" ; Section 10.2.6: Reset Content - | "206" ; Section 10.2.7: Partial Content - | "300" ; Section 10.3.1: Multiple Choices - | "301" ; Section 10.3.2: Moved Permanently - | "302" ; Section 10.3.3: Found - | "303" ; Section 10.3.4: See Other - | "304" ; Section 10.3.5: Not Modified - | "305" ; Section 10.3.6: Use Proxy - | "307" ; Section 10.3.8: Temporary Redirect - | "400" ; Section 10.4.1: Bad Request - | "401" ; Section 10.4.2: Unauthorized - | "402" ; Section 10.4.3: Payment Required - | "403" ; Section 10.4.4: Forbidden - | "404" ; Section 10.4.5: Not Found - | "405" ; Section 10.4.6: Method Not Allowed - | "406" ; Section 10.4.7: Not Acceptable - - - -Fielding, et al. Standards Track [Page 40] - -RFC 2616 HTTP/1.1 June 1999 - - - | "407" ; Section 10.4.8: Proxy Authentication Required - | "408" ; Section 10.4.9: Request Time-out - | "409" ; Section 10.4.10: Conflict - | "410" ; Section 10.4.11: Gone - | "411" ; Section 10.4.12: Length Required - | "412" ; Section 10.4.13: Precondition Failed - | "413" ; Section 10.4.14: Request Entity Too Large - | "414" ; Section 10.4.15: Request-URI Too Large - | "415" ; Section 10.4.16: Unsupported Media Type - | "416" ; Section 10.4.17: Requested range not satisfiable - | "417" ; Section 10.4.18: Expectation Failed - | "500" ; Section 10.5.1: Internal Server Error - | "501" ; Section 10.5.2: Not Implemented - | "502" ; Section 10.5.3: Bad Gateway - | "503" ; Section 10.5.4: Service Unavailable - | "504" ; Section 10.5.5: Gateway Time-out - | "505" ; Section 10.5.6: HTTP Version not supported - | extension-code - - extension-code = 3DIGIT - Reason-Phrase = *<TEXT, excluding CR, LF> - - HTTP status codes are extensible. HTTP applications are not required - to understand the meaning of all registered status codes, though such - understanding is obviously desirable. However, applications MUST - understand the class of any status code, as indicated by the first - digit, and treat any unrecognized response as being equivalent to the - x00 status code of that class, with the exception that an - unrecognized response MUST NOT be cached. For example, if an - unrecognized status code of 431 is received by the client, it can - safely assume that there was something wrong with its request and - treat the response as if it had received a 400 status code. In such - cases, user agents SHOULD present to the user the entity returned - with the response, since that entity is likely to include human- - readable information which will explain the unusual status. - -6.2 Response Header Fields - - The response-header fields allow the server to pass additional - information about the response which cannot be placed in the Status- - Line. These header fields give information about the server and about - further access to the resource identified by the Request-URI. - - response-header = Accept-Ranges ; Section 14.5 - | Age ; Section 14.6 - | ETag ; Section 14.19 - | Location ; Section 14.30 - | Proxy-Authenticate ; Section 14.33 - - - -Fielding, et al. Standards Track [Page 41] - -RFC 2616 HTTP/1.1 June 1999 - - - | Retry-After ; Section 14.37 - | Server ; Section 14.38 - | Vary ; Section 14.44 - | WWW-Authenticate ; Section 14.47 - - Response-header field names can be extended reliably only in - combination with a change in the protocol version. However, new or - experimental header fields MAY be given the semantics of response- - header fields if all parties in the communication recognize them to - be response-header fields. Unrecognized header fields are treated as - entity-header fields. - -7 Entity - - Request and Response messages MAY transfer an entity if not otherwise - restricted by the request method or response status code. An entity - consists of entity-header fields and an entity-body, although some - responses will only include the entity-headers. - - In this section, both sender and recipient refer to either the client - or the server, depending on who sends and who receives the entity. - -7.1 Entity Header Fields - - Entity-header fields define metainformation about the entity-body or, - if no body is present, about the resource identified by the request. - Some of this metainformation is OPTIONAL; some might be REQUIRED by - portions of this specification. - - entity-header = Allow ; Section 14.7 - | Content-Encoding ; Section 14.11 - | Content-Language ; Section 14.12 - | Content-Length ; Section 14.13 - | Content-Location ; Section 14.14 - | Content-MD5 ; Section 14.15 - | Content-Range ; Section 14.16 - | Content-Type ; Section 14.17 - | Expires ; Section 14.21 - | Last-Modified ; Section 14.29 - | extension-header - - extension-header = message-header - - The extension-header mechanism allows additional entity-header fields - to be defined without changing the protocol, but these fields cannot - be assumed to be recognizable by the recipient. Unrecognized header - fields SHOULD be ignored by the recipient and MUST be forwarded by - transparent proxies. - - - -Fielding, et al. Standards Track [Page 42] - -RFC 2616 HTTP/1.1 June 1999 - - -7.2 Entity Body - - The entity-body (if any) sent with an HTTP request or response is in - a format and encoding defined by the entity-header fields. - - entity-body = *OCTET - - An entity-body is only present in a message when a message-body is - present, as described in section 4.3. The entity-body is obtained - from the message-body by decoding any Transfer-Encoding that might - have been applied to ensure safe and proper transfer of the message. - -7.2.1 Type - - When an entity-body is included with a message, the data type of that - body is determined via the header fields Content-Type and Content- - Encoding. These define a two-layer, ordered encoding model: - - entity-body := Content-Encoding( Content-Type( data ) ) - - Content-Type specifies the media type of the underlying data. - Content-Encoding may be used to indicate any additional content - codings applied to the data, usually for the purpose of data - compression, that are a property of the requested resource. There is - no default encoding. - - Any HTTP/1.1 message containing an entity-body SHOULD include a - Content-Type header field defining the media type of that body. If - and only if the media type is not given by a Content-Type field, the - recipient MAY attempt to guess the media type via inspection of its - content and/or the name extension(s) of the URI used to identify the - resource. If the media type remains unknown, the recipient SHOULD - treat it as type "application/octet-stream". - -7.2.2 Entity Length - - The entity-length of a message is the length of the message-body - before any transfer-codings have been applied. Section 4.4 defines - how the transfer-length of a message-body is determined. - - - - - - - - - - - - -Fielding, et al. Standards Track [Page 43] - -RFC 2616 HTTP/1.1 June 1999 - - -8 Connections - -8.1 Persistent Connections - -8.1.1 Purpose - - Prior to persistent connections, a separate TCP connection was - established to fetch each URL, increasing the load on HTTP servers - and causing congestion on the Internet. The use of inline images and - other associated data often require a client to make multiple - requests of the same server in a short amount of time. Analysis of - these performance problems and results from a prototype - implementation are available [26] [30]. Implementation experience and - measurements of actual HTTP/1.1 (RFC 2068) implementations show good - results [39]. Alternatives have also been explored, for example, - T/TCP [27]. - - Persistent HTTP connections have a number of advantages: - - - By opening and closing fewer TCP connections, CPU time is saved - in routers and hosts (clients, servers, proxies, gateways, - tunnels, or caches), and memory used for TCP protocol control - blocks can be saved in hosts. - - - HTTP requests and responses can be pipelined on a connection. - Pipelining allows a client to make multiple requests without - waiting for each response, allowing a single TCP connection to - be used much more efficiently, with much lower elapsed time. - - - Network congestion is reduced by reducing the number of packets - caused by TCP opens, and by allowing TCP sufficient time to - determine the congestion state of the network. - - - Latency on subsequent requests is reduced since there is no time - spent in TCP's connection opening handshake. - - - HTTP can evolve more gracefully, since errors can be reported - without the penalty of closing the TCP connection. Clients using - future versions of HTTP might optimistically try a new feature, - but if communicating with an older server, retry with old - semantics after an error is reported. - - HTTP implementations SHOULD implement persistent connections. - - - - - - - - -Fielding, et al. Standards Track [Page 44] - -RFC 2616 HTTP/1.1 June 1999 - - -8.1.2 Overall Operation - - A significant difference between HTTP/1.1 and earlier versions of - HTTP is that persistent connections are the default behavior of any - HTTP connection. That is, unless otherwise indicated, the client - SHOULD assume that the server will maintain a persistent connection, - even after error responses from the server. - - Persistent connections provide a mechanism by which a client and a - server can signal the close of a TCP connection. This signaling takes - place using the Connection header field (section 14.10). Once a close - has been signaled, the client MUST NOT send any more requests on that - connection. - -8.1.2.1 Negotiation - - An HTTP/1.1 server MAY assume that a HTTP/1.1 client intends to - maintain a persistent connection unless a Connection header including - the connection-token "close" was sent in the request. If the server - chooses to close the connection immediately after sending the - response, it SHOULD send a Connection header including the - connection-token close. - - An HTTP/1.1 client MAY expect a connection to remain open, but would - decide to keep it open based on whether the response from a server - contains a Connection header with the connection-token close. In case - the client does not want to maintain a connection for more than that - request, it SHOULD send a Connection header including the - connection-token close. - - If either the client or the server sends the close token in the - Connection header, that request becomes the last one for the - connection. - - Clients and servers SHOULD NOT assume that a persistent connection is - maintained for HTTP versions less than 1.1 unless it is explicitly - signaled. See section 19.6.2 for more information on backward - compatibility with HTTP/1.0 clients. - - In order to remain persistent, all messages on the connection MUST - have a self-defined message length (i.e., one not defined by closure - of the connection), as described in section 4.4. - - - - - - - - - -Fielding, et al. Standards Track [Page 45] - -RFC 2616 HTTP/1.1 June 1999 - - -8.1.2.2 Pipelining - - A client that supports persistent connections MAY "pipeline" its - requests (i.e., send multiple requests without waiting for each - response). A server MUST send its responses to those requests in the - same order that the requests were received. - - Clients which assume persistent connections and pipeline immediately - after connection establishment SHOULD be prepared to retry their - connection if the first pipelined attempt fails. If a client does - such a retry, it MUST NOT pipeline before it knows the connection is - persistent. Clients MUST also be prepared to resend their requests if - the server closes the connection before sending all of the - corresponding responses. - - Clients SHOULD NOT pipeline requests using non-idempotent methods or - non-idempotent sequences of methods (see section 9.1.2). Otherwise, a - premature termination of the transport connection could lead to - indeterminate results. A client wishing to send a non-idempotent - request SHOULD wait to send that request until it has received the - response status for the previous request. - -8.1.3 Proxy Servers - - It is especially important that proxies correctly implement the - properties of the Connection header field as specified in section - 14.10. - - The proxy server MUST signal persistent connections separately with - its clients and the origin servers (or other proxy servers) that it - connects to. Each persistent connection applies to only one transport - link. - - A proxy server MUST NOT establish a HTTP/1.1 persistent connection - with an HTTP/1.0 client (but see RFC 2068 [33] for information and - discussion of the problems with the Keep-Alive header implemented by - many HTTP/1.0 clients). - -8.1.4 Practical Considerations - - Servers will usually have some time-out value beyond which they will - no longer maintain an inactive connection. Proxy servers might make - this a higher value since it is likely that the client will be making - more connections through the same server. The use of persistent - connections places no requirements on the length (or existence) of - this time-out for either the client or the server. - - - - - -Fielding, et al. Standards Track [Page 46] - -RFC 2616 HTTP/1.1 June 1999 - - - When a client or server wishes to time-out it SHOULD issue a graceful - close on the transport connection. Clients and servers SHOULD both - constantly watch for the other side of the transport close, and - respond to it as appropriate. If a client or server does not detect - the other side's close promptly it could cause unnecessary resource - drain on the network. - - A client, server, or proxy MAY close the transport connection at any - time. For example, a client might have started to send a new request - at the same time that the server has decided to close the "idle" - connection. From the server's point of view, the connection is being - closed while it was idle, but from the client's point of view, a - request is in progress. - - This means that clients, servers, and proxies MUST be able to recover - from asynchronous close events. Client software SHOULD reopen the - transport connection and retransmit the aborted sequence of requests - without user interaction so long as the request sequence is - idempotent (see section 9.1.2). Non-idempotent methods or sequences - MUST NOT be automatically retried, although user agents MAY offer a - human operator the choice of retrying the request(s). Confirmation by - user-agent software with semantic understanding of the application - MAY substitute for user confirmation. The automatic retry SHOULD NOT - be repeated if the second sequence of requests fails. - - Servers SHOULD always respond to at least one request per connection, - if at all possible. Servers SHOULD NOT close a connection in the - middle of transmitting a response, unless a network or client failure - is suspected. - - Clients that use persistent connections SHOULD limit the number of - simultaneous connections that they maintain to a given server. A - single-user client SHOULD NOT maintain more than 2 connections with - any server or proxy. A proxy SHOULD use up to 2*N connections to - another server or proxy, where N is the number of simultaneously - active users. These guidelines are intended to improve HTTP response - times and avoid congestion. - -8.2 Message Transmission Requirements - -8.2.1 Persistent Connections and Flow Control - - HTTP/1.1 servers SHOULD maintain persistent connections and use TCP's - flow control mechanisms to resolve temporary overloads, rather than - terminating connections with the expectation that clients will retry. - The latter technique can exacerbate network congestion. - - - - - -Fielding, et al. Standards Track [Page 47] - -RFC 2616 HTTP/1.1 June 1999 - - -8.2.2 Monitoring Connections for Error Status Messages - - An HTTP/1.1 (or later) client sending a message-body SHOULD monitor - the network connection for an error status while it is transmitting - the request. If the client sees an error status, it SHOULD - immediately cease transmitting the body. If the body is being sent - using a "chunked" encoding (section 3.6), a zero length chunk and - empty trailer MAY be used to prematurely mark the end of the message. - If the body was preceded by a Content-Length header, the client MUST - close the connection. - -8.2.3 Use of the 100 (Continue) Status - - The purpose of the 100 (Continue) status (see section 10.1.1) is to - allow a client that is sending a request message with a request body - to determine if the origin server is willing to accept the request - (based on the request headers) before the client sends the request - body. In some cases, it might either be inappropriate or highly - inefficient for the client to send the body if the server will reject - the message without looking at the body. - - Requirements for HTTP/1.1 clients: - - - If a client will wait for a 100 (Continue) response before - sending the request body, it MUST send an Expect request-header - field (section 14.20) with the "100-continue" expectation. - - - A client MUST NOT send an Expect request-header field (section - 14.20) with the "100-continue" expectation if it does not intend - to send a request body. - - Because of the presence of older implementations, the protocol allows - ambiguous situations in which a client may send "Expect: 100- - continue" without receiving either a 417 (Expectation Failed) status - or a 100 (Continue) status. Therefore, when a client sends this - header field to an origin server (possibly via a proxy) from which it - has never seen a 100 (Continue) status, the client SHOULD NOT wait - for an indefinite period before sending the request body. - - Requirements for HTTP/1.1 origin servers: - - - Upon receiving a request which includes an Expect request-header - field with the "100-continue" expectation, an origin server MUST - either respond with 100 (Continue) status and continue to read - from the input stream, or respond with a final status code. The - origin server MUST NOT wait for the request body before sending - the 100 (Continue) response. If it responds with a final status - code, it MAY close the transport connection or it MAY continue - - - -Fielding, et al. Standards Track [Page 48] - -RFC 2616 HTTP/1.1 June 1999 - - - to read and discard the rest of the request. It MUST NOT - perform the requested method if it returns a final status code. - - - An origin server SHOULD NOT send a 100 (Continue) response if - the request message does not include an Expect request-header - field with the "100-continue" expectation, and MUST NOT send a - 100 (Continue) response if such a request comes from an HTTP/1.0 - (or earlier) client. There is an exception to this rule: for - compatibility with RFC 2068, a server MAY send a 100 (Continue) - status in response to an HTTP/1.1 PUT or POST request that does - not include an Expect request-header field with the "100- - continue" expectation. This exception, the purpose of which is - to minimize any client processing delays associated with an - undeclared wait for 100 (Continue) status, applies only to - HTTP/1.1 requests, and not to requests with any other HTTP- - version value. - - - An origin server MAY omit a 100 (Continue) response if it has - already received some or all of the request body for the - corresponding request. - - - An origin server that sends a 100 (Continue) response MUST - ultimately send a final status code, once the request body is - received and processed, unless it terminates the transport - connection prematurely. - - - If an origin server receives a request that does not include an - Expect request-header field with the "100-continue" expectation, - the request includes a request body, and the server responds - with a final status code before reading the entire request body - from the transport connection, then the server SHOULD NOT close - the transport connection until it has read the entire request, - or until the client closes the connection. Otherwise, the client - might not reliably receive the response message. However, this - requirement is not be construed as preventing a server from - defending itself against denial-of-service attacks, or from - badly broken client implementations. - - Requirements for HTTP/1.1 proxies: - - - If a proxy receives a request that includes an Expect request- - header field with the "100-continue" expectation, and the proxy - either knows that the next-hop server complies with HTTP/1.1 or - higher, or does not know the HTTP version of the next-hop - server, it MUST forward the request, including the Expect header - field. - - - - - -Fielding, et al. Standards Track [Page 49] - -RFC 2616 HTTP/1.1 June 1999 - - - - If the proxy knows that the version of the next-hop server is - HTTP/1.0 or lower, it MUST NOT forward the request, and it MUST - respond with a 417 (Expectation Failed) status. - - - Proxies SHOULD maintain a cache recording the HTTP version - numbers received from recently-referenced next-hop servers. - - - A proxy MUST NOT forward a 100 (Continue) response if the - request message was received from an HTTP/1.0 (or earlier) - client and did not include an Expect request-header field with - the "100-continue" expectation. This requirement overrides the - general rule for forwarding of 1xx responses (see section 10.1). - -8.2.4 Client Behavior if Server Prematurely Closes Connection - - If an HTTP/1.1 client sends a request which includes a request body, - but which does not include an Expect request-header field with the - "100-continue" expectation, and if the client is not directly - connected to an HTTP/1.1 origin server, and if the client sees the - connection close before receiving any status from the server, the - client SHOULD retry the request. If the client does retry this - request, it MAY use the following "binary exponential backoff" - algorithm to be assured of obtaining a reliable response: - - 1. Initiate a new connection to the server - - 2. Transmit the request-headers - - 3. Initialize a variable R to the estimated round-trip time to the - server (e.g., based on the time it took to establish the - connection), or to a constant value of 5 seconds if the round- - trip time is not available. - - 4. Compute T = R * (2**N), where N is the number of previous - retries of this request. - - 5. Wait either for an error response from the server, or for T - seconds (whichever comes first) - - 6. If no error response is received, after T seconds transmit the - body of the request. - - 7. If client sees that the connection is closed prematurely, - repeat from step 1 until the request is accepted, an error - response is received, or the user becomes impatient and - terminates the retry process. - - - - - -Fielding, et al. Standards Track [Page 50] - -RFC 2616 HTTP/1.1 June 1999 - - - If at any point an error status is received, the client - - - SHOULD NOT continue and - - - SHOULD close the connection if it has not completed sending the - request message. - -9 Method Definitions - - The set of common methods for HTTP/1.1 is defined below. Although - this set can be expanded, additional methods cannot be assumed to - share the same semantics for separately extended clients and servers. - - The Host request-header field (section 14.23) MUST accompany all - HTTP/1.1 requests. - -9.1 Safe and Idempotent Methods - -9.1.1 Safe Methods - - Implementors should be aware that the software represents the user in - their interactions over the Internet, and should be careful to allow - the user to be aware of any actions they might take which may have an - unexpected significance to themselves or others. - - In particular, the convention has been established that the GET and - HEAD methods SHOULD NOT have the significance of taking an action - other than retrieval. These methods ought to be considered "safe". - This allows user agents to represent other methods, such as POST, PUT - and DELETE, in a special way, so that the user is made aware of the - fact that a possibly unsafe action is being requested. - - Naturally, it is not possible to ensure that the server does not - generate side-effects as a result of performing a GET request; in - fact, some dynamic resources consider that a feature. The important - distinction here is that the user did not request the side-effects, - so therefore cannot be held accountable for them. - -9.1.2 Idempotent Methods - - Methods can also have the property of "idempotence" in that (aside - from error or expiration issues) the side-effects of N > 0 identical - requests is the same as for a single request. The methods GET, HEAD, - PUT and DELETE share this property. Also, the methods OPTIONS and - TRACE SHOULD NOT have side effects, and so are inherently idempotent. - - - - - - -Fielding, et al. Standards Track [Page 51] - -RFC 2616 HTTP/1.1 June 1999 - - - However, it is possible that a sequence of several requests is non- - idempotent, even if all of the methods executed in that sequence are - idempotent. (A sequence is idempotent if a single execution of the - entire sequence always yields a result that is not changed by a - reexecution of all, or part, of that sequence.) For example, a - sequence is non-idempotent if its result depends on a value that is - later modified in the same sequence. - - A sequence that never has side effects is idempotent, by definition - (provided that no concurrent operations are being executed on the - same set of resources). - -9.2 OPTIONS - - The OPTIONS method represents a request for information about the - communication options available on the request/response chain - identified by the Request-URI. This method allows the client to - determine the options and/or requirements associated with a resource, - or the capabilities of a server, without implying a resource action - or initiating a resource retrieval. - - Responses to this method are not cacheable. - - If the OPTIONS request includes an entity-body (as indicated by the - presence of Content-Length or Transfer-Encoding), then the media type - MUST be indicated by a Content-Type field. Although this - specification does not define any use for such a body, future - extensions to HTTP might use the OPTIONS body to make more detailed - queries on the server. A server that does not support such an - extension MAY discard the request body. - - If the Request-URI is an asterisk ("*"), the OPTIONS request is - intended to apply to the server in general rather than to a specific - resource. Since a server's communication options typically depend on - the resource, the "*" request is only useful as a "ping" or "no-op" - type of method; it does nothing beyond allowing the client to test - the capabilities of the server. For example, this can be used to test - a proxy for HTTP/1.1 compliance (or lack thereof). - - If the Request-URI is not an asterisk, the OPTIONS request applies - only to the options that are available when communicating with that - resource. - - A 200 response SHOULD include any header fields that indicate - optional features implemented by the server and applicable to that - resource (e.g., Allow), possibly including extensions not defined by - this specification. The response body, if any, SHOULD also include - information about the communication options. The format for such a - - - -Fielding, et al. Standards Track [Page 52] - -RFC 2616 HTTP/1.1 June 1999 - - - body is not defined by this specification, but might be defined by - future extensions to HTTP. Content negotiation MAY be used to select - the appropriate response format. If no response body is included, the - response MUST include a Content-Length field with a field-value of - "0". - - The Max-Forwards request-header field MAY be used to target a - specific proxy in the request chain. When a proxy receives an OPTIONS - request on an absoluteURI for which request forwarding is permitted, - the proxy MUST check for a Max-Forwards field. If the Max-Forwards - field-value is zero ("0"), the proxy MUST NOT forward the message; - instead, the proxy SHOULD respond with its own communication options. - If the Max-Forwards field-value is an integer greater than zero, the - proxy MUST decrement the field-value when it forwards the request. If - no Max-Forwards field is present in the request, then the forwarded - request MUST NOT include a Max-Forwards field. - -9.3 GET - - The GET method means retrieve whatever information (in the form of an - entity) is identified by the Request-URI. If the Request-URI refers - to a data-producing process, it is the produced data which shall be - returned as the entity in the response and not the source text of the - process, unless that text happens to be the output of the process. - - The semantics of the GET method change to a "conditional GET" if the - request message includes an If-Modified-Since, If-Unmodified-Since, - If-Match, If-None-Match, or If-Range header field. A conditional GET - method requests that the entity be transferred only under the - circumstances described by the conditional header field(s). The - conditional GET method is intended to reduce unnecessary network - usage by allowing cached entities to be refreshed without requiring - multiple requests or transferring data already held by the client. - - The semantics of the GET method change to a "partial GET" if the - request message includes a Range header field. A partial GET requests - that only part of the entity be transferred, as described in section - 14.35. The partial GET method is intended to reduce unnecessary - network usage by allowing partially-retrieved entities to be - completed without transferring data already held by the client. - - The response to a GET request is cacheable if and only if it meets - the requirements for HTTP caching described in section 13. - - See section 15.1.3 for security considerations when used for forms. - - - - - - -Fielding, et al. Standards Track [Page 53] - -RFC 2616 HTTP/1.1 June 1999 - - -9.4 HEAD - - The HEAD method is identical to GET except that the server MUST NOT - return a message-body in the response. The metainformation contained - in the HTTP headers in response to a HEAD request SHOULD be identical - to the information sent in response to a GET request. This method can - be used for obtaining metainformation about the entity implied by the - request without transferring the entity-body itself. This method is - often used for testing hypertext links for validity, accessibility, - and recent modification. - - The response to a HEAD request MAY be cacheable in the sense that the - information contained in the response MAY be used to update a - previously cached entity from that resource. If the new field values - indicate that the cached entity differs from the current entity (as - would be indicated by a change in Content-Length, Content-MD5, ETag - or Last-Modified), then the cache MUST treat the cache entry as - stale. - -9.5 POST - - The POST method is used to request that the origin server accept the - entity enclosed in the request as a new subordinate of the resource - identified by the Request-URI in the Request-Line. POST is designed - to allow a uniform method to cover the following functions: - -[[ Should be: ]] -[[ The POST method is used to request that the origin server accept the ]] -[[ entity enclosed in the request as data to be processed by the resource ]] -[[ identified by the Request-URI in the Request-Line. POST is designed ]] -[[ to allow a uniform method to cover the following functions: ]] - - - Annotation of existing resources; - - - Posting a message to a bulletin board, newsgroup, mailing list, - or similar group of articles; - - - Providing a block of data, such as the result of submitting a - form, to a data-handling process; - - - Extending a database through an append operation. - - The actual function performed by the POST method is determined by the - server and is usually dependent on the Request-URI. The posted entity - is subordinate to that URI in the same way that a file is subordinate - to a directory containing it, a news article is subordinate to a - newsgroup to which it is posted, or a record is subordinate to a - database. - - [[ Remove second sentence ("The posted entity is subordinate") above ]] - - The action performed by the POST method might not result in a - resource that can be identified by a URI. In this case, either 200 - (OK) or 204 (No Content) is the appropriate response status, - depending on whether or not the response includes an entity that - describes the result. - - - -Fielding, et al. Standards Track [Page 54] - -RFC 2616 HTTP/1.1 June 1999 - - - If a resource has been created on the origin server, the response - SHOULD be 201 (Created) and contain an entity which describes the - status of the request and refers to the new resource, and a Location - header (see section 14.30). - - Responses to this method are not cacheable, unless the response - includes appropriate Cache-Control or Expires header fields. However, - the 303 (See Other) response can be used to direct the user agent to - retrieve a cacheable resource. - - POST requests MUST obey the message transmission requirements set out - in section 8.2. - - See section 15.1.3 for security considerations. - -9.6 PUT - - The PUT method requests that the enclosed entity be stored under the - supplied Request-URI. If the Request-URI refers to an already - existing resource, the enclosed entity SHOULD be considered as a - modified version of the one residing on the origin server. If the - Request-URI does not point to an existing resource, and that URI is - capable of being defined as a new resource by the requesting user - agent, the origin server can create the resource with that URI. If a - new resource is created, the origin server MUST inform the user agent - via the 201 (Created) response. If an existing resource is modified, - either the 200 (OK) or 204 (No Content) response codes SHOULD be sent - to indicate successful completion of the request. If the resource - could not be created or modified with the Request-URI, an appropriate - error response SHOULD be given that reflects the nature of the - problem. The recipient of the entity MUST NOT ignore any Content-* - (e.g. Content-Range) headers that it does not understand or implement - and MUST return a 501 (Not Implemented) response in such cases. - - If the request passes through a cache and the Request-URI identifies - one or more currently cached entities, those entries SHOULD be - treated as stale. Responses to this method are not cacheable. - - The fundamental difference between the POST and PUT requests is - reflected in the different meaning of the Request-URI. The URI in a - POST request identifies the resource that will handle the enclosed - entity. That resource might be a data-accepting process, a gateway to - some other protocol, or a separate entity that accepts annotations. - In contrast, the URI in a PUT request identifies the entity enclosed - with the request -- the user agent knows what URI is intended and the - server MUST NOT attempt to apply the request to some other resource. - If the server desires that the request be applied to a different URI, - - - - -Fielding, et al. Standards Track [Page 55] - -RFC 2616 HTTP/1.1 June 1999 - - - it MUST send a 301 (Moved Permanently) response; the user agent MAY - then make its own decision regarding whether or not to redirect the - request. - - A single resource MAY be identified by many different URIs. For - example, an article might have a URI for identifying "the current - version" which is separate from the URI identifying each particular - version. In this case, a PUT request on a general URI might result in - several other URIs being defined by the origin server. - - HTTP/1.1 does not define how a PUT method affects the state of an - origin server. - - PUT requests MUST obey the message transmission requirements set out - in section 8.2. - - Unless otherwise specified for a particular entity-header, the - entity-headers in the PUT request SHOULD be applied to the resource - created or modified by the PUT. - -9.7 DELETE - - The DELETE method requests that the origin server delete the resource - identified by the Request-URI. This method MAY be overridden by human - intervention (or other means) on the origin server. The client cannot - be guaranteed that the operation has been carried out, even if the - status code returned from the origin server indicates that the action - has been completed successfully. However, the server SHOULD NOT - indicate success unless, at the time the response is given, it - intends to delete the resource or move it to an inaccessible - location. - - A successful response SHOULD be 200 (OK) if the response includes an - entity describing the status, 202 (Accepted) if the action has not - yet been enacted, or 204 (No Content) if the action has been enacted - but the response does not include an entity. - - If the request passes through a cache and the Request-URI identifies - one or more currently cached entities, those entries SHOULD be - treated as stale. Responses to this method are not cacheable. - -9.8 TRACE - - The TRACE method is used to invoke a remote, application-layer loop- - back of the request message. The final recipient of the request - SHOULD reflect the message received back to the client as the - entity-body of a 200 (OK) response. The final recipient is either the - - - - -Fielding, et al. Standards Track [Page 56] - -RFC 2616 HTTP/1.1 June 1999 - - - origin server or the first proxy or gateway to receive a Max-Forwards - value of zero (0) in the request (see section 14.31). A TRACE request - MUST NOT include an entity. - - TRACE allows the client to see what is being received at the other - end of the request chain and use that data for testing or diagnostic - information. The value of the Via header field (section 14.45) is of - particular interest, since it acts as a trace of the request chain. - Use of the Max-Forwards header field allows the client to limit the - length of the request chain, which is useful for testing a chain of - proxies forwarding messages in an infinite loop. - - If the request is valid, the response SHOULD contain the entire - request message in the entity-body, with a Content-Type of - "message/http". Responses to this method MUST NOT be cached. - -9.9 CONNECT - - This specification reserves the method name CONNECT for use with a - proxy that can dynamically switch to being a tunnel (e.g. SSL - tunneling [44]). - -10 Status Code Definitions - - Each Status-Code is described below, including a description of which - method(s) it can follow and any metainformation required in the - response. - -10.1 Informational 1xx - - This class of status code indicates a provisional response, - consisting only of the Status-Line and optional headers, and is - terminated by an empty line. There are no required headers for this - class of status code. Since HTTP/1.0 did not define any 1xx status - codes, servers MUST NOT send a 1xx response to an HTTP/1.0 client - except under experimental conditions. - - A client MUST be prepared to accept one or more 1xx status responses - prior to a regular response, even if the client does not expect a 100 - (Continue) status message. Unexpected 1xx status responses MAY be - ignored by a user agent. - - Proxies MUST forward 1xx responses, unless the connection between the - proxy and its client has been closed, or unless the proxy itself - requested the generation of the 1xx response. (For example, if a - - - - - - -Fielding, et al. Standards Track [Page 57] - -RFC 2616 HTTP/1.1 June 1999 - - - proxy adds a "Expect: 100-continue" field when it forwards a request, - then it need not forward the corresponding 100 (Continue) - response(s).) - -10.1.1 100 Continue - - The client SHOULD continue with its request. This interim response is - used to inform the client that the initial part of the request has - been received and has not yet been rejected by the server. The client - SHOULD continue by sending the remainder of the request or, if the - request has already been completed, ignore this response. The server - MUST send a final response after the request has been completed. See - section 8.2.3 for detailed discussion of the use and handling of this - status code. - -10.1.2 101 Switching Protocols - - The server understands and is willing to comply with the client's - request, via the Upgrade message header field (section 14.42), for a - change in the application protocol being used on this connection. The - server will switch protocols to those defined by the response's - Upgrade header field immediately after the empty line which - terminates the 101 response. - - The protocol SHOULD be switched only when it is advantageous to do - so. For example, switching to a newer version of HTTP is advantageous - over older versions, and switching to a real-time, synchronous - protocol might be advantageous when delivering resources that use - such features. - -10.2 Successful 2xx - - This class of status code indicates that the client's request was - successfully received, understood, and accepted. - -10.2.1 200 OK - - The request has succeeded. The information returned with the response - is dependent on the method used in the request, for example: - - GET an entity corresponding to the requested resource is sent in - the response; - - HEAD the entity-header fields corresponding to the requested - resource are sent in the response without any message-body; - - POST an entity describing or containing the result of the action; - - - - -Fielding, et al. Standards Track [Page 58] - -RFC 2616 HTTP/1.1 June 1999 - - - TRACE an entity containing the request message as received by the - end server. - -10.2.2 201 Created - - The request has been fulfilled and resulted in a new resource being - created. The newly created resource can be referenced by the URI(s) - returned in the entity of the response, with the most specific URI - for the resource given by a Location header field. The response - SHOULD include an entity containing a list of resource - characteristics and location(s) from which the user or user agent can - choose the one most appropriate. The entity format is specified by - the media type given in the Content-Type header field. The origin - server MUST create the resource before returning the 201 status code. - If the action cannot be carried out immediately, the server SHOULD - respond with 202 (Accepted) response instead. - - A 201 response MAY contain an ETag response header field indicating - the current value of the entity tag for the requested variant just - created, see section 14.19. - -10.2.3 202 Accepted - - The request has been accepted for processing, but the processing has - not been completed. The request might or might not eventually be - acted upon, as it might be disallowed when processing actually takes - place. There is no facility for re-sending a status code from an - asynchronous operation such as this. - - The 202 response is intentionally non-committal. Its purpose is to - allow a server to accept a request for some other process (perhaps a - batch-oriented process that is only run once per day) without - requiring that the user agent's connection to the server persist - until the process is completed. The entity returned with this - response SHOULD include an indication of the request's current status - and either a pointer to a status monitor or some estimate of when the - user can expect the request to be fulfilled. - -10.2.4 203 Non-Authoritative Information - - The returned metainformation in the entity-header is not the - definitive set as available from the origin server, but is gathered - from a local or a third-party copy. The set presented MAY be a subset - or superset of the original version. For example, including local - annotation information about the resource might result in a superset - of the metainformation known by the origin server. Use of this - response code is not required and is only appropriate when the - response would otherwise be 200 (OK). - - - -Fielding, et al. Standards Track [Page 59] - -RFC 2616 HTTP/1.1 June 1999 - - -10.2.5 204 No Content - - The server has fulfilled the request but does not need to return an - entity-body, and might want to return updated metainformation. The - response MAY include new or updated metainformation in the form of - entity-headers, which if present SHOULD be associated with the - requested variant. - - If the client is a user agent, it SHOULD NOT change its document view - from that which caused the request to be sent. This response is - primarily intended to allow input for actions to take place without - causing a change to the user agent's active document view, although - any new or updated metainformation SHOULD be applied to the document - currently in the user agent's active view. - - The 204 response MUST NOT include a message-body, and thus is always - terminated by the first empty line after the header fields. - -10.2.6 205 Reset Content - - The server has fulfilled the request and the user agent SHOULD reset - the document view which caused the request to be sent. This response - is primarily intended to allow input for actions to take place via - user input, followed by a clearing of the form in which the input is - given so that the user can easily initiate another input action. The - response MUST NOT include an entity. - -10.2.7 206 Partial Content - - The server has fulfilled the partial GET request for the resource. - The request MUST have included a Range header field (section 14.35) - indicating the desired range, and MAY have included an If-Range - header field (section 14.27) to make the request conditional. - - The response MUST include the following header fields: - - - Either a Content-Range header field (section 14.16) indicating - the range included with this response, or a multipart/byteranges - Content-Type including Content-Range fields for each part. If a - Content-Length header field is present in the response, its - value MUST match the actual number of OCTETs transmitted in the - message-body. - - - Date - - - ETag and/or Content-Location, if the header would have been sent - in a 200 response to the same request - - - - -Fielding, et al. Standards Track [Page 60] - -RFC 2616 HTTP/1.1 June 1999 - - - - Expires, Cache-Control, and/or Vary, if the field-value might - differ from that sent in any previous response for the same - variant - - If the 206 response is the result of an If-Range request that used a - strong cache validator (see section 13.3.3), the response SHOULD NOT - include other entity-headers. If the response is the result of an - If-Range request that used a weak validator, the response MUST NOT - include other entity-headers; this prevents inconsistencies between - cached entity-bodies and updated headers. Otherwise, the response - MUST include all of the entity-headers that would have been returned - with a 200 (OK) response to the same request. - -[[ Should be: ]] -[[ If the 206 response is the result of an If-Range request, the ]] -[[ response SHOULD NOT include other entity-headers. Otherwise, the ]] -[[ response MUST include all of the entity-headers that would have ]] -[[ been returned with a 200 (OK) response to the same request. ]] - - A cache MUST NOT combine a 206 response with other previously cached - content if the ETag or Last-Modified headers do not match exactly, - see 13.5.4. - - A cache that does not support the Range and Content-Range headers - MUST NOT cache 206 (Partial) responses. - -10.3 Redirection 3xx - - This class of status code indicates that further action needs to be - taken by the user agent in order to fulfill the request. The action - required MAY be carried out by the user agent without interaction - with the user if and only if the method used in the second request is - GET or HEAD. A client SHOULD detect infinite redirection loops, since - such loops generate network traffic for each redirection. - - Note: previous versions of this specification recommended a - maximum of five redirections. Content developers should be aware - that there might be clients that implement such a fixed - limitation. - -10.3.1 300 Multiple Choices - - The requested resource corresponds to any one of a set of - representations, each with its own specific location, and agent- - driven negotiation information (section 12) is being provided so that - the user (or user agent) can select a preferred representation and - redirect its request to that location. - - Unless it was a HEAD request, the response SHOULD include an entity - containing a list of resource characteristics and location(s) from - which the user or user agent can choose the one most appropriate. The - entity format is specified by the media type given in the Content- - Type header field. Depending upon the format and the capabilities of - - - - -Fielding, et al. Standards Track [Page 61] - -RFC 2616 HTTP/1.1 June 1999 - - - the user agent, selection of the most appropriate choice MAY be - performed automatically. However, this specification does not define - any standard for such automatic selection. - - If the server has a preferred choice of representation, it SHOULD - include the specific URI for that representation in the Location - field; user agents MAY use the Location field value for automatic - redirection. This response is cacheable unless indicated otherwise. - -10.3.2 301 Moved Permanently - - The requested resource has been assigned a new permanent URI and any - future references to this resource SHOULD use one of the returned - URIs. Clients with link editing capabilities ought to automatically - re-link references to the Request-URI to one or more of the new - references returned by the server, where possible. This response is - cacheable unless indicated otherwise. - - The new permanent URI SHOULD be given by the Location field in the - response. Unless the request method was HEAD, the entity of the - response SHOULD contain a short hypertext note with a hyperlink to - the new URI(s). - - If the 301 status code is received in response to a request other - than GET or HEAD, the user agent MUST NOT automatically redirect the - request unless it can be confirmed by the user, since this might - change the conditions under which the request was issued. - -[[ Should be: ]] -[[ If the 301 status code is received in response to a request method ]] -[[ that is known to be "safe", as defined in section 9.1.1, then the ]] -[[ request MAY be automatically redirected by the user agent without ]] -[[ confirmation. Otherwise, the user agent MUST NOT automatically ]] -[[ redirect the request unless it is confirmed by the user, since the ]] -[[ new URI might change the conditions under which the request was ]] -[[ issued. ]] - - Note: When automatically redirecting a POST request after - receiving a 301 status code, some existing HTTP/1.0 user agents - will erroneously change it into a GET request. - -10.3.3 302 Found - - The requested resource resides temporarily under a different URI. - Since the redirection might be altered on occasion, the client SHOULD - continue to use the Request-URI for future requests. This response - is only cacheable if indicated by a Cache-Control or Expires header - field. - - The temporary URI SHOULD be given by the Location field in the - response. Unless the request method was HEAD, the entity of the - response SHOULD contain a short hypertext note with a hyperlink to - the new URI(s). - - - - - - - -Fielding, et al. Standards Track [Page 62] - -RFC 2616 HTTP/1.1 June 1999 - - - If the 302 status code is received in response to a request other - than GET or HEAD, the user agent MUST NOT automatically redirect the - request unless it can be confirmed by the user, since this might - change the conditions under which the request was issued. - - [[ See errata to 10.3.3 ]] - - Note: RFC 1945 and RFC 2068 specify that the client is not allowed - to change the method on the redirected request. However, most - existing user agent implementations treat 302 as if it were a 303 - response, performing a GET on the Location field-value regardless - of the original request method. The status codes 303 and 307 have - been added for servers that wish to make unambiguously clear which - kind of reaction is expected of the client. - -10.3.4 303 See Other - - The response to the request can be found under a different URI and - SHOULD be retrieved using a GET method on that resource. This method - exists primarily to allow the output of a POST-activated script to - redirect the user agent to a selected resource. The new URI is not a - substitute reference for the originally requested resource. The 303 - response MUST NOT be cached, but the response to the second - (redirected) request might be cacheable. - - The different URI SHOULD be given by the Location field in the - response. Unless the request method was HEAD, the entity of the - response SHOULD contain a short hypertext note with a hyperlink to - the new URI(s). - - Note: Many pre-HTTP/1.1 user agents do not understand the 303 - status. When interoperability with such clients is a concern, the - 302 status code may be used instead, since most user agents react - to a 302 response as described here for 303. - -10.3.5 304 Not Modified - - If the client has performed a conditional GET request and access is - allowed, but the document has not been modified, the server SHOULD - respond with this status code. The 304 response MUST NOT contain a - message-body, and thus is always terminated by the first empty line - after the header fields. - - The response MUST include the following header fields: - - - Date, unless its omission is required by section 14.18.1 - - - - - - - -Fielding, et al. Standards Track [Page 63] - -RFC 2616 HTTP/1.1 June 1999 - - - If a clockless origin server obeys these rules, and proxies and - clients add their own Date to any response received without one (as - already specified by [RFC 2068], section 14.19), caches will operate - correctly. - - - ETag and/or Content-Location, if the header would have been sent - in a 200 response to the same request - - - Expires, Cache-Control, and/or Vary, if the field-value might - differ from that sent in any previous response for the same - variant - - If the conditional GET used a strong cache validator (see section - 13.3.3), the response SHOULD NOT include other entity-headers. - Otherwise (i.e., the conditional GET used a weak validator), the - response MUST NOT include other entity-headers; this prevents - inconsistencies between cached entity-bodies and updated headers. - - If a 304 response indicates an entity not currently cached, then the - cache MUST disregard the response and repeat the request without the - conditional. - - If a cache uses a received 304 response to update a cache entry, the - cache MUST update the entry to reflect any new field values given in - the response. - -10.3.6 305 Use Proxy - - The requested resource MUST be accessed through the proxy given by - the Location field. The Location field gives the URI of the proxy. - The recipient is expected to repeat this single request via the - proxy. 305 responses MUST only be generated by origin servers. - - Note: RFC 2068 was not clear that 305 was intended to redirect a - single request, and to be generated by origin servers only. Not - observing these limitations has significant security consequences. - -10.3.7 306 (Unused) - - The 306 status code was used in a previous version of the - specification, is no longer used, and the code is reserved. - - - - - - - - - - -Fielding, et al. Standards Track [Page 64] - -RFC 2616 HTTP/1.1 June 1999 - - -10.3.8 307 Temporary Redirect - - The requested resource resides temporarily under a different URI. - Since the redirection MAY be altered on occasion, the client SHOULD - continue to use the Request-URI for future requests. This response - is only cacheable if indicated by a Cache-Control or Expires header - field. - - The temporary URI SHOULD be given by the Location field in the - response. Unless the request method was HEAD, the entity of the - response SHOULD contain a short hypertext note with a hyperlink to - the new URI(s) , since many pre-HTTP/1.1 user agents do not - understand the 307 status. Therefore, the note SHOULD contain the - information necessary for a user to repeat the original request on - the new URI. - - If the 307 status code is received in response to a request other - than GET or HEAD, the user agent MUST NOT automatically redirect the - request unless it can be confirmed by the user, since this might - change the conditions under which the request was issued. - - [[ See errata to 10.3.3 ]] - -10.4 Client Error 4xx - - The 4xx class of status code is intended for cases in which the - client seems to have erred. Except when responding to a HEAD request, - the server SHOULD include an entity containing an explanation of the - error situation, and whether it is a temporary or permanent - condition. These status codes are applicable to any request method. - User agents SHOULD display any included entity to the user. - - If the client is sending data, a server implementation using TCP - SHOULD be careful to ensure that the client acknowledges receipt of - the packet(s) containing the response, before the server closes the - input connection. If the client continues sending data to the server - after the close, the server's TCP stack will send a reset packet to - the client, which may erase the client's unacknowledged input buffers - before they can be read and interpreted by the HTTP application. - -10.4.1 400 Bad Request - - The request could not be understood by the server due to malformed - syntax. The client SHOULD NOT repeat the request without - modifications. - - - - - - - - -Fielding, et al. Standards Track [Page 65] - -RFC 2616 HTTP/1.1 June 1999 - - -10.4.2 401 Unauthorized - - The request requires user authentication. The response MUST include a - WWW-Authenticate header field (section 14.47) containing a challenge - applicable to the requested resource. The client MAY repeat the - request with a suitable Authorization header field (section 14.8). If - the request already included Authorization credentials, then the 401 - response indicates that authorization has been refused for those - credentials. If the 401 response contains the same challenge as the - prior response, and the user agent has already attempted - authentication at least once, then the user SHOULD be presented the - entity that was given in the response, since that entity might - include relevant diagnostic information. HTTP access authentication - is explained in "HTTP Authentication: Basic and Digest Access - Authentication" [43]. - -10.4.3 402 Payment Required - - This code is reserved for future use. - -10.4.4 403 Forbidden - - The server understood the request, but is refusing to fulfill it. - Authorization will not help and the request SHOULD NOT be repeated. - If the request method was not HEAD and the server wishes to make - public why the request has not been fulfilled, it SHOULD describe the - reason for the refusal in the entity. If the server does not wish to - make this information available to the client, the status code 404 - (Not Found) can be used instead. - -10.4.5 404 Not Found - - The server has not found anything matching the Request-URI. No - indication is given of whether the condition is temporary or - permanent. The 410 (Gone) status code SHOULD be used if the server - knows, through some internally configurable mechanism, that an old - resource is permanently unavailable and has no forwarding address. - This status code is commonly used when the server does not wish to - reveal exactly why the request has been refused, or when no other - response is applicable. - -10.4.6 405 Method Not Allowed - - The method specified in the Request-Line is not allowed for the - resource identified by the Request-URI. The response MUST include an - Allow header containing a list of valid methods for the requested - resource. - - - - -Fielding, et al. Standards Track [Page 66] - -RFC 2616 HTTP/1.1 June 1999 - - -10.4.7 406 Not Acceptable - - The resource identified by the request is only capable of generating - response entities which have content characteristics not acceptable - according to the accept headers sent in the request. - - Unless it was a HEAD request, the response SHOULD include an entity - containing a list of available entity characteristics and location(s) - from which the user or user agent can choose the one most - appropriate. The entity format is specified by the media type given - in the Content-Type header field. Depending upon the format and the - capabilities of the user agent, selection of the most appropriate - choice MAY be performed automatically. However, this specification - does not define any standard for such automatic selection. - - Note: HTTP/1.1 servers are allowed to return responses which are - not acceptable according to the accept headers sent in the - request. In some cases, this may even be preferable to sending a - 406 response. User agents are encouraged to inspect the headers of - an incoming response to determine if it is acceptable. - - If the response could be unacceptable, a user agent SHOULD - temporarily stop receipt of more data and query the user for a - decision on further actions. - -10.4.8 407 Proxy Authentication Required - - This code is similar to 401 (Unauthorized), but indicates that the - client must first authenticate itself with the proxy. The proxy MUST - return a Proxy-Authenticate header field (section 14.33) containing a - challenge applicable to the proxy for the requested resource. The - client MAY repeat the request with a suitable Proxy-Authorization - header field (section 14.34). HTTP access authentication is explained - in "HTTP Authentication: Basic and Digest Access Authentication" - [43]. - -10.4.9 408 Request Timeout - - The client did not produce a request within the time that the server - was prepared to wait. The client MAY repeat the request without - modifications at any later time. - -10.4.10 409 Conflict - - The request could not be completed due to a conflict with the current - state of the resource. This code is only allowed in situations where - it is expected that the user might be able to resolve the conflict - and resubmit the request. The response body SHOULD include enough - - - -Fielding, et al. Standards Track [Page 67] - -RFC 2616 HTTP/1.1 June 1999 - - - information for the user to recognize the source of the conflict. - Ideally, the response entity would include enough information for the - user or user agent to fix the problem; however, that might not be - possible and is not required. - - Conflicts are most likely to occur in response to a PUT request. For - example, if versioning were being used and the entity being PUT - included changes to a resource which conflict with those made by an - earlier (third-party) request, the server might use the 409 response - to indicate that it can't complete the request. In this case, the - response entity would likely contain a list of the differences - between the two versions in a format defined by the response - Content-Type. - -10.4.11 410 Gone - - The requested resource is no longer available at the server and no - forwarding address is known. This condition is expected to be - considered permanent. Clients with link editing capabilities SHOULD - delete references to the Request-URI after user approval. If the - server does not know, or has no facility to determine, whether or not - the condition is permanent, the status code 404 (Not Found) SHOULD be - used instead. This response is cacheable unless indicated otherwise. - - The 410 response is primarily intended to assist the task of web - maintenance by notifying the recipient that the resource is - intentionally unavailable and that the server owners desire that - remote links to that resource be removed. Such an event is common for - limited-time, promotional services and for resources belonging to - individuals no longer working at the server's site. It is not - necessary to mark all permanently unavailable resources as "gone" or - to keep the mark for any length of time -- that is left to the - discretion of the server owner. - -10.4.12 411 Length Required - - The server refuses to accept the request without a defined Content- - Length. The client MAY repeat the request if it adds a valid - Content-Length header field containing the length of the message-body - in the request message. - -10.4.13 412 Precondition Failed - - The precondition given in one or more of the request-header fields - evaluated to false when it was tested on the server. This response - code allows the client to place preconditions on the current resource - metainformation (header field data) and thus prevent the requested - method from being applied to a resource other than the one intended. - - - -Fielding, et al. Standards Track [Page 68] - -RFC 2616 HTTP/1.1 June 1999 - - -10.4.14 413 Request Entity Too Large - - The server is refusing to process a request because the request - entity is larger than the server is willing or able to process. The - server MAY close the connection to prevent the client from continuing - the request. - - If the condition is temporary, the server SHOULD include a Retry- - After header field to indicate that it is temporary and after what - time the client MAY try again. - -10.4.15 414 Request-URI Too Long - - The server is refusing to service the request because the Request-URI - is longer than the server is willing to interpret. This rare - condition is only likely to occur when a client has improperly - converted a POST request to a GET request with long query - information, when the client has descended into a URI "black hole" of - redirection (e.g., a redirected URI prefix that points to a suffix of - itself), or when the server is under attack by a client attempting to - exploit security holes present in some servers using fixed-length - buffers for reading or manipulating the Request-URI. - -10.4.16 415 Unsupported Media Type - - The server is refusing to service the request because the entity of - the request is in a format not supported by the requested resource - for the requested method. - -10.4.17 416 Requested Range Not Satisfiable - - A server SHOULD return a response with this status code if a request - included a Range request-header field (section 14.35), and none of - the range-specifier values in this field overlap the current extent - of the selected resource, and the request did not include an If-Range - request-header field. (For byte-ranges, this means that the first- - byte-pos of all of the byte-range-spec values were greater than the - current length of the selected resource.) - - When this status code is returned for a byte-range request, the - response SHOULD include a Content-Range entity-header field - specifying the current length of the selected resource (see section - 14.16). This response MUST NOT use the multipart/byteranges content- - type. - - - - - - - -Fielding, et al. Standards Track [Page 69] - -RFC 2616 HTTP/1.1 June 1999 - - -10.4.18 417 Expectation Failed - - The expectation given in an Expect request-header field (see section - 14.20) could not be met by this server, or, if the server is a proxy, - the server has unambiguous evidence that the request could not be met - by the next-hop server. - -10.5 Server Error 5xx - - Response status codes beginning with the digit "5" indicate cases in - which the server is aware that it has erred or is incapable of - performing the request. Except when responding to a HEAD request, the - server SHOULD include an entity containing an explanation of the - error situation, and whether it is a temporary or permanent - condition. User agents SHOULD display any included entity to the - user. These response codes are applicable to any request method. - -10.5.1 500 Internal Server Error - - The server encountered an unexpected condition which prevented it - from fulfilling the request. - -10.5.2 501 Not Implemented - - The server does not support the functionality required to fulfill the - request. This is the appropriate response when the server does not - recognize the request method and is not capable of supporting it for - any resource. - -10.5.3 502 Bad Gateway - - The server, while acting as a gateway or proxy, received an invalid - response from the upstream server it accessed in attempting to - fulfill the request. - -10.5.4 503 Service Unavailable - - The server is currently unable to handle the request due to a - temporary overloading or maintenance of the server. The implication - is that this is a temporary condition which will be alleviated after - some delay. If known, the length of the delay MAY be indicated in a - Retry-After header. If no Retry-After is given, the client SHOULD - handle the response as it would for a 500 response. - - Note: The existence of the 503 status code does not imply that a - server must use it when becoming overloaded. Some servers may wish - to simply refuse the connection. - - - - -Fielding, et al. Standards Track [Page 70] - -RFC 2616 HTTP/1.1 June 1999 - - -10.5.5 504 Gateway Timeout - - The server, while acting as a gateway or proxy, did not receive a - timely response from the upstream server specified by the URI (e.g. - HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed - to access in attempting to complete the request. - - Note: Note to implementors: some deployed proxies are known to - return 400 or 500 when DNS lookups time out. - -10.5.6 505 HTTP Version Not Supported - - The server does not support, or refuses to support, the HTTP protocol - version that was used in the request message. The server is - indicating that it is unable or unwilling to complete the request - using the same major version as the client, as described in section - 3.1, other than with this error message. The response SHOULD contain - an entity describing why that version is not supported and what other - protocols are supported by that server. - -11 Access Authentication - - HTTP provides several OPTIONAL challenge-response authentication - mechanisms which can be used by a server to challenge a client - request and by a client to provide authentication information. The - general framework for access authentication, and the specification of - "basic" and "digest" authentication, are specified in "HTTP - Authentication: Basic and Digest Access Authentication" [43]. This - specification adopts the definitions of "challenge" and "credentials" - from that specification. - -12 Content Negotiation - - Most HTTP responses include an entity which contains information for - interpretation by a human user. Naturally, it is desirable to supply - the user with the "best available" entity corresponding to the - request. Unfortunately for servers and caches, not all users have the - same preferences for what is "best," and not all user agents are - equally capable of rendering all entity types. For that reason, HTTP - has provisions for several mechanisms for "content negotiation" -- - the process of selecting the best representation for a given response - when there are multiple representations available. - - Note: This is not called "format negotiation" because the - alternate representations may be of the same media type, but use - different capabilities of that type, be in different languages, - etc. - - - - -Fielding, et al. Standards Track [Page 71] - -RFC 2616 HTTP/1.1 June 1999 - - - Any response containing an entity-body MAY be subject to negotiation, - including error responses. - - There are two kinds of content negotiation which are possible in - HTTP: server-driven and agent-driven negotiation. These two kinds of - negotiation are orthogonal and thus may be used separately or in - combination. One method of combination, referred to as transparent - negotiation, occurs when a cache uses the agent-driven negotiation - information provided by the origin server in order to provide - server-driven negotiation for subsequent requests. - -12.1 Server-driven Negotiation - - If the selection of the best representation for a response is made by - an algorithm located at the server, it is called server-driven - negotiation. Selection is based on the available representations of - the response (the dimensions over which it can vary; e.g. language, - content-coding, etc.) and the contents of particular header fields in - the request message or on other information pertaining to the request - (such as the network address of the client). - - Server-driven negotiation is advantageous when the algorithm for - selecting from among the available representations is difficult to - describe to the user agent, or when the server desires to send its - "best guess" to the client along with the first response (hoping to - avoid the round-trip delay of a subsequent request if the "best - guess" is good enough for the user). In order to improve the server's - guess, the user agent MAY include request header fields (Accept, - Accept-Language, Accept-Encoding, etc.) which describe its - preferences for such a response. - - Server-driven negotiation has disadvantages: - - 1. It is impossible for the server to accurately determine what - might be "best" for any given user, since that would require - complete knowledge of both the capabilities of the user agent - and the intended use for the response (e.g., does the user want - to view it on screen or print it on paper?). - - 2. Having the user agent describe its capabilities in every - request can be both very inefficient (given that only a small - percentage of responses have multiple representations) and a - potential violation of the user's privacy. - - 3. It complicates the implementation of an origin server and the - algorithms for generating responses to a request. - - - - - -Fielding, et al. Standards Track [Page 72] - -RFC 2616 HTTP/1.1 June 1999 - - - 4. It may limit a public cache's ability to use the same response - for multiple user's requests. - - HTTP/1.1 includes the following request-header fields for enabling - server-driven negotiation through description of user agent - capabilities and user preferences: Accept (section 14.1), Accept- - Charset (section 14.2), Accept-Encoding (section 14.3), Accept- - Language (section 14.4), and User-Agent (section 14.43). However, an - origin server is not limited to these dimensions and MAY vary the - response based on any aspect of the request, including information - outside the request-header fields or within extension header fields - not defined by this specification. - - The Vary header field can be used to express the parameters the - server uses to select a representation that is subject to server- - driven negotiation. See section 13.6 for use of the Vary header field - by caches and section 14.44 for use of the Vary header field by - servers. - -12.2 Agent-driven Negotiation - - With agent-driven negotiation, selection of the best representation - for a response is performed by the user agent after receiving an - initial response from the origin server. Selection is based on a list - of the available representations of the response included within the - header fields or entity-body of the initial response, with each - representation identified by its own URI. Selection from among the - representations may be performed automatically (if the user agent is - capable of doing so) or manually by the user selecting from a - generated (possibly hypertext) menu. - - Agent-driven negotiation is advantageous when the response would vary - over commonly-used dimensions (such as type, language, or encoding), - when the origin server is unable to determine a user agent's - capabilities from examining the request, and generally when public - caches are used to distribute server load and reduce network usage. - - Agent-driven negotiation suffers from the disadvantage of needing a - second request to obtain the best alternate representation. This - second request is only efficient when caching is used. In addition, - this specification does not define any mechanism for supporting - automatic selection, though it also does not prevent any such - mechanism from being developed as an extension and used within - HTTP/1.1. - - - - - - - -Fielding, et al. Standards Track [Page 73] - -RFC 2616 HTTP/1.1 June 1999 - - - HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable) - status codes for enabling agent-driven negotiation when the server is - unwilling or unable to provide a varying response using server-driven - negotiation. - -12.3 Transparent Negotiation - - Transparent negotiation is a combination of both server-driven and - agent-driven negotiation. When a cache is supplied with a form of the - list of available representations of the response (as in agent-driven - negotiation) and the dimensions of variance are completely understood - by the cache, then the cache becomes capable of performing server- - driven negotiation on behalf of the origin server for subsequent - requests on that resource. - - Transparent negotiation has the advantage of distributing the - negotiation work that would otherwise be required of the origin - server and also removing the second request delay of agent-driven - negotiation when the cache is able to correctly guess the right - response. - - This specification does not define any mechanism for transparent - negotiation, though it also does not prevent any such mechanism from - being developed as an extension that could be used within HTTP/1.1. - -13 Caching in HTTP - - HTTP is typically used for distributed information systems, where - performance can be improved by the use of response caches. The - HTTP/1.1 protocol includes a number of elements intended to make - caching work as well as possible. Because these elements are - inextricable from other aspects of the protocol, and because they - interact with each other, it is useful to describe the basic caching - design of HTTP separately from the detailed descriptions of methods, - headers, response codes, etc. - - Caching would be useless if it did not significantly improve - performance. The goal of caching in HTTP/1.1 is to eliminate the need - to send requests in many cases, and to eliminate the need to send - full responses in many other cases. The former reduces the number of - network round-trips required for many operations; we use an - "expiration" mechanism for this purpose (see section 13.2). The - latter reduces network bandwidth requirements; we use a "validation" - mechanism for this purpose (see section 13.3). - - Requirements for performance, availability, and disconnected - operation require us to be able to relax the goal of semantic - transparency. The HTTP/1.1 protocol allows origin servers, caches, - - - -Fielding, et al. Standards Track [Page 74] - -RFC 2616 HTTP/1.1 June 1999 - - - and clients to explicitly reduce transparency when necessary. - However, because non-transparent operation may confuse non-expert - users, and might be incompatible with certain server applications - (such as those for ordering merchandise), the protocol requires that - transparency be relaxed - - - only by an explicit protocol-level request when relaxed by - client or origin server - - - only with an explicit warning to the end user when relaxed by - cache or client - - Therefore, the HTTP/1.1 protocol provides these important elements: - - 1. Protocol features that provide full semantic transparency when - this is required by all parties. - - 2. Protocol features that allow an origin server or user agent to - explicitly request and control non-transparent operation. - - 3. Protocol features that allow a cache to attach warnings to - responses that do not preserve the requested approximation of - semantic transparency. - - A basic principle is that it must be possible for the clients to - detect any potential relaxation of semantic transparency. - - Note: The server, cache, or client implementor might be faced with - design decisions not explicitly discussed in this specification. - If a decision might affect semantic transparency, the implementor - ought to err on the side of maintaining transparency unless a - careful and complete analysis shows significant benefits in - breaking transparency. - -13.1.1 Cache Correctness - - A correct cache MUST respond to a request with the most up-to-date - response held by the cache that is appropriate to the request (see - sections 13.2.5, 13.2.6, and 13.12) which meets one of the following - conditions: - - 1. It has been checked for equivalence with what the origin server - would have returned by revalidating the response with the - origin server (section 13.3); - - - - - - - -Fielding, et al. Standards Track [Page 75] - -RFC 2616 HTTP/1.1 June 1999 - - - 2. It is "fresh enough" (see section 13.2). In the default case, - this means it meets the least restrictive freshness requirement - of the client, origin server, and cache (see section 14.9); if - the origin server so specifies, it is the freshness requirement - of the origin server alone. - - If a stored response is not "fresh enough" by the most - restrictive freshness requirement of both the client and the - origin server, in carefully considered circumstances the cache - MAY still return the response with the appropriate Warning - header (see section 13.1.5 and 14.46), unless such a response - is prohibited (e.g., by a "no-store" cache-directive, or by a - "no-cache" cache-request-directive; see section 14.9). - - 3. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), - or error (4xx or 5xx) response message. - - If the cache can not communicate with the origin server, then a - correct cache SHOULD respond as above if the response can be - correctly served from the cache; if not it MUST return an error or - warning indicating that there was a communication failure. - - If a cache receives a response (either an entire response, or a 304 - (Not Modified) response) that it would normally forward to the - requesting client, and the received response is no longer fresh, the - cache SHOULD forward it to the requesting client without adding a new - Warning (but without removing any existing Warning headers). A cache - SHOULD NOT attempt to revalidate a response simply because that - response became stale in transit; this might lead to an infinite - loop. A user agent that receives a stale response without a Warning - MAY display a warning indication to the user. - -13.1.2 Warnings - - Whenever a cache returns a response that is neither first-hand nor - "fresh enough" (in the sense of condition 2 in section 13.1.1), it - MUST attach a warning to that effect, using a Warning general-header. - The Warning header and the currently defined warnings are described - in section 14.46. The warning allows clients to take appropriate - action. - - Warnings MAY be used for other purposes, both cache-related and - otherwise. The use of a warning, rather than an error status code, - distinguish these responses from true failures. - - Warnings are assigned three digit warn-codes. The first digit - indicates whether the Warning MUST or MUST NOT be deleted from a - stored cache entry after a successful revalidation: - - - -Fielding, et al. Standards Track [Page 76] - -RFC 2616 HTTP/1.1 June 1999 - - - 1xx Warnings that describe the freshness or revalidation status of - the response, and so MUST be deleted after a successful - revalidation. 1XX warn-codes MAY be generated by a cache only when - validating a cached entry. It MUST NOT be generated by clients. - - 2xx Warnings that describe some aspect of the entity body or entity - headers that is not rectified by a revalidation (for example, a - lossy compression of the entity bodies) and which MUST NOT be - deleted after a successful revalidation. - - See section 14.46 for the definitions of the codes themselves. - - HTTP/1.0 caches will cache all Warnings in responses, without - deleting the ones in the first category. Warnings in responses that - are passed to HTTP/1.0 caches carry an extra warning-date field, - which prevents a future HTTP/1.1 recipient from believing an - erroneously cached Warning. - - Warnings also carry a warning text. The text MAY be in any - appropriate natural language (perhaps based on the client's Accept - headers), and include an OPTIONAL indication of what character set is - used. - - Multiple warnings MAY be attached to a response (either by the origin - server or by a cache), including multiple warnings with the same code - number. For example, a server might provide the same warning with - texts in both English and Basque. - - When multiple warnings are attached to a response, it might not be - practical or reasonable to display all of them to the user. This - version of HTTP does not specify strict priority rules for deciding - which warnings to display and in what order, but does suggest some - heuristics. - -13.1.3 Cache-control Mechanisms - - The basic cache mechanisms in HTTP/1.1 (server-specified expiration - times and validators) are implicit directives to caches. In some - cases, a server or client might need to provide explicit directives - to the HTTP caches. We use the Cache-Control header for this purpose. - - The Cache-Control header allows a client or server to transmit a - variety of directives in either requests or responses. These - directives typically override the default caching algorithms. As a - general rule, if there is any apparent conflict between header - values, the most restrictive interpretation is applied (that is, the - one that is most likely to preserve semantic transparency). However, - - - - -Fielding, et al. Standards Track [Page 77] - -RFC 2616 HTTP/1.1 June 1999 - - - in some cases, cache-control directives are explicitly specified as - weakening the approximation of semantic transparency (for example, - "max-stale" or "public"). - - The cache-control directives are described in detail in section 14.9. - -13.1.4 Explicit User Agent Warnings - - Many user agents make it possible for users to override the basic - caching mechanisms. For example, the user agent might allow the user - to specify that cached entities (even explicitly stale ones) are - never validated. Or the user agent might habitually add "Cache- - Control: max-stale=3600" to every request. The user agent SHOULD NOT - default to either non-transparent behavior, or behavior that results - in abnormally ineffective caching, but MAY be explicitly configured - to do so by an explicit action of the user. - - If the user has overridden the basic caching mechanisms, the user - agent SHOULD explicitly indicate to the user whenever this results in - the display of information that might not meet the server's - transparency requirements (in particular, if the displayed entity is - known to be stale). Since the protocol normally allows the user agent - to determine if responses are stale or not, this indication need only - be displayed when this actually happens. The indication need not be a - dialog box; it could be an icon (for example, a picture of a rotting - fish) or some other indicator. - - If the user has overridden the caching mechanisms in a way that would - abnormally reduce the effectiveness of caches, the user agent SHOULD - continually indicate this state to the user (for example, by a - display of a picture of currency in flames) so that the user does not - inadvertently consume excess resources or suffer from excessive - latency. - -13.1.5 Exceptions to the Rules and Warnings - - In some cases, the operator of a cache MAY choose to configure it to - return stale responses even when not requested by clients. This - decision ought not be made lightly, but may be necessary for reasons - of availability or performance, especially when the cache is poorly - connected to the origin server. Whenever a cache returns a stale - response, it MUST mark it as such (using a Warning header) enabling - the client software to alert the user that there might be a potential - problem. - - - - - - - -Fielding, et al. Standards Track [Page 78] - -RFC 2616 HTTP/1.1 June 1999 - - - It also allows the user agent to take steps to obtain a first-hand or - fresh response. For this reason, a cache SHOULD NOT return a stale - response if the client explicitly requests a first-hand or fresh one, - unless it is impossible to comply for technical or policy reasons. - -13.1.6 Client-controlled Behavior - - While the origin server (and to a lesser extent, intermediate caches, - by their contribution to the age of a response) are the primary - source of expiration information, in some cases the client might need - to control a cache's decision about whether to return a cached - response without validating it. Clients do this using several - directives of the Cache-Control header. - - A client's request MAY specify the maximum age it is willing to - accept of an unvalidated response; specifying a value of zero forces - the cache(s) to revalidate all responses. A client MAY also specify - the minimum time remaining before a response expires. Both of these - options increase constraints on the behavior of caches, and so cannot - further relax the cache's approximation of semantic transparency. - - A client MAY also specify that it will accept stale responses, up to - some maximum amount of staleness. This loosens the constraints on the - caches, and so might violate the origin server's specified - constraints on semantic transparency, but might be necessary to - support disconnected operation, or high availability in the face of - poor connectivity. - -13.2 Expiration Model - -13.2.1 Server-Specified Expiration - - HTTP caching works best when caches can entirely avoid making - requests to the origin server. The primary mechanism for avoiding - requests is for an origin server to provide an explicit expiration - time in the future, indicating that a response MAY be used to satisfy - subsequent requests. In other words, a cache can return a fresh - response without first contacting the server. - - Our expectation is that servers will assign future explicit - expiration times to responses in the belief that the entity is not - likely to change, in a semantically significant way, before the - expiration time is reached. This normally preserves semantic - transparency, as long as the server's expiration times are carefully - chosen. - - - - - - -Fielding, et al. Standards Track [Page 79] - -RFC 2616 HTTP/1.1 June 1999 - - - The expiration mechanism applies only to responses taken from a cache - and not to first-hand responses forwarded immediately to the - requesting client. - - If an origin server wishes to force a semantically transparent cache - to validate every request, it MAY assign an explicit expiration time - in the past. This means that the response is always stale, and so the - cache SHOULD validate it before using it for subsequent requests. See - section 14.9.4 for a more restrictive way to force revalidation. - - If an origin server wishes to force any HTTP/1.1 cache, no matter how - it is configured, to validate every request, it SHOULD use the "must- - revalidate" cache-control directive (see section 14.9). - - Servers specify explicit expiration times using either the Expires - header, or the max-age directive of the Cache-Control header. - - An expiration time cannot be used to force a user agent to refresh - its display or reload a resource; its semantics apply only to caching - mechanisms, and such mechanisms need only check a resource's - expiration status when a new request for that resource is initiated. - See section 13.13 for an explanation of the difference between caches - and history mechanisms. - -13.2.2 Heuristic Expiration - - Since origin servers do not always provide explicit expiration times, - HTTP caches typically assign heuristic expiration times, employing - algorithms that use other header values (such as the Last-Modified - time) to estimate a plausible expiration time. The HTTP/1.1 - specification does not provide specific algorithms, but does impose - worst-case constraints on their results. Since heuristic expiration - times might compromise semantic transparency, they ought to used - cautiously, and we encourage origin servers to provide explicit - expiration times as much as possible. - -13.2.3 Age Calculations - - In order to know if a cached entry is fresh, a cache needs to know if - its age exceeds its freshness lifetime. We discuss how to calculate - the latter in section 13.2.4; this section describes how to calculate - the age of a response or cache entry. - - In this discussion, we use the term "now" to mean "the current value - of the clock at the host performing the calculation." Hosts that use - HTTP, but especially hosts running origin servers and caches, SHOULD - use NTP [28] or some similar protocol to synchronize their clocks to - a globally accurate time standard. - - - -Fielding, et al. Standards Track [Page 80] - -RFC 2616 HTTP/1.1 June 1999 - - - HTTP/1.1 requires origin servers to send a Date header, if possible, - with every response, giving the time at which the response was - generated (see section 14.18). We use the term "date_value" to denote - the value of the Date header, in a form appropriate for arithmetic - operations. - - HTTP/1.1 uses the Age response-header to convey the estimated age of - the response message when obtained from a cache. The Age field value - is the cache's estimate of the amount of time since the response was - generated or revalidated by the origin server. - - In essence, the Age value is the sum of the time that the response - has been resident in each of the caches along the path from the - origin server, plus the amount of time it has been in transit along - network paths. - - We use the term "age_value" to denote the value of the Age header, in - a form appropriate for arithmetic operations. - - A response's age can be calculated in two entirely independent ways: - - 1. now minus date_value, if the local clock is reasonably well - synchronized to the origin server's clock. If the result is - negative, the result is replaced by zero. - - 2. age_value, if all of the caches along the response path - implement HTTP/1.1. - - Given that we have two independent ways to compute the age of a - response when it is received, we can combine these as - - corrected_received_age = max(now - date_value, age_value) - - and as long as we have either nearly synchronized clocks or all- - HTTP/1.1 paths, one gets a reliable (conservative) result. - - Because of network-imposed delays, some significant interval might - pass between the time that a server generates a response and the time - it is received at the next outbound cache or client. If uncorrected, - this delay could result in improperly low ages. - - Because the request that resulted in the returned Age value must have - been initiated prior to that Age value's generation, we can correct - for delays imposed by the network by recording the time at which the - request was initiated. Then, when an Age value is received, it MUST - be interpreted relative to the time the request was initiated, not - - - - - -Fielding, et al. Standards Track [Page 81] - -RFC 2616 HTTP/1.1 June 1999 - - - the time that the response was received. This algorithm results in - conservative behavior no matter how much delay is experienced. So, we - compute: - - corrected_initial_age = corrected_received_age - + (now - request_time) - - where "request_time" is the time (according to the local clock) when - the request that elicited this response was sent. - - Summary of age calculation algorithm, when a cache receives a - response: - - /* - * age_value - * is the value of Age: header received by the cache with - * this response. - * date_value - * is the value of the origin server's Date: header - * request_time - * is the (local) time when the cache made the request - * that resulted in this cached response - * response_time - * is the (local) time when the cache received the - * response - * now - * is the current (local) time - */ - - apparent_age = max(0, response_time - date_value); - corrected_received_age = max(apparent_age, age_value); - response_delay = response_time - request_time; - corrected_initial_age = corrected_received_age + response_delay; - resident_time = now - response_time; - current_age = corrected_initial_age + resident_time; - - The current_age of a cache entry is calculated by adding the amount - of time (in seconds) since the cache entry was last validated by the - origin server to the corrected_initial_age. When a response is - generated from a cache entry, the cache MUST include a single Age - header field in the response with a value equal to the cache entry's - current_age. - - The presence of an Age header field in a response implies that a - response is not first-hand. However, the converse is not true, since - the lack of an Age header field in a response does not imply that the - - - - - -Fielding, et al. Standards Track [Page 82] - -RFC 2616 HTTP/1.1 June 1999 - - - response is first-hand unless all caches along the request path are - compliant with HTTP/1.1 (i.e., older HTTP caches did not implement - the Age header field). - -13.2.4 Expiration Calculations - - In order to decide whether a response is fresh or stale, we need to - compare its freshness lifetime to its age. The age is calculated as - described in section 13.2.3; this section describes how to calculate - the freshness lifetime, and to determine if a response has expired. - In the discussion below, the values can be represented in any form - appropriate for arithmetic operations. - - We use the term "expires_value" to denote the value of the Expires - header. We use the term "max_age_value" to denote an appropriate - value of the number of seconds carried by the "max-age" directive of - the Cache-Control header in a response (see section 14.9.3). - - The max-age directive takes priority over Expires, so if max-age is - present in a response, the calculation is simply: - - freshness_lifetime = max_age_value - - Otherwise, if Expires is present in the response, the calculation is: - - freshness_lifetime = expires_value - date_value - - Note that neither of these calculations is vulnerable to clock skew, - since all of the information comes from the origin server. - - If none of Expires, Cache-Control: max-age, or Cache-Control: s- - maxage (see section 14.9.3) appears in the response, and the response - does not include other restrictions on caching, the cache MAY compute - a freshness lifetime using a heuristic. The cache MUST attach Warning - 113 to any response whose age is more than 24 hours if such warning - has not already been added. - - Also, if the response does have a Last-Modified time, the heuristic - expiration value SHOULD be no more than some fraction of the interval - since that time. A typical setting of this fraction might be 10%. - - The calculation to determine if a response has expired is quite - simple: - - response_is_fresh = (freshness_lifetime > current_age) - - - - - - -Fielding, et al. Standards Track [Page 83] - -RFC 2616 HTTP/1.1 June 1999 - - -13.2.5 Disambiguating Expiration Values - - Because expiration values are assigned optimistically, it is possible - for two caches to contain fresh values for the same resource that are - different. - - If a client performing a retrieval receives a non-first-hand response - for a request that was already fresh in its own cache, and the Date - header in its existing cache entry is newer than the Date on the new - response, then the client MAY ignore the response. If so, it MAY - retry the request with a "Cache-Control: max-age=0" directive (see - section 14.9), to force a check with the origin server. - - If a cache has two fresh responses for the same representation with - different validators, it MUST use the one with the more recent Date - header. This situation might arise because the cache is pooling - responses from other caches, or because a client has asked for a - reload or a revalidation of an apparently fresh cache entry. - -13.2.6 Disambiguating Multiple Responses - - Because a client might be receiving responses via multiple paths, so - that some responses flow through one set of caches and other - responses flow through a different set of caches, a client might - receive responses in an order different from that in which the origin - server sent them. We would like the client to use the most recently - generated response, even if older responses are still apparently - fresh. - - Neither the entity tag nor the expiration value can impose an - ordering on responses, since it is possible that a later response - intentionally carries an earlier expiration time. The Date values are - ordered to a granularity of one second. - - When a client tries to revalidate a cache entry, and the response it - receives contains a Date header that appears to be older than the one - for the existing entry, then the client SHOULD repeat the request - unconditionally, and include - - Cache-Control: max-age=0 - - to force any intermediate caches to validate their copies directly - with the origin server, or - - Cache-Control: no-cache - - to force any intermediate caches to obtain a new copy from the origin - server. - - - -Fielding, et al. Standards Track [Page 84] - -RFC 2616 HTTP/1.1 June 1999 - - - If the Date values are equal, then the client MAY use either response - (or MAY, if it is being extremely prudent, request a new response). - Servers MUST NOT depend on clients being able to choose - deterministically between responses generated during the same second, - if their expiration times overlap. - -13.3 Validation Model - - When a cache has a stale entry that it would like to use as a - response to a client's request, it first has to check with the origin - server (or possibly an intermediate cache with a fresh response) to - see if its cached entry is still usable. We call this "validating" - the cache entry. Since we do not want to have to pay the overhead of - retransmitting the full response if the cached entry is good, and we - do not want to pay the overhead of an extra round trip if the cached - entry is invalid, the HTTP/1.1 protocol supports the use of - conditional methods. - - The key protocol features for supporting conditional methods are - those concerned with "cache validators." When an origin server - generates a full response, it attaches some sort of validator to it, - which is kept with the cache entry. When a client (user agent or - proxy cache) makes a conditional request for a resource for which it - has a cache entry, it includes the associated validator in the - request. - - The server then checks that validator against the current validator - for the entity, and, if they match (see section 13.3.3), it responds - with a special status code (usually, 304 (Not Modified)) and no - entity-body. Otherwise, it returns a full response (including - entity-body). Thus, we avoid transmitting the full response if the - validator matches, and we avoid an extra round trip if it does not - match. - - In HTTP/1.1, a conditional request looks exactly the same as a normal - request for the same resource, except that it carries a special - header (which includes the validator) that implicitly turns the - method (usually, GET) into a conditional. - - The protocol includes both positive and negative senses of cache- - validating conditions. That is, it is possible to request either that - a method be performed if and only if a validator matches or if and - only if no validators match. - - - - - - - - -Fielding, et al. Standards Track [Page 85] - -RFC 2616 HTTP/1.1 June 1999 - - - Note: a response that lacks a validator may still be cached, and - served from cache until it expires, unless this is explicitly - prohibited by a cache-control directive. However, a cache cannot - do a conditional retrieval if it does not have a validator for the - entity, which means it will not be refreshable after it expires. - -13.3.1 Last-Modified Dates - - The Last-Modified entity-header field value is often used as a cache - validator. In simple terms, a cache entry is considered to be valid - if the entity has not been modified since the Last-Modified value. - -13.3.2 Entity Tag Cache Validators - - The ETag response-header field value, an entity tag, provides for an - "opaque" cache validator. This might allow more reliable validation - in situations where it is inconvenient to store modification dates, - where the one-second resolution of HTTP date values is not - sufficient, or where the origin server wishes to avoid certain - paradoxes that might arise from the use of modification dates. - - Entity Tags are described in section 3.11. The headers used with - entity tags are described in sections 14.19, 14.24, 14.26 and 14.44. - -13.3.3 Weak and Strong Validators - - Since both origin servers and caches will compare two validators to - decide if they represent the same or different entities, one normally - would expect that if the entity (the entity-body or any entity- - headers) changes in any way, then the associated validator would - change as well. If this is true, then we call this validator a - "strong validator." - - However, there might be cases when a server prefers to change the - validator only on semantically significant changes, and not when - insignificant aspects of the entity change. A validator that does not - always change when the resource changes is a "weak validator." - - Entity tags are normally "strong validators," but the protocol - provides a mechanism to tag an entity tag as "weak." One can think of - a strong validator as one that changes whenever the bits of an entity - changes, while a weak value changes whenever the meaning of an entity - changes. Alternatively, one can think of a strong validator as part - of an identifier for a specific entity, while a weak validator is - part of an identifier for a set of semantically equivalent entities. - - Note: One example of a strong validator is an integer that is - incremented in stable storage every time an entity is changed. - - - -Fielding, et al. Standards Track [Page 86] - -RFC 2616 HTTP/1.1 June 1999 - - - An entity's modification time, if represented with one-second - resolution, could be a weak validator, since it is possible that - the resource might be modified twice during a single second. - - Support for weak validators is optional. However, weak validators - allow for more efficient caching of equivalent objects; for - example, a hit counter on a site is probably good enough if it is - updated every few days or weeks, and any value during that period - is likely "good enough" to be equivalent. - - A "use" of a validator is either when a client generates a request - and includes the validator in a validating header field, or when a - server compares two validators. - - Strong validators are usable in any context. Weak validators are only - usable in contexts that do not depend on exact equality of an entity. - For example, either kind is usable for a conditional GET of a full - entity. However, only a strong validator is usable for a sub-range - retrieval, since otherwise the client might end up with an internally - inconsistent entity. - - Clients MAY issue simple (non-subrange) GET requests with either weak - validators or strong validators. Clients MUST NOT use weak validators - in other forms of request. - - The only function that the HTTP/1.1 protocol defines on validators is - comparison. There are two validator comparison functions, depending - on whether the comparison context allows the use of weak validators - or not: - - - The strong comparison function: in order to be considered equal, - both validators MUST be identical in every way, and both MUST - NOT be weak. - - - The weak comparison function: in order to be considered equal, - both validators MUST be identical in every way, but either or - both of them MAY be tagged as "weak" without affecting the - result. - - An entity tag is strong unless it is explicitly tagged as weak. - Section 3.11 gives the syntax for entity tags. - - A Last-Modified time, when used as a validator in a request, is - implicitly weak unless it is possible to deduce that it is strong, - using the following rules: - - - The validator is being compared by an origin server to the - actual current validator for the entity and, - - - -Fielding, et al. Standards Track [Page 87] - -RFC 2616 HTTP/1.1 June 1999 - - - - That origin server reliably knows that the associated entity did - not change twice during the second covered by the presented - validator. - - or - - - The validator is about to be used by a client in an If- - Modified-Since or If-Unmodified-Since header, because the client - has a cache entry for the associated entity, and - - - That cache entry includes a Date value, which gives the time - when the origin server sent the original response, and - - - The presented Last-Modified time is at least 60 seconds before - the Date value. - - or - - - The validator is being compared by an intermediate cache to the - validator stored in its cache entry for the entity, and - - - That cache entry includes a Date value, which gives the time - when the origin server sent the original response, and - - - The presented Last-Modified time is at least 60 seconds before - the Date value. - - This method relies on the fact that if two different responses were - sent by the origin server during the same second, but both had the - same Last-Modified time, then at least one of those responses would - have a Date value equal to its Last-Modified time. The arbitrary 60- - second limit guards against the possibility that the Date and Last- - Modified values are generated from different clocks, or at somewhat - different times during the preparation of the response. An - implementation MAY use a value larger than 60 seconds, if it is - believed that 60 seconds is too short. - - If a client wishes to perform a sub-range retrieval on a value for - which it has only a Last-Modified time and no opaque validator, it - MAY do this only if the Last-Modified time is strong in the sense - described here. - - A cache or origin server receiving a conditional request, other than - a full-body GET request, MUST use the strong comparison function to - evaluate the condition. - - These rules allow HTTP/1.1 caches and clients to safely perform sub- - range retrievals on values that have been obtained from HTTP/1.0 - - - -Fielding, et al. Standards Track [Page 88] - -RFC 2616 HTTP/1.1 June 1999 - - - servers. - -13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates - - We adopt a set of rules and recommendations for origin servers, - clients, and caches regarding when various validator types ought to - be used, and for what purposes. - - HTTP/1.1 origin servers: - - - SHOULD send an entity tag validator unless it is not feasible to - generate one. - - - MAY send a weak entity tag instead of a strong entity tag, if - performance considerations support the use of weak entity tags, - or if it is unfeasible to send a strong entity tag. - - - SHOULD send a Last-Modified value if it is feasible to send one, - unless the risk of a breakdown in semantic transparency that - could result from using this date in an If-Modified-Since header - would lead to serious problems. - - In other words, the preferred behavior for an HTTP/1.1 origin server - is to send both a strong entity tag and a Last-Modified value. - - In order to be legal, a strong entity tag MUST change whenever the - associated entity value changes in any way. A weak entity tag SHOULD - change whenever the associated entity changes in a semantically - significant way. - - Note: in order to provide semantically transparent caching, an - origin server must avoid reusing a specific strong entity tag - value for two different entities, or reusing a specific weak - entity tag value for two semantically different entities. Cache - entries might persist for arbitrarily long periods, regardless of - expiration times, so it might be inappropriate to expect that a - cache will never again attempt to validate an entry using a - validator that it obtained at some point in the past. - - HTTP/1.1 clients: - - - If an entity tag has been provided by the origin server, MUST - use that entity tag in any cache-conditional request (using If- - Match or If-None-Match). - - - If only a Last-Modified value has been provided by the origin - server, SHOULD use that value in non-subrange cache-conditional - requests (using If-Modified-Since). - - - -Fielding, et al. Standards Track [Page 89] - -RFC 2616 HTTP/1.1 June 1999 - - - - If only a Last-Modified value has been provided by an HTTP/1.0 - origin server, MAY use that value in subrange cache-conditional - requests (using If-Unmodified-Since:). The user agent SHOULD - provide a way to disable this, in case of difficulty. - - - If both an entity tag and a Last-Modified value have been - provided by the origin server, SHOULD use both validators in - cache-conditional requests. This allows both HTTP/1.0 and - HTTP/1.1 caches to respond appropriately. - - An HTTP/1.1 origin server, upon receiving a conditional request that - includes both a Last-Modified date (e.g., in an If-Modified-Since or - If-Unmodified-Since header field) and one or more entity tags (e.g., - in an If-Match, If-None-Match, or If-Range header field) as cache - validators, MUST NOT return a response status of 304 (Not Modified) - unless doing so is consistent with all of the conditional header - fields in the request. - - An HTTP/1.1 caching proxy, upon receiving a conditional request that - includes both a Last-Modified date and one or more entity tags as - cache validators, MUST NOT return a locally cached response to the - client unless that cached response is consistent with all of the - conditional header fields in the request. - - Note: The general principle behind these rules is that HTTP/1.1 - servers and clients should transmit as much non-redundant - information as is available in their responses and requests. - HTTP/1.1 systems receiving this information will make the most - conservative assumptions about the validators they receive. - - HTTP/1.0 clients and caches will ignore entity tags. Generally, - last-modified values received or used by these systems will - support transparent and efficient caching, and so HTTP/1.1 origin - servers should provide Last-Modified values. In those rare cases - where the use of a Last-Modified value as a validator by an - HTTP/1.0 system could result in a serious problem, then HTTP/1.1 - origin servers should not provide one. - -13.3.5 Non-validating Conditionals - - The principle behind entity tags is that only the service author - knows the semantics of a resource well enough to select an - appropriate cache validation mechanism, and the specification of any - validator comparison function more complex than byte-equality would - open up a can of worms. Thus, comparisons of any other headers - (except Last-Modified, for compatibility with HTTP/1.0) are never - used for purposes of validating a cache entry. - - - - -Fielding, et al. Standards Track [Page 90] - -RFC 2616 HTTP/1.1 June 1999 - - -13.4 Response Cacheability - - Unless specifically constrained by a cache-control (section 14.9) - directive, a caching system MAY always store a successful response - (see section 13.8) as a cache entry, MAY return it without validation - if it is fresh, and MAY return it after successful validation. If - there is neither a cache validator nor an explicit expiration time - associated with a response, we do not expect it to be cached, but - certain caches MAY violate this expectation (for example, when little - or no network connectivity is available). A client can usually detect - that such a response was taken from a cache by comparing the Date - header to the current time. - - Note: some HTTP/1.0 caches are known to violate this expectation - without providing any Warning. - - However, in some cases it might be inappropriate for a cache to - retain an entity, or to return it in response to a subsequent - request. This might be because absolute semantic transparency is - deemed necessary by the service author, or because of security or - privacy considerations. Certain cache-control directives are - therefore provided so that the server can indicate that certain - resource entities, or portions thereof, are not to be cached - regardless of other considerations. - - Note that section 14.8 normally prevents a shared cache from saving - and returning a response to a previous request if that request - included an Authorization header. - - A response received with a status code of 200, 203, 206, 300, 301 or - 410 MAY be stored by a cache and used in reply to a subsequent - request, subject to the expiration mechanism, unless a cache-control - directive prohibits caching. However, a cache that does not support - the Range and Content-Range headers MUST NOT cache 206 (Partial - Content) responses. - - A response received with any other status code (e.g. status codes 302 - and 307) MUST NOT be returned in a reply to a subsequent request - unless there are cache-control directives or another header(s) that - explicitly allow it. For example, these include the following: an - Expires header (section 14.21); a "max-age", "s-maxage", "must- - revalidate", "proxy-revalidate", "public" or "private" cache-control - directive (section 14.9). - - - - - - - - -Fielding, et al. Standards Track [Page 91] - -RFC 2616 HTTP/1.1 June 1999 - - -13.5 Constructing Responses From Caches - - The purpose of an HTTP cache is to store information received in - response to requests for use in responding to future requests. In - many cases, a cache simply returns the appropriate parts of a - response to the requester. However, if the cache holds a cache entry - based on a previous response, it might have to combine parts of a new - response with what is held in the cache entry. - -13.5.1 End-to-end and Hop-by-hop Headers - - For the purpose of defining the behavior of caches and non-caching - proxies, we divide HTTP headers into two categories: - - - End-to-end headers, which are transmitted to the ultimate - recipient of a request or response. End-to-end headers in - responses MUST be stored as part of a cache entry and MUST be - transmitted in any response formed from a cache entry. - - - Hop-by-hop headers, which are meaningful only for a single - transport-level connection, and are not stored by caches or - forwarded by proxies. - - The following HTTP/1.1 headers are hop-by-hop headers: - - - Connection - - Keep-Alive - - Proxy-Authenticate - - Proxy-Authorization - - TE - - Trailers [[should be "Trailer"]] - - Transfer-Encoding - - Upgrade - - All other headers defined by HTTP/1.1 are end-to-end headers. - - Other hop-by-hop headers MUST be listed in a Connection header, - (section 14.10) to be introduced into HTTP/1.1 (or later). - -13.5.2 Non-modifiable Headers - - Some features of the HTTP/1.1 protocol, such as Digest - Authentication, depend on the value of certain end-to-end headers. A - transparent proxy SHOULD NOT modify an end-to-end header unless the - definition of that header requires or specifically allows that. - - - - - - -Fielding, et al. Standards Track [Page 92] - -RFC 2616 HTTP/1.1 June 1999 - - - A transparent proxy MUST NOT modify any of the following fields in a - request or response, and it MUST NOT add any of these fields if not - already present: - - - Content-Location - - - Content-MD5 - - - ETag - - - Last-Modified - - A transparent proxy MUST NOT modify any of the following fields in a - response: - - - Expires - - but it MAY add any of these fields if not already present. If an - Expires header is added, it MUST be given a field-value identical to - that of the Date header in that response. - - A proxy MUST NOT modify or add any of the following fields in a - message that contains the no-transform cache-control directive, or in - any request: - - - Content-Encoding - - - Content-Range - - - Content-Type - - A non-transparent proxy MAY modify or add these fields to a message - that does not include no-transform, but if it does so, it MUST add a - Warning 214 (Transformation applied) if one does not already appear - in the message (see section 14.46). - - Warning: unnecessary modification of end-to-end headers might - cause authentication failures if stronger authentication - mechanisms are introduced in later versions of HTTP. Such - authentication mechanisms MAY rely on the values of header fields - not listed here. - - The Content-Length field of a request or response is added or deleted - according to the rules in section 4.4. A transparent proxy MUST - preserve the entity-length (section 7.2.2) of the entity-body, - although it MAY change the transfer-length (section 4.4). - - - - - -Fielding, et al. Standards Track [Page 93] - -RFC 2616 HTTP/1.1 June 1999 - - -13.5.3 Combining Headers - - When a cache makes a validating request to a server, and the server - provides a 304 (Not Modified) response or a 206 (Partial Content) - response, the cache then constructs a response to send to the - requesting client. - - If the status code is 304 (Not Modified), the cache uses the entity- - body stored in the cache entry as the entity-body of this outgoing - response. If the status code is 206 (Partial Content) and the ETag or - Last-Modified headers match exactly, the cache MAY combine the - contents stored in the cache entry with the new contents received in - the response and use the result as the entity-body of this outgoing - response, (see 13.5.4). - - The end-to-end headers stored in the cache entry are used for the - constructed response, except that - - - any stored Warning headers with warn-code 1xx (see section - 14.46) MUST be deleted from the cache entry and the forwarded - response. - - - any stored Warning headers with warn-code 2xx MUST be retained - in the cache entry and the forwarded response. - - - any end-to-end headers provided in the 304 or 206 response MUST - replace the corresponding headers from the cache entry. - - Unless the cache decides to remove the cache entry, it MUST also - replace the end-to-end headers stored with the cache entry with - corresponding headers received in the incoming response, except for - Warning headers as described immediately above. If a header field- - name in the incoming response matches more than one header in the - cache entry, all such old headers MUST be replaced. - - In other words, the set of end-to-end headers received in the - incoming response overrides all corresponding end-to-end headers - stored with the cache entry (except for stored Warning headers with - warn-code 1xx, which are deleted even if not overridden). - - Note: this rule allows an origin server to use a 304 (Not - Modified) or a 206 (Partial Content) response to update any header - associated with a previous response for the same entity or sub- - ranges thereof, although it might not always be meaningful or - correct to do so. This rule does not allow an origin server to use - a 304 (Not Modified) or a 206 (Partial Content) response to - entirely delete a header that it had provided with a previous - response. - - - -Fielding, et al. Standards Track [Page 94] - -RFC 2616 HTTP/1.1 June 1999 - - -13.5.4 Combining Byte Ranges - - A response might transfer only a subrange of the bytes of an entity- - body, either because the request included one or more Range - specifications, or because a connection was broken prematurely. After - several such transfers, a cache might have received several ranges of - the same entity-body. - - If a cache has a stored non-empty set of subranges for an entity, and - an incoming response transfers another subrange, the cache MAY - combine the new subrange with the existing set if both the following - conditions are met: - - - Both the incoming response and the cache entry have a cache - validator. - - - The two cache validators match using the strong comparison - function (see section 13.3.3). - - If either requirement is not met, the cache MUST use only the most - recent partial response (based on the Date values transmitted with - every response, and using the incoming response if these values are - equal or missing), and MUST discard the other partial information. - -13.6 Caching Negotiated Responses - - Use of server-driven content negotiation (section 12.1), as indicated - by the presence of a Vary header field in a response, alters the - conditions and procedure by which a cache can use the response for - subsequent requests. See section 14.44 for use of the Vary header - field by servers. - - A server SHOULD use the Vary header field to inform a cache of what - request-header fields were used to select among multiple - representations of a cacheable response subject to server-driven - negotiation. The set of header fields named by the Vary field value - is known as the "selecting" request-headers. - - When the cache receives a subsequent request whose Request-URI - specifies one or more cache entries including a Vary header field, - the cache MUST NOT use such a cache entry to construct a response to - the new request unless all of the selecting request-headers present - in the new request match the corresponding stored request-headers in - the original request. - - The selecting request-headers from two requests are defined to match - if and only if the selecting request-headers in the first request can - be transformed to the selecting request-headers in the second request - - - -Fielding, et al. Standards Track [Page 95] - -RFC 2616 HTTP/1.1 June 1999 - - - by adding or removing linear white space (LWS) at places where this - is allowed by the corresponding BNF, and/or combining multiple - message-header fields with the same field name following the rules - about message headers in section 4.2. - - A Vary header field-value of "*" always fails to match and subsequent - requests on that resource can only be properly interpreted by the - origin server. - - If the selecting request header fields for the cached entry do not - match the selecting request header fields of the new request, then - the cache MUST NOT use a cached entry to satisfy the request unless - it first relays the new request to the origin server in a conditional - request and the server responds with 304 (Not Modified), including an - entity tag or Content-Location that indicates the entity to be used. - - If an entity tag was assigned to a cached representation, the - forwarded request SHOULD be conditional and include the entity tags - in an If-None-Match header field from all its cache entries for the - resource. This conveys to the server the set of entities currently - held by the cache, so that if any one of these entities matches the - requested entity, the server can use the ETag header field in its 304 - (Not Modified) response to tell the cache which entry is appropriate. - If the entity-tag of the new response matches that of an existing - entry, the new response SHOULD be used to update the header fields of - the existing entry, and the result MUST be returned to the client. - - If any of the existing cache entries contains only partial content - for the associated entity, its entity-tag SHOULD NOT be included in - the If-None-Match header field unless the request is for a range that - would be fully satisfied by that entry. - - If a cache receives a successful response whose Content-Location - field matches that of an existing cache entry for the same Request- - ]URI, whose entity-tag differs from that of the existing entry, and - whose Date is more recent than that of the existing entry, the - existing entry SHOULD NOT be returned in response to future requests - and SHOULD be deleted from the cache. - -13.7 Shared and Non-Shared Caches - - For reasons of security and privacy, it is necessary to make a - distinction between "shared" and "non-shared" caches. A non-shared - cache is one that is accessible only to a single user. Accessibility - in this case SHOULD be enforced by appropriate security mechanisms. - All other caches are considered to be "shared." Other sections of - - - - - -Fielding, et al. Standards Track [Page 96] - -RFC 2616 HTTP/1.1 June 1999 - - - this specification place certain constraints on the operation of - shared caches in order to prevent loss of privacy or failure of - access controls. - -13.8 Errors or Incomplete Response Cache Behavior - - A cache that receives an incomplete response (for example, with fewer - bytes of data than specified in a Content-Length header) MAY store - the response. However, the cache MUST treat this as a partial - response. Partial responses MAY be combined as described in section - 13.5.4; the result might be a full response or might still be - partial. A cache MUST NOT return a partial response to a client - without explicitly marking it as such, using the 206 (Partial - Content) status code. A cache MUST NOT return a partial response - using a status code of 200 (OK). - - If a cache receives a 5xx response while attempting to revalidate an - entry, it MAY either forward this response to the requesting client, - or act as if the server failed to respond. In the latter case, it MAY - return a previously received response unless the cached entry - includes the "must-revalidate" cache-control directive (see section - 14.9). - -13.9 Side Effects of GET and HEAD - - Unless the origin server explicitly prohibits the caching of their - responses, the application of GET and HEAD methods to any resources - SHOULD NOT have side effects that would lead to erroneous behavior if - these responses are taken from a cache. They MAY still have side - effects, but a cache is not required to consider such side effects in - its caching decisions. Caches are always expected to observe an - origin server's explicit restrictions on caching. - - We note one exception to this rule: since some applications have - traditionally used GETs and HEADs with query URLs (those containing a - "?" in the rel_path part) to perform operations with significant side - effects, caches MUST NOT treat responses to such URIs as fresh unless - the server provides an explicit expiration time. This specifically - means that responses from HTTP/1.0 servers for such URIs SHOULD NOT - be taken from a cache. See section 9.1.1 for related information. - -13.10 Invalidation After Updates or Deletions - - The effect of certain methods performed on a resource at the origin - server might cause one or more existing cache entries to become non- - transparently invalid. That is, although they might continue to be - "fresh," they do not accurately reflect what the origin server would - return for a new request on that resource. - - - -Fielding, et al. Standards Track [Page 97] - -RFC 2616 HTTP/1.1 June 1999 - - - There is no way for the HTTP protocol to guarantee that all such - cache entries are marked invalid. For example, the request that - caused the change at the origin server might not have gone through - the proxy where a cache entry is stored. However, several rules help - reduce the likelihood of erroneous behavior. - - In this section, the phrase "invalidate an entity" means that the - cache will either remove all instances of that entity from its - storage, or will mark these as "invalid" and in need of a mandatory - revalidation before they can be returned in response to a subsequent - request. - - Some HTTP methods MUST cause a cache to invalidate an entity. This is - either the entity referred to by the Request-URI, or by the Location - or Content-Location headers (if present). These methods are: - - - PUT - - - DELETE - - - POST - - In order to prevent denial of service attacks, an invalidation based - on the URI in a Location or Content-Location header MUST only be - performed if the host part is the same as in the Request-URI. - -[[ Should be: ]] -[[ An invalidation based on the URI in a Location or Content-Location ]] -[[ header MUST NOT be performed if the host part of that URI differs ]] -[[ from the host part in the Request-URI. This helps prevent denial of ]] -[[ service attacks. ]] - - A cache that passes through requests for methods it does not - understand SHOULD invalidate any entities referred to by the - Request-URI. - -13.11 Write-Through Mandatory - - All methods that might be expected to cause modifications to the - origin server's resources MUST be written through to the origin - server. This currently includes all methods except for GET and HEAD. - A cache MUST NOT reply to such a request from a client before having - transmitted the request to the inbound server, and having received a - corresponding response from the inbound server. This does not prevent - a proxy cache from sending a 100 (Continue) response before the - inbound server has sent its final reply. - - The alternative (known as "write-back" or "copy-back" caching) is not - allowed in HTTP/1.1, due to the difficulty of providing consistent - updates and the problems arising from server, cache, or network - failure prior to write-back. - - - - - - -Fielding, et al. Standards Track [Page 98] - -RFC 2616 HTTP/1.1 June 1999 - - -13.12 Cache Replacement - - If a new cacheable (see sections 14.9.2, 13.2.5, 13.2.6 and 13.8) - response is received from a resource while any existing responses for - the same resource are cached, the cache SHOULD use the new response - to reply to the current request. It MAY insert it into cache storage - and MAY, if it meets all other requirements, use it to respond to any - future requests that would previously have caused the old response to - be returned. If it inserts the new response into cache storage the - rules in section 13.5.3 apply. - - Note: a new response that has an older Date header value than - existing cached responses is not cacheable. - -13.13 History Lists - - User agents often have history mechanisms, such as "Back" buttons and - history lists, which can be used to redisplay an entity retrieved - earlier in a session. - - History mechanisms and caches are different. In particular history - mechanisms SHOULD NOT try to show a semantically transparent view of - the current state of a resource. Rather, a history mechanism is meant - to show exactly what the user saw at the time when the resource was - retrieved. - - By default, an expiration time does not apply to history mechanisms. - If the entity is still in storage, a history mechanism SHOULD display - it even if the entity has expired, unless the user has specifically - configured the agent to refresh expired history documents. - - This is not to be construed to prohibit the history mechanism from - telling the user that a view might be stale. - - Note: if history list mechanisms unnecessarily prevent users from - viewing stale resources, this will tend to force service authors - to avoid using HTTP expiration controls and cache controls when - they would otherwise like to. Service authors may consider it - important that users not be presented with error messages or - warning messages when they use navigation controls (such as BACK) - to view previously fetched resources. Even though sometimes such - resources ought not to cached, or ought to expire quickly, user - interface considerations may force service authors to resort to - other means of preventing caching (e.g. "once-only" URLs) in order - not to suffer the effects of improperly functioning history - mechanisms. - - - - - -Fielding, et al. Standards Track [Page 99] - -RFC 2616 HTTP/1.1 June 1999 - - -14 Header Field Definitions - - This section defines the syntax and semantics of all standard - HTTP/1.1 header fields. For entity-header fields, both sender and - recipient refer to either the client or the server, depending on who - sends and who receives the entity. - -14.1 Accept - - The Accept request-header field can be used to specify certain media - types which are acceptable for the response. Accept headers can be - used to indicate that the request is specifically limited to a small - set of desired types, as in the case of a request for an in-line - image. - - Accept = "Accept" ":" - #( media-range [ accept-params ] ) - - media-range = ( "*/*" - | ( type "/" "*" ) - | ( type "/" subtype ) - ) *( ";" parameter ) - accept-params = ";" "q" "=" qvalue *( accept-extension ) - accept-extension = ";" token [ "=" ( token | quoted-string ) ] - - The asterisk "*" character is used to group media types into ranges, - with "*/*" indicating all media types and "type/*" indicating all - subtypes of that type. The media-range MAY include media type - parameters that are applicable to that range. - - Each media-range MAY be followed by one or more accept-params, - beginning with the "q" parameter for indicating a relative quality - factor. The first "q" parameter (if any) separates the media-range - parameter(s) from the accept-params. Quality factors allow the user - or user agent to indicate the relative degree of preference for that - media-range, using the qvalue scale from 0 to 1 (section 3.9). The - default value is q=1. - - Note: Use of the "q" parameter name to separate media type - parameters from Accept extension parameters is due to historical - practice. Although this prevents any media type parameter named - "q" from being used with a media range, such an event is believed - to be unlikely given the lack of any "q" parameters in the IANA - media type registry and the rare usage of any media type - parameters in Accept. Future media types are discouraged from - registering any parameter named "q". - - - - - -Fielding, et al. Standards Track [Page 100] - -RFC 2616 HTTP/1.1 June 1999 - - - The example - - Accept: audio/*; q=0.2, audio/basic - - SHOULD be interpreted as "I prefer audio/basic, but send me any audio - type if it is the best available after an 80% mark-down in quality." - - If no Accept header field is present, then it is assumed that the - client accepts all media types. If an Accept header field is present, - and if the server cannot send a response which is acceptable - according to the combined Accept field value, then the server SHOULD - send a 406 (not acceptable) response. - - A more elaborate example is - - Accept: text/plain; q=0.5, text/html, - text/x-dvi; q=0.8, text/x-c - - Verbally, this would be interpreted as "text/html and text/x-c are - the preferred media types, but if they do not exist, then send the - text/x-dvi entity, and if that does not exist, send the text/plain - entity." - - Media ranges can be overridden by more specific media ranges or - specific media types. If more than one media range applies to a given - type, the most specific reference has precedence. For example, - - Accept: text/*, text/html, text/html;level=1, */* - - have the following precedence: - - 1) text/html;level=1 - 2) text/html - 3) text/* - 4) */* - - The media type quality factor associated with a given type is - determined by finding the media range with the highest precedence - which matches that type. For example, - - Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1, - text/html;level=2;q=0.4, */*;q=0.5 - - would cause the following values to be associated: - - text/html;level=1 = 1 - text/html = 0.7 - text/plain = 0.3 - - - -Fielding, et al. Standards Track [Page 101] - -RFC 2616 HTTP/1.1 June 1999 - - - image/jpeg = 0.5 - text/html;level=2 = 0.4 - text/html;level=3 = 0.7 - - Note: A user agent might be provided with a default set of quality - values for certain media ranges. However, unless the user agent is - a closed system which cannot interact with other rendering agents, - this default set ought to be configurable by the user. - -14.2 Accept-Charset - - The Accept-Charset request-header field can be used to indicate what - character sets are acceptable for the response. This field allows - clients capable of understanding more comprehensive or special- - purpose character sets to signal that capability to a server which is - capable of representing documents in those character sets. - - Accept-Charset = "Accept-Charset" ":" - 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] ) - - - Character set values are described in section 3.4. Each charset MAY - be given an associated quality value which represents the user's - preference for that charset. The default value is q=1. An example is - - Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 - - The special value "*", if present in the Accept-Charset field, - matches every character set (including ISO-8859-1) which is not - mentioned elsewhere in the Accept-Charset field. If no "*" is present - in an Accept-Charset field, then all character sets not explicitly - mentioned get a quality value of 0, except for ISO-8859-1, which gets - a quality value of 1 if not explicitly mentioned. - - If no Accept-Charset header is present, the default is that any - character set is acceptable. If an Accept-Charset header is present, - and if the server cannot send a response which is acceptable - according to the Accept-Charset header, then the server SHOULD send - an error response with the 406 (not acceptable) status code, though - the sending of an unacceptable response is also allowed. - -14.3 Accept-Encoding - - The Accept-Encoding request-header field is similar to Accept, but - restricts the content-codings (section 3.5) that are acceptable in - the response. - - Accept-Encoding = "Accept-Encoding" ":" - - - -Fielding, et al. Standards Track [Page 102] - -RFC 2616 HTTP/1.1 June 1999 - - - 1#( codings [ ";" "q" "=" qvalue ] ) - codings = ( content-coding | "*" ) - - [[ http://lists.w3.org/Archives/Public/ietf-http-wg/2005AprJun/0029.html ]] - [[ points out that the "1#" must be "#" to make the examples below and ]] - [[ the text of rule 4 correct. ]] - - Examples of its use are: - - Accept-Encoding: compress, gzip - Accept-Encoding: - Accept-Encoding: * - Accept-Encoding: compress;q=0.5, gzip;q=1.0 - Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 - - A server tests whether a content-coding is acceptable, according to - an Accept-Encoding field, using these rules: - - 1. If the content-coding is one of the content-codings listed in - the Accept-Encoding field, then it is acceptable, unless it is - accompanied by a qvalue of 0. (As defined in section 3.9, a - qvalue of 0 means "not acceptable.") - - 2. The special "*" symbol in an Accept-Encoding field matches any - available content-coding not explicitly listed in the header - field. - - 3. If multiple content-codings are acceptable, then the acceptable - content-coding with the highest non-zero qvalue is preferred. - - 4. The "identity" content-coding is always acceptable, unless - specifically refused because the Accept-Encoding field includes - "identity;q=0", or because the field includes "*;q=0" and does - not explicitly include the "identity" content-coding. If the - Accept-Encoding field-value is empty, then only the "identity" - encoding is acceptable. - - If an Accept-Encoding field is present in a request, and if the - server cannot send a response which is acceptable according to the - Accept-Encoding header, then the server SHOULD send an error response - with the 406 (Not Acceptable) status code. - - If no Accept-Encoding field is present in a request, the server MAY - assume that the client will accept any content coding. In this case, - if "identity" is one of the available content-codings, then the - server SHOULD use the "identity" content-coding, unless it has - additional information that a different content-coding is meaningful - to the client. - - Note: If the request does not include an Accept-Encoding field, - and if the "identity" content-coding is unavailable, then - content-codings commonly understood by HTTP/1.0 clients (i.e., - - - -Fielding, et al. Standards Track [Page 103] - -RFC 2616 HTTP/1.1 June 1999 - - - "gzip" and "compress") are preferred; some older clients - improperly display messages sent with other content-codings. The - server might also make this decision based on information about - the particular user-agent or client. - - Note: Most HTTP/1.0 applications do not recognize or obey qvalues - associated with content-codings. This means that qvalues will not - work and are not permitted with x-gzip or x-compress. - -14.4 Accept-Language - - The Accept-Language request-header field is similar to Accept, but - restricts the set of natural languages that are preferred as a - response to the request. Language tags are defined in section 3.10. - - Accept-Language = "Accept-Language" ":" - 1#( language-range [ ";" "q" "=" qvalue ] ) - language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" ) - - Each language-range MAY be given an associated quality value which - represents an estimate of the user's preference for the languages - specified by that range. The quality value defaults to "q=1". For - example, - - Accept-Language: da, en-gb;q=0.8, en;q=0.7 - - would mean: "I prefer Danish, but will accept British English and - other types of English." A language-range matches a language-tag if - it exactly equals the tag, or if it exactly equals a prefix of the - tag such that the first tag character following the prefix is "-". - The special range "*", if present in the Accept-Language field, - matches every tag not matched by any other range present in the - Accept-Language field. - - Note: This use of a prefix matching rule does not imply that - language tags are assigned to languages in such a way that it is - always true that if a user understands a language with a certain - tag, then this user will also understand all languages with tags - for which this tag is a prefix. The prefix rule simply allows the - use of prefix tags if this is the case. - - The language quality factor assigned to a language-tag by the - Accept-Language field is the quality value of the longest language- - range in the field that matches the language-tag. If no language- - range in the field matches the tag, the language quality factor - assigned is 0. If no Accept-Language header is present in the - request, the server - - - - -Fielding, et al. Standards Track [Page 104] - -RFC 2616 HTTP/1.1 June 1999 - - - SHOULD assume that all languages are equally acceptable. If an - Accept-Language header is present, then all languages which are - assigned a quality factor greater than 0 are acceptable. - - It might be contrary to the privacy expectations of the user to send - an Accept-Language header with the complete linguistic preferences of - the user in every request. For a discussion of this issue, see - section 15.1.4. - - As intelligibility is highly dependent on the individual user, it is - recommended that client applications make the choice of linguistic - preference available to the user. If the choice is not made - available, then the Accept-Language header field MUST NOT be given in - the request. - - Note: When making the choice of linguistic preference available to - the user, we remind implementors of the fact that users are not - familiar with the details of language matching as described above, - and should provide appropriate guidance. As an example, users - might assume that on selecting "en-gb", they will be served any - kind of English document if British English is not available. A - user agent might suggest in such a case to add "en" to get the - best matching behavior. - -14.5 Accept-Ranges - - The Accept-Ranges response-header field allows the server to - indicate its acceptance of range requests for a resource: - - Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges - acceptable-ranges = 1#range-unit | "none" - - Origin servers that accept byte-range requests MAY send - - Accept-Ranges: bytes - - but are not required to do so. Clients MAY generate byte-range - requests without having received this header for the resource - involved. Range units are defined in section 3.12. - - Servers that do not accept any kind of range request for a - resource MAY send - - Accept-Ranges: none - - to advise the client not to attempt a range request. - - - - - -Fielding, et al. Standards Track [Page 105] - -RFC 2616 HTTP/1.1 June 1999 - - -14.6 Age - - The Age response-header field conveys the sender's estimate of the - amount of time since the response (or its revalidation) was - generated at the origin server. A cached response is "fresh" if - its age does not exceed its freshness lifetime. Age values are - calculated as specified in section 13.2.3. - - Age = "Age" ":" age-value - age-value = delta-seconds - - Age values are non-negative decimal integers, representing time in - seconds. - - If a cache receives a value larger than the largest positive - integer it can represent, or if any of its age calculations - overflows, it MUST transmit an Age header with a value of - 2147483648 (2^31). An HTTP/1.1 server that includes a cache MUST - include an Age header field in every response generated from its - own cache. Caches SHOULD use an arithmetic type of at least 31 - bits of range. - -14.7 Allow - - The Allow entity-header field lists the set of methods supported - by the resource identified by the Request-URI. The purpose of this - field is strictly to inform the recipient of valid methods - associated with the resource. An Allow header field MUST be - present in a 405 (Method Not Allowed) response. - - Allow = "Allow" ":" #Method - - Example of use: - - Allow: GET, HEAD, PUT - - This field cannot prevent a client from trying other methods. - However, the indications given by the Allow header field value - SHOULD be followed. The actual set of allowed methods is defined - by the origin server at the time of each request. - - The Allow header field MAY be provided with a PUT request to - recommend the methods to be supported by the new or modified - resource. The server is not required to support these methods and - SHOULD include an Allow header in the response giving the actual - supported methods. - - - - - -Fielding, et al. Standards Track [Page 106] - -RFC 2616 HTTP/1.1 June 1999 - - - A proxy MUST NOT modify the Allow header field even if it does not - understand all the methods specified, since the user agent might - have other means of communicating with the origin server. - -14.8 Authorization - - A user agent that wishes to authenticate itself with a server-- - usually, but not necessarily, after receiving a 401 response--does - so by including an Authorization request-header field with the - request. The Authorization field value consists of credentials - containing the authentication information of the user agent for - the realm of the resource being requested. - - Authorization = "Authorization" ":" credentials - - HTTP access authentication is described in "HTTP Authentication: - Basic and Digest Access Authentication" [43]. If a request is - authenticated and a realm specified, the same credentials SHOULD - be valid for all other requests within this realm (assuming that - the authentication scheme itself does not require otherwise, such - as credentials that vary according to a challenge value or using - synchronized clocks). - - When a shared cache (see section 13.7) receives a request - containing an Authorization field, it MUST NOT return the - corresponding response as a reply to any other request, unless one - of the following specific exceptions holds: - - 1. If the response includes the "s-maxage" cache-control - directive, the cache MAY use that response in replying to a - subsequent request. But (if the specified maximum age has - passed) a proxy cache MUST first revalidate it with the origin - server, using the request-headers from the new request to allow - the origin server to authenticate the new request. (This is the - defined behavior for s-maxage.) If the response includes "s- - maxage=0", the proxy MUST always revalidate it before re-using - it. - - 2. If the response includes the "must-revalidate" cache-control - directive, the cache MAY use that response in replying to a - subsequent request. But if the response is stale, all caches - MUST first revalidate it with the origin server, using the - request-headers from the new request to allow the origin server - to authenticate the new request. - - 3. If the response includes the "public" cache-control directive, - it MAY be returned in reply to any subsequent request. - - - - -Fielding, et al. Standards Track [Page 107] - -RFC 2616 HTTP/1.1 June 1999 - - -14.9 Cache-Control - - The Cache-Control general-header field is used to specify directives - that MUST be obeyed by all caching mechanisms along the - request/response chain. The directives specify behavior intended to - prevent caches from adversely interfering with the request or - response. These directives typically override the default caching - algorithms. Cache directives are unidirectional in that the presence - of a directive in a request does not imply that the same directive is - to be given in the response. - - Note that HTTP/1.0 caches might not implement Cache-Control and - might only implement Pragma: no-cache (see section 14.32). - - Cache directives MUST be passed through by a proxy or gateway - application, regardless of their significance to that application, - since the directives might be applicable to all recipients along the - request/response chain. It is not possible to specify a cache- - directive for a specific cache. - - Cache-Control = "Cache-Control" ":" 1#cache-directive - - cache-directive = cache-request-directive - | cache-response-directive - - cache-request-directive = - "no-cache" ; Section 14.9.1 - | "no-store" ; Section 14.9.2 - | "max-age" "=" delta-seconds ; Section 14.9.3, 14.9.4 - | "max-stale" [ "=" delta-seconds ] ; Section 14.9.3 - | "min-fresh" "=" delta-seconds ; Section 14.9.3 - | "no-transform" ; Section 14.9.5 - | "only-if-cached" ; Section 14.9.4 - | cache-extension ; Section 14.9.6 - - cache-response-directive = - "public" ; Section 14.9.1 - | "private" [ "=" <"> 1#field-name <"> ] ; Section 14.9.1 - | "no-cache" [ "=" <"> 1#field-name <"> ]; Section 14.9.1 - | "no-store" ; Section 14.9.2 - | "no-transform" ; Section 14.9.5 - | "must-revalidate" ; Section 14.9.4 - | "proxy-revalidate" ; Section 14.9.4 - | "max-age" "=" delta-seconds ; Section 14.9.3 - | "s-maxage" "=" delta-seconds ; Section 14.9.3 - | cache-extension ; Section 14.9.6 - - cache-extension = token [ "=" ( token | quoted-string ) ] - - - -Fielding, et al. Standards Track [Page 108] - -RFC 2616 HTTP/1.1 June 1999 - - - When a directive appears without any 1#field-name parameter, the - directive applies to the entire request or response. When such a - directive appears with a 1#field-name parameter, it applies only to - the named field or fields, and not to the rest of the request or - response. This mechanism supports extensibility; implementations of - future versions of the HTTP protocol might apply these directives to - header fields not defined in HTTP/1.1. - - The cache-control directives can be broken down into these general - categories: - - - Restrictions on what are cacheable; these may only be imposed by - the origin server. - - - Restrictions on what may be stored by a cache; these may be - imposed by either the origin server or the user agent. - - - Modifications of the basic expiration mechanism; these may be - imposed by either the origin server or the user agent. - - - Controls over cache revalidation and reload; these may only be - imposed by a user agent. - - - Control over transformation of entities. - - - Extensions to the caching system. - -14.9.1 What is Cacheable - - By default, a response is cacheable if the requirements of the - request method, request header fields, and the response status - indicate that it is cacheable. Section 13.4 summarizes these defaults - for cacheability. The following Cache-Control response directives - allow an origin server to override the default cacheability of a - response: - - public - Indicates that the response MAY be cached by any cache, even if it - would normally be non-cacheable or cacheable only within a non- - shared cache. (See also Authorization, section 14.8, for - additional details.) - - private - Indicates that all or part of the response message is intended for - a single user and MUST NOT be cached by a shared cache. This - allows an origin server to state that the specified parts of the - - - - - -Fielding, et al. Standards Track [Page 109] - -RFC 2616 HTTP/1.1 June 1999 - - - response are intended for only one user and are not a valid - response for requests by other users. A private (non-shared) cache - MAY cache the response. - - Note: This usage of the word private only controls where the - response may be cached, and cannot ensure the privacy of the - message content. - - no-cache - If the no-cache directive does not specify a field-name, then a - cache MUST NOT use the response to satisfy a subsequent request - without successful revalidation with the origin server. This - allows an origin server to prevent caching even by caches that - have been configured to return stale responses to client requests. - - If the no-cache directive does specify one or more field-names, - then a cache MAY use the response to satisfy a subsequent request, - subject to any other restrictions on caching. However, the - specified field-name(s) MUST NOT be sent in the response to a - subsequent request without successful revalidation with the origin - server. This allows an origin server to prevent the re-use of - certain header fields in a response, while still allowing caching - of the rest of the response. - - Note: Most HTTP/1.0 caches will not recognize or obey this - directive. - -14.9.2 What May be Stored by Caches - - no-store - The purpose of the no-store directive is to prevent the - inadvertent release or retention of sensitive information (for - example, on backup tapes). The no-store directive applies to the - entire message, and MAY be sent either in a response or in a - request. If sent in a request, a cache MUST NOT store any part of - either this request or any response to it. If sent in a response, - a cache MUST NOT store any part of either this response or the - request that elicited it. This directive applies to both non- - shared and shared caches. "MUST NOT store" in this context means - that the cache MUST NOT intentionally store the information in - non-volatile storage, and MUST make a best-effort attempt to - remove the information from volatile storage as promptly as - possible after forwarding it. - - Even when this directive is associated with a response, users - might explicitly store such a response outside of the caching - system (e.g., with a "Save As" dialog). History buffers MAY store - such responses as part of their normal operation. - - - -Fielding, et al. Standards Track [Page 110] - -RFC 2616 HTTP/1.1 June 1999 - - - The purpose of this directive is to meet the stated requirements - of certain users and service authors who are concerned about - accidental releases of information via unanticipated accesses to - cache data structures. While the use of this directive might - improve privacy in some cases, we caution that it is NOT in any - way a reliable or sufficient mechanism for ensuring privacy. In - particular, malicious or compromised caches might not recognize or - obey this directive, and communications networks might be - vulnerable to eavesdropping. - -14.9.3 Modifications of the Basic Expiration Mechanism - - The expiration time of an entity MAY be specified by the origin - server using the Expires header (see section 14.21). Alternatively, - it MAY be specified using the max-age directive in a response. When - the max-age cache-control directive is present in a cached response, - the response is stale if its current age is greater than the age - value given (in seconds) at the time of a new request for that - resource. The max-age directive on a response implies that the - response is cacheable (i.e., "public") unless some other, more - restrictive cache directive is also present. - - If a response includes both an Expires header and a max-age - directive, the max-age directive overrides the Expires header, even - if the Expires header is more restrictive. This rule allows an origin - server to provide, for a given response, a longer expiration time to - an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This might be - useful if certain HTTP/1.0 caches improperly calculate ages or - expiration times, perhaps due to desynchronized clocks. - - Many HTTP/1.0 cache implementations will treat an Expires value that - is less than or equal to the response Date value as being equivalent - to the Cache-Control response directive "no-cache". If an HTTP/1.1 - cache receives such a response, and the response does not include a - Cache-Control header field, it SHOULD consider the response to be - non-cacheable in order to retain compatibility with HTTP/1.0 servers. - - Note: An origin server might wish to use a relatively new HTTP - cache control feature, such as the "private" directive, on a - network including older caches that do not understand that - feature. The origin server will need to combine the new feature - with an Expires field whose value is less than or equal to the - Date value. This will prevent older caches from improperly - caching the response. - - - - - - - -Fielding, et al. Standards Track [Page 111] - -RFC 2616 HTTP/1.1 June 1999 - - - s-maxage - If a response includes an s-maxage directive, then for a shared - cache (but not for a private cache), the maximum age specified by - this directive overrides the maximum age specified by either the - max-age directive or the Expires header. The s-maxage directive - also implies the semantics of the proxy-revalidate directive (see - section 14.9.4), i.e., that the shared cache must not use the - entry after it becomes stale to respond to a subsequent request - without first revalidating it with the origin server. The s- - maxage directive is always ignored by a private cache. - - Note that most older caches, not compliant with this specification, - do not implement any cache-control directives. An origin server - wishing to use a cache-control directive that restricts, but does not - prevent, caching by an HTTP/1.1-compliant cache MAY exploit the - requirement that the max-age directive overrides the Expires header, - and the fact that pre-HTTP/1.1-compliant caches do not observe the - max-age directive. - - Other directives allow a user agent to modify the basic expiration - mechanism. These directives MAY be specified on a request: - - max-age - Indicates that the client is willing to accept a response whose - age is no greater than the specified time in seconds. Unless max- - stale directive is also included, the client is not willing to - accept a stale response. - - min-fresh - Indicates that the client is willing to accept a response whose - freshness lifetime is no less than its current age plus the - specified time in seconds. That is, the client wants a response - that will still be fresh for at least the specified number of - seconds. - - max-stale - Indicates that the client is willing to accept a response that has - exceeded its expiration time. If max-stale is assigned a value, - then the client is willing to accept a response that has exceeded - its expiration time by no more than the specified number of - seconds. If no value is assigned to max-stale, then the client is - willing to accept a stale response of any age. - - If a cache returns a stale response, either because of a max-stale - directive on a request, or because the cache is configured to - override the expiration time of a response, the cache MUST attach a - Warning header to the stale response, using Warning 110 (Response is - stale). - - - -Fielding, et al. Standards Track [Page 112] - -RFC 2616 HTTP/1.1 June 1999 - - - A cache MAY be configured to return stale responses without - validation, but only if this does not conflict with any "MUST"-level - requirements concerning cache validation (e.g., a "must-revalidate" - cache-control directive). - - If both the new request and the cached entry include "max-age" - directives, then the lesser of the two values is used for determining - the freshness of the cached entry for that request. - -14.9.4 Cache Revalidation and Reload Controls - - Sometimes a user agent might want or need to insist that a cache - revalidate its cache entry with the origin server (and not just with - the next cache along the path to the origin server), or to reload its - cache entry from the origin server. End-to-end revalidation might be - necessary if either the cache or the origin server has overestimated - the expiration time of the cached response. End-to-end reload may be - necessary if the cache entry has become corrupted for some reason. - - End-to-end revalidation may be requested either when the client does - not have its own local cached copy, in which case we call it - "unspecified end-to-end revalidation", or when the client does have a - local cached copy, in which case we call it "specific end-to-end - revalidation." - - The client can specify these three kinds of action using Cache- - Control request directives: - - End-to-end reload - The request includes a "no-cache" cache-control directive or, for - compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field - names MUST NOT be included with the no-cache directive in a - request. The server MUST NOT use a cached copy when responding to - such a request. - - Specific end-to-end revalidation - The request includes a "max-age=0" cache-control directive, which - forces each cache along the path to the origin server to - revalidate its own entry, if any, with the next cache or server. - The initial request includes a cache-validating conditional with - the client's current validator. - - Unspecified end-to-end revalidation - The request includes "max-age=0" cache-control directive, which - forces each cache along the path to the origin server to - revalidate its own entry, if any, with the next cache or server. - The initial request does not include a cache-validating - - - - -Fielding, et al. Standards Track [Page 113] - -RFC 2616 HTTP/1.1 June 1999 - - - conditional; the first cache along the path (if any) that holds a - cache entry for this resource includes a cache-validating - conditional with its current validator. - - max-age - When an intermediate cache is forced, by means of a max-age=0 - directive, to revalidate its own cache entry, and the client has - supplied its own validator in the request, the supplied validator - might differ from the validator currently stored with the cache - entry. In this case, the cache MAY use either validator in making - its own request without affecting semantic transparency. - - However, the choice of validator might affect performance. The - best approach is for the intermediate cache to use its own - validator when making its request. If the server replies with 304 - (Not Modified), then the cache can return its now validated copy - to the client with a 200 (OK) response. If the server replies with - a new entity and cache validator, however, the intermediate cache - can compare the returned validator with the one provided in the - client's request, using the strong comparison function. If the - client's validator is equal to the origin server's, then the - intermediate cache simply returns 304 (Not Modified). Otherwise, - it returns the new entity with a 200 (OK) response. - - If a request includes the no-cache directive, it SHOULD NOT - include min-fresh, max-stale, or max-age. - - only-if-cached - In some cases, such as times of extremely poor network - connectivity, a client may want a cache to return only those - responses that it currently has stored, and not to reload or - revalidate with the origin server. To do this, the client may - include the only-if-cached directive in a request. If it receives - this directive, a cache SHOULD either respond using a cached entry - that is consistent with the other constraints of the request, or - respond with a 504 (Gateway Timeout) status. However, if a group - of caches is being operated as a unified system with good internal - connectivity, such a request MAY be forwarded within that group of - caches. - - must-revalidate - Because a cache MAY be configured to ignore a server's specified - expiration time, and because a client request MAY include a max- - stale directive (which has a similar effect), the protocol also - includes a mechanism for the origin server to require revalidation - of a cache entry on any subsequent use. When the must-revalidate - directive is present in a response received by a cache, that cache - MUST NOT use the entry after it becomes stale to respond to a - - - -Fielding, et al. Standards Track [Page 114] - -RFC 2616 HTTP/1.1 June 1999 - - - subsequent request without first revalidating it with the origin - server. (I.e., the cache MUST do an end-to-end revalidation every - time, if, based solely on the origin server's Expires or max-age - value, the cached response is stale.) - - The must-revalidate directive is necessary to support reliable - operation for certain protocol features. In all circumstances an - HTTP/1.1 cache MUST obey the must-revalidate directive; in - particular, if the cache cannot reach the origin server for any - reason, it MUST generate a 504 (Gateway Timeout) response. - - Servers SHOULD send the must-revalidate directive if and only if - failure to revalidate a request on the entity could result in - incorrect operation, such as a silently unexecuted financial - transaction. Recipients MUST NOT take any automated action that - violates this directive, and MUST NOT automatically provide an - unvalidated copy of the entity if revalidation fails. - - Although this is not recommended, user agents operating under - severe connectivity constraints MAY violate this directive but, if - so, MUST explicitly warn the user that an unvalidated response has - been provided. The warning MUST be provided on each unvalidated - access, and SHOULD require explicit user confirmation. - - proxy-revalidate - The proxy-revalidate directive has the same meaning as the must- - revalidate directive, except that it does not apply to non-shared - user agent caches. It can be used on a response to an - authenticated request to permit the user's cache to store and - later return the response without needing to revalidate it (since - it has already been authenticated once by that user), while still - requiring proxies that service many users to revalidate each time - (in order to make sure that each user has been authenticated). - Note that such authenticated responses also need the public cache - control directive in order to allow them to be cached at all. - -14.9.5 No-Transform Directive - - no-transform - Implementors of intermediate caches (proxies) have found it useful - to convert the media type of certain entity bodies. A non- - transparent proxy might, for example, convert between image - formats in order to save cache space or to reduce the amount of - traffic on a slow link. - - Serious operational problems occur, however, when these - transformations are applied to entity bodies intended for certain - kinds of applications. For example, applications for medical - - - -Fielding, et al. Standards Track [Page 115] - -RFC 2616 HTTP/1.1 June 1999 - - - imaging, scientific data analysis and those using end-to-end - authentication, all depend on receiving an entity body that is bit - for bit identical to the original entity-body. - - Therefore, if a message includes the no-transform directive, an - intermediate cache or proxy MUST NOT change those headers that are - listed in section 13.5.2 as being subject to the no-transform - directive. This implies that the cache or proxy MUST NOT change - any aspect of the entity-body that is specified by these headers, - including the value of the entity-body itself. - -14.9.6 Cache Control Extensions - - The Cache-Control header field can be extended through the use of one - or more cache-extension tokens, each with an optional assigned value. - Informational extensions (those which do not require a change in - cache behavior) MAY be added without changing the semantics of other - directives. Behavioral extensions are designed to work by acting as - modifiers to the existing base of cache directives. Both the new - directive and the standard directive are supplied, such that - applications which do not understand the new directive will default - to the behavior specified by the standard directive, and those that - understand the new directive will recognize it as modifying the - requirements associated with the standard directive. In this way, - extensions to the cache-control directives can be made without - requiring changes to the base protocol. - - This extension mechanism depends on an HTTP cache obeying all of the - cache-control directives defined for its native HTTP-version, obeying - certain extensions, and ignoring all directives that it does not - understand. - - For example, consider a hypothetical new response directive called - community which acts as a modifier to the private directive. We - define this new directive to mean that, in addition to any non-shared - cache, any cache which is shared only by members of the community - named within its value may cache the response. An origin server - wishing to allow the UCI community to use an otherwise private - response in their shared cache(s) could do so by including - - Cache-Control: private, community="UCI" - - A cache seeing this header field will act correctly even if the cache - does not understand the community cache-extension, since it will also - see and understand the private directive and thus default to the safe - behavior. - - - - - -Fielding, et al. Standards Track [Page 116] - -RFC 2616 HTTP/1.1 June 1999 - - - Unrecognized cache-directives MUST be ignored; it is assumed that any - cache-directive likely to be unrecognized by an HTTP/1.1 cache will - be combined with standard directives (or the response's default - cacheability) such that the cache behavior will remain minimally - correct even if the cache does not understand the extension(s). - -14.10 Connection - - The Connection general-header field allows the sender to specify - options that are desired for that particular connection and MUST NOT - be communicated by proxies over further connections. - - The Connection header has the following grammar: - - Connection = "Connection" ":" 1#(connection-token) - connection-token = token - - HTTP/1.1 proxies MUST parse the Connection header field before a - message is forwarded and, for each connection-token in this field, - remove any header field(s) from the message with the same name as the - connection-token. Connection options are signaled by the presence of - a connection-token in the Connection header field, not by any - corresponding additional header field(s), since the additional header - field may not be sent if there are no parameters associated with that - connection option. - - Message headers listed in the Connection header MUST NOT include - end-to-end headers, such as Cache-Control. - - HTTP/1.1 defines the "close" connection option for the sender to - signal that the connection will be closed after completion of the - response. For example, - - Connection: close - - in either the request or the response header fields indicates that - the connection SHOULD NOT be considered `persistent' (section 8.1) - after the current request/response is complete. - - HTTP/1.1 applications that do not support persistent connections MUST - include the "close" connection option in every message. - -[[ Should say: ]] -[[ An HTTP/1.1 client that does not support persistent connections ]] -[[ MUST include the "close" connection option in every request message. ]] -[[ ]] -[[ An HTTP/1.1 server that does not support persistent connections ]] -[[ MUST include the "close" connection option in every response ]] -[[ message that does not have a 1xx (informational) status code. ]] - - A system receiving an HTTP/1.0 (or lower-version) message that - includes a Connection header MUST, for each connection-token in this - field, remove and ignore any header field(s) from the message with - the same name as the connection-token. This protects against mistaken - forwarding of such header fields by pre-HTTP/1.1 proxies. See section - 19.6.2. - - - -Fielding, et al. Standards Track [Page 117] - -RFC 2616 HTTP/1.1 June 1999 - - -14.11 Content-Encoding - - The Content-Encoding entity-header field is used as a modifier to the - media-type. When present, its value indicates what additional content - codings have been applied to the entity-body, and thus what decoding - mechanisms must be applied in order to obtain the media-type - referenced by the Content-Type header field. Content-Encoding is - primarily used to allow a document to be compressed without losing - the identity of its underlying media type. - - Content-Encoding = "Content-Encoding" ":" 1#content-coding - - Content codings are defined in section 3.5. An example of its use is - - Content-Encoding: gzip - - The content-coding is a characteristic of the entity identified by - the Request-URI. Typically, the entity-body is stored with this - encoding and is only decoded before rendering or analogous usage. - However, a non-transparent proxy MAY modify the content-coding if the - new coding is known to be acceptable to the recipient, unless the - "no-transform" cache-control directive is present in the message. - - If the content-coding of an entity is not "identity", then the - response MUST include a Content-Encoding entity-header (section - 14.11) that lists the non-identity content-coding(s) used. - - If the content-coding of an entity in a request message is not - acceptable to the origin server, the server SHOULD respond with a - status code of 415 (Unsupported Media Type). - - If multiple encodings have been applied to an entity, the content - codings MUST be listed in the order in which they were applied. - Additional information about the encoding parameters MAY be provided - by other entity-header fields not defined by this specification. - -14.12 Content-Language - - The Content-Language entity-header field describes the natural - language(s) of the intended audience for the enclosed entity. Note - that this might not be equivalent to all the languages used within - the entity-body. - - Content-Language = "Content-Language" ":" 1#language-tag - - - - - - - -Fielding, et al. Standards Track [Page 118] - -RFC 2616 HTTP/1.1 June 1999 - - - Language tags are defined in section 3.10. The primary purpose of - Content-Language is to allow a user to identify and differentiate - entities according to the user's own preferred language. Thus, if the - body content is intended only for a Danish-literate audience, the - appropriate field is - - Content-Language: da - - If no Content-Language is specified, the default is that the content - is intended for all language audiences. This might mean that the - sender does not consider it to be specific to any natural language, - or that the sender does not know for which language it is intended. - - Multiple languages MAY be listed for content that is intended for - multiple audiences. For example, a rendition of the "Treaty of - Waitangi," presented simultaneously in the original Maori and English - versions, would call for - - Content-Language: mi, en - - However, just because multiple languages are present within an entity - does not mean that it is intended for multiple linguistic audiences. - An example would be a beginner's language primer, such as "A First - Lesson in Latin," which is clearly intended to be used by an - English-literate audience. In this case, the Content-Language would - properly only include "en". - - Content-Language MAY be applied to any media type -- it is not - limited to textual documents. - -14.13 Content-Length - - The Content-Length entity-header field indicates the size of the - entity-body, in decimal number of OCTETs, sent to the recipient or, - in the case of the HEAD method, the size of the entity-body that - would have been sent had the request been a GET. - - Content-Length = "Content-Length" ":" 1*DIGIT - - An example is - - Content-Length: 3495 - - Applications SHOULD use this field to indicate the transfer-length of - the message-body, unless this is prohibited by the rules in section - 4.4. - - - - - -Fielding, et al. Standards Track [Page 119] - -RFC 2616 HTTP/1.1 June 1999 - - - Any Content-Length greater than or equal to zero is a valid value. - Section 4.4 describes how to determine the length of a message-body - if a Content-Length is not given. - - Note that the meaning of this field is significantly different from - the corresponding definition in MIME, where it is an optional field - used within the "message/external-body" content-type. In HTTP, it - SHOULD be sent whenever the message's length can be determined prior - to being transferred, unless this is prohibited by the rules in - section 4.4. - -14.14 Content-Location - - The Content-Location entity-header field MAY be used to supply the - resource location for the entity enclosed in the message when that - entity is accessible from a location separate from the requested - resource's URI. A server SHOULD provide a Content-Location for the - variant corresponding to the response entity; especially in the case - where a resource has multiple entities associated with it, and those - entities actually have separate locations by which they might be - individually accessed, the server SHOULD provide a Content-Location - for the particular variant which is returned. - - Content-Location = "Content-Location" ":" - ( absoluteURI | relativeURI ) - - The value of Content-Location also defines the base URI for the - entity. - - The Content-Location value is not a replacement for the original - requested URI; it is only a statement of the location of the resource - corresponding to this particular entity at the time of the request. - Future requests MAY specify the Content-Location URI as the request- - URI if the desire is to identify the source of that particular - entity. - - A cache cannot assume that an entity with a Content-Location - different from the URI used to retrieve it can be used to respond to - later requests on that Content-Location URI. However, the Content- - Location can be used to differentiate between multiple entities - retrieved from a single requested resource, as described in section - 13.6. - - If the Content-Location is a relative URI, the relative URI is - interpreted relative to the Request-URI. - - The meaning of the Content-Location header in PUT or POST requests is - undefined; servers are free to ignore it in those cases. - - - -Fielding, et al. Standards Track [Page 120] - -RFC 2616 HTTP/1.1 June 1999 - - -14.15 Content-MD5 - - The Content-MD5 entity-header field, as defined in RFC 1864 [23], is - an MD5 digest of the entity-body for the purpose of providing an - end-to-end message integrity check (MIC) of the entity-body. (Note: a - MIC is good for detecting accidental modification of the entity-body - in transit, but is not proof against malicious attacks.) - - Content-MD5 = "Content-MD5" ":" md5-digest - md5-digest = <base64 of 128 bit MD5 digest as per RFC 1864> - - The Content-MD5 header field MAY be generated by an origin server or - client to function as an integrity check of the entity-body. Only - origin servers or clients MAY generate the Content-MD5 header field; - proxies and gateways MUST NOT generate it, as this would defeat its - value as an end-to-end integrity check. Any recipient of the entity- - body, including gateways and proxies, MAY check that the digest value - in this header field matches that of the entity-body as received. - - The MD5 digest is computed based on the content of the entity-body, - including any content-coding that has been applied, but not including - any transfer-encoding applied to the message-body. If the message is - received with a transfer-encoding, that encoding MUST be removed - prior to checking the Content-MD5 value against the received entity. - - This has the result that the digest is computed on the octets of the - entity-body exactly as, and in the order that, they would be sent if - no transfer-encoding were being applied. - - HTTP extends RFC 1864 to permit the digest to be computed for MIME - composite media-types (e.g., multipart/* and message/rfc822), but - this does not change how the digest is computed as defined in the - preceding paragraph. - - There are several consequences of this. The entity-body for composite - types MAY contain many body-parts, each with its own MIME and HTTP - headers (including Content-MD5, Content-Transfer-Encoding, and - Content-Encoding headers). If a body-part has a Content-Transfer- - Encoding or Content-Encoding header, it is assumed that the content - of the body-part has had the encoding applied, and the body-part is - included in the Content-MD5 digest as is -- i.e., after the - application. The Transfer-Encoding header field is not allowed within - body-parts. - - Conversion of all line breaks to CRLF MUST NOT be done before - computing or checking the digest: the line break convention used in - the text actually transmitted MUST be left unaltered when computing - the digest. - - - -Fielding, et al. Standards Track [Page 121] - -RFC 2616 HTTP/1.1 June 1999 - - - Note: while the definition of Content-MD5 is exactly the same for - HTTP as in RFC 1864 for MIME entity-bodies, there are several ways - in which the application of Content-MD5 to HTTP entity-bodies - differs from its application to MIME entity-bodies. One is that - HTTP, unlike MIME, does not use Content-Transfer-Encoding, and - does use Transfer-Encoding and Content-Encoding. Another is that - HTTP more frequently uses binary content types than MIME, so it is - worth noting that, in such cases, the byte order used to compute - the digest is the transmission byte order defined for the type. - Lastly, HTTP allows transmission of text types with any of several - line break conventions and not just the canonical form using CRLF. - -14.16 Content-Range - - The Content-Range entity-header is sent with a partial entity-body to - specify where in the full entity-body the partial body should be - applied. Range units are defined in section 3.12. - - Content-Range = "Content-Range" ":" content-range-spec - - content-range-spec = byte-content-range-spec - byte-content-range-spec = bytes-unit SP - byte-range-resp-spec "/" - ( instance-length | "*" ) - - byte-range-resp-spec = (first-byte-pos "-" last-byte-pos) - | "*" - instance-length = 1*DIGIT - - The header SHOULD indicate the total length of the full entity-body, - unless this length is unknown or difficult to determine. The asterisk - "*" character means that the instance-length is unknown at the time - when the response was generated. - - Unlike byte-ranges-specifier values (see section 14.35.1), a byte- - range-resp-spec MUST only specify one range, and MUST contain - absolute byte positions for both the first and last byte of the - range. - - A byte-content-range-spec with a byte-range-resp-spec whose last- - byte-pos value is less than its first-byte-pos value, or whose - instance-length value is less than or equal to its last-byte-pos - value, is invalid. The recipient of an invalid byte-content-range- - spec MUST ignore it and any content transferred along with it. - - A server sending a response with status code 416 (Requested range not - satisfiable) SHOULD include a Content-Range field with a byte-range- - resp-spec of "*". The instance-length specifies the current length of - - - -Fielding, et al. Standards Track [Page 122] - -RFC 2616 HTTP/1.1 June 1999 - - - the selected resource. A response with status code 206 (Partial - Content) MUST NOT include a Content-Range field with a byte-range- - resp-spec of "*". - - Examples of byte-content-range-spec values, assuming that the entity - contains a total of 1234 bytes: - - . The first 500 bytes: - bytes 0-499/1234 - - . The second 500 bytes: - bytes 500-999/1234 - - . All except for the first 500 bytes: - bytes 500-1233/1234 - - . The last 500 bytes: - bytes 734-1233/1234 - - When an HTTP message includes the content of a single range (for - example, a response to a request for a single range, or to a request - for a set of ranges that overlap without any holes), this content is - transmitted with a Content-Range header, and a Content-Length header - showing the number of bytes actually transferred. For example, - - HTTP/1.1 206 Partial content - Date: Wed, 15 Nov 1995 06:25:24 GMT - Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT - Content-Range: bytes 21010-47021/47022 - Content-Length: 26012 - Content-Type: image/gif - - When an HTTP message includes the content of multiple ranges (for - example, a response to a request for multiple non-overlapping - ranges), these are transmitted as a multipart message. The multipart - media type used for this purpose is "multipart/byteranges" as defined - in appendix 19.2. See appendix 19.6.3 for a compatibility issue. - - A response to a request for a single range MUST NOT be sent using the - multipart/byteranges media type. A response to a request for - multiple ranges, whose result is a single range, MAY be sent as a - multipart/byteranges media type with one part. A client that cannot - decode a multipart/byteranges message MUST NOT ask for multiple - byte-ranges in a single request. - - When a client requests multiple byte-ranges in one request, the - server SHOULD return them in the order that they appeared in the - request. - - - -Fielding, et al. Standards Track [Page 123] - -RFC 2616 HTTP/1.1 June 1999 - - - If the server ignores a byte-range-spec because it is syntactically - invalid, the server SHOULD treat the request as if the invalid Range - header field did not exist. (Normally, this means return a 200 - response containing the full entity). - - If the server receives a request (other than one including an If- - Range request-header field) with an unsatisfiable Range request- - header field (that is, all of whose byte-range-spec values have a - first-byte-pos value greater than the current length of the selected - resource), it SHOULD return a response code of 416 (Requested range - not satisfiable) (section 10.4.17). - - Note: clients cannot depend on servers to send a 416 (Requested - range not satisfiable) response instead of a 200 (OK) response for - an unsatisfiable Range request-header, since not all servers - implement this request-header. - -14.17 Content-Type - - The Content-Type entity-header field indicates the media type of the - entity-body sent to the recipient or, in the case of the HEAD method, - the media type that would have been sent had the request been a GET. - - Content-Type = "Content-Type" ":" media-type - - Media types are defined in section 3.7. An example of the field is - - Content-Type: text/html; charset=ISO-8859-4 - - Further discussion of methods for identifying the media type of an - entity is provided in section 7.2.1. - -14.18 Date - - The Date general-header field represents the date and time at which - the message was originated, having the same semantics as orig-date in - RFC 822. The field value is an HTTP-date, as described in section - 3.3.1; it MUST be sent in RFC 1123 [8]-date format. - - Date = "Date" ":" HTTP-date - - An example is - - Date: Tue, 15 Nov 1994 08:12:31 GMT - - Origin servers MUST include a Date header field in all responses, - except in these cases: - - - - -Fielding, et al. Standards Track [Page 124] - -RFC 2616 HTTP/1.1 June 1999 - - - 1. If the response status code is 100 (Continue) or 101 (Switching - Protocols), the response MAY include a Date header field, at - the server's option. - - 2. If the response status code conveys a server error, e.g. 500 - (Internal Server Error) or 503 (Service Unavailable), and it is - inconvenient or impossible to generate a valid Date. - - 3. If the server does not have a clock that can provide a - reasonable approximation of the current time, its responses - MUST NOT include a Date header field. In this case, the rules - in section 14.18.1 MUST be followed. - - A received message that does not have a Date header field MUST be - assigned one by the recipient if the message will be cached by that - recipient or gatewayed via a protocol which requires a Date. An HTTP - implementation without a clock MUST NOT cache responses without - revalidating them on every use. An HTTP cache, especially a shared - cache, SHOULD use a mechanism, such as NTP [28], to synchronize its - clock with a reliable external standard. - - Clients SHOULD only send a Date header field in messages that include - an entity-body, as in the case of the PUT and POST requests, and even - then it is optional. A client without a clock MUST NOT send a Date - header field in a request. - - The HTTP-date sent in a Date header SHOULD NOT represent a date and - time subsequent to the generation of the message. It SHOULD represent - the best available approximation of the date and time of message - generation, unless the implementation has no means of generating a - reasonably accurate date and time. In theory, the date ought to - represent the moment just before the entity is generated. In - practice, the date can be generated at any time during the message - origination without affecting its semantic value. - -14.18.1 Clockless Origin Server Operation - - Some origin server implementations might not have a clock available. - An origin server without a clock MUST NOT assign Expires or Last- - Modified values to a response, unless these values were associated - with the resource by a system or user with a reliable clock. It MAY - assign an Expires value that is known, at or before server - configuration time, to be in the past (this allows "pre-expiration" - of responses without storing separate Expires values for each - resource). - - - - - - -Fielding, et al. Standards Track [Page 125] - -RFC 2616 HTTP/1.1 June 1999 - - -14.19 ETag - - The ETag response-header field provides the current value of the - entity tag for the requested variant. The headers used with entity - tags are described in sections 14.24, 14.26 and 14.44. The entity tag - MAY be used for comparison with other entities from the same resource - (see section 13.3.3). - - ETag = "ETag" ":" entity-tag - - Examples: - - ETag: "xyzzy" - ETag: W/"xyzzy" - ETag: "" - -14.20 Expect - - The Expect request-header field is used to indicate that particular - server behaviors are required by the client. - - Expect = "Expect" ":" 1#expectation - - expectation = "100-continue" | expectation-extension - expectation-extension = token [ "=" ( token | quoted-string ) - *expect-params ] - expect-params = ";" token [ "=" ( token | quoted-string ) ] - - - A server that does not understand or is unable to comply with any of - the expectation values in the Expect field of a request MUST respond - with appropriate error status. The server MUST respond with a 417 - (Expectation Failed) status if any of the expectations cannot be met - or, if there are other problems with the request, some other 4xx - status. - - This header field is defined with extensible syntax to allow for - future extensions. If a server receives a request containing an - Expect field that includes an expectation-extension that it does not - support, it MUST respond with a 417 (Expectation Failed) status. - - Comparison of expectation values is case-insensitive for unquoted - tokens (including the 100-continue token), and is case-sensitive for - quoted-string expectation-extensions. - - - - - - - -Fielding, et al. Standards Track [Page 126] - -RFC 2616 HTTP/1.1 June 1999 - - - The Expect mechanism is hop-by-hop: that is, an HTTP/1.1 proxy MUST - return a 417 (Expectation Failed) status if it receives a request - with an expectation that it cannot meet. However, the Expect - request-header itself is end-to-end; it MUST be forwarded if the - request is forwarded. - - Many older HTTP/1.0 and HTTP/1.1 applications do not understand the - Expect header. - - See section 8.2.3 for the use of the 100 (continue) status. - -14.21 Expires - - The Expires entity-header field gives the date/time after which the - response is considered stale. A stale cache entry may not normally be - returned by a cache (either a proxy cache or a user agent cache) - unless it is first validated with the origin server (or with an - intermediate cache that has a fresh copy of the entity). See section - 13.2 for further discussion of the expiration model. - - The presence of an Expires field does not imply that the original - resource will change or cease to exist at, before, or after that - time. - - The format is an absolute date and time as defined by HTTP-date in - section 3.3.1; it MUST be in RFC 1123 date format: - - Expires = "Expires" ":" HTTP-date - - An example of its use is - - Expires: Thu, 01 Dec 1994 16:00:00 GMT - - Note: if a response includes a Cache-Control field with the max- - age directive (see section 14.9.3), that directive overrides the - Expires field. - - HTTP/1.1 clients and caches MUST treat other invalid date formats, - especially including the value "0", as in the past (i.e., "already - expired"). - - To mark a response as "already expired," an origin server sends an - Expires date that is equal to the Date header value. (See the rules - for expiration calculations in section 13.2.4.) - - - - - - - -Fielding, et al. Standards Track [Page 127] - -RFC 2616 HTTP/1.1 June 1999 - - - To mark a response as "never expires," an origin server sends an - Expires date approximately one year from the time the response is - sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one - year in the future. - - The presence of an Expires header field with a date value of some - time in the future on a response that otherwise would by default be - non-cacheable indicates that the response is cacheable, unless - indicated otherwise by a Cache-Control header field (section 14.9). - -14.22 From - - The From request-header field, if given, SHOULD contain an Internet - e-mail address for the human user who controls the requesting user - agent. The address SHOULD be machine-usable, as defined by "mailbox" - in RFC 822 [9] as updated by RFC 1123 [8]: - - From = "From" ":" mailbox - - An example is: - - From: webmaster@w3.org - - This header field MAY be used for logging purposes and as a means for - identifying the source of invalid or unwanted requests. It SHOULD NOT - be used as an insecure form of access protection. The interpretation - of this field is that the request is being performed on behalf of the - person given, who accepts responsibility for the method performed. In - particular, robot agents SHOULD include this header so that the - person responsible for running the robot can be contacted if problems - occur on the receiving end. - - The Internet e-mail address in this field MAY be separate from the - Internet host which issued the request. For example, when a request - is passed through a proxy the original issuer's address SHOULD be - used. - - The client SHOULD NOT send the From header field without the user's - approval, as it might conflict with the user's privacy interests or - their site's security policy. It is strongly recommended that the - user be able to disable, enable, and modify the value of this field - at any time prior to a request. - -14.23 Host - - The Host request-header field specifies the Internet host and port - number of the resource being requested, as obtained from the original - URI given by the user or referring resource (generally an HTTP URL, - - - -Fielding, et al. Standards Track [Page 128] - -RFC 2616 HTTP/1.1 June 1999 - - - as described in section 3.2.2). The Host field value MUST represent - the naming authority of the origin server or gateway given by the - original URL. This allows the origin server or gateway to - differentiate between internally-ambiguous URLs, such as the root "/" - URL of a server for multiple host names on a single IP address. - - Host = "Host" ":" host [ ":" port ] ; Section 3.2.2 - - A "host" without any trailing port information implies the default - port for the service requested (e.g., "80" for an HTTP URL). For - example, a request on the origin server for - <http://www.w3.org/pub/WWW/> would properly include: - - GET /pub/WWW/ HTTP/1.1 - Host: www.w3.org - - A client MUST include a Host header field in all HTTP/1.1 request - messages . If the requested URI does not include an Internet host - name for the service being requested, then the Host header field MUST - be given with an empty value. An HTTP/1.1 proxy MUST ensure that any - request message it forwards does contain an appropriate Host header - field that identifies the service being requested by the proxy. All - Internet-based HTTP/1.1 servers MUST respond with a 400 (Bad Request) - status code to any HTTP/1.1 request message which lacks a Host header - field. - - See sections 5.2 and 19.6.1.1 for other requirements relating to - Host. - -14.24 If-Match - - The If-Match request-header field is used with a method to make it - conditional. A client that has one or more entities previously - obtained from the resource can verify that one of those entities is - current by including a list of their associated entity tags in the - If-Match header field. Entity tags are defined in section 3.11. The - purpose of this feature is to allow efficient updates of cached - information with a minimum amount of transaction overhead. It is also - used, on updating requests, to prevent inadvertent modification of - the wrong version of a resource. As a special case, the value "*" - matches any current entity of the resource. - - If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) - - If any of the entity tags match the entity tag of the entity that - would have been returned in the response to a similar GET request - (without the If-Match header) on that resource, or if "*" is given - - - - -Fielding, et al. Standards Track [Page 129] - -RFC 2616 HTTP/1.1 June 1999 - - - and any current entity exists for that resource, then the server MAY - perform the requested method as if the If-Match header field did not - exist. - - A server MUST use the strong comparison function (see section 13.3.3) - to compare the entity tags in If-Match. - - If none of the entity tags match, or if "*" is given and no current - entity exists, the server MUST NOT perform the requested method, and - MUST return a 412 (Precondition Failed) response. This behavior is - most useful when the client wants to prevent an updating method, such - as PUT, from modifying a resource that has changed since the client - last retrieved it. - - If the request would, without the If-Match header field, result in - anything other than a 2xx or 412 status, then the If-Match header - MUST be ignored. - - The meaning of "If-Match: *" is that the method SHOULD be performed - if the representation selected by the origin server (or by a cache, - possibly using the Vary mechanism, see section 14.44) exists, and - MUST NOT be performed if the representation does not exist. - - A request intended to update a resource (e.g., a PUT) MAY include an - If-Match header field to signal that the request method MUST NOT be - applied if the entity corresponding to the If-Match value (a single - entity tag) is no longer a representation of that resource. This - allows the user to indicate that they do not wish the request to be - successful if the resource has been changed without their knowledge. - Examples: - - If-Match: "xyzzy" - If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" - If-Match: * - - The result of a request having both an If-Match header field and - either an If-None-Match or an If-Modified-Since header fields is - undefined by this specification. - -14.25 If-Modified-Since - - The If-Modified-Since request-header field is used with a method to - make it conditional: if the requested variant has not been modified - since the time specified in this field, an entity will not be - returned from the server; instead, a 304 (not modified) response will - be returned without any message-body. - - If-Modified-Since = "If-Modified-Since" ":" HTTP-date - - - -Fielding, et al. Standards Track [Page 130] - -RFC 2616 HTTP/1.1 June 1999 - - - An example of the field is: - - If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT - - A GET method with an If-Modified-Since header and no Range header - requests that the identified entity be transferred only if it has - been modified since the date given by the If-Modified-Since header. - The algorithm for determining this includes the following cases: - - a) If the request would normally result in anything other than a - 200 (OK) status, or if the passed If-Modified-Since date is - invalid, the response is exactly the same as for a normal GET. - A date which is later than the server's current time is - invalid. - - b) If the variant has been modified since the If-Modified-Since - date, the response is exactly the same as for a normal GET. - - c) If the variant has not been modified since a valid If- - Modified-Since date, the server SHOULD return a 304 (Not - Modified) response. - - The purpose of this feature is to allow efficient updates of cached - information with a minimum amount of transaction overhead. - - Note: The Range request-header field modifies the meaning of If- - Modified-Since; see section 14.35 for full details. - - Note: If-Modified-Since times are interpreted by the server, whose - clock might not be synchronized with the client. - - Note: When handling an If-Modified-Since header field, some - servers will use an exact date comparison function, rather than a - less-than function, for deciding whether to send a 304 (Not - Modified) response. To get best results when sending an If- - Modified-Since header field for cache validation, clients are - advised to use the exact date string received in a previous Last- - Modified header field whenever possible. - - Note: If a client uses an arbitrary date in the If-Modified-Since - header instead of a date taken from the Last-Modified header for - the same request, the client should be aware of the fact that this - date is interpreted in the server's understanding of time. The - client should consider unsynchronized clocks and rounding problems - due to the different encodings of time between the client and - server. This includes the possibility of race conditions if the - document has changed between the time it was first requested and - the If-Modified-Since date of a subsequent request, and the - - - -Fielding, et al. Standards Track [Page 131] - -RFC 2616 HTTP/1.1 June 1999 - - - possibility of clock-skew-related problems if the If-Modified- - Since date is derived from the client's clock without correction - to the server's clock. Corrections for different time bases - between client and server are at best approximate due to network - latency. - - The result of a request having both an If-Modified-Since header field - and either an If-Match or an If-Unmodified-Since header fields is - undefined by this specification. - -14.26 If-None-Match - - The If-None-Match request-header field is used with a method to make - it conditional. A client that has one or more entities previously - obtained from the resource can verify that none of those entities is - current by including a list of their associated entity tags in the - If-None-Match header field. The purpose of this feature is to allow - efficient updates of cached information with a minimum amount of - transaction overhead. It is also used to prevent a method (e.g. PUT) - from inadvertently modifying an existing resource when the client - believes that the resource does not exist. - - As a special case, the value "*" matches any current entity of the - resource. - - If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag ) - - If any of the entity tags match the entity tag of the entity that - would have been returned in the response to a similar GET request - (without the If-None-Match header) on that resource, or if "*" is - given and any current entity exists for that resource, then the - server MUST NOT perform the requested method, unless required to do - so because the resource's modification date fails to match that - supplied in an If-Modified-Since header field in the request. - Instead, if the request method was GET or HEAD, the server SHOULD - respond with a 304 (Not Modified) response, including the cache- - related header fields (particularly ETag) of one of the entities that - matched. For all other request methods, the server MUST respond with - a status of 412 (Precondition Failed). - - See section 13.3.3 for rules on how to determine if two entities tags - match. The weak comparison function can only be used with GET or HEAD - requests. - - - - - - - - -Fielding, et al. Standards Track [Page 132] - -RFC 2616 HTTP/1.1 June 1999 - - - If none of the entity tags match, then the server MAY perform the - requested method as if the If-None-Match header field did not exist, - but MUST also ignore any If-Modified-Since header field(s) in the - request. That is, if no entity tags match, then the server MUST NOT - return a 304 (Not Modified) response. - - If the request would, without the If-None-Match header field, result - in anything other than a 2xx or 304 status, then the If-None-Match - header MUST be ignored. (See section 13.3.4 for a discussion of - server behavior when both If-Modified-Since and If-None-Match appear - in the same request.) - - The meaning of "If-None-Match: *" is that the method MUST NOT be - performed if the representation selected by the origin server (or by - a cache, possibly using the Vary mechanism, see section 14.44) - exists, and SHOULD be performed if the representation does not exist. - This feature is intended to be useful in preventing races between PUT - operations. - - Examples: - - If-None-Match: "xyzzy" - If-None-Match: W/"xyzzy" - If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" - If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" - If-None-Match: * - - The result of a request having both an If-None-Match header field and - either an If-Match or an If-Unmodified-Since header fields is - undefined by this specification. - -14.27 If-Range - - If a client has a partial copy of an entity in its cache, and wishes - to have an up-to-date copy of the entire entity in its cache, it - could use the Range request-header with a conditional GET (using - either or both of If-Unmodified-Since and If-Match.) However, if the - condition fails because the entity has been modified, the client - would then have to make a second request to obtain the entire current - entity-body. - - The If-Range header allows a client to "short-circuit" the second - request. Informally, its meaning is `if the entity is unchanged, send - me the part(s) that I am missing; otherwise, send me the entire new - entity'. - - If-Range = "If-Range" ":" ( entity-tag | HTTP-date ) - - - - -Fielding, et al. Standards Track [Page 133] - -RFC 2616 HTTP/1.1 June 1999 - - - If the client has no entity tag for an entity, but does have a Last- - Modified date, it MAY use that date in an If-Range header. (The - server can distinguish between a valid HTTP-date and any form of - entity-tag by examining no more than two characters.) The If-Range - header SHOULD only be used together with a Range header, and MUST be - ignored if the request does not include a Range header, or if the - server does not support the sub-range operation. - - If the entity tag given in the If-Range header matches the current - entity tag for the entity, then the server SHOULD provide the - specified sub-range of the entity using a 206 (Partial content) - response. If the entity tag does not match, then the server SHOULD - return the entire entity using a 200 (OK) response. - -14.28 If-Unmodified-Since - - The If-Unmodified-Since request-header field is used with a method to - make it conditional. If the requested resource has not been modified - since the time specified in this field, the server SHOULD perform the - requested operation as if the If-Unmodified-Since header were not - present. - - If the requested variant has been modified since the specified time, - the server MUST NOT perform the requested operation, and MUST return - a 412 (Precondition Failed). - - If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date - - An example of the field is: - - If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT - - If the request normally (i.e., without the If-Unmodified-Since - header) would result in anything other than a 2xx or 412 status, the - If-Unmodified-Since header SHOULD be ignored. - - If the specified date is invalid, the header is ignored. - - The result of a request having both an If-Unmodified-Since header - field and either an If-None-Match or an If-Modified-Since header - fields is undefined by this specification. - -14.29 Last-Modified - - The Last-Modified entity-header field indicates the date and time at - which the origin server believes the variant was last modified. - - Last-Modified = "Last-Modified" ":" HTTP-date - - - -Fielding, et al. Standards Track [Page 134] - -RFC 2616 HTTP/1.1 June 1999 - - - An example of its use is - - Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT - - The exact meaning of this header field depends on the implementation - of the origin server and the nature of the original resource. For - files, it may be just the file system last-modified time. For - entities with dynamically included parts, it may be the most recent - of the set of last-modify times for its component parts. For database - gateways, it may be the last-update time stamp of the record. For - virtual objects, it may be the last time the internal state changed. - - An origin server MUST NOT send a Last-Modified date which is later - than the server's time of message origination. In such cases, where - the resource's last modification would indicate some time in the - future, the server MUST replace that date with the message - origination date. - - An origin server SHOULD obtain the Last-Modified value of the entity - as close as possible to the time that it generates the Date value of - its response. This allows a recipient to make an accurate assessment - of the entity's modification time, especially if the entity changes - near the time that the response is generated. - - HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. - -14.30 Location - - The Location response-header field is used to redirect the recipient - to a location other than the Request-URI for completion of the - request or identification of a new resource. For 201 (Created) - responses, the Location is that of the new resource which was created - by the request. For 3xx responses, the location SHOULD indicate the - server's preferred URI for automatic redirection to the resource. The - field value consists of a single absolute URI. - - Location = "Location" ":" absoluteURI - [[ [ "#" fragment ] ]] - - An example is: - - Location: http://www.w3.org/pub/WWW/People.html - - Note: The Content-Location header field (section 14.14) differs - from Location in that the Content-Location identifies the original - location of the entity enclosed in the request. It is therefore - possible for a response to contain header fields for both Location - and Content-Location. Also see section 13.10 for cache - requirements of some methods. - - - -Fielding, et al. Standards Track [Page 135] - -RFC 2616 HTTP/1.1 June 1999 - - -14.31 Max-Forwards - - The Max-Forwards request-header field provides a mechanism with the - TRACE (section 9.8) and OPTIONS (section 9.2) methods to limit the - number of proxies or gateways that can forward the request to the - next inbound server. This can be useful when the client is attempting - to trace a request chain which appears to be failing or looping in - mid-chain. - - Max-Forwards = "Max-Forwards" ":" 1*DIGIT - - The Max-Forwards value is a decimal integer indicating the remaining - number of times this request message may be forwarded. - - Each proxy or gateway recipient of a TRACE or OPTIONS request - containing a Max-Forwards header field MUST check and update its - value prior to forwarding the request. If the received value is zero - (0), the recipient MUST NOT forward the request; instead, it MUST - respond as the final recipient. If the received Max-Forwards value is - greater than zero, then the forwarded message MUST contain an updated - Max-Forwards field with a value decremented by one (1). - - The Max-Forwards header field MAY be ignored for all other methods - defined by this specification and for any extension methods for which - it is not explicitly referred to as part of that method definition. - -14.32 Pragma - - The Pragma general-header field is used to include implementation- - specific directives that might apply to any recipient along the - request/response chain. All pragma directives specify optional - behavior from the viewpoint of the protocol; however, some systems - MAY require that behavior be consistent with the directives. - - Pragma = "Pragma" ":" 1#pragma-directive - pragma-directive = "no-cache" | extension-pragma - extension-pragma = token [ "=" ( token | quoted-string ) ] - - When the no-cache directive is present in a request message, an - application SHOULD forward the request toward the origin server even - if it has a cached copy of what is being requested. This pragma - directive has the same semantics as the no-cache cache-directive (see - section 14.9) and is defined here for backward compatibility with - HTTP/1.0. Clients SHOULD include both header fields when a no-cache - request is sent to a server not known to be HTTP/1.1 compliant. - - - - - - -Fielding, et al. Standards Track [Page 136] - -RFC 2616 HTTP/1.1 June 1999 - - - Pragma directives MUST be passed through by a proxy or gateway - application, regardless of their significance to that application, - since the directives might be applicable to all recipients along the - request/response chain. It is not possible to specify a pragma for a - specific recipient; however, any pragma directive not relevant to a - recipient SHOULD be ignored by that recipient. - - HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had - sent "Cache-Control: no-cache". No new Pragma directives will be - defined in HTTP. - - Note: because the meaning of "Pragma: no-cache as a response - header field is not actually specified, it does not provide a - reliable replacement for "Cache-Control: no-cache" in a response - -14.33 Proxy-Authenticate - - The Proxy-Authenticate response-header field MUST be included as part - of a 407 (Proxy Authentication Required) response. The field value - consists of a challenge that indicates the authentication scheme and - parameters applicable to the proxy for this Request-URI. - - Proxy-Authenticate = "Proxy-Authenticate" ":" 1#challenge - - The HTTP access authentication process is described in "HTTP - Authentication: Basic and Digest Access Authentication" [43]. Unlike - WWW-Authenticate, the Proxy-Authenticate header field applies only to - the current connection and SHOULD NOT be passed on to downstream - clients. However, an intermediate proxy might need to obtain its own - credentials by requesting them from the downstream client, which in - some circumstances will appear as if the proxy is forwarding the - Proxy-Authenticate header field. - -14.34 Proxy-Authorization - - The Proxy-Authorization request-header field allows the client to - identify itself (or its user) to a proxy which requires - authentication. The Proxy-Authorization field value consists of - credentials containing the authentication information of the user - agent for the proxy and/or realm of the resource being requested. - - Proxy-Authorization = "Proxy-Authorization" ":" credentials - - The HTTP access authentication process is described in "HTTP - Authentication: Basic and Digest Access Authentication" [43] . Unlike - Authorization, the Proxy-Authorization header field applies only to - the next outbound proxy that demanded authentication using the Proxy- - Authenticate field. When multiple proxies are used in a chain, the - - - -Fielding, et al. Standards Track [Page 137] - -RFC 2616 HTTP/1.1 June 1999 - - - Proxy-Authorization header field is consumed by the first outbound - proxy that was expecting to receive credentials. A proxy MAY relay - the credentials from the client request to the next proxy if that is - the mechanism by which the proxies cooperatively authenticate a given - request. - -14.35 Range - -14.35.1 Byte Ranges - - Since all HTTP entities are represented in HTTP messages as sequences - of bytes, the concept of a byte range is meaningful for any HTTP - entity. (However, not all clients and servers need to support byte- - range operations.) - - Byte range specifications in HTTP apply to the sequence of bytes in - the entity-body (not necessarily the same as the message-body). - - A byte range operation MAY specify a single range of bytes, or a set - of ranges within a single entity. - - ranges-specifier = byte-ranges-specifier - byte-ranges-specifier = bytes-unit "=" byte-range-set - byte-range-set = 1#( byte-range-spec | suffix-byte-range-spec ) - byte-range-spec = first-byte-pos "-" [last-byte-pos] - first-byte-pos = 1*DIGIT - last-byte-pos = 1*DIGIT - - The first-byte-pos value in a byte-range-spec gives the byte-offset - of the first byte in a range. The last-byte-pos value gives the - byte-offset of the last byte in the range; that is, the byte - positions specified are inclusive. Byte offsets start at zero. - - If the last-byte-pos value is present, it MUST be greater than or - equal to the first-byte-pos in that byte-range-spec, or the byte- - range-spec is syntactically invalid. The recipient of a byte-range- - set that includes one or more syntactically invalid byte-range-spec - values MUST ignore the header field that includes that byte-range- - set. - - If the last-byte-pos value is absent, or if the value is greater than - or equal to the current length of the entity-body, last-byte-pos is - taken to be equal to one less than the current length of the entity- - body in bytes. - - By its choice of last-byte-pos, a client can limit the number of - bytes retrieved without knowing the size of the entity. - - - - -Fielding, et al. Standards Track [Page 138] - -RFC 2616 HTTP/1.1 June 1999 - - - suffix-byte-range-spec = "-" suffix-length - suffix-length = 1*DIGIT - - A suffix-byte-range-spec is used to specify the suffix of the - entity-body, of a length given by the suffix-length value. (That is, - this form specifies the last N bytes of an entity-body.) If the - entity is shorter than the specified suffix-length, the entire - entity-body is used. - - If a syntactically valid byte-range-set includes at least one byte- - range-spec whose first-byte-pos is less than the current length of - the entity-body, or at least one suffix-byte-range-spec with a non- - zero suffix-length, then the byte-range-set is satisfiable. - Otherwise, the byte-range-set is unsatisfiable. If the byte-range-set - is unsatisfiable, the server SHOULD return a response with a status - of 416 (Requested range not satisfiable). Otherwise, the server - SHOULD return a response with a status of 206 (Partial Content) - containing the satisfiable ranges of the entity-body. - - Examples of byte-ranges-specifier values (assuming an entity-body of - length 10000): - - - The first 500 bytes (byte offsets 0-499, inclusive): bytes=0- - 499 - - - The second 500 bytes (byte offsets 500-999, inclusive): - bytes=500-999 - - - The final 500 bytes (byte offsets 9500-9999, inclusive): - bytes=-500 - - - Or bytes=9500- - - - The first and last bytes only (bytes 0 and 9999): bytes=0-0,-1 - - - Several legal but not canonical specifications of the second 500 - bytes (byte offsets 500-999, inclusive): - bytes=500-600,601-999 - bytes=500-700,601-999 - -14.35.2 Range Retrieval Requests - - HTTP retrieval requests using conditional or unconditional GET - methods MAY request one or more sub-ranges of the entity, instead of - the entire entity, using the Range request header, which applies to - the entity returned as the result of the request: - - Range = "Range" ":" ranges-specifier - - - -Fielding, et al. Standards Track [Page 139] - -RFC 2616 HTTP/1.1 June 1999 - - - A server MAY ignore the Range header. However, HTTP/1.1 origin - servers and intermediate caches ought to support byte ranges when - possible, since Range supports efficient recovery from partially - failed transfers, and supports efficient partial retrieval of large - entities. - - If the server supports the Range header and the specified range or - ranges are appropriate for the entity: - - - The presence of a Range header in an unconditional GET modifies - what is returned if the GET is otherwise successful. In other - words, the response carries a status code of 206 (Partial - Content) instead of 200 (OK). - - - The presence of a Range header in a conditional GET (a request - using one or both of If-Modified-Since and If-None-Match, or - one or both of If-Unmodified-Since and If-Match) modifies what - is returned if the GET is otherwise successful and the - condition is true. It does not affect the 304 (Not Modified) - response returned if the conditional is false. - - In some cases, it might be more appropriate to use the If-Range - header (see section 14.27) in addition to the Range header. - - If a proxy that supports ranges receives a Range request, forwards - the request to an inbound server, and receives an entire entity in - reply, it SHOULD only return the requested range to its client. It - SHOULD store the entire received response in its cache if that is - consistent with its cache allocation policies. - -14.36 Referer - - The Referer[sic] request-header field allows the client to specify, - for the server's benefit, the address (URI) of the resource from - which the Request-URI was obtained (the "referrer", although the - header field is misspelled.) The Referer request-header allows a - server to generate lists of back-links to resources for interest, - logging, optimized caching, etc. It also allows obsolete or mistyped - links to be traced for maintenance. The Referer field MUST NOT be - sent if the Request-URI was obtained from a source that does not have - its own URI, such as input from the user keyboard. - - Referer = "Referer" ":" ( absoluteURI | relativeURI ) - - Example: - - Referer: http://www.w3.org/hypertext/DataSources/Overview.html - - - - -Fielding, et al. Standards Track [Page 140] - -RFC 2616 HTTP/1.1 June 1999 - - - If the field value is a relative URI, it SHOULD be interpreted - relative to the Request-URI. The URI MUST NOT include a fragment. See - section 15.1.3 for security considerations. - -14.37 Retry-After - - The Retry-After response-header field can be used with a 503 (Service - Unavailable) response to indicate how long the service is expected to - be unavailable to the requesting client. This field MAY also be used - with any 3xx (Redirection) response to indicate the minimum time the - user-agent is asked wait before issuing the redirected request. The - value of this field can be either an HTTP-date or an integer number - of seconds (in decimal) after the time of the response. - - Retry-After = "Retry-After" ":" ( HTTP-date | delta-seconds ) - - Two examples of its use are - - Retry-After: Fri, 31 Dec 1999 23:59:59 GMT - Retry-After: 120 - - In the latter example, the delay is 2 minutes. - -14.38 Server - - The Server response-header field contains information about the - software used by the origin server to handle the request. The field - can contain multiple product tokens (section 3.8) and comments - identifying the server and any significant subproducts. The product - tokens are listed in order of their significance for identifying the - application. - - Server = "Server" ":" 1*( product | comment ) - - Example: - - Server: CERN/3.0 libwww/2.17 - - If the response is being forwarded through a proxy, the proxy - application MUST NOT modify the Server response-header. Instead, it - SHOULD include a Via field (as described in section 14.45). - [[ Actually, it MUST ]] - - Note: Revealing the specific software version of the server might - allow the server machine to become more vulnerable to attacks - against software that is known to contain security holes. Server - implementors are encouraged to make this field a configurable - option. - - - - -Fielding, et al. Standards Track [Page 141] - -RFC 2616 HTTP/1.1 June 1999 - - -14.39 TE - - The TE request-header field indicates what extension transfer-codings - it is willing to accept in the response and whether or not it is - willing to accept trailer fields in a chunked transfer-coding. Its - value may consist of the keyword "trailers" and/or a comma-separated - list of extension transfer-coding names with optional accept - parameters (as described in section 3.6). - - TE = "TE" ":" #( t-codings ) - t-codings = "trailers" | ( transfer-extension [ accept-params ] ) - - The presence of the keyword "trailers" indicates that the client is - willing to accept trailer fields in a chunked transfer-coding, as - defined in section 3.6.1. This keyword is reserved for use with - transfer-coding values even though it does not itself represent a - transfer-coding. - - Examples of its use are: - - TE: deflate - TE: - TE: trailers, deflate;q=0.5 - - The TE header field only applies to the immediate connection. - Therefore, the keyword MUST be supplied within a Connection header - field (section 14.10) whenever TE is present in an HTTP/1.1 message. - - A server tests whether a transfer-coding is acceptable, according to - a TE field, using these rules: - - 1. The "chunked" transfer-coding is always acceptable. If the - keyword "trailers" is listed, the client indicates that it is - willing to accept trailer fields in the chunked response on - behalf of itself and any downstream clients. The implication is - that, if given, the client is stating that either all - downstream clients are willing to accept trailer fields in the - forwarded response, or that it will attempt to buffer the - response on behalf of downstream recipients. - - Note: HTTP/1.1 does not define any means to limit the size of a - chunked response such that a client can be assured of buffering - the entire response. - - 2. If the transfer-coding being tested is one of the transfer- - codings listed in the TE field, then it is acceptable unless it - is accompanied by a qvalue of 0. (As defined in section 3.9, a - qvalue of 0 means "not acceptable.") - - - -Fielding, et al. Standards Track [Page 142] - -RFC 2616 HTTP/1.1 June 1999 - - - 3. If multiple transfer-codings are acceptable, then the - acceptable transfer-coding with the highest non-zero qvalue is - preferred. The "chunked" transfer-coding always has a qvalue - of 1. - - If the TE field-value is empty or if no TE field is present, the only - transfer-coding is "chunked". A message with no transfer-coding is - always acceptable. - -14.40 Trailer - - The Trailer general field value indicates that the given set of - header fields is present in the trailer of a message encoded with - chunked transfer-coding. - - Trailer = "Trailer" ":" 1#field-name - - An HTTP/1.1 message SHOULD include a Trailer header field in a - message using chunked transfer-coding with a non-empty trailer. Doing - so allows the recipient to know which header fields to expect in the - trailer. - - If no Trailer header field is present, the trailer SHOULD NOT include - any header fields. See section 3.6.1 for restrictions on the use of - trailer fields in a "chunked" transfer-coding. - - Message header fields listed in the Trailer header field MUST NOT - include the following header fields: - - . Transfer-Encoding - - . Content-Length - - . Trailer - -14.41 Transfer-Encoding - - The Transfer-Encoding general-header field indicates what (if any) - type of transformation has been applied to the message body in order - to safely transfer it between the sender and the recipient. This - differs from the content-coding in that the transfer-coding is a - property of the message, not of the entity. - - Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer-coding - - Transfer-codings are defined in section 3.6. An example is: - - Transfer-Encoding: chunked - - - -Fielding, et al. Standards Track [Page 143] - -RFC 2616 HTTP/1.1 June 1999 - - - If multiple encodings have been applied to an entity, the transfer- - codings MUST be listed in the order in which they were applied. - Additional information about the encoding parameters MAY be provided - by other entity-header fields not defined by this specification. - - Many older HTTP/1.0 applications do not understand the Transfer- - Encoding header. - -14.42 Upgrade - - The Upgrade general-header allows the client to specify what - additional communication protocols it supports and would like to use - if the server finds it appropriate to switch protocols. The server - MUST use the Upgrade header field within a 101 (Switching Protocols) - response to indicate which protocol(s) are being switched. - - Upgrade = "Upgrade" ":" 1#product - - For example, - - Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11 - - The Upgrade header field is intended to provide a simple mechanism - for transition from HTTP/1.1 to some other, incompatible protocol. It - does so by allowing the client to advertise its desire to use another - protocol, such as a later version of HTTP with a higher major version - number, even though the current request has been made using HTTP/1.1. - This eases the difficult transition between incompatible protocols by - allowing the client to initiate a request in the more commonly - supported protocol while indicating to the server that it would like - to use a "better" protocol if available (where "better" is determined - by the server, possibly according to the nature of the method and/or - resource being requested). - - The Upgrade header field only applies to switching application-layer - protocols upon the existing transport-layer connection. Upgrade - cannot be used to insist on a protocol change; its acceptance and use - by the server is optional. The capabilities and nature of the - application-layer communication after the protocol change is entirely - dependent upon the new protocol chosen, although the first action - after changing the protocol MUST be a response to the initial HTTP - request containing the Upgrade header field. - - The Upgrade header field only applies to the immediate connection. - Therefore, the upgrade keyword MUST be supplied within a Connection - header field (section 14.10) whenever Upgrade is present in an - HTTP/1.1 message. - - - - -Fielding, et al. Standards Track [Page 144] - -RFC 2616 HTTP/1.1 June 1999 - - - The Upgrade header field cannot be used to indicate a switch to a - protocol on a different connection. For that purpose, it is more - appropriate to use a 301, 302, 303, or 305 redirection response. - - This specification only defines the protocol name "HTTP" for use by - the family of Hypertext Transfer Protocols, as defined by the HTTP - version rules of section 3.1 and future updates to this - specification. Any token can be used as a protocol name; however, it - will only be useful if both the client and server associate the name - with the same protocol. - -14.43 User-Agent - - The User-Agent request-header field contains information about the - user agent originating the request. This is for statistical purposes, - the tracing of protocol violations, and automated recognition of user - agents for the sake of tailoring responses to avoid particular user - agent limitations. User agents SHOULD include this field with - requests. The field can contain multiple product tokens (section 3.8) - and comments identifying the agent and any subproducts which form a - significant part of the user agent. By convention, the product tokens - are listed in order of their significance for identifying the - application. - - User-Agent = "User-Agent" ":" 1*( product | comment ) - - Example: - - User-Agent: CERN-LineMode/2.15 libwww/2.17b3 - -14.44 Vary - - The Vary field value indicates the set of request-header fields that - fully determines, while the response is fresh, whether a cache is - permitted to use the response to reply to a subsequent request - without revalidation. For uncacheable or stale responses, the Vary - field value advises the user agent about the criteria that were used - to select the representation. A Vary field value of "*" implies that - a cache cannot determine from the request headers of a subsequent - request whether this response is the appropriate representation. See - section 13.6 for use of the Vary header field by caches. - - Vary = "Vary" ":" ( "*" | 1#field-name ) - - An HTTP/1.1 server SHOULD include a Vary header field with any - cacheable response that is subject to server-driven negotiation. - Doing so allows a cache to properly interpret future requests on that - resource and informs the user agent about the presence of negotiation - - - -Fielding, et al. Standards Track [Page 145] - -RFC 2616 HTTP/1.1 June 1999 - - - on that resource. A server MAY include a Vary header field with a - non-cacheable response that is subject to server-driven negotiation, - since this might provide the user agent with useful information about - the dimensions over which the response varies at the time of the - response. - - A Vary field value consisting of a list of field-names signals that - the representation selected for the response is based on a selection - algorithm which considers ONLY the listed request-header field values - in selecting the most appropriate representation. A cache MAY assume - that the same selection will be made for future requests with the - same values for the listed field names, for the duration of time for - which the response is fresh. - - The field-names given are not limited to the set of standard - request-header fields defined by this specification. Field names are - case-insensitive. - - A Vary field value of "*" signals that unspecified parameters not - limited to the request-headers (e.g., the network address of the - client), play a role in the selection of the response representation. - The "*" value MUST NOT be generated by a proxy server; it may only be - generated by an origin server. - -14.45 Via - - The Via general-header field MUST be used by gateways and proxies to - indicate the intermediate protocols and recipients between the user - agent and the server on requests, and between the origin server and - the client on responses. It is analogous to the "Received" field of - RFC 822 [9] and is intended to be used for tracking message forwards, - avoiding request loops, and identifying the protocol capabilities of - all senders along the request/response chain. - - Via = "Via" ":" 1#( received-protocol received-by [ comment ] ) - received-protocol = [ protocol-name "/" ] protocol-version - protocol-name = token - protocol-version = token - received-by = ( host [ ":" port ] ) | pseudonym - pseudonym = token - - The received-protocol indicates the protocol version of the message - received by the server or client along each segment of the - request/response chain. The received-protocol version is appended to - the Via field value when the message is forwarded so that information - about the protocol capabilities of upstream applications remains - visible to all recipients. - - - - -Fielding, et al. Standards Track [Page 146] - -RFC 2616 HTTP/1.1 June 1999 - - - The protocol-name is optional if and only if it would be "HTTP". The - received-by field is normally the host and optional port number of a - recipient server or client that subsequently forwarded the message. - However, if the real host is considered to be sensitive information, - it MAY be replaced by a pseudonym. If the port is not given, it MAY - be assumed to be the default port of the received-protocol. - - Multiple Via field values represents each proxy or gateway that has - forwarded the message. Each recipient MUST append its information - such that the end result is ordered according to the sequence of - forwarding applications. - - Comments MAY be used in the Via header field to identify the software - of the recipient proxy or gateway, analogous to the User-Agent and - Server header fields. However, all comments in the Via field are - optional and MAY be removed by any recipient prior to forwarding the - message. - - For example, a request message could be sent from an HTTP/1.0 user - agent to an internal proxy code-named "fred", which uses HTTP/1.1 to - forward the request to a public proxy at nowhere.com, which completes - the request by forwarding it to the origin server at www.ics.uci.edu. - The request received by www.ics.uci.edu would then have the following - Via header field: - - Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1) - - Proxies and gateways used as a portal through a network firewall - SHOULD NOT, by default, forward the names and ports of hosts within - the firewall region. This information SHOULD only be propagated if - explicitly enabled. If not enabled, the received-by host of any host - behind the firewall SHOULD be replaced by an appropriate pseudonym - for that host. - - For organizations that have strong privacy requirements for hiding - internal structures, a proxy MAY combine an ordered subsequence of - Via header field entries with identical received-protocol values into - a single such entry. For example, - - Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy - - could be collapsed to - - Via: 1.0 ricky, 1.1 mertz, 1.0 lucy - - - - - - - -Fielding, et al. Standards Track [Page 147] - -RFC 2616 HTTP/1.1 June 1999 - - - Applications SHOULD NOT combine multiple entries unless they are all - under the same organizational control and the hosts have already been - replaced by pseudonyms. Applications MUST NOT combine entries which - have different received-protocol values. - -14.46 Warning - - The Warning general-header field is used to carry additional - information about the status or transformation of a message which - might not be reflected in the message. This information is typically - used to warn about a possible lack of semantic transparency from - caching operations or transformations applied to the entity body of - the message. - - Warning headers are sent with responses using: - - Warning = "Warning" ":" 1#warning-value - - warning-value = warn-code SP warn-agent SP warn-text - [SP warn-date] - - warn-code = 3DIGIT - warn-agent = ( host [ ":" port ] ) | pseudonym - ; the name or pseudonym of the server adding - ; the Warning header, for use in debugging - warn-text = quoted-string - warn-date = <"> HTTP-date <"> - - A response MAY carry more than one Warning header. - - The warn-text SHOULD be in a natural language and character set that - is most likely to be intelligible to the human user receiving the - response. This decision MAY be based on any available knowledge, such - as the location of the cache or user, the Accept-Language field in a - request, the Content-Language field in a response, etc. The default - language is English and the default character set is ISO-8859-1. - - If a character set other than ISO-8859-1 is used, it MUST be encoded - in the warn-text using the method described in RFC 2047 [14]. - - Warning headers can in general be applied to any message, however - some specific warn-codes are specific to caches and can only be - applied to response messages. New Warning headers SHOULD be added - after any existing Warning headers. A cache MUST NOT delete any - Warning header that it received with a message. However, if a cache - successfully validates a cache entry, it SHOULD remove any Warning - headers previously attached to that entry except as specified for - - - - -Fielding, et al. Standards Track [Page 148] - -RFC 2616 HTTP/1.1 June 1999 - - - specific Warning codes. It MUST then add any Warning headers received - in the validating response. In other words, Warning headers are those - that would be attached to the most recent relevant response. - - When multiple Warning headers are attached to a response, the user - agent ought to inform the user of as many of them as possible, in the - order that they appear in the response. If it is not possible to - inform the user of all of the warnings, the user agent SHOULD follow - these heuristics: - - - Warnings that appear early in the response take priority over - those appearing later in the response. - - - Warnings in the user's preferred character set take priority - over warnings in other character sets but with identical warn- - codes and warn-agents. - - Systems that generate multiple Warning headers SHOULD order them with - this user agent behavior in mind. - - Requirements for the behavior of caches with respect to Warnings are - stated in section 13.1.2. - - This is a list of the currently-defined warn-codes, each with a - recommended warn-text in English, and a description of its meaning. - - 110 Response is stale - MUST be included whenever the returned response is stale. - - 111 Revalidation failed - MUST be included if a cache returns a stale response because an - attempt to revalidate the response failed, due to an inability to - reach the server. - - 112 Disconnected operation - SHOULD be included if the cache is intentionally disconnected from - the rest of the network for a period of time. - - 113 Heuristic expiration - MUST be included if the cache heuristically chose a freshness - lifetime greater than 24 hours and the response's age is greater - than 24 hours. - - 199 Miscellaneous warning - The warning text MAY include arbitrary information to be presented - to a human user, or logged. A system receiving this warning MUST - NOT take any automated action, besides presenting the warning to - the user. - - - -Fielding, et al. Standards Track [Page 149] - -RFC 2616 HTTP/1.1 June 1999 - - - 214 Transformation applied - MUST be added by an intermediate cache or proxy if it applies any - transformation changing the content-coding (as specified in the - Content-Encoding header) or media-type (as specified in the - Content-Type header) of the response, or the entity-body of the - response, unless this Warning code already appears in the response. - - 299 Miscellaneous persistent warning - The warning text MAY include arbitrary information to be presented - to a human user, or logged. A system receiving this warning MUST - NOT take any automated action. - - If an implementation sends a message with one or more Warning headers - whose version is HTTP/1.0 or lower, then the sender MUST include in - each warning-value a warn-date that matches the date in the response. - - If an implementation receives a message with a warning-value that - includes a warn-date, and that warn-date is different from the Date - value in the response, then that warning-value MUST be deleted from - the message before storing, forwarding, or using it. (This prevents - bad consequences of naive caching of Warning header fields.) If all - of the warning-values are deleted for this reason, the Warning header - MUST be deleted as well. - -14.47 WWW-Authenticate - - The WWW-Authenticate response-header field MUST be included in 401 - (Unauthorized) response messages. The field value consists of at - least one challenge that indicates the authentication scheme(s) and - parameters applicable to the Request-URI. - - WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge - - The HTTP access authentication process is described in "HTTP - Authentication: Basic and Digest Access Authentication" [43]. User - agents are advised to take special care in parsing the WWW- - Authenticate field value as it might contain more than one challenge, - or if more than one WWW-Authenticate header field is provided, the - contents of a challenge itself can contain a comma-separated list of - authentication parameters. - -15 Security Considerations - - This section is meant to inform application developers, information - providers, and users of the security limitations in HTTP/1.1 as - described by this document. The discussion does not include - definitive solutions to the problems revealed, though it does make - some suggestions for reducing security risks. - - - -Fielding, et al. Standards Track [Page 150] - -RFC 2616 HTTP/1.1 June 1999 - - -15.1 Personal Information - - HTTP clients are often privy to large amounts of personal information - (e.g. the user's name, location, mail address, passwords, encryption - keys, etc.), and SHOULD be very careful to prevent unintentional - leakage of this information via the HTTP protocol to other sources. - We very strongly recommend that a convenient interface be provided - for the user to control dissemination of such information, and that - designers and implementors be particularly careful in this area. - History shows that errors in this area often create serious security - and/or privacy problems and generate highly adverse publicity for the - implementor's company. - -15.1.1 Abuse of Server Log Information - - A server is in the position to save personal data about a user's - requests which might identify their reading patterns or subjects of - interest. This information is clearly confidential in nature and its - handling can be constrained by law in certain countries. People using - the HTTP protocol to provide data are responsible for ensuring that - such material is not distributed without the permission of any - individuals that are identifiable by the published results. - -15.1.2 Transfer of Sensitive Information - - Like any generic data transfer protocol, HTTP cannot regulate the - content of the data that is transferred, nor is there any a priori - method of determining the sensitivity of any particular piece of - information within the context of any given request. Therefore, - applications SHOULD supply as much control over this information as - possible to the provider of that information. Four header fields are - worth special mention in this context: Server, Via, Referer and From. - - Revealing the specific software version of the server might allow the - server machine to become more vulnerable to attacks against software - that is known to contain security holes. Implementors SHOULD make the - Server header field a configurable option. - - Proxies which serve as a portal through a network firewall SHOULD - take special precautions regarding the transfer of header information - that identifies the hosts behind the firewall. In particular, they - SHOULD remove, or replace with sanitized versions, any Via fields - generated behind the firewall. - - The Referer header allows reading patterns to be studied and reverse - links drawn. Although it can be very useful, its power can be abused - if user details are not separated from the information contained in - - - - -Fielding, et al. Standards Track [Page 151] - -RFC 2616 HTTP/1.1 June 1999 - - - the Referer. Even when the personal information has been removed, the - Referer header might indicate a private document's URI whose - publication would be inappropriate. - - The information sent in the From field might conflict with the user's - privacy interests or their site's security policy, and hence it - SHOULD NOT be transmitted without the user being able to disable, - enable, and modify the contents of the field. The user MUST be able - to set the contents of this field within a user preference or - application defaults configuration. - - We suggest, though do not require, that a convenient toggle interface - be provided for the user to enable or disable the sending of From and - Referer information. - - The User-Agent (section 14.43) or Server (section 14.38) header - fields can sometimes be used to determine that a specific client or - server have a particular security hole which might be exploited. - Unfortunately, this same information is often used for other valuable - purposes for which HTTP currently has no better mechanism. - -15.1.3 Encoding Sensitive Information in URI's - - Because the source of a link might be private information or might - reveal an otherwise private information source, it is strongly - recommended that the user be able to select whether or not the - Referer field is sent. For example, a browser client could have a - toggle switch for browsing openly/anonymously, which would - respectively enable/disable the sending of Referer and From - information. - - Clients SHOULD NOT include a Referer header field in a (non-secure) - HTTP request if the referring page was transferred with a secure - protocol. - - Authors of services which use the HTTP protocol SHOULD NOT use GET - based forms for the submission of sensitive data, because this will - cause this data to be encoded in the Request-URI. Many existing - servers, proxies, and user agents will log the request URI in some - place where it might be visible to third parties. Servers can use - POST-based form submission instead - -15.1.4 Privacy Issues Connected to Accept Headers - - Accept request-headers can reveal information about the user to all - servers which are accessed. The Accept-Language header in particular - can reveal information the user would consider to be of a private - nature, because the understanding of particular languages is often - - - -Fielding, et al. Standards Track [Page 152] - -RFC 2616 HTTP/1.1 June 1999 - - - strongly correlated to the membership of a particular ethnic group. - User agents which offer the option to configure the contents of an - Accept-Language header to be sent in every request are strongly - encouraged to let the configuration process include a message which - makes the user aware of the loss of privacy involved. - - An approach that limits the loss of privacy would be for a user agent - to omit the sending of Accept-Language headers by default, and to ask - the user whether or not to start sending Accept-Language headers to a - server if it detects, by looking for any Vary response-header fields - generated by the server, that such sending could improve the quality - of service. - - Elaborate user-customized accept header fields sent in every request, - in particular if these include quality values, can be used by servers - as relatively reliable and long-lived user identifiers. Such user - identifiers would allow content providers to do click-trail tracking, - and would allow collaborating content providers to match cross-server - click-trails or form submissions of individual users. Note that for - many users not behind a proxy, the network address of the host - running the user agent will also serve as a long-lived user - identifier. In environments where proxies are used to enhance - privacy, user agents ought to be conservative in offering accept - header configuration options to end users. As an extreme privacy - measure, proxies could filter the accept headers in relayed requests. - General purpose user agents which provide a high degree of header - configurability SHOULD warn users about the loss of privacy which can - be involved. - -15.2 Attacks Based On File and Path Names - - Implementations of HTTP origin servers SHOULD be careful to restrict - the documents returned by HTTP requests to be only those that were - intended by the server administrators. If an HTTP server translates - HTTP URIs directly into file system calls, the server MUST take - special care not to serve files that were not intended to be - delivered to HTTP clients. For example, UNIX, Microsoft Windows, and - other operating systems use ".." as a path component to indicate a - directory level above the current one. On such a system, an HTTP - server MUST disallow any such construct in the Request-URI if it - would otherwise allow access to a resource outside those intended to - be accessible via the HTTP server. Similarly, files intended for - reference only internally to the server (such as access control - files, configuration files, and script code) MUST be protected from - inappropriate retrieval, since they might contain sensitive - information. Experience has shown that minor bugs in such HTTP server - implementations have turned into security risks. - - - - -Fielding, et al. Standards Track [Page 153] - -RFC 2616 HTTP/1.1 June 1999 - - -15.3 DNS Spoofing - - Clients using HTTP rely heavily on the Domain Name Service, and are - thus generally prone to security attacks based on the deliberate - mis-association of IP addresses and DNS names. Clients need to be - cautious in assuming the continuing validity of an IP number/DNS name - association. - - In particular, HTTP clients SHOULD rely on their name resolver for - confirmation of an IP number/DNS name association, rather than - caching the result of previous host name lookups. Many platforms - already can cache host name lookups locally when appropriate, and - they SHOULD be configured to do so. It is proper for these lookups to - be cached, however, only when the TTL (Time To Live) information - reported by the name server makes it likely that the cached - information will remain useful. - - If HTTP clients cache the results of host name lookups in order to - achieve a performance improvement, they MUST observe the TTL - information reported by DNS. - - If HTTP clients do not observe this rule, they could be spoofed when - a previously-accessed server's IP address changes. As network - renumbering is expected to become increasingly common [24], the - possibility of this form of attack will grow. Observing this - requirement thus reduces this potential security vulnerability. - - This requirement also improves the load-balancing behavior of clients - for replicated servers using the same DNS name and reduces the - likelihood of a user's experiencing failure in accessing sites which - use that strategy. - -15.4 Location Headers and Spoofing - - If a single server supports multiple organizations that do not trust - one another, then it MUST check the values of Location and Content- - Location headers in responses that are generated under control of - said organizations to make sure that they do not attempt to - invalidate resources over which they have no authority. - -15.5 Content-Disposition Issues - - RFC 1806 [35], from which the often implemented Content-Disposition - (see section 19.5.1) header in HTTP is derived, has a number of very - serious security considerations. Content-Disposition is not part of - the HTTP standard, but since it is widely implemented, we are - documenting its use and risks for implementors. See RFC 2183 [49] - (which updates RFC 1806) for details. - - - -Fielding, et al. Standards Track [Page 154] - -RFC 2616 HTTP/1.1 June 1999 - - -15.6 Authentication Credentials and Idle Clients - - Existing HTTP clients and user agents typically retain authentication - information indefinitely. HTTP/1.1. does not provide a method for a - server to direct clients to discard these cached credentials. This is - a significant defect that requires further extensions to HTTP. - Circumstances under which credential caching can interfere with the - application's security model include but are not limited to: - - - Clients which have been idle for an extended period following - which the server might wish to cause the client to reprompt the - user for credentials. - - - Applications which include a session termination indication - (such as a `logout' or `commit' button on a page) after which - the server side of the application `knows' that there is no - further reason for the client to retain the credentials. - - This is currently under separate study. There are a number of work- - arounds to parts of this problem, and we encourage the use of - password protection in screen savers, idle time-outs, and other - methods which mitigate the security problems inherent in this - problem. In particular, user agents which cache credentials are - encouraged to provide a readily accessible mechanism for discarding - cached credentials under user control. - -15.7 Proxies and Caching - - By their very nature, HTTP proxies are men-in-the-middle, and - represent an opportunity for man-in-the-middle attacks. Compromise of - the systems on which the proxies run can result in serious security - and privacy problems. Proxies have access to security-related - information, personal information about individual users and - organizations, and proprietary information belonging to users and - content providers. A compromised proxy, or a proxy implemented or - configured without regard to security and privacy considerations, - might be used in the commission of a wide range of potential attacks. - - Proxy operators should protect the systems on which proxies run as - they would protect any system that contains or transports sensitive - information. In particular, log information gathered at proxies often - contains highly sensitive personal information, and/or information - about organizations. Log information should be carefully guarded, and - appropriate guidelines for use developed and followed. (Section - 15.1.1). - - - - - - -Fielding, et al. Standards Track [Page 155] - -RFC 2616 HTTP/1.1 June 1999 - - - Caching proxies provide additional potential vulnerabilities, since - the contents of the cache represent an attractive target for - malicious exploitation. Because cache contents persist after an HTTP - request is complete, an attack on the cache can reveal information - long after a user believes that the information has been removed from - the network. Therefore, cache contents should be protected as - sensitive information. - - Proxy implementors should consider the privacy and security - implications of their design and coding decisions, and of the - configuration options they provide to proxy operators (especially the - default configuration). - - Users of a proxy need to be aware that they are no trustworthier than - the people who run the proxy; HTTP itself cannot solve this problem. - - The judicious use of cryptography, when appropriate, may suffice to - protect against a broad range of security and privacy attacks. Such - cryptography is beyond the scope of the HTTP/1.1 specification. - -15.7.1 Denial of Service Attacks on Proxies - - They exist. They are hard to defend against. Research continues. - Beware. - -16 Acknowledgments - - This specification makes heavy use of the augmented BNF and generic - constructs defined by David H. Crocker for RFC 822 [9]. Similarly, it - reuses many of the definitions provided by Nathaniel Borenstein and - Ned Freed for MIME [7]. We hope that their inclusion in this - specification will help reduce past confusion over the relationship - between HTTP and Internet mail message formats. - - The HTTP protocol has evolved considerably over the years. It has - benefited from a large and active developer community--the many - people who have participated on the www-talk mailing list--and it is - that community which has been most responsible for the success of - HTTP and of the World-Wide Web in general. Marc Andreessen, Robert - Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jean-Francois - Groff, Phillip M. Hallam-Baker, Hakon W. Lie, Ari Luotonen, Rob - McCool, Lou Montulli, Dave Raggett, Tony Sanders, and Marc - VanHeyningen deserve special recognition for their efforts in - defining early aspects of the protocol. - - This document has benefited greatly from the comments of all those - participating in the HTTP-WG. In addition to those already mentioned, - the following individuals have contributed to this specification: - - - -Fielding, et al. Standards Track [Page 156] - -RFC 2616 HTTP/1.1 June 1999 - - - Gary Adams Ross Patterson - Harald Tveit Alvestrand Albert Lunde - Keith Ball John C. Mallery - Brian Behlendorf Jean-Philippe Martin-Flatin - Paul Burchard Mitra - Maurizio Codogno David Morris - Mike Cowlishaw Gavin Nicol - Roman Czyborra Bill Perry - Michael A. Dolan Jeffrey Perry - David J. Fiander Scott Powers - Alan Freier Owen Rees - Marc Hedlund Luigi Rizzo - Greg Herlihy David Robinson - Koen Holtman Marc Salomon - Alex Hopmann Rich Salz - Bob Jernigan Allan M. Schiffman - Shel Kaphan Jim Seidman - Rohit Khare Chuck Shotton - John Klensin Eric W. Sink - Martijn Koster Simon E. Spero - Alexei Kosut Richard N. Taylor - David M. Kristol Robert S. Thau - Daniel LaLiberte Bill (BearHeart) Weinman - Ben Laurie Francois Yergeau - Paul J. Leach Mary Ellen Zurko - Daniel DuBois Josh Cohen - - - Much of the content and presentation of the caching design is due to - suggestions and comments from individuals including: Shel Kaphan, - Paul Leach, Koen Holtman, David Morris, and Larry Masinter. - - Most of the specification of ranges is based on work originally done - by Ari Luotonen and John Franks, with additional input from Steve - Zilles. - - Thanks to the "cave men" of Palo Alto. You know who you are. - - Jim Gettys (the current editor of this document) wishes particularly - to thank Roy Fielding, the previous editor of this document, along - with John Klensin, Jeff Mogul, Paul Leach, Dave Kristol, Koen - Holtman, John Franks, Josh Cohen, Alex Hopmann, Scott Lawrence, and - Larry Masinter for their help. And thanks go particularly to Jeff - Mogul and Scott Lawrence for performing the "MUST/MAY/SHOULD" audit. - - - - - - - -Fielding, et al. Standards Track [Page 157] - -RFC 2616 HTTP/1.1 June 1999 - - - The Apache Group, Anselm Baird-Smith, author of Jigsaw, and Henrik - Frystyk implemented RFC 2068 early, and we wish to thank them for the - discovery of many of the problems that this document attempts to - rectify. - -17 References - - [1] Alvestrand, H., "Tags for the Identification of Languages", RFC - 1766, March 1995. - - [2] Anklesaria, F., McCahill, M., Lindner, P., Johnson, D., Torrey, - D. and B. Alberti, "The Internet Gopher Protocol (a distributed - document search and retrieval protocol)", RFC 1436, March 1993. - - [3] Berners-Lee, T., "Universal Resource Identifiers in WWW", RFC - 1630, June 1994. - - [4] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource - Locators (URL)", RFC 1738, December 1994. - - [5] Berners-Lee, T. and D. Connolly, "Hypertext Markup Language - - 2.0", RFC 1866, November 1995. - - [6] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext Transfer - Protocol -- HTTP/1.0", RFC 1945, May 1996. - - [7] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message Bodies", - RFC 2045, November 1996. - - [8] Braden, R., "Requirements for Internet Hosts -- Communication - Layers", STD 3, RFC 1123, October 1989. - - [9] Crocker, D., "Standard for The Format of ARPA Internet Text - Messages", STD 11, RFC 822, August 1982. - - [10] Davis, F., Kahle, B., Morris, H., Salem, J., Shen, T., Wang, R., - Sui, J., and M. Grinbaum, "WAIS Interface Protocol Prototype - Functional Specification," (v1.5), Thinking Machines - Corporation, April 1990. - - [11] Fielding, R., "Relative Uniform Resource Locators", RFC 1808, - June 1995. - - [12] Horton, M. and R. Adams, "Standard for Interchange of USENET - Messages", RFC 1036, December 1987. - - - - - -Fielding, et al. Standards Track [Page 158] - -RFC 2616 HTTP/1.1 June 1999 - - - [13] Kantor, B. and P. Lapsley, "Network News Transfer Protocol", RFC - 977, February 1986. - - [14] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part - Three: Message Header Extensions for Non-ASCII Text", RFC 2047, - November 1996. - - [15] Nebel, E. and L. Masinter, "Form-based File Upload in HTML", RFC - 1867, November 1995. - - [16] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821, - August 1982. - - [17] Postel, J., "Media Type Registration Procedure", RFC 1590, - November 1996. - -[[ Should be: ]] -[[ [17] Freed, N., Klensin, J., and Postel, J., "Multipurpose Internet ]] -[[ Mail Extensions (MIME) Part Four: "Registration Procedure", ]] -[[ RFC 2048, November 1996. ]] - - [18] Postel, J. and J. Reynolds, "File Transfer Protocol", STD 9, RFC - 959, October 1985. - - [19] Reynolds, J. and J. Postel, "Assigned Numbers", STD 2, RFC 1700, - October 1994. - - [20] Sollins, K. and L. Masinter, "Functional Requirements for - Uniform Resource Names", RFC 1737, December 1994. - - [21] US-ASCII. Coded Character Set - 7-Bit American Standard Code for - Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986. - - [22] ISO-8859. International Standard -- Information Processing -- - 8-bit Single-Byte Coded Graphic Character Sets -- - Part 1: Latin alphabet No. 1, ISO-8859-1:1987. - Part 2: Latin alphabet No. 2, ISO-8859-2, 1987. - Part 3: Latin alphabet No. 3, ISO-8859-3, 1988. - Part 4: Latin alphabet No. 4, ISO-8859-4, 1988. - Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988. - Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987. - Part 7: Latin/Greek alphabet, ISO-8859-7, 1987. - Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988. - Part 9: Latin alphabet No. 5, ISO-8859-9, 1990. - - [23] Meyers, J. and M. Rose, "The Content-MD5 Header Field", RFC - 1864, October 1995. - - [24] Carpenter, B. and Y. Rekhter, "Renumbering Needs Work", RFC - 1900, February 1996. - - [25] Deutsch, P., "GZIP file format specification version 4.3", RFC - 1952, May 1996. - - - -Fielding, et al. Standards Track [Page 159] - -RFC 2616 HTTP/1.1 June 1999 - - - [26] Venkata N. Padmanabhan, and Jeffrey C. Mogul. "Improving HTTP - Latency", Computer Networks and ISDN Systems, v. 28, pp. 25-35, - Dec. 1995. Slightly revised version of paper in Proc. 2nd - International WWW Conference '94: Mosaic and the Web, Oct. 1994, - which is available at - http://www.ncsa.uiuc.edu/SDG/IT94/Proceedings/DDay/mogul/HTTPLat - ency.html. - - [27] Joe Touch, John Heidemann, and Katia Obraczka. "Analysis of HTTP - Performance", <URL: http://www.isi.edu/touch/pubs/http-perf96/>, - ISI Research Report ISI/RR-98-463, (original report dated Aug. - 1996), USC/Information Sciences Institute, August 1998. - - [28] Mills, D., "Network Time Protocol (Version 3) Specification, - Implementation and Analysis", RFC 1305, March 1992. - - [29] Deutsch, P., "DEFLATE Compressed Data Format Specification - version 1.3", RFC 1951, May 1996. - - [30] S. Spero, "Analysis of HTTP Performance Problems," - http://sunsite.unc.edu/mdma-release/http-prob.html. - - [31] Deutsch, P. and J. Gailly, "ZLIB Compressed Data Format - Specification version 3.3", RFC 1950, May 1996. - - [32] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P., - Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP: - Digest Access Authentication", RFC 2069, January 1997. - - [33] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and T. - Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC - 2068, January 1997. - - [34] Bradner, S., "Key words for use in RFCs to Indicate Requirement - Levels", BCP 14, RFC 2119, March 1997. - - [35] Troost, R. and Dorner, S., "Communicating Presentation - Information in Internet Messages: The Content-Disposition - Header", RFC 1806, June 1995. - - [36] Mogul, J., Fielding, R., Gettys, J. and H. Frystyk, "Use and - Interpretation of HTTP Version Numbers", RFC 2145, May 1997. - [jg639] - - [37] Palme, J., "Common Internet Message Headers", RFC 2076, February - 1997. [jg640] - - - - - -Fielding, et al. Standards Track [Page 160] - -RFC 2616 HTTP/1.1 June 1999 - - - [38] Yergeau, F., "UTF-8, a transformation format of Unicode and - ISO-10646", RFC 2279, January 1998. [jg641] - - [39] Nielsen, H.F., Gettys, J., Baird-Smith, A., Prud'hommeaux, E., - Lie, H., and C. Lilley. "Network Performance Effects of - HTTP/1.1, CSS1, and PNG," Proceedings of ACM SIGCOMM '97, Cannes - France, September 1997.[jg642] - - [40] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part Two: Media Types", RFC 2046, November - 1996. [jg643] - - [41] Alvestrand, H., "IETF Policy on Character Sets and Languages", - BCP 18, RFC 2277, January 1998. [jg644] - - [42] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource - Identifiers (URI): Generic Syntax and Semantics", RFC 2396, - August 1998. [jg645] - - [43] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., - Leach, P., Luotonen, A., Sink, E. and L. Stewart, "HTTP - Authentication: Basic and Digest Access Authentication", RFC - 2617, June 1999. [jg646] - - [44] Luotonen, A., "Tunneling TCP based protocols through Web proxy - servers," Work in Progress. [jg647] - - [45] Palme, J. and A. Hopmann, "MIME E-mail Encapsulation of - Aggregate Documents, such as HTML (MHTML)", RFC 2110, March - 1997. - - [46] Bradner, S., "The Internet Standards Process -- Revision 3", BCP - 9, RFC 2026, October 1996. - - [47] Masinter, L., "Hyper Text Coffee Pot Control Protocol - (HTCPCP/1.0)", RFC 2324, 1 April 1998. - - [48] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part Five: Conformance Criteria and Examples", - RFC 2049, November 1996. - - [49] Troost, R., Dorner, S. and K. Moore, "Communicating Presentation - Information in Internet Messages: The Content-Disposition Header - Field", RFC 2183, August 1997. - - - - - - - -Fielding, et al. Standards Track [Page 161] - -RFC 2616 HTTP/1.1 June 1999 - - -18 Authors' Addresses - - Roy T. Fielding - Information and Computer Science - University of California, Irvine - Irvine, CA 92697-3425, USA - - Fax: +1 (949) 824-1715 - EMail: fielding@ics.uci.edu - - - James Gettys - World Wide Web Consortium - MIT Laboratory for Computer Science - 545 Technology Square - Cambridge, MA 02139, USA - - Fax: +1 (617) 258 8682 - EMail: jg@w3.org - - - Jeffrey C. Mogul - Western Research Laboratory - Compaq Computer Corporation - 250 University Avenue - Palo Alto, California, 94305, USA - - EMail: mogul@wrl.dec.com - - - Henrik Frystyk Nielsen - World Wide Web Consortium - MIT Laboratory for Computer Science - 545 Technology Square - Cambridge, MA 02139, USA - - Fax: +1 (617) 258 8682 - EMail: frystyk@w3.org - - - Larry Masinter - Xerox Corporation - 3333 Coyote Hill Road - Palo Alto, CA 94034, USA - - EMail: masinter@parc.xerox.com - - - - - -Fielding, et al. Standards Track [Page 162] - -RFC 2616 HTTP/1.1 June 1999 - - - Paul J. Leach - Microsoft Corporation - 1 Microsoft Way - Redmond, WA 98052, USA - - EMail: paulle@microsoft.com - - - Tim Berners-Lee - Director, World Wide Web Consortium - MIT Laboratory for Computer Science - 545 Technology Square - Cambridge, MA 02139, USA - - Fax: +1 (617) 258 8682 - EMail: timbl@w3.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Fielding, et al. Standards Track [Page 163] - -RFC 2616 HTTP/1.1 June 1999 - - -19 Appendices - -19.1 Internet Media Type message/http and application/http - - In addition to defining the HTTP/1.1 protocol, this document serves - as the specification for the Internet media type "message/http" and - "application/http". The message/http type can be used to enclose a - single HTTP request or response message, provided that it obeys the - MIME restrictions for all "message" types regarding line length and - encodings. The application/http type can be used to enclose a - pipeline of one or more HTTP request or response messages (not - intermixed). The following is to be registered with IANA [17]. - - Media Type name: message - Media subtype name: http - Required parameters: none - Optional parameters: version, msgtype - version: The HTTP-Version number of the enclosed message - (e.g., "1.1"). If not present, the version can be - determined from the first line of the body. - msgtype: The message type -- "request" or "response". If not - present, the type can be determined from the first - line of the body. - Encoding considerations: only "7bit", "8bit", or "binary" are - permitted - Security considerations: none - - Media Type name: application - Media subtype name: http - Required parameters: none - Optional parameters: version, msgtype - version: The HTTP-Version number of the enclosed messages - (e.g., "1.1"). If not present, the version can be - determined from the first line of the body. - msgtype: The message type -- "request" or "response". If not - present, the type can be determined from the first - line of the body. - Encoding considerations: HTTP messages enclosed by this type - are in "binary" format; use of an appropriate - Content-Transfer-Encoding is required when - transmitted via E-mail. - Security considerations: none - - - - - - - - - -Fielding, et al. Standards Track [Page 164] - -RFC 2616 HTTP/1.1 June 1999 - - -19.2 Internet Media Type multipart/byteranges - - When an HTTP 206 (Partial Content) response message includes the - content of multiple ranges (a response to a request for multiple - non-overlapping ranges), these are transmitted as a multipart - message-body. The media type for this purpose is called - "multipart/byteranges". - - The multipart/byteranges media type includes two or more parts, each - with its own Content-Type and Content-Range fields. The required - boundary parameter specifies the boundary string used to separate - each body-part. - - Media Type name: multipart - Media subtype name: byteranges - Required parameters: boundary - Optional parameters: none - Encoding considerations: only "7bit", "8bit", or "binary" are - permitted - Security considerations: none - - - For example: - - HTTP/1.1 206 Partial Content - Date: Wed, 15 Nov 1995 06:25:24 GMT - Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT - Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES - - --THIS_STRING_SEPARATES - Content-type: application/pdf - Content-range: bytes 500-999/8000 - - ...the first range... - --THIS_STRING_SEPARATES - Content-type: application/pdf - Content-range: bytes 7000-7999/8000 - - ...the second range - --THIS_STRING_SEPARATES-- - - Notes: - - 1) Additional CRLFs may precede the first boundary string in the - entity. - - - - - - -Fielding, et al. Standards Track [Page 165] - -RFC 2616 HTTP/1.1 June 1999 - - - 2) Although RFC 2046 [40] permits the boundary string to be - quoted, some existing implementations handle a quoted boundary - string incorrectly. - - 3) A number of browsers and servers were coded to an early draft - of the byteranges specification to use a media type of - multipart/x-byteranges, which is almost, but not quite - compatible with the version documented in HTTP/1.1. - -19.3 Tolerant Applications - - Although this document specifies the requirements for the generation - of HTTP/1.1 messages, not all applications will be correct in their - implementation. We therefore recommend that operational applications - be tolerant of deviations whenever those deviations can be - interpreted unambiguously. - - Clients SHOULD be tolerant in parsing the Status-Line and servers - tolerant when parsing the Request-Line. In particular, they SHOULD - accept any amount of SP or HT characters between fields, even though - only a single SP is required. - - The line terminator for message-header fields is the sequence CRLF. - However, we recommend that applications, when parsing such headers, - recognize a single LF as a line terminator and ignore the leading CR. - - The character set of an entity-body SHOULD be labeled as the lowest - common denominator of the character codes used within that body, with - the exception that not labeling the entity is preferred over labeling - the entity with the labels US-ASCII or ISO-8859-1. See section 3.7.1 - and 3.4.1. - - Additional rules for requirements on parsing and encoding of dates - and other potential problems with date encodings include: - - - HTTP/1.1 clients and caches SHOULD assume that an RFC-850 date - which appears to be more than 50 years in the future is in fact - in the past (this helps solve the "year 2000" problem). - - - An HTTP/1.1 implementation MAY internally represent a parsed - Expires date as earlier than the proper value, but MUST NOT - internally represent a parsed Expires date as later than the - proper value. - - - All expiration-related calculations MUST be done in GMT. The - local time zone MUST NOT influence the calculation or comparison - of an age or expiration time. - - - - -Fielding, et al. Standards Track [Page 166] - -RFC 2616 HTTP/1.1 June 1999 - - - - If an HTTP header incorrectly carries a date value with a time - zone other than GMT, it MUST be converted into GMT using the - most conservative possible conversion. - -19.4 Differences Between HTTP Entities and RFC 2045 Entities - - HTTP/1.1 uses many of the constructs defined for Internet Mail (RFC - 822 [9]) and the Multipurpose Internet Mail Extensions (MIME [7]) to - allow entities to be transmitted in an open variety of - representations and with extensible mechanisms. However, RFC 2045 - discusses mail, and HTTP has a few features that are different from - those described in RFC 2045. These differences were carefully chosen - to optimize performance over binary connections, to allow greater - freedom in the use of new media types, to make date comparisons - easier, and to acknowledge the practice of some early HTTP servers - and clients. - - This appendix describes specific areas where HTTP differs from RFC - 2045. Proxies and gateways to strict MIME environments SHOULD be - aware of these differences and provide the appropriate conversions - where necessary. Proxies and gateways from MIME environments to HTTP - also need to be aware of the differences because some conversions - might be required. - -19.4.1 MIME-Version - - HTTP is not a MIME-compliant protocol. However, HTTP/1.1 messages MAY - include a single MIME-Version general-header field to indicate what - version of the MIME protocol was used to construct the message. Use - of the MIME-Version header field indicates that the message is in - full compliance with the MIME protocol (as defined in RFC 2045[7]). - Proxies/gateways are responsible for ensuring full compliance (where - possible) when exporting HTTP messages to strict MIME environments. - - MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT - - MIME version "1.0" is the default for use in HTTP/1.1. However, - HTTP/1.1 message parsing and semantics are defined by this document - and not the MIME specification. - -19.4.2 Conversion to Canonical Form - - RFC 2045 [7] requires that an Internet mail entity be converted to - canonical form prior to being transferred, as described in section 4 - of RFC 2049 [48]. Section 3.7.1 of this document describes the forms - allowed for subtypes of the "text" media type when transmitted over - HTTP. RFC 2046 requires that content with a type of "text" represent - line breaks as CRLF and forbids the use of CR or LF outside of line - - - -Fielding, et al. Standards Track [Page 167] - -RFC 2616 HTTP/1.1 June 1999 - - - break sequences. HTTP allows CRLF, bare CR, and bare LF to indicate a - line break within text content when a message is transmitted over - HTTP. - - Where it is possible, a proxy or gateway from HTTP to a strict MIME - environment SHOULD translate all line breaks within the text media - types described in section 3.7.1 of this document to the RFC 2049 - canonical form of CRLF. Note, however, that this might be complicated - by the presence of a Content-Encoding and by the fact that HTTP - allows the use of some character sets which do not use octets 13 and - 10 to represent CR and LF, as is the case for some multi-byte - character sets. - - Implementors should note that conversion will break any cryptographic - checksums applied to the original content unless the original content - is already in canonical form. Therefore, the canonical form is - recommended for any content that uses such checksums in HTTP. - -19.4.3 Conversion of Date Formats - - HTTP/1.1 uses a restricted set of date formats (section 3.3.1) to - simplify the process of date comparison. Proxies and gateways from - other protocols SHOULD ensure that any Date header field present in a - message conforms to one of the HTTP/1.1 formats and rewrite the date - if necessary. - -19.4.4 Introduction of Content-Encoding - - RFC 2045 does not include any concept equivalent to HTTP/1.1's - Content-Encoding header field. Since this acts as a modifier on the - media type, proxies and gateways from HTTP to MIME-compliant - protocols MUST either change the value of the Content-Type header - field or decode the entity-body before forwarding the message. (Some - experimental applications of Content-Type for Internet mail have used - a media-type parameter of ";conversions=<content-coding>" to perform - a function equivalent to Content-Encoding. However, this parameter is - not part of RFC 2045.) - -19.4.5 No Content-Transfer-Encoding - - HTTP does not use the Content-Transfer-Encoding (CTE) field of RFC - 2045. Proxies and gateways from MIME-compliant protocols to HTTP MUST - remove any non-identity CTE ("quoted-printable" or "base64") encoding - prior to delivering the response message to an HTTP client. - - [[ "MUST remove any CTE encoding prior to delivering the response ]] - [[ message to an HTTP client." ]] - - Proxies and gateways from HTTP to MIME-compliant protocols are - responsible for ensuring that the message is in the correct format - and encoding for safe transport on that protocol, where "safe - - - -Fielding, et al. Standards Track [Page 168] - -RFC 2616 HTTP/1.1 June 1999 - - - transport" is defined by the limitations of the protocol being used. - Such a proxy or gateway SHOULD label the data with an appropriate - Content-Transfer-Encoding if doing so will improve the likelihood of - safe transport over the destination protocol. - -19.4.6 Introduction of Transfer-Encoding - - HTTP/1.1 introduces the Transfer-Encoding header field (section - 14.41). Proxies/gateways MUST remove any transfer-coding prior to - forwarding a message via a MIME-compliant protocol. - - A process for decoding the "chunked" transfer-coding (section 3.6) - can be represented in pseudo-code as: - - length := 0 - read chunk-size, chunk-extension (if any) and CRLF - while (chunk-size > 0) { - read chunk-data and CRLF - append chunk-data to entity-body - length := length + chunk-size - read chunk-size and CRLF - } - read entity-header - while (entity-header not empty) { - append entity-header to existing header fields - read entity-header - } - Content-Length := length - Remove "chunked" from Transfer-Encoding - -19.4.7 MHTML and Line Length Limitations - - HTTP implementations which share code with MHTML [45] implementations - need to be aware of MIME line length limitations. Since HTTP does not - have this limitation, HTTP does not fold long lines. MHTML messages - being transported by HTTP follow all conventions of MHTML, including - line length limitations and folding, canonicalization, etc., since - HTTP transports all message-bodies as payload (see section 3.7.2) and - does not interpret the content or any MIME header lines that might be - contained therein. - -19.5 Additional Features - - RFC 1945 and RFC 2068 document protocol elements used by some - existing HTTP implementations, but not consistently and correctly - across most HTTP/1.1 applications. Implementors are advised to be - aware of these features, but cannot rely upon their presence in, or - interoperability with, other HTTP/1.1 applications. Some of these - - - -Fielding, et al. Standards Track [Page 169] - -RFC 2616 HTTP/1.1 June 1999 - - - describe proposed experimental features, and some describe features - that experimental deployment found lacking that are now addressed in - the base HTTP/1.1 specification. - - A number of other headers, such as Content-Disposition and Title, - from SMTP and MIME are also often implemented (see RFC 2076 [37]). - -19.5.1 Content-Disposition - - The Content-Disposition response-header field has been proposed as a - means for the origin server to suggest a default filename if the user - requests that the content is saved to a file. This usage is derived - from the definition of Content-Disposition in RFC 1806 [35]. - - content-disposition = "Content-Disposition" ":" - disposition-type *( ";" disposition-parm ) - disposition-type = "attachment" | disp-extension-token - disposition-parm = filename-parm | disp-extension-parm - filename-parm = "filename" "=" quoted-string - disp-extension-token = token - disp-extension-parm = token "=" ( token | quoted-string ) - - An example is - - Content-Disposition: attachment; filename="fname.ext" - - The receiving user agent SHOULD NOT respect any directory path - information present in the filename-parm parameter, which is the only - parameter believed to apply to HTTP implementations at this time. The - filename SHOULD be treated as a terminal component only. - - If this header is used in a response with the application/octet- - stream content-type, the implied suggestion is that the user agent - should not display the response, but directly enter a `save response - as...' dialog. - - See section 15.5 for Content-Disposition security issues. - -19.6 Compatibility with Previous Versions - - It is beyond the scope of a protocol specification to mandate - compliance with previous versions. HTTP/1.1 was deliberately - designed, however, to make supporting previous versions easy. It is - worth noting that, at the time of composing this specification - (1996), we would expect commercial HTTP/1.1 servers to: - - - recognize the format of the Request-Line for HTTP/0.9, 1.0, and - 1.1 requests; - - - -Fielding, et al. Standards Track [Page 170] - -RFC 2616 HTTP/1.1 June 1999 - - - - understand any valid request in the format of HTTP/0.9, 1.0, or - 1.1; - - - respond appropriately with a message in the same major version - used by the client. - - And we would expect HTTP/1.1 clients to: - - - recognize the format of the Status-Line for HTTP/1.0 and 1.1 - responses; - - - understand any valid response in the format of HTTP/0.9, 1.0, or - 1.1. - - For most implementations of HTTP/1.0, each connection is established - by the client prior to the request and closed by the server after - sending the response. Some implementations implement the Keep-Alive - version of persistent connections described in section 19.7.1 of RFC - 2068 [33]. - -19.6.1 Changes from HTTP/1.0 - - This section summarizes major differences between versions HTTP/1.0 - and HTTP/1.1. - -19.6.1.1 Changes to Simplify Multi-homed Web Servers and Conserve IP - Addresses - - The requirements that clients and servers support the Host request- - header, report an error if the Host request-header (section 14.23) is - missing from an HTTP/1.1 request, and accept absolute URIs (section - 5.1.2) are among the most important changes defined by this - specification. - - Older HTTP/1.0 clients assumed a one-to-one relationship of IP - addresses and servers; there was no other established mechanism for - distinguishing the intended server of a request than the IP address - to which that request was directed. The changes outlined above will - allow the Internet, once older HTTP clients are no longer common, to - support multiple Web sites from a single IP address, greatly - simplifying large operational Web servers, where allocation of many - IP addresses to a single host has created serious problems. The - Internet will also be able to recover the IP addresses that have been - allocated for the sole purpose of allowing special-purpose domain - names to be used in root-level HTTP URLs. Given the rate of growth of - the Web, and the number of servers already deployed, it is extremely - - - - - -Fielding, et al. Standards Track [Page 171] - -RFC 2616 HTTP/1.1 June 1999 - - - important that all implementations of HTTP (including updates to - existing HTTP/1.0 applications) correctly implement these - requirements: - - - Both clients and servers MUST support the Host request-header. - - - A client that sends an HTTP/1.1 request MUST send a Host header. - - - Servers MUST report a 400 (Bad Request) error if an HTTP/1.1 - request does not include a Host request-header. - - - Servers MUST accept absolute URIs. - -19.6.2 Compatibility with HTTP/1.0 Persistent Connections - - Some clients and servers might wish to be compatible with some - previous implementations of persistent connections in HTTP/1.0 - clients and servers. Persistent connections in HTTP/1.0 are - explicitly negotiated as they are not the default behavior. HTTP/1.0 - experimental implementations of persistent connections are faulty, - and the new facilities in HTTP/1.1 are designed to rectify these - problems. The problem was that some existing 1.0 clients may be - sending Keep-Alive to a proxy server that doesn't understand - Connection, which would then erroneously forward it to the next - inbound server, which would establish the Keep-Alive connection and - result in a hung HTTP/1.0 proxy waiting for the close on the - response. The result is that HTTP/1.0 clients must be prevented from - using Keep-Alive when talking to proxies. - - However, talking to proxies is the most important use of persistent - connections, so that prohibition is clearly unacceptable. Therefore, - we need some other mechanism for indicating a persistent connection - is desired, which is safe to use even when talking to an old proxy - that ignores Connection. Persistent connections are the default for - HTTP/1.1 messages; we introduce a new keyword (Connection: close) for - declaring non-persistence. See section 14.10. - - The original HTTP/1.0 form of persistent connections (the Connection: - Keep-Alive and Keep-Alive header) is documented in RFC 2068. [33] - -19.6.3 Changes from RFC 2068 - - This specification has been carefully audited to correct and - disambiguate key word usage; RFC 2068 had many problems in respect to - the conventions laid out in RFC 2119 [34]. - - Clarified which error code should be used for inbound server failures - (e.g. DNS failures). (Section 10.5.5). - - - -Fielding, et al. Standards Track [Page 172] - -RFC 2616 HTTP/1.1 June 1999 - - - CREATE had a race that required an Etag be sent when a resource is - first created. (Section 10.2.2). - - Content-Base was deleted from the specification: it was not - implemented widely, and there is no simple, safe way to introduce it - without a robust extension mechanism. In addition, it is used in a - similar, but not identical fashion in MHTML [45]. - - Transfer-coding and message lengths all interact in ways that - required fixing exactly when chunked encoding is used (to allow for - transfer encoding that may not be self delimiting); it was important - to straighten out exactly how message lengths are computed. (Sections - 3.6, 4.4, 7.2.2, 13.5.2, 14.13, 14.16) - - A content-coding of "identity" was introduced, to solve problems - discovered in caching. (section 3.5) - - Quality Values of zero should indicate that "I don't want something" - to allow clients to refuse a representation. (Section 3.9) - - The use and interpretation of HTTP version numbers has been clarified - by RFC 2145. Require proxies to upgrade requests to highest protocol - version they support to deal with problems discovered in HTTP/1.0 - implementations (Section 3.1) - - Charset wildcarding is introduced to avoid explosion of character set - names in accept headers. (Section 14.2) - - A case was missed in the Cache-Control model of HTTP/1.1; s-maxage - was introduced to add this missing case. (Sections 13.4, 14.8, 14.9, - 14.9.3) - - The Cache-Control: max-age directive was not properly defined for - responses. (Section 14.9.3) - - There are situations where a server (especially a proxy) does not - know the full length of a response but is capable of serving a - byterange request. We therefore need a mechanism to allow byteranges - with a content-range not indicating the full length of the message. - (Section 14.16) - - Range request responses would become very verbose if all meta-data - were always returned; by allowing the server to only send needed - headers in a 206 response, this problem can be avoided. (Section - 10.2.7, 13.5.3, and 14.27) - - - - - - -Fielding, et al. Standards Track [Page 173] - -RFC 2616 HTTP/1.1 June 1999 - - - Fix problem with unsatisfiable range requests; there are two cases: - syntactic problems, and range doesn't exist in the document. The 416 - status code was needed to resolve this ambiguity needed to indicate - an error for a byte range request that falls outside of the actual - contents of a document. (Section 10.4.17, 14.16) - - Rewrite of message transmission requirements to make it much harder - for implementors to get it wrong, as the consequences of errors here - can have significant impact on the Internet, and to deal with the - following problems: - - 1. Changing "HTTP/1.1 or later" to "HTTP/1.1", in contexts where - this was incorrectly placing a requirement on the behavior of - an implementation of a future version of HTTP/1.x - - 2. Made it clear that user-agents should retry requests, not - "clients" in general. - - 3. Converted requirements for clients to ignore unexpected 100 - (Continue) responses, and for proxies to forward 100 responses, - into a general requirement for 1xx responses. - - 4. Modified some TCP-specific language, to make it clearer that - non-TCP transports are possible for HTTP. - - 5. Require that the origin server MUST NOT wait for the request - body before it sends a required 100 (Continue) response. - - 6. Allow, rather than require, a server to omit 100 (Continue) if - it has already seen some of the request body. - - 7. Allow servers to defend against denial-of-service attacks and - broken clients. - - This change adds the Expect header and 417 status code. The message - transmission requirements fixes are in sections 8.2, 10.4.18, - 8.1.2.2, 13.11, and 14.20. - - Proxies should be able to add Content-Length when appropriate. - (Section 13.5.2) - - Clean up confusion between 403 and 404 responses. (Section 10.4.4, - 10.4.5, and 10.4.11) - - Warnings could be cached incorrectly, or not updated appropriately. - (Section 13.1.2, 13.2.4, 13.5.2, 13.5.3, 14.9.3, and 14.46) Warning - also needed to be a general header, as PUT or other methods may have - need for it in requests. - - - -Fielding, et al. Standards Track [Page 174] - -RFC 2616 HTTP/1.1 June 1999 - - - Transfer-coding had significant problems, particularly with - interactions with chunked encoding. The solution is that transfer- - codings become as full fledged as content-codings. This involves - adding an IANA registry for transfer-codings (separate from content - codings), a new header field (TE) and enabling trailer headers in the - future. Transfer encoding is a major performance benefit, so it was - worth fixing [39]. TE also solves another, obscure, downward - interoperability problem that could have occurred due to interactions - between authentication trailers, chunked encoding and HTTP/1.0 - clients.(Section 3.6, 3.6.1, and 14.39) - - The PATCH, LINK, UNLINK methods were defined but not commonly - implemented in previous versions of this specification. See RFC 2068 - [33]. - - The Alternates, Content-Version, Derived-From, Link, URI, Public and - Content-Base header fields were defined in previous versions of this - specification, but not commonly implemented. See RFC 2068 [33]. - -20 Index - - Please see the PostScript version of this RFC for the INDEX. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Fielding, et al. Standards Track [Page 175] - -RFC 2616 HTTP/1.1 June 1999 - - -21. Full Copyright Statement - - Copyright (C) The Internet Society (1999). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Fielding, et al. Standards Track [Page 176] - diff --git a/docs/specs/rfc2617.txt b/docs/specs/rfc2617.txt deleted file mode 100644 index b8fdf59f..00000000 --- a/docs/specs/rfc2617.txt +++ /dev/null @@ -1,1909 +0,0 @@ - -[[ Text in double brackets is from the unofficial errata at ]] -[[ http://skrb.org/ietf/http_errata.html ]] - -Network Working Group J. Franks -Request for Comments: 2617 Northwestern University -Obsoletes: 2069 P. Hallam-Baker -Category: Standards Track Verisign, Inc. - J. Hostetler - AbiSource, Inc. - S. Lawrence - Agranat Systems, Inc. - P. Leach - Microsoft Corporation - A. Luotonen - Netscape Communications Corporation - L. Stewart - Open Market, Inc. - June 1999 - - - HTTP Authentication: Basic and Digest Access Authentication - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (1999). All Rights Reserved. - -Abstract - - "HTTP/1.0", includes the specification for a Basic Access - Authentication scheme. This scheme is not considered to be a secure - method of user authentication (unless used in conjunction with some - external secure system such as SSL [5]), as the user name and - password are passed over the network as cleartext. - - This document also provides the specification for HTTP's - authentication framework, the original Basic authentication scheme - and a scheme based on cryptographic hashes, referred to as "Digest - Access Authentication". It is therefore also intended to serve as a - replacement for RFC 2069 [6]. Some optional elements specified by - RFC 2069 have been removed from this specification due to problems - found since its publication; other new elements have been added for - compatibility, those new elements have been made optional, but are - strongly recommended. - - - -Franks, et al. Standards Track [Page 1] - -RFC 2617 HTTP Authentication June 1999 - - - Like Basic, Digest access authentication verifies that both parties - to a communication know a shared secret (a password); unlike Basic, - this verification can be done without sending the password in the - clear, which is Basic's biggest weakness. As with most other - authentication protocols, the greatest sources of risks are usually - found not in the core protocol itself but in policies and procedures - surrounding its use. - -Table of Contents - - 1 Access Authentication................................ 3 - 1.1 Reliance on the HTTP/1.1 Specification............ 3 - 1.2 Access Authentication Framework................... 3 - 2 Basic Authentication Scheme.......................... 5 - 3 Digest Access Authentication Scheme.................. 6 - 3.1 Introduction...................................... 6 - 3.1.1 Purpose......................................... 6 - 3.1.2 Overall Operation............................... 6 - 3.1.3 Representation of digest values................. 7 - 3.1.4 Limitations..................................... 7 - 3.2 Specification of Digest Headers................... 7 - 3.2.1 The WWW-Authenticate Response Header............ 8 - 3.2.2 The Authorization Request Header................ 11 - 3.2.3 The Authentication-Info Header.................. 15 - 3.3 Digest Operation.................................. 17 - 3.4 Security Protocol Negotiation..................... 18 - 3.5 Example........................................... 18 - 3.6 Proxy-Authentication and Proxy-Authorization...... 19 - 4 Security Considerations.............................. 19 - 4.1 Authentication of Clients using Basic - Authentication.................................... 19 - 4.2 Authentication of Clients using Digest - Authentication.................................... 20 - 4.3 Limited Use Nonce Values.......................... 21 - 4.4 Comparison of Digest with Basic Authentication.... 22 - 4.5 Replay Attacks.................................... 22 - 4.6 Weakness Created by Multiple Authentication - Schemes........................................... 23 - 4.7 Online dictionary attacks......................... 23 - 4.8 Man in the Middle................................. 24 - 4.9 Chosen plaintext attacks.......................... 24 - 4.10 Precomputed dictionary attacks.................... 25 - 4.11 Batch brute force attacks......................... 25 - 4.12 Spoofing by Counterfeit Servers................... 25 - 4.13 Storing passwords................................. 26 - 4.14 Summary........................................... 26 - 5 Sample implementation................................ 27 - 6 Acknowledgments...................................... 31 - - - -Franks, et al. Standards Track [Page 2] - -RFC 2617 HTTP Authentication June 1999 - - - 7 References........................................... 31 - 8 Authors' Addresses................................... 32 - 9 Full Copyright Statement............................. 34 - -1 Access Authentication - -1.1 Reliance on the HTTP/1.1 Specification - - This specification is a companion to the HTTP/1.1 specification [2]. - It uses the augmented BNF section 2.1 of that document, and relies on - both the non-terminals defined in that document and other aspects of - the HTTP/1.1 specification. - -1.2 Access Authentication Framework - - HTTP provides a simple challenge-response authentication mechanism - that MAY be used by a server to challenge a client request and by a - client to provide authentication information. It uses an extensible, - case-insensitive token to identify the authentication scheme, - followed by a comma-separated list of attribute-value pairs which - carry the parameters necessary for achieving authentication via that - scheme. - - auth-scheme = token - auth-param = token "=" ( token | quoted-string ) - - The 401 (Unauthorized) response message is used by an origin server - to challenge the authorization of a user agent. This response MUST - include a WWW-Authenticate header field containing at least one - challenge applicable to the requested resource. The 407 (Proxy - Authentication Required) response message is used by a proxy to - challenge the authorization of a client and MUST include a Proxy- - Authenticate header field containing at least one challenge - applicable to the proxy for the requested resource. - - challenge = auth-scheme 1*SP 1#auth-param - - Note: User agents will need to take special care in parsing the WWW- - Authenticate or Proxy-Authenticate header field value if it contains - more than one challenge, or if more than one WWW-Authenticate header - field is provided, since the contents of a challenge may itself - contain a comma-separated list of authentication parameters. - - The authentication parameter realm is defined for all authentication - schemes: - - realm = "realm" "=" realm-value - realm-value = quoted-string - - - -Franks, et al. Standards Track [Page 3] - -RFC 2617 HTTP Authentication June 1999 - - - The realm directive (case-insensitive) is required for all - authentication schemes that issue a challenge. The realm value - (case-sensitive), in combination with the canonical root URL (the - absoluteURI for the server whose abs_path is empty; see section 5.1.2 - of [2]) of the server being accessed, defines the protection space. - These realms allow the protected resources on a server to be - partitioned into a set of protection spaces, each with its own - authentication scheme and/or authorization database. The realm value - is a string, generally assigned by the origin server, which may have - additional semantics specific to the authentication scheme. Note that - there may be multiple challenges with the same auth-scheme but - different realms. - - A user agent that wishes to authenticate itself with an origin - server--usually, but not necessarily, after receiving a 401 - (Unauthorized)--MAY do so by including an Authorization header field - with the request. A client that wishes to authenticate itself with a - proxy--usually, but not necessarily, after receiving a 407 (Proxy - Authentication Required)--MAY do so by including a Proxy- - Authorization header field with the request. Both the Authorization - field value and the Proxy-Authorization field value consist of - credentials containing the authentication information of the client - for the realm of the resource being requested. The user agent MUST - choose to use one of the challenges with the strongest auth-scheme it - understands and request credentials from the user based upon that - challenge. - - credentials = auth-scheme #auth-param - - Note that many browsers will only recognize Basic and will require - that it be the first auth-scheme presented. Servers should only - include Basic if it is minimally acceptable. - - The protection space determines the domain over which credentials can - be automatically applied. If a prior request has been authorized, the - same credentials MAY be reused for all other requests within that - protection space for a period of time determined by the - authentication scheme, parameters, and/or user preference. Unless - otherwise defined by the authentication scheme, a single protection - space cannot extend outside the scope of its server. - - If the origin server does not wish to accept the credentials sent - with a request, it SHOULD return a 401 (Unauthorized) response. The - response MUST include a WWW-Authenticate header field containing at - least one (possibly new) challenge applicable to the requested - resource. If a proxy does not accept the credentials sent with a - request, it SHOULD return a 407 (Proxy Authentication Required). The - response MUST include a Proxy-Authenticate header field containing a - - - -Franks, et al. Standards Track [Page 4] - -RFC 2617 HTTP Authentication June 1999 - - - (possibly new) challenge applicable to the proxy for the requested - resource. - - The HTTP protocol does not restrict applications to this simple - challenge-response mechanism for access authentication. Additional - mechanisms MAY be used, such as encryption at the transport level or - via message encapsulation, and with additional header fields - specifying authentication information. However, these additional - mechanisms are not defined by this specification. - - Proxies MUST be completely transparent regarding user agent - authentication by origin servers. That is, they must forward the - WWW-Authenticate and Authorization headers untouched, and follow the - rules found in section 14.8 of [2]. Both the Proxy-Authenticate and - the Proxy-Authorization header fields are hop-by-hop headers (see - section 13.5.1 of [2]). - -2 Basic Authentication Scheme - - The "basic" authentication scheme is based on the model that the - client must authenticate itself with a user-ID and a password for - each realm. The realm value should be considered an opaque string - which can only be compared for equality with other realms on that - server. The server will service the request only if it can validate - the user-ID and password for the protection space of the Request-URI. - There are no optional authentication parameters. - - For Basic, the framework above is utilized as follows: - - challenge = "Basic" realm - credentials = "Basic" basic-credentials - - Upon receipt of an unauthorized request for a URI within the - protection space, the origin server MAY respond with a challenge like - the following: - - WWW-Authenticate: Basic realm="WallyWorld" - - where "WallyWorld" is the string assigned by the server to identify - the protection space of the Request-URI. A proxy may respond with the - same challenge using the Proxy-Authenticate header field. - - To receive authorization, the client sends the userid and password, - separated by a single colon (":") character, within a base64 [7] - encoded string in the credentials. - - basic-credentials = base64-user-pass - base64-user-pass = <base64 [4] encoding of user-pass, - - - -Franks, et al. Standards Track [Page 5] - -RFC 2617 HTTP Authentication June 1999 - - - except not limited to 76 char/line> - user-pass = userid ":" password - userid = *<TEXT excluding ":"> - password = *TEXT - - Userids might be case sensitive. - - If the user agent wishes to send the userid "Aladdin" and password - "open sesame", it would use the following header field: - - Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== - - A client SHOULD assume that all paths at or deeper than the depth of - the last symbolic element in the path field of the Request-URI also - are within the protection space specified by the Basic realm value of - the current challenge. A client MAY preemptively send the - corresponding Authorization header with requests for resources in - that space without receipt of another challenge from the server. - Similarly, when a client sends a request to a proxy, it may reuse a - userid and password in the Proxy-Authorization header field without - receiving another challenge from the proxy server. See section 4 for - security considerations associated with Basic authentication. - -3 Digest Access Authentication Scheme - -3.1 Introduction - -3.1.1 Purpose - - The protocol referred to as "HTTP/1.0" includes the specification for - a Basic Access Authentication scheme[1]. That scheme is not - considered to be a secure method of user authentication, as the user - name and password are passed over the network in an unencrypted form. - This section provides the specification for a scheme that does not - send the password in cleartext, referred to as "Digest Access - Authentication". - - The Digest Access Authentication scheme is not intended to be a - complete answer to the need for security in the World Wide Web. This - scheme provides no encryption of message content. The intent is - simply to create an access authentication method that avoids the most - serious flaws of Basic authentication. - -3.1.2 Overall Operation - - Like Basic Access Authentication, the Digest scheme is based on a - simple challenge-response paradigm. The Digest scheme challenges - using a nonce value. A valid response contains a checksum (by - - - -Franks, et al. Standards Track [Page 6] - -RFC 2617 HTTP Authentication June 1999 - - - default, the MD5 checksum) of the username, the password, the given - nonce value, the HTTP method, and the requested URI. In this way, the - password is never sent in the clear. Just as with the Basic scheme, - the username and password must be prearranged in some fashion not - addressed by this document. - -3.1.3 Representation of digest values - - An optional header allows the server to specify the algorithm used to - create the checksum or digest. By default the MD5 algorithm is used - and that is the only algorithm described in this document. - - For the purposes of this document, an MD5 digest of 128 bits is - represented as 32 ASCII printable characters. The bits in the 128 bit - digest are converted from most significant to least significant bit, - four bits at a time to their ASCII presentation as follows. Each four - bits is represented by its familiar hexadecimal notation from the - characters 0123456789abcdef. That is, binary 0000 gets represented by - the character '0', 0001, by '1', and so on up to the representation - of 1111 as 'f'. - -3.1.4 Limitations - - The Digest authentication scheme described in this document suffers - from many known limitations. It is intended as a replacement for - Basic authentication and nothing more. It is a password-based system - and (on the server side) suffers from all the same problems of any - password system. In particular, no provision is made in this protocol - for the initial secure arrangement between user and server to - establish the user's password. - - Users and implementors should be aware that this protocol is not as - secure as Kerberos, and not as secure as any client-side private-key - scheme. Nevertheless it is better than nothing, better than what is - commonly used with telnet and ftp, and better than Basic - authentication. - -3.2 Specification of Digest Headers - - The Digest Access Authentication scheme is conceptually similar to - the Basic scheme. The formats of the modified WWW-Authenticate header - line and the Authorization header line are specified below. In - addition, a new header, Authentication-Info, is specified. - - - - - - - - -Franks, et al. Standards Track [Page 7] - -RFC 2617 HTTP Authentication June 1999 - - -3.2.1 The WWW-Authenticate Response Header - - If a server receives a request for an access-protected object, and an - acceptable Authorization header is not sent, the server responds with - a "401 Unauthorized" status code, and a WWW-Authenticate header as - per the framework defined above, which for the digest scheme is - utilized as follows: - - challenge = "Digest" digest-challenge - - digest-challenge = 1#( realm | [ domain ] | nonce | - [ opaque ] |[ stale ] | [ algorithm ] | - [ qop-options ] | [auth-param] ) - - - domain = "domain" "=" <"> URI ( 1*SP URI ) <"> - [[ Should be: ]] - [[ domain = "domain" "=" <"> URI *( 1*SP URI ) <"> ]] - URI = absoluteURI | abs_path - nonce = "nonce" "=" nonce-value - nonce-value = quoted-string - opaque = "opaque" "=" quoted-string - stale = "stale" "=" ( "true" | "false" ) - algorithm = "algorithm" "=" ( "MD5" | "MD5-sess" | - token ) - qop-options = "qop" "=" <"> 1#qop-value <"> - qop-value = "auth" | "auth-int" | token - - The meanings of the values of the directives used above are as - follows: - - realm - A string to be displayed to users so they know which username and - password to use. This string should contain at least the name of - the host performing the authentication and might additionally - indicate the collection of users who might have access. An example - might be "registered_users@gotham.news.com". - - domain - A quoted, space-separated list of URIs, as specified in RFC XURI - [7], that define the protection space. If a URI is an abs_path, it - is relative to the canonical root URL (see section 1.2 above) of - the server being accessed. An absoluteURI in this list may refer to - a different server than the one being accessed. The client can use - this list to determine the set of URIs for which the same - authentication information may be sent: any URI that has a URI in - this list as a prefix (after both have been made absolute) may be - assumed to be in the same protection space. If this directive is - omitted or its value is empty, the client should assume that the - protection space consists of all URIs on the responding server. - - - -Franks, et al. Standards Track [Page 8] - -RFC 2617 HTTP Authentication June 1999 - - - This directive is not meaningful in Proxy-Authenticate headers, for - which the protection space is always the entire proxy; if present - it should be ignored. - - nonce - A server-specified data string which should be uniquely generated - each time a 401 response is made. It is recommended that this - string be base64 or hexadecimal data. Specifically, since the - string is passed in the header lines as a quoted string, the - double-quote character is not allowed. - - The contents of the nonce are implementation dependent. The quality - of the implementation depends on a good choice. A nonce might, for - example, be constructed as the base 64 encoding of - - time-stamp H(time-stamp ":" ETag ":" private-key) - - where time-stamp is a server-generated time or other non-repeating - value, ETag is the value of the HTTP ETag header associated with - the requested entity, and private-key is data known only to the - server. With a nonce of this form a server would recalculate the - hash portion after receiving the client authentication header and - reject the request if it did not match the nonce from that header - or if the time-stamp value is not recent enough. In this way the - server can limit the time of the nonce's validity. The inclusion of - the ETag prevents a replay request for an updated version of the - resource. (Note: including the IP address of the client in the - nonce would appear to offer the server the ability to limit the - reuse of the nonce to the same client that originally got it. - However, that would break proxy farms, where requests from a single - user often go through different proxies in the farm. Also, IP - address spoofing is not that hard.) - - An implementation might choose not to accept a previously used - nonce or a previously used digest, in order to protect against a - replay attack. Or, an implementation might choose to use one-time - nonces or digests for POST or PUT requests and a time-stamp for GET - requests. For more details on the issues involved see section 4. - of this document. - - The nonce is opaque to the client. - - opaque - A string of data, specified by the server, which should be returned - by the client unchanged in the Authorization header of subsequent - requests with URIs in the same protection space. It is recommended - that this string be base64 or hexadecimal data. - - - - -Franks, et al. Standards Track [Page 9] - -RFC 2617 HTTP Authentication June 1999 - - - stale - A flag, indicating that the previous request from the client was - rejected because the nonce value was stale. If stale is TRUE - (case-insensitive), the client may wish to simply retry the request - with a new encrypted response, without reprompting the user for a - new username and password. The server should only set stale to TRUE - if it receives a request for which the nonce is invalid but with a - valid digest for that nonce (indicating that the client knows the - correct username/password). If stale is FALSE, or anything other - than TRUE, or the stale directive is not present, the username - and/or password are invalid, and new values must be obtained. - - algorithm - A string indicating a pair of algorithms used to produce the digest - and a checksum. If this is not present it is assumed to be "MD5". - If the algorithm is not understood, the challenge should be ignored - (and a different one used, if there is more than one). - - In this document the string obtained by applying the digest - algorithm to the data "data" with secret "secret" will be denoted - by KD(secret, data), and the string obtained by applying the - checksum algorithm to the data "data" will be denoted H(data). The - notation unq(X) means the value of the quoted-string X without the - surrounding quotes. - - For the "MD5" and "MD5-sess" algorithms - - H(data) = MD5(data) - - and - - KD(secret, data) = H(concat(secret, ":", data)) - - i.e., the digest is the MD5 of the secret concatenated with a colon - concatenated with the data. The "MD5-sess" algorithm is intended to - allow efficient 3rd party authentication servers; for the - difference in usage, see the description in section 3.2.2.2. - - qop-options - This directive is optional, but is made so only for backward - compatibility with RFC 2069 [6]; it SHOULD be used by all - implementations compliant with this version of the Digest scheme. - If present, it is a quoted string of one or more tokens indicating - the "quality of protection" values supported by the server. The - value "auth" indicates authentication; the value "auth-int" - indicates authentication with integrity protection; see the - - - - - -Franks, et al. Standards Track [Page 10] - -RFC 2617 HTTP Authentication June 1999 - - - descriptions below for calculating the response directive value for - the application of this choice. Unrecognized options MUST be - ignored. - - auth-param - This directive allows for future extensions. Any unrecognized - directive MUST be ignored. - -3.2.2 The Authorization Request Header - - The client is expected to retry the request, passing an Authorization - header line, which is defined according to the framework above, - utilized as follows. - - credentials = "Digest" digest-response - digest-response = 1#( username | realm | nonce | digest-uri - | response | [ algorithm ] | [cnonce] | - [opaque] | [message-qop] | - [nonce-count] | [auth-param] ) - - username = "username" "=" username-value - username-value = quoted-string - digest-uri = "uri" "=" digest-uri-value - digest-uri-value = request-uri ; As specified by HTTP/1.1 - message-qop = "qop" "=" qop-value - cnonce = "cnonce" "=" cnonce-value - cnonce-value = nonce-value - nonce-count = "nc" "=" nc-value - nc-value = 8LHEX - response = "response" "=" request-digest - request-digest = <"> 32LHEX <"> - LHEX = "0" | "1" | "2" | "3" | - "4" | "5" | "6" | "7" | - "8" | "9" | "a" | "b" | - "c" | "d" | "e" | "f" - - The values of the opaque and algorithm fields must be those supplied - in the WWW-Authenticate response header for the entity being - requested. - - response - A string of 32 hex digits computed as defined below, which proves - that the user knows a password - - username - The user's name in the specified realm. - - - - - -Franks, et al. Standards Track [Page 11] - -RFC 2617 HTTP Authentication June 1999 - - - digest-uri - The URI from Request-URI of the Request-Line; duplicated here - because proxies are allowed to change the Request-Line in transit. - - qop - Indicates what "quality of protection" the client has applied to - the message. If present, its value MUST be one of the alternatives - the server indicated it supports in the WWW-Authenticate header. - These values affect the computation of the request-digest. Note - that this is a single token, not a quoted list of alternatives as - in WWW- Authenticate. This directive is optional in order to - preserve backward compatibility with a minimal implementation of - RFC 2069 [6], but SHOULD be used if the server indicated that qop - is supported by providing a qop directive in the WWW-Authenticate - header field. - - cnonce - This MUST be specified if a qop directive is sent (see above), and - MUST NOT be specified if the server did not send a qop directive in - the WWW-Authenticate header field. The cnonce-value is an opaque - quoted string value provided by the client and used by both client - and server to avoid chosen plaintext attacks, to provide mutual - authentication, and to provide some message integrity protection. - See the descriptions below of the calculation of the response- - digest and request-digest values. - - nonce-count - This MUST be specified if a qop directive is sent (see above), and - MUST NOT be specified if the server did not send a qop directive in - the WWW-Authenticate header field. The nc-value is the hexadecimal - count of the number of requests (including the current request) - that the client has sent with the nonce value in this request. For - example, in the first request sent in response to a given nonce - value, the client sends "nc=00000001". The purpose of this - directive is to allow the server to detect request replays by - maintaining its own copy of this count - if the same nc-value is - seen twice, then the request is a replay. See the description - below of the construction of the request-digest value. - - auth-param - This directive allows for future extensions. Any unrecognized - directive MUST be ignored. - - If a directive or its value is improper, or required directives are - missing, the proper response is 400 Bad Request. If the request- - digest is invalid, then a login failure should be logged, since - repeated login failures from a single client may indicate an attacker - attempting to guess passwords. - - - -Franks, et al. Standards Track [Page 12] - -RFC 2617 HTTP Authentication June 1999 - - - The definition of request-digest above indicates the encoding for its - value. The following definitions show how the value is computed. - -3.2.2.1 Request-Digest - - If the "qop" value is "auth" or "auth-int": - - request-digest = <"> < KD ( H(A1), unq(nonce-value) - ":" nc-value - ":" unq(cnonce-value) - ":" unq(qop-value) - ":" H(A2) - ) <"> - - If the "qop" directive is not present (this construction is for - compatibility with RFC 2069): - - request-digest = - <"> < KD ( H(A1), unq(nonce-value) ":" H(A2) ) > - <"> - - See below for the definitions for A1 and A2. - -3.2.2.2 A1 - - If the "algorithm" directive's value is "MD5" or is unspecified, then - A1 is: - - A1 = unq(username-value) ":" unq(realm-value) ":" passwd - - where - - passwd = < user's password > - - If the "algorithm" directive's value is "MD5-sess", then A1 is - calculated only once - on the first request by the client following - receipt of a WWW-Authenticate challenge from the server. It uses the - server nonce from that challenge, and the first client nonce value to - construct A1 as follows: - - A1 = H( unq(username-value) ":" unq(realm-value) - ":" passwd ) - ":" unq(nonce-value) ":" unq(cnonce-value) - - This creates a 'session key' for the authentication of subsequent - requests and responses which is different for each "authentication - session", thus limiting the amount of material hashed with any one - key. (Note: see further discussion of the authentication session in - - - -Franks, et al. Standards Track [Page 13] - -RFC 2617 HTTP Authentication June 1999 - - - section 3.3.) Because the server need only use the hash of the user - credentials in order to create the A1 value, this construction could - be used in conjunction with a third party authentication service so - that the web server would not need the actual password value. The - specification of such a protocol is beyond the scope of this - specification. - -3.2.2.3 A2 - - If the "qop" directive's value is "auth" or is unspecified, then A2 - is: - - A2 = Method ":" digest-uri-value - - If the "qop" value is "auth-int", then A2 is: - - A2 = Method ":" digest-uri-value ":" H(entity-body) - -3.2.2.4 Directive values and quoted-string - - Note that the value of many of the directives, such as "username- - value", are defined as a "quoted-string". However, the "unq" notation - indicates that surrounding quotation marks are removed in forming the - string A1. Thus if the Authorization header includes the fields - - username="Mufasa", realm=myhost@testrealm.com - - and the user Mufasa has password "Circle Of Life" then H(A1) would be - H(Mufasa:myhost@testrealm.com:Circle Of Life) with no quotation marks - in the digested string. - - No white space is allowed in any of the strings to which the digest - function H() is applied unless that white space exists in the quoted - strings or entity body whose contents make up the string to be - digested. For example, the string A1 illustrated above must be - - Mufasa:myhost@testrealm.com:Circle Of Life - - with no white space on either side of the colons, but with the white - space between the words used in the password value. Likewise, the - other strings digested by H() must not have white space on either - side of the colons which delimit their fields unless that white space - was in the quoted strings or entity body being digested. - - Also note that if integrity protection is applied (qop=auth-int), the - H(entity-body) is the hash of the entity body, not the message body - - it is computed before any transfer encoding is applied by the sender - - - - -Franks, et al. Standards Track [Page 14] - -RFC 2617 HTTP Authentication June 1999 - - - and after it has been removed by the recipient. Note that this - includes multipart boundaries and embedded headers in each part of - any multipart content-type. - -3.2.2.5 Various considerations - - The "Method" value is the HTTP request method as specified in section - 5.1.1 of [2]. The "request-uri" value is the Request-URI from the - request line as specified in section 5.1.2 of [2]. This may be "*", - an "absoluteURL" or an "abs_path" as specified in section 5.1.2 of - [2], but it MUST agree with the Request-URI. In particular, it MUST - be an "absoluteURL" if the Request-URI is an "absoluteURL". The - "cnonce-value" is an optional client-chosen value whose purpose is - to foil chosen plaintext attacks. - - The authenticating server must assure that the resource designated by - the "uri" directive is the same as the resource specified in the - Request-Line; if they are not, the server SHOULD return a 400 Bad - Request error. (Since this may be a symptom of an attack, server - implementers may want to consider logging such errors.) The purpose - of duplicating information from the request URL in this field is to - deal with the possibility that an intermediate proxy may alter the - client's Request-Line. This altered (but presumably semantically - equivalent) request would not result in the same digest as that - calculated by the client. - - Implementers should be aware of how authenticated transactions - interact with shared caches. The HTTP/1.1 protocol specifies that - when a shared cache (see section 13.7 of [2]) has received a request - containing an Authorization header and a response from relaying that - request, it MUST NOT return that response as a reply to any other - request, unless one of two Cache-Control (see section 14.9 of [2]) - directives was present in the response. If the original response - included the "must-revalidate" Cache-Control directive, the cache MAY - use the entity of that response in replying to a subsequent request, - but MUST first revalidate it with the origin server, using the - request headers from the new request to allow the origin server to - authenticate the new request. Alternatively, if the original response - included the "public" Cache-Control directive, the response entity - MAY be returned in reply to any subsequent request. - -3.2.3 The Authentication-Info Header - - The Authentication-Info header is used by the server to communicate - some information regarding the successful authentication in the - response. - - - - - -Franks, et al. Standards Track [Page 15] - -RFC 2617 HTTP Authentication June 1999 - - - AuthenticationInfo = "Authentication-Info" ":" auth-info - auth-info = 1#(nextnonce | [ message-qop ] - | [ response-auth ] | [ cnonce ] - | [nonce-count] ) - nextnonce = "nextnonce" "=" nonce-value - response-auth = "rspauth" "=" response-digest - response-digest = <"> *LHEX <"> - - The value of the nextnonce directive is the nonce the server wishes - the client to use for a future authentication response. The server - may send the Authentication-Info header with a nextnonce field as a - means of implementing one-time or otherwise changing nonces. If the - nextnonce field is present the client SHOULD use it when constructing - the Authorization header for its next request. Failure of the client - to do so may result in a request to re-authenticate from the server - with the "stale=TRUE". - - Server implementations should carefully consider the performance - implications of the use of this mechanism; pipelined requests will - not be possible if every response includes a nextnonce directive - that must be used on the next request received by the server. - Consideration should be given to the performance vs. security - tradeoffs of allowing an old nonce value to be used for a limited - time to permit request pipelining. Use of the nonce-count can - retain most of the security advantages of a new server nonce - without the deleterious affects on pipelining. - - message-qop - Indicates the "quality of protection" options applied to the - response by the server. The value "auth" indicates authentication; - the value "auth-int" indicates authentication with integrity - protection. The server SHOULD use the same value for the message- - qop directive in the response as was sent by the client in the - corresponding request. - - The optional response digest in the "response-auth" directive - supports mutual authentication -- the server proves that it knows the - user's secret, and with qop=auth-int also provides limited integrity - protection of the response. The "response-digest" value is calculated - as for the "request-digest" in the Authorization header, except that - if "qop=auth" or is not specified in the Authorization header for the - request, A2 is - - A2 = ":" digest-uri-value - - and if "qop=auth-int", then A2 is - - A2 = ":" digest-uri-value ":" H(entity-body) - - - -Franks, et al. Standards Track [Page 16] - -RFC 2617 HTTP Authentication June 1999 - - - where "digest-uri-value" is the value of the "uri" directive on the - Authorization header in the request. The "cnonce-value" and "nc- - value" MUST be the ones for the client request to which this message - is the response. The "response-auth", "cnonce", and "nonce-count" - directives MUST BE present if "qop=auth" or "qop=auth-int" is - specified. - - The Authentication-Info header is allowed in the trailer of an HTTP - message transferred via chunked transfer-coding. - -3.3 Digest Operation - - Upon receiving the Authorization header, the server may check its - validity by looking up the password that corresponds to the submitted - username. Then, the server must perform the same digest operation - (e.g., MD5) performed by the client, and compare the result to the - given request-digest value. - - Note that the HTTP server does not actually need to know the user's - cleartext password. As long as H(A1) is available to the server, the - validity of an Authorization header may be verified. - - The client response to a WWW-Authenticate challenge for a protection - space starts an authentication session with that protection space. - The authentication session lasts until the client receives another - WWW-Authenticate challenge from any server in the protection space. A - client should remember the username, password, nonce, nonce count and - opaque values associated with an authentication session to use to - construct the Authorization header in future requests within that - protection space. The Authorization header may be included - preemptively; doing so improves server efficiency and avoids extra - round trips for authentication challenges. The server may choose to - accept the old Authorization header information, even though the - nonce value included might not be fresh. Alternatively, the server - may return a 401 response with a new nonce value, causing the client - to retry the request; by specifying stale=TRUE with this response, - the server tells the client to retry with the new nonce, but without - prompting for a new username and password. - - Because the client is required to return the value of the opaque - directive given to it by the server for the duration of a session, - the opaque data may be used to transport authentication session state - information. (Note that any such use can also be accomplished more - easily and safely by including the state in the nonce.) For example, - a server could be responsible for authenticating content that - actually sits on another server. It would achieve this by having the - first 401 response include a domain directive whose value includes a - URI on the second server, and an opaque directive whose value - - - -Franks, et al. Standards Track [Page 17] - -RFC 2617 HTTP Authentication June 1999 - - - contains the state information. The client will retry the request, at - which time the server might respond with a 301/302 redirection, - pointing to the URI on the second server. The client will follow the - redirection, and pass an Authorization header , including the - <opaque> data. - - As with the basic scheme, proxies must be completely transparent in - the Digest access authentication scheme. That is, they must forward - the WWW-Authenticate, Authentication-Info and Authorization headers - untouched. If a proxy wants to authenticate a client before a request - is forwarded to the server, it can be done using the Proxy- - Authenticate and Proxy-Authorization headers described in section 3.6 - below. - -3.4 Security Protocol Negotiation - - It is useful for a server to be able to know which security schemes a - client is capable of handling. - - It is possible that a server may want to require Digest as its - authentication method, even if the server does not know that the - client supports it. A client is encouraged to fail gracefully if the - server specifies only authentication schemes it cannot handle. - -3.5 Example - - The following example assumes that an access-protected document is - being requested from the server via a GET request. The URI of the - document is "http://www.nowhere.org/dir/index.html". Both client and - server know that the username for this document is "Mufasa", and the - password is "Circle Of Life" (with one space between each of the - three words). - - The first time the client requests the document, no Authorization - header is sent, so the server responds with: - - HTTP/1.1 401 Unauthorized - WWW-Authenticate: Digest - realm="testrealm@host.com", - qop="auth,auth-int", - nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", - opaque="5ccc069c403ebaf9f0171e9517f40e41" - - The client may prompt the user for the username and password, after - which it will respond with a new request, including the following - Authorization header: - - - - - -Franks, et al. Standards Track [Page 18] - -RFC 2617 HTTP Authentication June 1999 - - - Authorization: Digest username="Mufasa", - realm="testrealm@host.com", - nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", - uri="/dir/index.html", - qop=auth, - nc=00000001, - cnonce="0a4f113b", - response="6629fae49393a05397450978507c4ef1", - opaque="5ccc069c403ebaf9f0171e9517f40e41" - -3.6 Proxy-Authentication and Proxy-Authorization - - The digest authentication scheme may also be used for authenticating - users to proxies, proxies to proxies, or proxies to origin servers by - use of the Proxy-Authenticate and Proxy-Authorization headers. These - headers are instances of the Proxy-Authenticate and Proxy- - Authorization headers specified in sections 10.33 and 10.34 of the - HTTP/1.1 specification [2] and their behavior is subject to - restrictions described there. The transactions for proxy - authentication are very similar to those already described. Upon - receiving a request which requires authentication, the proxy/server - must issue the "407 Proxy Authentication Required" response with a - "Proxy-Authenticate" header. The digest-challenge used in the - Proxy-Authenticate header is the same as that for the WWW- - Authenticate header as defined above in section 3.2.1. - - The client/proxy must then re-issue the request with a Proxy- - Authorization header, with directives as specified for the - Authorization header in section 3.2.2 above. - - On subsequent responses, the server sends Proxy-Authentication-Info - with directives the same as those for the Authentication-Info header - field. - - Note that in principle a client could be asked to authenticate itself - to both a proxy and an end-server, but never in the same response. - -4 Security Considerations - -4.1 Authentication of Clients using Basic Authentication - - The Basic authentication scheme is not a secure method of user - authentication, nor does it in any way protect the entity, which is - transmitted in cleartext across the physical network used as the - carrier. HTTP does not prevent additional authentication schemes and - encryption mechanisms from being employed to increase security or the - addition of enhancements (such as schemes to use one-time passwords) - to Basic authentication. - - - -Franks, et al. Standards Track [Page 19] - -RFC 2617 HTTP Authentication June 1999 - - - The most serious flaw in Basic authentication is that it results in - the essentially cleartext transmission of the user's password over - the physical network. It is this problem which Digest Authentication - attempts to address. - - Because Basic authentication involves the cleartext transmission of - passwords it SHOULD NOT be used (without enhancements) to protect - sensitive or valuable information. - - A common use of Basic authentication is for identification purposes - -- requiring the user to provide a user name and password as a means - of identification, for example, for purposes of gathering accurate - usage statistics on a server. When used in this way it is tempting to - think that there is no danger in its use if illicit access to the - protected documents is not a major concern. This is only correct if - the server issues both user name and password to the users and in - particular does not allow the user to choose his or her own password. - The danger arises because naive users frequently reuse a single - password to avoid the task of maintaining multiple passwords. - - If a server permits users to select their own passwords, then the - threat is not only unauthorized access to documents on the server but - also unauthorized access to any other resources on other systems that - the user protects with the same password. Furthermore, in the - server's password database, many of the passwords may also be users' - passwords for other sites. The owner or administrator of such a - system could therefore expose all users of the system to the risk of - unauthorized access to all those sites if this information is not - maintained in a secure fashion. - - Basic Authentication is also vulnerable to spoofing by counterfeit - servers. If a user can be led to believe that he is connecting to a - host containing information protected by Basic authentication when, - in fact, he is connecting to a hostile server or gateway, then the - attacker can request a password, store it for later use, and feign an - error. This type of attack is not possible with Digest - Authentication. Server implementers SHOULD guard against the - possibility of this sort of counterfeiting by gateways or CGI - scripts. In particular it is very dangerous for a server to simply - turn over a connection to a gateway. That gateway can then use the - persistent connection mechanism to engage in multiple transactions - with the client while impersonating the original server in a way that - is not detectable by the client. - -4.2 Authentication of Clients using Digest Authentication - - Digest Authentication does not provide a strong authentication - mechanism, when compared to public key based mechanisms, for example. - - - -Franks, et al. Standards Track [Page 20] - -RFC 2617 HTTP Authentication June 1999 - - - However, it is significantly stronger than (e.g.) CRAM-MD5, which has - been proposed for use with LDAP [10], POP and IMAP (see RFC 2195 - [9]). It is intended to replace the much weaker and even more - dangerous Basic mechanism. - - Digest Authentication offers no confidentiality protection beyond - protecting the actual password. All of the rest of the request and - response are available to an eavesdropper. - - Digest Authentication offers only limited integrity protection for - the messages in either direction. If qop=auth-int mechanism is used, - those parts of the message used in the calculation of the WWW- - Authenticate and Authorization header field response directive values - (see section 3.2 above) are protected. Most header fields and their - values could be modified as a part of a man-in-the-middle attack. - - Many needs for secure HTTP transactions cannot be met by Digest - Authentication. For those needs TLS or SHTTP are more appropriate - protocols. In particular Digest authentication cannot be used for any - transaction requiring confidentiality protection. Nevertheless many - functions remain for which Digest authentication is both useful and - appropriate. Any service in present use that uses Basic should be - switched to Digest as soon as practical. - -4.3 Limited Use Nonce Values - - The Digest scheme uses a server-specified nonce to seed the - generation of the request-digest value (as specified in section - 3.2.2.1 above). As shown in the example nonce in section 3.2.1, the - server is free to construct the nonce such that it may only be used - from a particular client, for a particular resource, for a limited - period of time or number of uses, or any other restrictions. Doing - so strengthens the protection provided against, for example, replay - attacks (see 4.5). However, it should be noted that the method - chosen for generating and checking the nonce also has performance and - resource implications. For example, a server may choose to allow - each nonce value to be used only once by maintaining a record of - whether or not each recently issued nonce has been returned and - sending a next-nonce directive in the Authentication-Info header - field of every response. This protects against even an immediate - replay attack, but has a high cost checking nonce values, and perhaps - more important will cause authentication failures for any pipelined - requests (presumably returning a stale nonce indication). Similarly, - incorporating a request-specific element such as the Etag value for a - resource limits the use of the nonce to that version of the resource - and also defeats pipelining. Thus it may be useful to do so for - methods with side effects but have unacceptable performance for those - that do not. - - - -Franks, et al. Standards Track [Page 21] - -RFC 2617 HTTP Authentication June 1999 - - -4.4 Comparison of Digest with Basic Authentication - - Both Digest and Basic Authentication are very much on the weak end of - the security strength spectrum. But a comparison between the two - points out the utility, even necessity, of replacing Basic by Digest. - - The greatest threat to the type of transactions for which these - protocols are used is network snooping. This kind of transaction - might involve, for example, online access to a database whose use is - restricted to paying subscribers. With Basic authentication an - eavesdropper can obtain the password of the user. This not only - permits him to access anything in the database, but, often worse, - will permit access to anything else the user protects with the same - password. - - By contrast, with Digest Authentication the eavesdropper only gets - access to the transaction in question and not to the user's password. - The information gained by the eavesdropper would permit a replay - attack, but only with a request for the same document, and even that - may be limited by the server's choice of nonce. - -4.5 Replay Attacks - - A replay attack against Digest authentication would usually be - pointless for a simple GET request since an eavesdropper would - already have seen the only document he could obtain with a replay. - This is because the URI of the requested document is digested in the - client request and the server will only deliver that document. By - contrast under Basic Authentication once the eavesdropper has the - user's password, any document protected by that password is open to - him. - - Thus, for some purposes, it is necessary to protect against replay - attacks. A good Digest implementation can do this in various ways. - The server created "nonce" value is implementation dependent, but if - it contains a digest of the client IP, a time-stamp, the resource - ETag, and a private server key (as recommended above) then a replay - attack is not simple. An attacker must convince the server that the - request is coming from a false IP address and must cause the server - to deliver the document to an IP address different from the address - to which it believes it is sending the document. An attack can only - succeed in the period before the time-stamp expires. Digesting the - client IP and time-stamp in the nonce permits an implementation which - does not maintain state between transactions. - - For applications where no possibility of replay attack can be - tolerated the server can use one-time nonce values which will not be - honored for a second use. This requires the overhead of the server - - - -Franks, et al. Standards Track [Page 22] - -RFC 2617 HTTP Authentication June 1999 - - - remembering which nonce values have been used until the nonce time- - stamp (and hence the digest built with it) has expired, but it - effectively protects against replay attacks. - - An implementation must give special attention to the possibility of - replay attacks with POST and PUT requests. Unless the server employs - one-time or otherwise limited-use nonces and/or insists on the use of - the integrity protection of qop=auth-int, an attacker could replay - valid credentials from a successful request with counterfeit form - data or other message body. Even with the use of integrity protection - most metadata in header fields is not protected. Proper nonce - generation and checking provides some protection against replay of - previously used valid credentials, but see 4.8. - -4.6 Weakness Created by Multiple Authentication Schemes - - An HTTP/1.1 server may return multiple challenges with a 401 - (Authenticate) response, and each challenge may use a different - auth-scheme. A user agent MUST choose to use the strongest auth- - scheme it understands and request credentials from the user based - upon that challenge. - - Note that many browsers will only recognize Basic and will require - that it be the first auth-scheme presented. Servers should only - include Basic if it is minimally acceptable. - - When the server offers choices of authentication schemes using the - WWW-Authenticate header, the strength of the resulting authentication - is only as good as that of the of the weakest of the authentication - schemes. See section 4.8 below for discussion of particular attack - scenarios that exploit multiple authentication schemes. - -4.7 Online dictionary attacks - - If the attacker can eavesdrop, then it can test any overheard - nonce/response pairs against a list of common words. Such a list is - usually much smaller than the total number of possible passwords. The - cost of computing the response for each password on the list is paid - once for each challenge. - - The server can mitigate this attack by not allowing users to select - passwords that are in a dictionary. - - - - - - - - - -Franks, et al. Standards Track [Page 23] - -RFC 2617 HTTP Authentication June 1999 - - -4.8 Man in the Middle - - Both Basic and Digest authentication are vulnerable to "man in the - middle" (MITM) attacks, for example, from a hostile or compromised - proxy. Clearly, this would present all the problems of eavesdropping. - But it also offers some additional opportunities to the attacker. - - A possible man-in-the-middle attack would be to add a weak - authentication scheme to the set of choices, hoping that the client - will use one that exposes the user's credentials (e.g. password). For - this reason, the client should always use the strongest scheme that - it understands from the choices offered. - - An even better MITM attack would be to remove all offered choices, - replacing them with a challenge that requests only Basic - authentication, then uses the cleartext credentials from the Basic - authentication to authenticate to the origin server using the - stronger scheme it requested. A particularly insidious way to mount - such a MITM attack would be to offer a "free" proxy caching service - to gullible users. - - User agents should consider measures such as presenting a visual - indication at the time of the credentials request of what - authentication scheme is to be used, or remembering the strongest - authentication scheme ever requested by a server and produce a - warning message before using a weaker one. It might also be a good - idea for the user agent to be configured to demand Digest - authentication in general, or from specific sites. - - Or, a hostile proxy might spoof the client into making a request the - attacker wanted rather than one the client wanted. Of course, this is - still much harder than a comparable attack against Basic - Authentication. - -4.9 Chosen plaintext attacks - - With Digest authentication, a MITM or a malicious server can - arbitrarily choose the nonce that the client will use to compute the - response. This is called a "chosen plaintext" attack. The ability to - choose the nonce is known to make cryptanalysis much easier [8]. - - However, no way to analyze the MD5 one-way function used by Digest - using chosen plaintext is currently known. - - The countermeasure against this attack is for clients to be - configured to require the use of the optional "cnonce" directive; - this allows the client to vary the input to the hash in a way not - chosen by the attacker. - - - -Franks, et al. Standards Track [Page 24] - -RFC 2617 HTTP Authentication June 1999 - - -4.10 Precomputed dictionary attacks - - With Digest authentication, if the attacker can execute a chosen - plaintext attack, the attacker can precompute the response for many - common words to a nonce of its choice, and store a dictionary of - (response, password) pairs. Such precomputation can often be done in - parallel on many machines. It can then use the chosen plaintext - attack to acquire a response corresponding to that challenge, and - just look up the password in the dictionary. Even if most passwords - are not in the dictionary, some might be. Since the attacker gets to - pick the challenge, the cost of computing the response for each - password on the list can be amortized over finding many passwords. A - dictionary with 100 million password/response pairs would take about - 3.2 gigabytes of disk storage. - - The countermeasure against this attack is to for clients to be - configured to require the use of the optional "cnonce" directive. - -4.11 Batch brute force attacks - - With Digest authentication, a MITM can execute a chosen plaintext - attack, and can gather responses from many users to the same nonce. - It can then find all the passwords within any subset of password - space that would generate one of the nonce/response pairs in a single - pass over that space. It also reduces the time to find the first - password by a factor equal to the number of nonce/response pairs - gathered. This search of the password space can often be done in - parallel on many machines, and even a single machine can search large - subsets of the password space very quickly -- reports exist of - searching all passwords with six or fewer letters in a few hours. - - The countermeasure against this attack is to for clients to be - configured to require the use of the optional "cnonce" directive. - -4.12 Spoofing by Counterfeit Servers - - Basic Authentication is vulnerable to spoofing by counterfeit - servers. If a user can be led to believe that she is connecting to a - host containing information protected by a password she knows, when - in fact she is connecting to a hostile server, then the hostile - server can request a password, store it away for later use, and feign - an error. This type of attack is more difficult with Digest - Authentication -- but the client must know to demand that Digest - authentication be used, perhaps using some of the techniques - described above to counter "man-in-the-middle" attacks. Again, the - user can be helped in detecting this attack by a visual indication of - the authentication mechanism in use with appropriate guidance in - interpreting the implications of each scheme. - - - -Franks, et al. Standards Track [Page 25] - -RFC 2617 HTTP Authentication June 1999 - - -4.13 Storing passwords - - Digest authentication requires that the authenticating agent (usually - the server) store some data derived from the user's name and password - in a "password file" associated with a given realm. Normally this - might contain pairs consisting of username and H(A1), where H(A1) is - the digested value of the username, realm, and password as described - above. - - The security implications of this are that if this password file is - compromised, then an attacker gains immediate access to documents on - the server using this realm. Unlike, say a standard UNIX password - file, this information need not be decrypted in order to access - documents in the server realm associated with this file. On the other - hand, decryption, or more likely a brute force attack, would be - necessary to obtain the user's password. This is the reason that the - realm is part of the digested data stored in the password file. It - means that if one Digest authentication password file is compromised, - it does not automatically compromise others with the same username - and password (though it does expose them to brute force attack). - - There are two important security consequences of this. First the - password file must be protected as if it contained unencrypted - passwords, because for the purpose of accessing documents in its - realm, it effectively does. - - A second consequence of this is that the realm string should be - unique among all realms which any single user is likely to use. In - particular a realm string should include the name of the host doing - the authentication. The inability of the client to authenticate the - server is a weakness of Digest Authentication. - -4.14 Summary - - By modern cryptographic standards Digest Authentication is weak. But - for a large range of purposes it is valuable as a replacement for - Basic Authentication. It remedies some, but not all, weaknesses of - Basic Authentication. Its strength may vary depending on the - implementation. In particular the structure of the nonce (which is - dependent on the server implementation) may affect the ease of - mounting a replay attack. A range of server options is appropriate - since, for example, some implementations may be willing to accept the - server overhead of one-time nonces or digests to eliminate the - possibility of replay. Others may satisfied with a nonce like the one - recommended above restricted to a single IP address and a single ETag - or with a limited lifetime. - - - - - -Franks, et al. Standards Track [Page 26] - -RFC 2617 HTTP Authentication June 1999 - - - The bottom line is that *any* compliant implementation will be - relatively weak by cryptographic standards, but *any* compliant - implementation will be far superior to Basic Authentication. - -5 Sample implementation - - [[ WARNING: DigestCalcHA1 IS WRONG ]] - - The following code implements the calculations of H(A1), H(A2), - request-digest and response-digest, and a test program which computes - the values used in the example of section 3.5. It uses the MD5 - implementation from RFC 1321. - - File "digcalc.h": - -#define HASHLEN 16 -typedef char HASH[HASHLEN]; -#define HASHHEXLEN 32 -typedef char HASHHEX[HASHHEXLEN+1]; -#define IN -#define OUT - -/* calculate H(A1) as per HTTP Digest spec */ -void DigestCalcHA1( - IN char * pszAlg, - IN char * pszUserName, - IN char * pszRealm, - IN char * pszPassword, - IN char * pszNonce, - IN char * pszCNonce, - OUT HASHHEX SessionKey - ); - -/* calculate request-digest/response-digest as per HTTP Digest spec */ -void DigestCalcResponse( - IN HASHHEX HA1, /* H(A1) */ - IN char * pszNonce, /* nonce from server */ - IN char * pszNonceCount, /* 8 hex digits */ - IN char * pszCNonce, /* client nonce */ - IN char * pszQop, /* qop-value: "", "auth", "auth-int" */ - IN char * pszMethod, /* method from the request */ - IN char * pszDigestUri, /* requested URL */ - IN HASHHEX HEntity, /* H(entity body) if qop="auth-int" */ - OUT HASHHEX Response /* request-digest or response-digest */ - ); - -File "digcalc.c": - -#include <global.h> -#include <md5.h> - - - -Franks, et al. Standards Track [Page 27] - -RFC 2617 HTTP Authentication June 1999 - - -#include <string.h> -#include "digcalc.h" - -void CvtHex( - IN HASH Bin, - OUT HASHHEX Hex - ) -{ - unsigned short i; - unsigned char j; - - for (i = 0; i < HASHLEN; i++) { - j = (Bin[i] >> 4) & 0xf; - if (j <= 9) - Hex[i*2] = (j + '0'); - else - Hex[i*2] = (j + 'a' - 10); - j = Bin[i] & 0xf; - if (j <= 9) - Hex[i*2+1] = (j + '0'); - else - Hex[i*2+1] = (j + 'a' - 10); - }; - Hex[HASHHEXLEN] = '\0'; -}; - -/* calculate H(A1) as per spec */ -void DigestCalcHA1( - IN char * pszAlg, - IN char * pszUserName, - IN char * pszRealm, - IN char * pszPassword, - IN char * pszNonce, - IN char * pszCNonce, - OUT HASHHEX SessionKey - ) -{ - MD5_CTX Md5Ctx; - HASH HA1; - - MD5Init(&Md5Ctx); - MD5Update(&Md5Ctx, pszUserName, strlen(pszUserName)); - MD5Update(&Md5Ctx, ":", 1); - MD5Update(&Md5Ctx, pszRealm, strlen(pszRealm)); - MD5Update(&Md5Ctx, ":", 1); - MD5Update(&Md5Ctx, pszPassword, strlen(pszPassword)); - MD5Final(HA1, &Md5Ctx); - if (stricmp(pszAlg, "md5-sess") == 0) { - - - -Franks, et al. Standards Track [Page 28] - -RFC 2617 HTTP Authentication June 1999 - - - MD5Init(&Md5Ctx); - MD5Update(&Md5Ctx, HA1, HASHLEN); - MD5Update(&Md5Ctx, ":", 1); - MD5Update(&Md5Ctx, pszNonce, strlen(pszNonce)); - MD5Update(&Md5Ctx, ":", 1); - MD5Update(&Md5Ctx, pszCNonce, strlen(pszCNonce)); - MD5Final(HA1, &Md5Ctx); - }; - CvtHex(HA1, SessionKey); -}; - -/* calculate request-digest/response-digest as per HTTP Digest spec */ -void DigestCalcResponse( - IN HASHHEX HA1, /* H(A1) */ - IN char * pszNonce, /* nonce from server */ - IN char * pszNonceCount, /* 8 hex digits */ - IN char * pszCNonce, /* client nonce */ - IN char * pszQop, /* qop-value: "", "auth", "auth-int" */ - IN char * pszMethod, /* method from the request */ - IN char * pszDigestUri, /* requested URL */ - IN HASHHEX HEntity, /* H(entity body) if qop="auth-int" */ - OUT HASHHEX Response /* request-digest or response-digest */ - ) -{ - MD5_CTX Md5Ctx; - HASH HA2; - HASH RespHash; - HASHHEX HA2Hex; - - // calculate H(A2) - MD5Init(&Md5Ctx); - MD5Update(&Md5Ctx, pszMethod, strlen(pszMethod)); - MD5Update(&Md5Ctx, ":", 1); - MD5Update(&Md5Ctx, pszDigestUri, strlen(pszDigestUri)); - if (stricmp(pszQop, "auth-int") == 0) { - MD5Update(&Md5Ctx, ":", 1); - MD5Update(&Md5Ctx, HEntity, HASHHEXLEN); - }; - MD5Final(HA2, &Md5Ctx); - CvtHex(HA2, HA2Hex); - - // calculate response - MD5Init(&Md5Ctx); - MD5Update(&Md5Ctx, HA1, HASHHEXLEN); - MD5Update(&Md5Ctx, ":", 1); - MD5Update(&Md5Ctx, pszNonce, strlen(pszNonce)); - MD5Update(&Md5Ctx, ":", 1); - if (*pszQop) { - - - -Franks, et al. Standards Track [Page 29] - -RFC 2617 HTTP Authentication June 1999 - - - MD5Update(&Md5Ctx, pszNonceCount, strlen(pszNonceCount)); - MD5Update(&Md5Ctx, ":", 1); - MD5Update(&Md5Ctx, pszCNonce, strlen(pszCNonce)); - MD5Update(&Md5Ctx, ":", 1); - MD5Update(&Md5Ctx, pszQop, strlen(pszQop)); - MD5Update(&Md5Ctx, ":", 1); - }; - MD5Update(&Md5Ctx, HA2Hex, HASHHEXLEN); - MD5Final(RespHash, &Md5Ctx); - CvtHex(RespHash, Response); -}; - -File "digtest.c": - - -#include <stdio.h> -#include "digcalc.h" - -void main(int argc, char ** argv) { - - char * pszNonce = "dcd98b7102dd2f0e8b11d0f600bfb0c093"; - char * pszCNonce = "0a4f113b"; - char * pszUser = "Mufasa"; - char * pszRealm = "testrealm@host.com"; - char * pszPass = "Circle Of Life"; - char * pszAlg = "md5"; - char szNonceCount[9] = "00000001"; - char * pszMethod = "GET"; - char * pszQop = "auth"; - char * pszURI = "/dir/index.html"; - HASHHEX HA1; - HASHHEX HA2 = ""; - HASHHEX Response; - - DigestCalcHA1(pszAlg, pszUser, pszRealm, pszPass, pszNonce, -pszCNonce, HA1); - DigestCalcResponse(HA1, pszNonce, szNonceCount, pszCNonce, pszQop, - pszMethod, pszURI, HA2, Response); - printf("Response = %s\n", Response); -}; - - - - - - - - - - - -Franks, et al. Standards Track [Page 30] - -RFC 2617 HTTP Authentication June 1999 - - -6 Acknowledgments - - Eric W. Sink, of AbiSource, Inc., was one of the original authors - before the specification underwent substantial revision. - - In addition to the authors, valuable discussion instrumental in - creating this document has come from Peter J. Churchyard, Ned Freed, - and David M. Kristol. - - Jim Gettys and Larry Masinter edited this document for update. - -7 References - - [1] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext - Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996. - - [2] Fielding, R., Gettys, J., Mogul, J., Frysyk, H., Masinter, L., - Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- - HTTP/1.1", RFC 2616, June 1999. - - [3] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April - 1992. - - [4] Freed, N. and N. Borenstein. "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message Bodies", - RFC 2045, November 1996. - - [5] Dierks, T. and C. Allen "The TLS Protocol, Version 1.0", RFC - 2246, January 1999. - - [6] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P., - Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP : - Digest Access Authentication", RFC 2069, January 1997. - - [7] Berners Lee, T, Fielding, R. and L. Masinter, "Uniform Resource - Identifiers (URI): Generic Syntax", RFC 2396, August 1998. - - [8] Kaliski, B.,Robshaw, M., "Message Authentication with MD5", - CryptoBytes, Sping 1995, RSA Inc, - (http://www.rsa.com/rsalabs/pubs/cryptobytes/spring95/md5.htm) - - [9] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP AUTHorize - Extension for Simple Challenge/Response", RFC 2195, September - 1997. - - [10] Morgan, B., Alvestrand, H., Hodges, J., Wahl, M., - "Authentication Methods for LDAP", Work in Progress. - - - - -Franks, et al. Standards Track [Page 31] - -RFC 2617 HTTP Authentication June 1999 - - -8 Authors' Addresses - - John Franks - Professor of Mathematics - Department of Mathematics - Northwestern University - Evanston, IL 60208-2730, USA - - EMail: john@math.nwu.edu - - - Phillip M. Hallam-Baker - Principal Consultant - Verisign Inc. - 301 Edgewater Place - Suite 210 - Wakefield MA 01880, USA - - EMail: pbaker@verisign.com - - - Jeffery L. Hostetler - Software Craftsman - AbiSource, Inc. - 6 Dunlap Court - Savoy, IL 61874 - - EMail: jeff@AbiSource.com - - - Scott D. Lawrence - Agranat Systems, Inc. - 5 Clocktower Place, Suite 400 - Maynard, MA 01754, USA - - EMail: lawrence@agranat.com - - - Paul J. Leach - Microsoft Corporation - 1 Microsoft Way - Redmond, WA 98052, USA - - EMail: paulle@microsoft.com - - - - - - - -Franks, et al. Standards Track [Page 32] - -RFC 2617 HTTP Authentication June 1999 - - - Ari Luotonen - Member of Technical Staff - Netscape Communications Corporation - 501 East Middlefield Road - Mountain View, CA 94043, USA - - - Lawrence C. Stewart - Open Market, Inc. - 215 First Street - Cambridge, MA 02142, USA - - EMail: stewart@OpenMarket.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Franks, et al. Standards Track [Page 33] - -RFC 2617 HTTP Authentication June 1999 - - -9. Full Copyright Statement - - Copyright (C) The Internet Society (1999). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Franks, et al. Standards Track [Page 34] - diff --git a/docs/specs/rfc2817.txt b/docs/specs/rfc2817.txt deleted file mode 100644 index d7b7e703..00000000 --- a/docs/specs/rfc2817.txt +++ /dev/null @@ -1,731 +0,0 @@ - - - - - - -Network Working Group R. Khare -Request for Comments: 2817 4K Associates / UC Irvine -Updates: 2616 S. Lawrence -Category: Standards Track Agranat Systems, Inc. - May 2000 - - - Upgrading to TLS Within HTTP/1.1 - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2000). All Rights Reserved. - -Abstract - - This memo explains how to use the Upgrade mechanism in HTTP/1.1 to - initiate Transport Layer Security (TLS) over an existing TCP - connection. This allows unsecured and secured HTTP traffic to share - the same well known port (in this case, http: at 80 rather than - https: at 443). It also enables "virtual hosting", so a single HTTP + - TLS server can disambiguate traffic intended for several hostnames at - a single IP address. - - Since HTTP/1.1 [1] defines Upgrade as a hop-by-hop mechanism, this - memo also documents the HTTP CONNECT method for establishing end-to- - end tunnels across HTTP proxies. Finally, this memo establishes new - IANA registries for public HTTP status codes, as well as public or - private Upgrade product tokens. - - This memo does NOT affect the current definition of the 'https' URI - scheme, which already defines a separate namespace - (http://example.org/ and https://example.org/ are not equivalent). - - - - - - - - - - - -Khare & Lawrence Standards Track [Page 1] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - -Table of Contents - - 1. Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2.1 Requirements Terminology . . . . . . . . . . . . . . . . . . . 4 - 3. Client Requested Upgrade to HTTP over TLS . . . . . . . . . . 4 - 3.1 Optional Upgrade . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.2 Mandatory Upgrade . . . . . . . . . . . . . . . . . . . . . . 4 - 3.3 Server Acceptance of Upgrade Request . . . . . . . . . . . . . 4 - 4. Server Requested Upgrade to HTTP over TLS . . . . . . . . . . 5 - 4.1 Optional Advertisement . . . . . . . . . . . . . . . . . . . . 5 - 4.2 Mandatory Advertisement . . . . . . . . . . . . . . . . . . . 5 - 5. Upgrade across Proxies . . . . . . . . . . . . . . . . . . . . 6 - 5.1 Implications of Hop By Hop Upgrade . . . . . . . . . . . . . . 6 - 5.2 Requesting a Tunnel with CONNECT . . . . . . . . . . . . . . . 6 - 5.3 Establishing a Tunnel with CONNECT . . . . . . . . . . . . . . 7 - 6. Rationale for the use of a 4xx (client error) Status Code . . 7 - 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 - 7.1 HTTP Status Code Registry . . . . . . . . . . . . . . . . . . 8 - 7.2 HTTP Upgrade Token Registry . . . . . . . . . . . . . . . . . 8 - 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 - 8.1 Implications for the https: URI Scheme . . . . . . . . . . . . 10 - 8.2 Security Considerations for CONNECT . . . . . . . . . . . . . 10 - References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 11 - A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 - Full Copyright Statement . . . . . . . . . . . . . . . . . . . 13 - -1. Motivation - - The historical practice of deploying HTTP over SSL3 [3] has - distinguished the combination from HTTP alone by a unique URI scheme - and the TCP port number. The scheme 'http' meant the HTTP protocol - alone on port 80, while 'https' meant the HTTP protocol over SSL on - port 443. Parallel well-known port numbers have similarly been - requested -- and in some cases, granted -- to distinguish between - secured and unsecured use of other application protocols (e.g. - snews, ftps). This approach effectively halves the number of - available well known ports. - - At the Washington DC IETF meeting in December 1997, the Applications - Area Directors and the IESG reaffirmed that the practice of issuing - parallel "secure" port numbers should be deprecated. The HTTP/1.1 - Upgrade mechanism can apply Transport Layer Security [6] to an open - HTTP connection. - - - - - - -Khare & Lawrence Standards Track [Page 2] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - - In the nearly two years since, there has been broad acceptance of the - concept behind this proposal, but little interest in implementing - alternatives to port 443 for generic Web browsing. In fact, nothing - in this memo affects the current interpretation of https: URIs. - However, new application protocols built atop HTTP, such as the - Internet Printing Protocol [7], call for just such a mechanism in - order to move ahead in the IETF standards process. - - The Upgrade mechanism also solves the "virtual hosting" problem. - Rather than allocating multiple IP addresses to a single host, an - HTTP/1.1 server will use the Host: header to disambiguate the - intended web service. As HTTP/1.1 usage has grown more prevalent, - more ISPs are offering name-based virtual hosting, thus delaying IP - address space exhaustion. - - TLS (and SSL) have been hobbled by the same limitation as earlier - versions of HTTP: the initial handshake does not specify the intended - hostname, relying exclusively on the IP address. Using a cleartext - HTTP/1.1 Upgrade: preamble to the TLS handshake -- choosing the - certificates based on the initial Host: header -- will allow ISPs to - provide secure name-based virtual hosting as well. - -2. Introduction - - TLS, a.k.a., SSL (Secure Sockets Layer), establishes a private end- - to-end connection, optionally including strong mutual authentication, - using a variety of cryptosystems. Initially, a handshake phase uses - three subprotocols to set up a record layer, authenticate endpoints, - set parameters, as well as report errors. Then, there is an ongoing - layered record protocol that handles encryption, compression, and - reassembly for the remainder of the connection. The latter is - intended to be completely transparent. For example, there is no - dependency between TLS's record markers and or certificates and - HTTP/1.1's chunked encoding or authentication. - - Either the client or server can use the HTTP/1.1 [1] Upgrade - mechanism (Section 14.42) to indicate that a TLS-secured connection - is desired or necessary. This memo defines the "TLS/1.0" Upgrade - token, and a new HTTP Status Code, "426 Upgrade Required". - - Section 3 and Section 4 describe the operation of a directly - connected client and server. Intermediate proxies must establish an - end-to-end tunnel before applying those operations, as explained in - Section 5. - - - - - - - -Khare & Lawrence Standards Track [Page 3] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - -2.1 Requirements Terminology - - Keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT" and - "MAY" that appear in this document are to be interpreted as described - in RFC 2119 [11]. - -3. Client Requested Upgrade to HTTP over TLS - - When the client sends an HTTP/1.1 request with an Upgrade header - field containing the token "TLS/1.0", it is requesting the server to - complete the current HTTP/1.1 request after switching to TLS/1.0. - -3.1 Optional Upgrade - - A client MAY offer to switch to secured operation during any clear - HTTP request when an unsecured response would be acceptable: - - GET http://example.bank.com/acct_stat.html?749394889300 HTTP/1.1 - Host: example.bank.com - Upgrade: TLS/1.0 - Connection: Upgrade - - In this case, the server MAY respond to the clear HTTP operation - normally, OR switch to secured operation (as detailed in the next - section). - - Note that HTTP/1.1 [1] specifies "the upgrade keyword MUST be - supplied within a Connection header field (section 14.10) whenever - Upgrade is present in an HTTP/1.1 message". - -3.2 Mandatory Upgrade - - If an unsecured response would be unacceptable, a client MUST send an - OPTIONS request first to complete the switch to TLS/1.0 (if - possible). - - OPTIONS * HTTP/1.1 - Host: example.bank.com - Upgrade: TLS/1.0 - Connection: Upgrade - -3.3 Server Acceptance of Upgrade Request - - As specified in HTTP/1.1 [1], if the server is prepared to initiate - the TLS handshake, it MUST send the intermediate "101 Switching - Protocol" and MUST include an Upgrade response header specifying the - tokens of the protocol stack it is switching to: - - - - -Khare & Lawrence Standards Track [Page 4] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - - HTTP/1.1 101 Switching Protocols - Upgrade: TLS/1.0, HTTP/1.1 - Connection: Upgrade - - Note that the protocol tokens listed in the Upgrade header of a 101 - Switching Protocols response specify an ordered 'bottom-up' stack. - - As specified in HTTP/1.1 [1], Section 10.1.2: "The server will - switch protocols to those defined by the response's Upgrade header - field immediately after the empty line which terminates the 101 - response". - - Once the TLS handshake completes successfully, the server MUST - continue with the response to the original request. Any TLS handshake - failure MUST lead to disconnection, per the TLS error alert - specification. - -4. Server Requested Upgrade to HTTP over TLS - - The Upgrade response header field advertises possible protocol - upgrades a server MAY accept. In conjunction with the "426 Upgrade - Required" status code, a server can advertise the exact protocol - upgrade(s) that a client MUST accept to complete the request. - -4.1 Optional Advertisement - - As specified in HTTP/1.1 [1], the server MAY include an Upgrade - header in any response other than 101 or 426 to indicate a - willingness to switch to any (combination) of the protocols listed. - -4.2 Mandatory Advertisement - - A server MAY indicate that a client request can not be completed - without TLS using the "426 Upgrade Required" status code, which MUST - include an an Upgrade header field specifying the token of the - required TLS version. - - HTTP/1.1 426 Upgrade Required - Upgrade: TLS/1.0, HTTP/1.1 - Connection: Upgrade - - The server SHOULD include a message body in the 426 response which - indicates in human readable form the reason for the error and - describes any alternative courses which may be available to the user. - - Note that even if a client is willing to use TLS, it must use the - operations in Section 3 to proceed; the TLS handshake cannot begin - immediately after the 426 response. - - - -Khare & Lawrence Standards Track [Page 5] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - -5. Upgrade across Proxies - - As a hop-by-hop header, Upgrade is negotiated between each pair of - HTTP counterparties. If a User Agent sends a request with an Upgrade - header to a proxy, it is requesting a change to the protocol between - itself and the proxy, not an end-to-end change. - - Since TLS, in particular, requires end-to-end connectivity to provide - authentication and prevent man-in-the-middle attacks, this memo - specifies the CONNECT method to establish a tunnel across proxies. - - Once a tunnel is established, any of the operations in Section 3 can - be used to establish a TLS connection. - -5.1 Implications of Hop By Hop Upgrade - - If an origin server receives an Upgrade header from a proxy and - responds with a 101 Switching Protocols response, it is changing the - protocol only on the connection between the proxy and itself. - Similarly, a proxy might return a 101 response to its client to - change the protocol on that connection independently of the protocols - it is using to communicate toward the origin server. - - These scenarios also complicate diagnosis of a 426 response. Since - Upgrade is a hop-by-hop header, a proxy that does not recognize 426 - might remove the accompanying Upgrade header and prevent the client - from determining the required protocol switch. If a client receives - a 426 status without an accompanying Upgrade header, it will need to - request an end to end tunnel connection as described in Section 5.2 - and repeat the request in order to obtain the required upgrade - information. - - This hop-by-hop definition of Upgrade was a deliberate choice. It - allows for incremental deployment on either side of proxies, and for - optimized protocols between cascaded proxies without the knowledge of - the parties that are not a part of the change. - -5.2 Requesting a Tunnel with CONNECT - - A CONNECT method requests that a proxy establish a tunnel connection - on its behalf. The Request-URI portion of the Request-Line is always - an 'authority' as defined by URI Generic Syntax [2], which is to say - the host name and port number destination of the requested connection - separated by a colon: - - CONNECT server.example.com:80 HTTP/1.1 - Host: server.example.com:80 - - - - -Khare & Lawrence Standards Track [Page 6] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - - Other HTTP mechanisms can be used normally with the CONNECT method -- - except end-to-end protocol Upgrade requests, of course, since the - tunnel must be established first. - - For example, proxy authentication might be used to establish the - authority to create a tunnel: - - CONNECT server.example.com:80 HTTP/1.1 - Host: server.example.com:80 - Proxy-Authorization: basic aGVsbG86d29ybGQ= - - Like any other pipelined HTTP/1.1 request, data to be tunneled may be - sent immediately after the blank line. The usual caveats also apply: - data may be discarded if the eventual response is negative, and the - connection may be reset with no response if more than one TCP segment - is outstanding. - -5.3 Establishing a Tunnel with CONNECT - - Any successful (2xx) response to a CONNECT request indicates that the - proxy has established a connection to the requested host and port, - and has switched to tunneling the current connection to that server - connection. - - It may be the case that the proxy itself can only reach the requested - origin server through another proxy. In this case, the first proxy - SHOULD make a CONNECT request of that next proxy, requesting a tunnel - to the authority. A proxy MUST NOT respond with any 2xx status code - unless it has either a direct or tunnel connection established to the - authority. - - An origin server which receives a CONNECT request for itself MAY - respond with a 2xx status code to indicate that a connection is - established. - - If at any point either one of the peers gets disconnected, any - outstanding data that came from that peer will be passed to the other - one, and after that also the other connection will be terminated by - the proxy. If there is outstanding data to that peer undelivered, - that data will be discarded. - -6. Rationale for the use of a 4xx (client error) Status Code - - Reliable, interoperable negotiation of Upgrade features requires an - unambiguous failure signal. The 426 Upgrade Required status code - allows a server to definitively state the precise protocol extensions - a given resource must be served with. - - - - -Khare & Lawrence Standards Track [Page 7] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - - It might at first appear that the response should have been some form - of redirection (a 3xx code), by analogy to an old-style redirection - to an https: URI. User agents that do not understand Upgrade: - preclude this. - - Suppose that a 3xx code had been assigned for "Upgrade Required"; a - user agent that did not recognize it would treat it as 300. It would - then properly look for a "Location" header in the response and - attempt to repeat the request at the URL in that header field. Since - it did not know to Upgrade to incorporate the TLS layer, it would at - best fail again at the new URL. - -7. IANA Considerations - - IANA shall create registries for two name spaces, as described in BCP - 26 [10]: - - o HTTP Status Codes - o HTTP Upgrade Tokens - -7.1 HTTP Status Code Registry - - The HTTP Status Code Registry defines the name space for the Status- - Code token in the Status line of an HTTP response. The initial - values for this name space are those specified by: - - 1. Draft Standard for HTTP/1.1 [1] - 2. Web Distributed Authoring and Versioning [4] [defines 420-424] - 3. WebDAV Advanced Collections [5] (Work in Progress) [defines 425] - 4. Section 6 [defines 426] - - Values to be added to this name space SHOULD be subject to review in - the form of a standards track document within the IETF Applications - Area. Any such document SHOULD be traceable through statuses of - either 'Obsoletes' or 'Updates' to the Draft Standard for - HTTP/1.1 [1]. - -7.2 HTTP Upgrade Token Registry - - The HTTP Upgrade Token Registry defines the name space for product - tokens used to identify protocols in the Upgrade HTTP header field. - Each registered token should be associated with one or a set of - specifications, and with contact information. - - The Draft Standard for HTTP/1.1 [1] specifies that these tokens obey - the production for 'product': - - - - - -Khare & Lawrence Standards Track [Page 8] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - - product = token ["/" product-version] - product-version = token - - Registrations should be allowed on a First Come First Served basis as - described in BCP 26 [10]. These specifications need not be IETF - documents or be subject to IESG review, but should obey the following - rules: - - 1. A token, once registered, stays registered forever. - 2. The registration MUST name a responsible party for the - registration. - 3. The registration MUST name a point of contact. - 4. The registration MAY name the documentation required for the - token. - 5. The responsible party MAY change the registration at any time. - The IANA will keep a record of all such changes, and make them - available upon request. - 6. The responsible party for the first registration of a "product" - token MUST approve later registrations of a "version" token - together with that "product" token before they can be registered. - 7. If absolutely required, the IESG MAY reassign the responsibility - for a token. This will normally only be used in the case when a - responsible party cannot be contacted. - - This specification defines the protocol token "TLS/1.0" as the - identifier for the protocol specified by The TLS Protocol [6]. - - It is NOT required that specifications for upgrade tokens be made - publicly available, but the contact information for the registration - SHOULD be. - -8. Security Considerations - - The potential for a man-in-the-middle attack (deleting the Upgrade - header) remains the same as current, mixed http/https practice: - - o Removing the Upgrade header is similar to rewriting web pages to - change https:// links to http:// links. - o The risk is only present if the server is willing to vend such - information over both a secure and an insecure channel in the - first place. - o If the client knows for a fact that a server is TLS-compliant, it - can insist on it by only sending an Upgrade request with a no-op - method like OPTIONS. - o Finally, as the https: specification warns, "users should - carefully examine the certificate presented by the server to - determine if it meets their expectations". - - - - -Khare & Lawrence Standards Track [Page 9] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - - Furthermore, for clients that do not explicitly try to invoke TLS, - servers can use the Upgrade header in any response other than 101 or - 426 to advertise TLS compliance. Since TLS compliance should be - considered a feature of the server and not the resource at hand, it - should be sufficient to send it once, and let clients cache that - fact. - -8.1 Implications for the https: URI Scheme - - While nothing in this memo affects the definition of the 'https' URI - scheme, widespread adoption of this mechanism for HyperText content - could use 'http' to identify both secure and non-secure resources. - - The choice of what security characteristics are required on the - connection is left to the client and server. This allows either - party to use any information available in making this determination. - For example, user agents may rely on user preference settings or - information about the security of the network such as 'TLS required - on all POST operations not on my local net', or servers may apply - resource access rules such as 'the FORM on this page must be served - and submitted using TLS'. - -8.2 Security Considerations for CONNECT - - A generic TCP tunnel is fraught with security risks. First, such - authorization should be limited to a small number of known ports. - The Upgrade: mechanism defined here only requires onward tunneling at - port 80. Second, since tunneled data is opaque to the proxy, there - are additional risks to tunneling to other well-known or reserved - ports. A putative HTTP client CONNECTing to port 25 could relay spam - via SMTP, for example. - -References - - [1] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., - Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- - HTTP/1.1", RFC 2616, June 1999. - - [2] Berners-Lee, T., Fielding, R. and L. Masinter, "URI Generic - Syntax", RFC 2396, August 1998. - - [3] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. - - [4] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D. Jensen, - "Web Distributed Authoring and Versioning", RFC 2518, February - 1999. - - - - - -Khare & Lawrence Standards Track [Page 10] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - - [5] Slein, J., Whitehead, E.J., et al., "WebDAV Advanced Collections - Protocol", Work In Progress. - - [6] Dierks, T. and C. Allen, "The TLS Protocol", RFC 2246, January - 1999. - - [7] Herriot, R., Butler, S., Moore, P. and R. Turner, "Internet - Printing Protocol/1.0: Encoding and Transport", RFC 2565, April - 1999. - - [8] Luotonen, A., "Tunneling TCP based protocols through Web proxy - servers", Work In Progress. (Also available in: Luotonen, Ari. - Web Proxy Servers, Prentice-Hall, 1997 ISBN:0136806120.) - - [9] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June - 1999. - - [10] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA - Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. - - [11] Bradner, S., "Key words for use in RFCs to Indicate Requirement - Levels", BCP 14, RFC 2119, March 1997. - -Authors' Addresses - - Rohit Khare - 4K Associates / UC Irvine - 3207 Palo Verde - Irvine, CA 92612 - US - - Phone: +1 626 806 7574 - EMail: rohit@4K-associates.com - URI: http://www.4K-associates.com/ - - - Scott Lawrence - Agranat Systems, Inc. - 5 Clocktower Place - Suite 400 - Maynard, MA 01754 - US - - Phone: +1 978 461 0888 - EMail: lawrence@agranat.com - URI: http://www.agranat.com/ - - - - - -Khare & Lawrence Standards Track [Page 11] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - -Appendix A. Acknowledgments - - The CONNECT method was originally described in a Work in Progress - titled, "Tunneling TCP based protocols through Web proxy servers", - [8] by Ari Luotonen of Netscape Communications Corporation. It was - widely implemented by HTTP proxies, but was never made a part of any - IETF Standards Track document. The method name CONNECT was reserved, - but not defined in [1]. - - The definition provided here is derived directly from that earlier - memo, with some editorial changes and conformance to the stylistic - conventions since established in other HTTP specifications. - - Additional Thanks to: - - o Paul Hoffman for his work on the STARTTLS command extension for - ESMTP. - o Roy Fielding for assistance with the rationale behind Upgrade: - and its interaction with OPTIONS. - o Eric Rescorla for his work on standardizing the existing https: - practice to compare with. - o Marshall Rose, for the xml2rfc document type description and tools - [9]. - o Jim Whitehead, for sorting out the current range of available HTTP - status codes. - o Henrik Frystyk Nielsen, whose work on the Mandatory extension - mechanism pointed out a hop-by-hop Upgrade still requires - tunneling. - o Harald Alvestrand for improvements to the token registration - rules. - - - - - - - - - - - - - - - - - - - - - -Khare & Lawrence Standards Track [Page 12] - -RFC 2817 HTTP Upgrade to TLS May 2000 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2000). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Khare & Lawrence Standards Track [Page 13] - diff --git a/docs/specs/rfc2818.txt b/docs/specs/rfc2818.txt deleted file mode 100644 index 219a1c42..00000000 --- a/docs/specs/rfc2818.txt +++ /dev/null @@ -1,395 +0,0 @@ - - - - - - -Network Working Group E. Rescorla -Request for Comments: 2818 RTFM, Inc. -Category: Informational May 2000 - - - HTTP Over TLS - -Status of this Memo - - This memo provides information for the Internet community. It does - not specify an Internet standard of any kind. Distribution of this - memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2000). All Rights Reserved. - -Abstract - - This memo describes how to use TLS to secure HTTP connections over - the Internet. Current practice is to layer HTTP over SSL (the - predecessor to TLS), distinguishing secured traffic from insecure - traffic by the use of a different server port. This document - documents that practice using TLS. A companion document describes a - method for using HTTP/TLS over the same port as normal HTTP - [RFC2817]. - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . 2 - 1.1. Requirements Terminology . . . . . . . . . . . . . . . 2 - 2. HTTP Over TLS . . . . . . . . . . . . . . . . . . . . . . 2 - 2.1. Connection Initiation . . . . . . . . . . . . . . . . . 2 - 2.2. Connection Closure . . . . . . . . . . . . . . . . . . 2 - 2.2.1. Client Behavior . . . . . . . . . . . . . . . . . . . 3 - 2.2.2. Server Behavior . . . . . . . . . . . . . . . . . . . 3 - 2.3. Port Number . . . . . . . . . . . . . . . . . . . . . . 4 - 2.4. URI Format . . . . . . . . . . . . . . . . . . . . . . 4 - 3. Endpoint Identification . . . . . . . . . . . . . . . . . 4 - 3.1. Server Identity . . . . . . . . . . . . . . . . . . . . 4 - 3.2. Client Identity . . . . . . . . . . . . . . . . . . . . 5 - References . . . . . . . . . . . . . . . . . . . . . . . . . 6 - Security Considerations . . . . . . . . . . . . . . . . . . 6 - Author's Address . . . . . . . . . . . . . . . . . . . . . . 6 - Full Copyright Statement . . . . . . . . . . . . . . . . . . 7 - - - - - - -Rescorla Informational [Page 1] - -RFC 2818 HTTP Over TLS May 2000 - - -1. Introduction - - HTTP [RFC2616] was originally used in the clear on the Internet. - However, increased use of HTTP for sensitive applications has - required security measures. SSL, and its successor TLS [RFC2246] were - designed to provide channel-oriented security. This document - describes how to use HTTP over TLS. - -1.1. Requirements Terminology - - Keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT" and - "MAY" that appear in this document are to be interpreted as described - in [RFC2119]. - -2. HTTP Over TLS - - Conceptually, HTTP/TLS is very simple. Simply use HTTP over TLS - precisely as you would use HTTP over TCP. - -2.1. Connection Initiation - - The agent acting as the HTTP client should also act as the TLS - client. It should initiate a connection to the server on the - appropriate port and then send the TLS ClientHello to begin the TLS - handshake. When the TLS handshake has finished. The client may then - initiate the first HTTP request. All HTTP data MUST be sent as TLS - "application data". Normal HTTP behavior, including retained - connections should be followed. - -2.2. Connection Closure - - TLS provides a facility for secure connection closure. When a valid - closure alert is received, an implementation can be assured that no - further data will be received on that connection. TLS - implementations MUST initiate an exchange of closure alerts before - closing a connection. A TLS implementation MAY, after sending a - closure alert, close the connection without waiting for the peer to - send its closure alert, generating an "incomplete close". Note that - an implementation which does this MAY choose to reuse the session. - This SHOULD only be done when the application knows (typically - through detecting HTTP message boundaries) that it has received all - the message data that it cares about. - - As specified in [RFC2246], any implementation which receives a - connection close without first receiving a valid closure alert (a - "premature close") MUST NOT reuse that session. Note that a - premature close does not call into question the security of the data - already received, but simply indicates that subsequent data might - - - -Rescorla Informational [Page 2] - -RFC 2818 HTTP Over TLS May 2000 - - - have been truncated. Because TLS is oblivious to HTTP - request/response boundaries, it is necessary to examine the HTTP data - itself (specifically the Content-Length header) to determine whether - the truncation occurred inside a message or between messages. - -2.2.1. Client Behavior - - Because HTTP uses connection closure to signal end of server data, - client implementations MUST treat any premature closes as errors and - the data received as potentially truncated. While in some cases the - HTTP protocol allows the client to find out whether truncation took - place so that, if it received the complete reply, it may tolerate - such errors following the principle to "[be] strict when sending and - tolerant when receiving" [RFC1958], often truncation does not show in - the HTTP protocol data; two cases in particular deserve special note: - - A HTTP response without a Content-Length header. Since data length - in this situation is signalled by connection close a premature - close generated by the server cannot be distinguished from a - spurious close generated by an attacker. - - A HTTP response with a valid Content-Length header closed before - all data has been read. Because TLS does not provide document - oriented protection, it is impossible to determine whether the - server has miscomputed the Content-Length or an attacker has - truncated the connection. - - There is one exception to the above rule. When encountering a - premature close, a client SHOULD treat as completed all requests for - which it has received as much data as specified in the Content-Length - header. - - A client detecting an incomplete close SHOULD recover gracefully. It - MAY resume a TLS session closed in this fashion. - - Clients MUST send a closure alert before closing the connection. - Clients which are unprepared to receive any more data MAY choose not - to wait for the server's closure alert and simply close the - connection, thus generating an incomplete close on the server side. - -2.2.2. Server Behavior - - RFC 2616 permits an HTTP client to close the connection at any time, - and requires servers to recover gracefully. In particular, servers - SHOULD be prepared to receive an incomplete close from the client, - since the client can often determine when the end of server data is. - Servers SHOULD be willing to resume TLS sessions closed in this - fashion. - - - -Rescorla Informational [Page 3] - -RFC 2818 HTTP Over TLS May 2000 - - - Implementation note: In HTTP implementations which do not use - persistent connections, the server ordinarily expects to be able to - signal end of data by closing the connection. When Content-Length is - used, however, the client may have already sent the closure alert and - dropped the connection. - - Servers MUST attempt to initiate an exchange of closure alerts with - the client before closing the connection. Servers MAY close the - connection after sending the closure alert, thus generating an - incomplete close on the client side. - -2.3. Port Number - - The first data that an HTTP server expects to receive from the client - is the Request-Line production. The first data that a TLS server (and - hence an HTTP/TLS server) expects to receive is the ClientHello. - Consequently, common practice has been to run HTTP/TLS over a - separate port in order to distinguish which protocol is being used. - When HTTP/TLS is being run over a TCP/IP connection, the default port - is 443. This does not preclude HTTP/TLS from being run over another - transport. TLS only presumes a reliable connection-oriented data - stream. - -2.4. URI Format - - HTTP/TLS is differentiated from HTTP URIs by using the 'https' - protocol identifier in place of the 'http' protocol identifier. An - example URI specifying HTTP/TLS is: - - https://www.example.com/~smith/home.html - -3. Endpoint Identification - -3.1. Server Identity - - In general, HTTP/TLS requests are generated by dereferencing a URI. - As a consequence, the hostname for the server is known to the client. - If the hostname is available, the client MUST check it against the - server's identity as presented in the server's Certificate message, - in order to prevent man-in-the-middle attacks. - - If the client has external information as to the expected identity of - the server, the hostname check MAY be omitted. (For instance, a - client may be connecting to a machine whose address and hostname are - dynamic but the client knows the certificate that the server will - present.) In such cases, it is important to narrow the scope of - acceptable certificates as much as possible in order to prevent man - - - - -Rescorla Informational [Page 4] - -RFC 2818 HTTP Over TLS May 2000 - - - in the middle attacks. In special cases, it may be appropriate for - the client to simply ignore the server's identity, but it must be - understood that this leaves the connection open to active attack. - - If a subjectAltName extension of type dNSName is present, that MUST - be used as the identity. Otherwise, the (most specific) Common Name - field in the Subject field of the certificate MUST be used. Although - the use of the Common Name is existing practice, it is deprecated and - Certification Authorities are encouraged to use the dNSName instead. - - Matching is performed using the matching rules specified by - [RFC2459]. If more than one identity of a given type is present in - the certificate (e.g., more than one dNSName name, a match in any one - of the set is considered acceptable.) Names may contain the wildcard - character * which is considered to match any single domain name - component or component fragment. E.g., *.a.com matches foo.a.com but - not bar.foo.a.com. f*.com matches foo.com but not bar.com. - - In some cases, the URI is specified as an IP address rather than a - hostname. In this case, the iPAddress subjectAltName must be present - in the certificate and must exactly match the IP in the URI. - - If the hostname does not match the identity in the certificate, user - oriented clients MUST either notify the user (clients MAY give the - user the opportunity to continue with the connection in any case) or - terminate the connection with a bad certificate error. Automated - clients MUST log the error to an appropriate audit log (if available) - and SHOULD terminate the connection (with a bad certificate error). - Automated clients MAY provide a configuration setting that disables - this check, but MUST provide a setting which enables it. - - Note that in many cases the URI itself comes from an untrusted - source. The above-described check provides no protection against - attacks where this source is compromised. For example, if the URI was - obtained by clicking on an HTML page which was itself obtained - without using HTTP/TLS, a man in the middle could have replaced the - URI. In order to prevent this form of attack, users should carefully - examine the certificate presented by the server to determine if it - meets their expectations. - -3.2. Client Identity - - Typically, the server has no external knowledge of what the client's - identity ought to be and so checks (other than that the client has a - certificate chain rooted in an appropriate CA) are not possible. If a - server has such knowledge (typically from some source external to - HTTP or TLS) it SHOULD check the identity as described above. - - - - -Rescorla Informational [Page 5] - -RFC 2818 HTTP Over TLS May 2000 - - -References - - [RFC2459] Housley, R., Ford, W., Polk, W. and D. Solo, "Internet - Public Key Infrastructure: Part I: X.509 Certificate and - CRL Profile", RFC 2459, January 1999. - - [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, - L., Leach, P. and T. Berners-Lee, "Hypertext Transfer - Protocol, HTTP/1.1", RFC 2616, June 1999. - - [RFC2119] Bradner, S., "Key Words for use in RFCs to indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol", RFC 2246, - January 1999. - - [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within - HTTP/1.1", RFC 2817, May 2000. - -Security Considerations - - This entire document is about security. - -Author's Address - - Eric Rescorla - RTFM, Inc. - 30 Newell Road, #16 - East Palo Alto, CA 94303 - - Phone: (650) 328-8631 - EMail: ekr@rtfm.com - - - - - - - - - - - - - - - - - - - -Rescorla Informational [Page 6] - -RFC 2818 HTTP Over TLS May 2000 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2000). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Rescorla Informational [Page 7] - diff --git a/docs/specs/rfc2965.txt b/docs/specs/rfc2965.txt deleted file mode 100644 index 8a4d02b1..00000000 --- a/docs/specs/rfc2965.txt +++ /dev/null @@ -1,1459 +0,0 @@ - - - - - - -Network Working Group D. Kristol -Request for Comments: 2965 Bell Laboratories, Lucent Technologies -Obsoletes: 2109 L. Montulli -Category: Standards Track Epinions.com, Inc. - October 2000 - - - HTTP State Management Mechanism - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2000). All Rights Reserved. - -IESG Note - - The IESG notes that this mechanism makes use of the .local top-level - domain (TLD) internally when handling host names that don't contain - any dots, and that this mechanism might not work in the expected way - should an actual .local TLD ever be registered. - -Abstract - - This document specifies a way to create a stateful session with - Hypertext Transfer Protocol (HTTP) requests and responses. It - describes three new headers, Cookie, Cookie2, and Set-Cookie2, which - carry state information between participating origin servers and user - agents. The method described here differs from Netscape's Cookie - proposal [Netscape], but it can interoperate with HTTP/1.0 user - agents that use Netscape's method. (See the HISTORICAL section.) - - This document reflects implementation experience with RFC 2109 and - obsoletes it. - -1. TERMINOLOGY - - The terms user agent, client, server, proxy, origin server, and - http_URL have the same meaning as in the HTTP/1.1 specification - [RFC2616]. The terms abs_path and absoluteURI have the same meaning - as in the URI Syntax specification [RFC2396]. - - - - -Kristol & Montulli Standards Track [Page 1] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - Host name (HN) means either the host domain name (HDN) or the numeric - Internet Protocol (IP) address of a host. The fully qualified domain - name is preferred; use of numeric IP addresses is strongly - discouraged. - - The terms request-host and request-URI refer to the values the client - would send to the server as, respectively, the host (but not port) - and abs_path portions of the absoluteURI (http_URL) of the HTTP - request line. Note that request-host is a HN. - - The term effective host name is related to host name. If a host name - contains no dots, the effective host name is that name with the - string .local appended to it. Otherwise the effective host name is - the same as the host name. Note that all effective host names - contain at least one dot. - - The term request-port refers to the port portion of the absoluteURI - (http_URL) of the HTTP request line. If the absoluteURI has no - explicit port, the request-port is the HTTP default, 80. The - request-port of a cookie is the request-port of the request in which - a Set-Cookie2 response header was returned to the user agent. - - Host names can be specified either as an IP address or a HDN string. - Sometimes we compare one host name with another. (Such comparisons - SHALL be case-insensitive.) Host A's name domain-matches host B's if - - * their host name strings string-compare equal; or - - * A is a HDN string and has the form NB, where N is a non-empty - name string, B has the form .B', and B' is a HDN string. (So, - x.y.com domain-matches .Y.com but not Y.com.) - - Note that domain-match is not a commutative operation: a.b.c.com - domain-matches .c.com, but not the reverse. - - The reach R of a host name H is defined as follows: - - * If - - - H is the host domain name of a host; and, - - - H has the form A.B; and - - - A has no embedded (that is, interior) dots; and - - - B has at least one embedded dot, or B is the string "local". - then the reach of H is .B. - - - - -Kristol & Montulli Standards Track [Page 2] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - * Otherwise, the reach of H is H. - - For two strings that represent paths, P1 and P2, P1 path-matches P2 - if P2 is a prefix of P1 (including the case where P1 and P2 string- - compare equal). Thus, the string /tec/waldo path-matches /tec. - - Because it was used in Netscape's original implementation of state - management, we will use the term cookie to refer to the state - information that passes between an origin server and user agent, and - that gets stored by the user agent. - -1.1 Requirements - - The key words "MAY", "MUST", "MUST NOT", "OPTIONAL", "RECOMMENDED", - "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT" in this - document are to be interpreted as described in RFC 2119 [RFC2119]. - -2. STATE AND SESSIONS - - This document describes a way to create stateful sessions with HTTP - requests and responses. Currently, HTTP servers respond to each - client request without relating that request to previous or - subsequent requests; the state management mechanism allows clients - and servers that wish to exchange state information to place HTTP - requests and responses within a larger context, which we term a - "session". This context might be used to create, for example, a - "shopping cart", in which user selections can be aggregated before - purchase, or a magazine browsing system, in which a user's previous - reading affects which offerings are presented. - - Neither clients nor servers are required to support cookies. A - server MAY refuse to provide content to a client that does not return - the cookies it sends. - -3. DESCRIPTION - - We describe here a way for an origin server to send state information - to the user agent, and for the user agent to return the state - information to the origin server. The goal is to have a minimal - impact on HTTP and user agents. - -3.1 Syntax: General - - The two state management headers, Set-Cookie2 and Cookie, have common - syntactic properties involving attribute-value pairs. The following - grammar uses the notation, and tokens DIGIT (decimal digits), token - - - - - -Kristol & Montulli Standards Track [Page 3] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - (informally, a sequence of non-special, non-white space characters), - and http_URL from the HTTP/1.1 specification [RFC2616] to describe - their syntax. - - av-pairs = av-pair *(";" av-pair) - av-pair = attr ["=" value] ; optional value - attr = token - value = token | quoted-string - - Attributes (names) (attr) are case-insensitive. White space is - permitted between tokens. Note that while the above syntax - description shows value as optional, most attrs require them. - - NOTE: The syntax above allows whitespace between the attribute and - the = sign. - -3.2 Origin Server Role - - 3.2.1 General The origin server initiates a session, if it so - desires. To do so, it returns an extra response header to the - client, Set-Cookie2. (The details follow later.) - - A user agent returns a Cookie request header (see below) to the - origin server if it chooses to continue a session. The origin server - MAY ignore it or use it to determine the current state of the - session. It MAY send back to the client a Set-Cookie2 response - header with the same or different information, or it MAY send no - Set-Cookie2 header at all. The origin server effectively ends a - session by sending the client a Set-Cookie2 header with Max-Age=0. - - Servers MAY return Set-Cookie2 response headers with any response. - User agents SHOULD send Cookie request headers, subject to other - rules detailed below, with every request. - - An origin server MAY include multiple Set-Cookie2 headers in a - response. Note that an intervening gateway could fold multiple such - headers into a single header. - - - - - - - - - - - - - - -Kristol & Montulli Standards Track [Page 4] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - 3.2.2 Set-Cookie2 Syntax The syntax for the Set-Cookie2 response - header is - - set-cookie = "Set-Cookie2:" cookies - cookies = 1#cookie - cookie = NAME "=" VALUE *(";" set-cookie-av) - NAME = attr - VALUE = value - set-cookie-av = "Comment" "=" value - | "CommentURL" "=" <"> http_URL <"> - | "Discard" - | "Domain" "=" value - | "Max-Age" "=" value - | "Path" "=" value - | "Port" [ "=" <"> portlist <"> ] - | "Secure" - | "Version" "=" 1*DIGIT - portlist = 1#portnum - portnum = 1*DIGIT - - Informally, the Set-Cookie2 response header comprises the token Set- - Cookie2:, followed by a comma-separated list of one or more cookies. - Each cookie begins with a NAME=VALUE pair, followed by zero or more - semi-colon-separated attribute-value pairs. The syntax for - attribute-value pairs was shown earlier. The specific attributes and - the semantics of their values follows. The NAME=VALUE attribute- - value pair MUST come first in each cookie. The others, if present, - can occur in any order. If an attribute appears more than once in a - cookie, the client SHALL use only the value associated with the first - appearance of the attribute; a client MUST ignore values after the - first. - - The NAME of a cookie MAY be the same as one of the attributes in this - specification. However, because the cookie's NAME must come first in - a Set-Cookie2 response header, the NAME and its VALUE cannot be - confused with an attribute-value pair. - - NAME=VALUE - REQUIRED. The name of the state information ("cookie") is NAME, - and its value is VALUE. NAMEs that begin with $ are reserved and - MUST NOT be used by applications. - - The VALUE is opaque to the user agent and may be anything the - origin server chooses to send, possibly in a server-selected - printable ASCII encoding. "Opaque" implies that the content is of - interest and relevance only to the origin server. The content - may, in fact, be readable by anyone that examines the Set-Cookie2 - header. - - - -Kristol & Montulli Standards Track [Page 5] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - Comment=value - OPTIONAL. Because cookies can be used to derive or store private - information about a user, the value of the Comment attribute - allows an origin server to document how it intends to use the - cookie. The user can inspect the information to decide whether to - initiate or continue a session with this cookie. Characters in - value MUST be in UTF-8 encoding. [RFC2279] - - CommentURL="http_URL" - OPTIONAL. Because cookies can be used to derive or store private - information about a user, the CommentURL attribute allows an - origin server to document how it intends to use the cookie. The - user can inspect the information identified by the URL to decide - whether to initiate or continue a session with this cookie. - - Discard - OPTIONAL. The Discard attribute instructs the user agent to - discard the cookie unconditionally when the user agent terminates. - - Domain=value - OPTIONAL. The value of the Domain attribute specifies the domain - for which the cookie is valid. If an explicitly specified value - does not start with a dot, the user agent supplies a leading dot. - - Max-Age=value - OPTIONAL. The value of the Max-Age attribute is delta-seconds, - the lifetime of the cookie in seconds, a decimal non-negative - integer. To handle cached cookies correctly, a client SHOULD - calculate the age of the cookie according to the age calculation - rules in the HTTP/1.1 specification [RFC2616]. When the age is - greater than delta-seconds seconds, the client SHOULD discard the - cookie. A value of zero means the cookie SHOULD be discarded - immediately. - - Path=value - OPTIONAL. The value of the Path attribute specifies the subset of - URLs on the origin server to which this cookie applies. - - Port[="portlist"] - OPTIONAL. The Port attribute restricts the port to which a cookie - may be returned in a Cookie request header. Note that the syntax - REQUIREs quotes around the OPTIONAL portlist even if there is only - one portnum in portlist. - - - - - - - - -Kristol & Montulli Standards Track [Page 6] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - Secure - OPTIONAL. The Secure attribute (with no value) directs the user - agent to use only (unspecified) secure means to contact the origin - server whenever it sends back this cookie, to protect the - confidentially and authenticity of the information in the cookie. - - The user agent (possibly with user interaction) MAY determine what - level of security it considers appropriate for "secure" cookies. - The Secure attribute should be considered security advice from the - server to the user agent, indicating that it is in the session's - interest to protect the cookie contents. When it sends a "secure" - cookie back to a server, the user agent SHOULD use no less than - the same level of security as was used when it received the cookie - from the server. - - Version=value - REQUIRED. The value of the Version attribute, a decimal integer, - identifies the version of the state management specification to - which the cookie conforms. For this specification, Version=1 - applies. - - 3.2.3 Controlling Caching An origin server must be cognizant of the - effect of possible caching of both the returned resource and the - Set-Cookie2 header. Caching "public" documents is desirable. For - example, if the origin server wants to use a public document such as - a "front door" page as a sentinel to indicate the beginning of a - session for which a Set-Cookie2 response header must be generated, - the page SHOULD be stored in caches "pre-expired" so that the origin - server will see further requests. "Private documents", for example - those that contain information strictly private to a session, SHOULD - NOT be cached in shared caches. - - If the cookie is intended for use by a single user, the Set-Cookie2 - header SHOULD NOT be cached. A Set-Cookie2 header that is intended - to be shared by multiple users MAY be cached. - - The origin server SHOULD send the following additional HTTP/1.1 - response headers, depending on circumstances: - - * To suppress caching of the Set-Cookie2 header: - - Cache-control: no-cache="set-cookie2" - - and one of the following: - - * To suppress caching of a private document in shared caches: - - Cache-control: private - - - -Kristol & Montulli Standards Track [Page 7] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - * To allow caching of a document and require that it be validated - before returning it to the client: - - Cache-Control: must-revalidate, max-age=0 - - * To allow caching of a document, but to require that proxy - caches (not user agent caches) validate it before returning it - to the client: - - Cache-Control: proxy-revalidate, max-age=0 - - * To allow caching of a document and request that it be validated - before returning it to the client (by "pre-expiring" it): - - Cache-control: max-age=0 - - Not all caches will revalidate the document in every case. - - HTTP/1.1 servers MUST send Expires: old-date (where old-date is a - date long in the past) on responses containing Set-Cookie2 response - headers unless they know for certain (by out of band means) that - there are no HTTP/1.0 proxies in the response chain. HTTP/1.1 - servers MAY send other Cache-Control directives that permit caching - by HTTP/1.1 proxies in addition to the Expires: old-date directive; - the Cache-Control directive will override the Expires: old-date for - HTTP/1.1 proxies. - -3.3 User Agent Role - - 3.3.1 Interpreting Set-Cookie2 The user agent keeps separate track - of state information that arrives via Set-Cookie2 response headers - from each origin server (as distinguished by name or IP address and - port). The user agent MUST ignore attribute-value pairs whose - attribute it does not recognize. The user agent applies these - defaults for optional attributes that are missing: - - Discard The default behavior is dictated by the presence or absence - of a Max-Age attribute. - - Domain Defaults to the effective request-host. (Note that because - there is no dot at the beginning of effective request-host, - the default Domain can only domain-match itself.) - - Max-Age The default behavior is to discard the cookie when the user - agent exits. - - Path Defaults to the path of the request URL that generated the - Set-Cookie2 response, up to and including the right-most /. - - - -Kristol & Montulli Standards Track [Page 8] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - Port The default behavior is that a cookie MAY be returned to any - request-port. - - Secure If absent, the user agent MAY send the cookie over an - insecure channel. - - 3.3.2 Rejecting Cookies To prevent possible security or privacy - violations, a user agent rejects a cookie according to rules below. - The goal of the rules is to try to limit the set of servers for which - a cookie is valid, based on the values of the Path, Domain, and Port - attributes and the request-URI, request-host and request-port. - - A user agent rejects (SHALL NOT store its information) if the Version - attribute is missing. Moreover, a user agent rejects (SHALL NOT - store its information) if any of the following is true of the - attributes explicitly present in the Set-Cookie2 response header: - - * The value for the Path attribute is not a prefix of the - request-URI. - - * The value for the Domain attribute contains no embedded dots, - and the value is not .local. - - * The effective host name that derives from the request-host does - not domain-match the Domain attribute. - - * The request-host is a HDN (not IP address) and has the form HD, - where D is the value of the Domain attribute, and H is a string - that contains one or more dots. - - * The Port attribute has a "port-list", and the request-port was - not in the list. - - Examples: - - * A Set-Cookie2 from request-host y.x.foo.com for Domain=.foo.com - would be rejected, because H is y.x and contains a dot. - - * A Set-Cookie2 from request-host x.foo.com for Domain=.foo.com - would be accepted. - - * A Set-Cookie2 with Domain=.com or Domain=.com., will always be - rejected, because there is no embedded dot. - - * A Set-Cookie2 with Domain=ajax.com will be accepted, and the - value for Domain will be taken to be .ajax.com, because a dot - gets prepended to the value. - - - - -Kristol & Montulli Standards Track [Page 9] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - * A Set-Cookie2 with Port="80,8000" will be accepted if the - request was made to port 80 or 8000 and will be rejected - otherwise. - - * A Set-Cookie2 from request-host example for Domain=.local will - be accepted, because the effective host name for the request- - host is example.local, and example.local domain-matches .local. - - 3.3.3 Cookie Management If a user agent receives a Set-Cookie2 - response header whose NAME is the same as that of a cookie it has - previously stored, the new cookie supersedes the old when: the old - and new Domain attribute values compare equal, using a case- - insensitive string-compare; and, the old and new Path attribute - values string-compare equal (case-sensitive). However, if the Set- - Cookie2 has a value for Max-Age of zero, the (old and new) cookie is - discarded. Otherwise a cookie persists (resources permitting) until - whichever happens first, then gets discarded: its Max-Age lifetime is - exceeded; or, if the Discard attribute is set, the user agent - terminates the session. - - Because user agents have finite space in which to store cookies, they - MAY also discard older cookies to make space for newer ones, using, - for example, a least-recently-used algorithm, along with constraints - on the maximum number of cookies that each origin server may set. - - If a Set-Cookie2 response header includes a Comment attribute, the - user agent SHOULD store that information in a human-readable form - with the cookie and SHOULD display the comment text as part of a - cookie inspection user interface. - - If a Set-Cookie2 response header includes a CommentURL attribute, the - user agent SHOULD store that information in a human-readable form - with the cookie, or, preferably, SHOULD allow the user to follow the - http_URL link as part of a cookie inspection user interface. - - The cookie inspection user interface may include a facility whereby a - user can decide, at the time the user agent receives the Set-Cookie2 - response header, whether or not to accept the cookie. A potentially - confusing situation could arise if the following sequence occurs: - - * the user agent receives a cookie that contains a CommentURL - attribute; - - * the user agent's cookie inspection interface is configured so - that it presents a dialog to the user before the user agent - accepts the cookie; - - - - - -Kristol & Montulli Standards Track [Page 10] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - * the dialog allows the user to follow the CommentURL link when - the user agent receives the cookie; and, - - * when the user follows the CommentURL link, the origin server - (or another server, via other links in the returned content) - returns another cookie. - - The user agent SHOULD NOT send any cookies in this context. The user - agent MAY discard any cookie it receives in this context that the - user has not, through some user agent mechanism, deemed acceptable. - - User agents SHOULD allow the user to control cookie destruction, but - they MUST NOT extend the cookie's lifetime beyond that controlled by - the Discard and Max-Age attributes. An infrequently-used cookie may - function as a "preferences file" for network applications, and a user - may wish to keep it even if it is the least-recently-used cookie. One - possible implementation would be an interface that allows the - permanent storage of a cookie through a checkbox (or, conversely, its - immediate destruction). - - Privacy considerations dictate that the user have considerable - control over cookie management. The PRIVACY section contains more - information. - - 3.3.4 Sending Cookies to the Origin Server When it sends a request - to an origin server, the user agent includes a Cookie request header - if it has stored cookies that are applicable to the request, based on - - * the request-host and request-port; - - * the request-URI; - - * the cookie's age. - - The syntax for the header is: - -cookie = "Cookie:" cookie-version 1*((";" | ",") cookie-value) -cookie-value = NAME "=" VALUE [";" path] [";" domain] [";" port] -cookie-version = "$Version" "=" value -NAME = attr -VALUE = value -path = "$Path" "=" value -domain = "$Domain" "=" value -port = "$Port" [ "=" <"> value <"> ] - - The value of the cookie-version attribute MUST be the value from the - Version attribute of the corresponding Set-Cookie2 response header. - Otherwise the value for cookie-version is 0. The value for the path - - - -Kristol & Montulli Standards Track [Page 11] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - attribute MUST be the value from the Path attribute, if one was - present, of the corresponding Set-Cookie2 response header. Otherwise - the attribute SHOULD be omitted from the Cookie request header. The - value for the domain attribute MUST be the value from the Domain - attribute, if one was present, of the corresponding Set-Cookie2 - response header. Otherwise the attribute SHOULD be omitted from the - Cookie request header. - - The port attribute of the Cookie request header MUST mirror the Port - attribute, if one was present, in the corresponding Set-Cookie2 - response header. That is, the port attribute MUST be present if the - Port attribute was present in the Set-Cookie2 header, and it MUST - have the same value, if any. Otherwise, if the Port attribute was - absent from the Set-Cookie2 header, the attribute likewise MUST be - omitted from the Cookie request header. - - Note that there is neither a Comment nor a CommentURL attribute in - the Cookie request header corresponding to the ones in the Set- - Cookie2 response header. The user agent does not return the comment - information to the origin server. - - The user agent applies the following rules to choose applicable - cookie-values to send in Cookie request headers from among all the - cookies it has received. - - Domain Selection - The origin server's effective host name MUST domain-match the - Domain attribute of the cookie. - - Port Selection - There are three possible behaviors, depending on the Port - attribute in the Set-Cookie2 response header: - - 1. By default (no Port attribute), the cookie MAY be sent to any - port. - - 2. If the attribute is present but has no value (e.g., Port), the - cookie MUST only be sent to the request-port it was received - from. - - 3. If the attribute has a port-list, the cookie MUST only be - returned if the new request-port is one of those listed in - port-list. - - Path Selection - The request-URI MUST path-match the Path attribute of the cookie. - - - - - -Kristol & Montulli Standards Track [Page 12] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - Max-Age Selection - Cookies that have expired should have been discarded and thus are - not forwarded to an origin server. - - If multiple cookies satisfy the criteria above, they are ordered in - the Cookie header such that those with more specific Path attributes - precede those with less specific. Ordering with respect to other - attributes (e.g., Domain) is unspecified. - - Note: For backward compatibility, the separator in the Cookie header - is semi-colon (;) everywhere. A server SHOULD also accept comma (,) - as the separator between cookie-values for future compatibility. - - 3.3.5 Identifying What Version is Understood: Cookie2 The Cookie2 - request header facilitates interoperation between clients and servers - that understand different versions of the cookie specification. When - the client sends one or more cookies to an origin server, if at least - one of those cookies contains a $Version attribute whose value is - different from the version that the client understands, then the - client MUST also send a Cookie2 request header, the syntax for which - is - - cookie2 = "Cookie2:" cookie-version - - Here the value for cookie-version is the highest version of cookie - specification (currently 1) that the client understands. The client - needs to send at most one such request header per request. - - 3.3.6 Sending Cookies in Unverifiable Transactions Users MUST have - control over sessions in order to ensure privacy. (See PRIVACY - section below.) To simplify implementation and to prevent an - additional layer of complexity where adequate safeguards exist, - however, this document distinguishes between transactions that are - verifiable and those that are unverifiable. A transaction is - verifiable if the user, or a user-designated agent, has the option to - review the request-URI prior to its use in the transaction. A - transaction is unverifiable if the user does not have that option. - Unverifiable transactions typically arise when a user agent - automatically requests inlined or embedded entities or when it - resolves redirection (3xx) responses from an origin server. - Typically the origin transaction, the transaction that the user - initiates, is verifiable, and that transaction may directly or - indirectly induce the user agent to make unverifiable transactions. - - An unverifiable transaction is to a third-party host if its request- - host U does not domain-match the reach R of the request-host O in the - origin transaction. - - - - -Kristol & Montulli Standards Track [Page 13] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - When it makes an unverifiable transaction, a user agent MUST disable - all cookie processing (i.e., MUST NOT send cookies, and MUST NOT - accept any received cookies) if the transaction is to a third-party - host. - - This restriction prevents a malicious service author from using - unverifiable transactions to induce a user agent to start or continue - a session with a server in a different domain. The starting or - continuation of such sessions could be contrary to the privacy - expectations of the user, and could also be a security problem. - - User agents MAY offer configurable options that allow the user agent, - or any autonomous programs that the user agent executes, to ignore - the above rule, so long as these override options default to "off". - - (N.B. Mechanisms may be proposed that will automate overriding the - third-party restrictions under controlled conditions.) - - Many current user agents already provide a review option that would - render many links verifiable. For instance, some user agents display - the URL that would be referenced for a particular link when the mouse - pointer is placed over that link. The user can therefore determine - whether to visit that site before causing the browser to do so. - (Though not implemented on current user agents, a similar technique - could be used for a button used to submit a form -- the user agent - could display the action to be taken if the user were to select that - button.) However, even this would not make all links verifiable; for - example, links to automatically loaded images would not normally be - subject to "mouse pointer" verification. - - Many user agents also provide the option for a user to view the HTML - source of a document, or to save the source to an external file where - it can be viewed by another application. While such an option does - provide a crude review mechanism, some users might not consider it - acceptable for this purpose. - -3.4 How an Origin Server Interprets the Cookie Header - - A user agent returns much of the information in the Set-Cookie2 - header to the origin server when the request-URI path-matches the - Path attribute of the cookie. When it receives a Cookie header, the - origin server SHOULD treat cookies with NAMEs whose prefix is $ - specially, as an attribute for the cookie. - - - - - - - - -Kristol & Montulli Standards Track [Page 14] - -RFC 2965 HTTP State Management Mechanism October 2000 - - -3.5 Caching Proxy Role - - One reason for separating state information from both a URL and - document content is to facilitate the scaling that caching permits. - To support cookies, a caching proxy MUST obey these rules already in - the HTTP specification: - - * Honor requests from the cache, if possible, based on cache - validity rules. - - * Pass along a Cookie request header in any request that the - proxy must make of another server. - - * Return the response to the client. Include any Set-Cookie2 - response header. - - * Cache the received response subject to the control of the usual - headers, such as Expires, - - Cache-control: no-cache - - and - - Cache-control: private - - * Cache the Set-Cookie2 subject to the control of the usual - header, - - Cache-control: no-cache="set-cookie2" - - (The Set-Cookie2 header should usually not be cached.) - - Proxies MUST NOT introduce Set-Cookie2 (Cookie) headers of their own - in proxy responses (requests). - -4. EXAMPLES - -4.1 Example 1 - - Most detail of request and response headers has been omitted. Assume - the user agent has no stored cookies. - - 1. User Agent -> Server - - POST /acme/login HTTP/1.1 - [form data] - - User identifies self via a form. - - - -Kristol & Montulli Standards Track [Page 15] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - 2. Server -> User Agent - - HTTP/1.1 200 OK - Set-Cookie2: Customer="WILE_E_COYOTE"; Version="1"; Path="/acme" - - Cookie reflects user's identity. - - 3. User Agent -> Server - - POST /acme/pickitem HTTP/1.1 - Cookie: $Version="1"; Customer="WILE_E_COYOTE"; $Path="/acme" - [form data] - - User selects an item for "shopping basket". - - 4. Server -> User Agent - - HTTP/1.1 200 OK - Set-Cookie2: Part_Number="Rocket_Launcher_0001"; Version="1"; - Path="/acme" - - Shopping basket contains an item. - - 5. User Agent -> Server - - POST /acme/shipping HTTP/1.1 - Cookie: $Version="1"; - Customer="WILE_E_COYOTE"; $Path="/acme"; - Part_Number="Rocket_Launcher_0001"; $Path="/acme" - [form data] - - User selects shipping method from form. - - 6. Server -> User Agent - - HTTP/1.1 200 OK - Set-Cookie2: Shipping="FedEx"; Version="1"; Path="/acme" - - New cookie reflects shipping method. - - 7. User Agent -> Server - - POST /acme/process HTTP/1.1 - Cookie: $Version="1"; - Customer="WILE_E_COYOTE"; $Path="/acme"; - Part_Number="Rocket_Launcher_0001"; $Path="/acme"; - Shipping="FedEx"; $Path="/acme" - [form data] - - - -Kristol & Montulli Standards Track [Page 16] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - User chooses to process order. - - 8. Server -> User Agent - - HTTP/1.1 200 OK - - Transaction is complete. - - The user agent makes a series of requests on the origin server, after - each of which it receives a new cookie. All the cookies have the - same Path attribute and (default) domain. Because the request-URIs - all path-match /acme, the Path attribute of each cookie, each request - contains all the cookies received so far. - -4.2 Example 2 - - This example illustrates the effect of the Path attribute. All - detail of request and response headers has been omitted. Assume the - user agent has no stored cookies. - - Imagine the user agent has received, in response to earlier requests, - the response headers - - Set-Cookie2: Part_Number="Rocket_Launcher_0001"; Version="1"; - Path="/acme" - - and - - Set-Cookie2: Part_Number="Riding_Rocket_0023"; Version="1"; - Path="/acme/ammo" - - A subsequent request by the user agent to the (same) server for URLs - of the form /acme/ammo/... would include the following request - header: - - Cookie: $Version="1"; - Part_Number="Riding_Rocket_0023"; $Path="/acme/ammo"; - Part_Number="Rocket_Launcher_0001"; $Path="/acme" - - Note that the NAME=VALUE pair for the cookie with the more specific - Path attribute, /acme/ammo, comes before the one with the less - specific Path attribute, /acme. Further note that the same cookie - name appears more than once. - - A subsequent request by the user agent to the (same) server for a URL - of the form /acme/parts/ would include the following request header: - - - - - -Kristol & Montulli Standards Track [Page 17] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - Cookie: $Version="1"; Part_Number="Rocket_Launcher_0001"; - $Path="/acme" - - Here, the second cookie's Path attribute /acme/ammo is not a prefix - of the request URL, /acme/parts/, so the cookie does not get - forwarded to the server. - -5. IMPLEMENTATION CONSIDERATIONS - - Here we provide guidance on likely or desirable details for an origin - server that implements state management. - -5.1 Set-Cookie2 Content - - An origin server's content should probably be divided into disjoint - application areas, some of which require the use of state - information. The application areas can be distinguished by their - request URLs. The Set-Cookie2 header can incorporate information - about the application areas by setting the Path attribute for each - one. - - The session information can obviously be clear or encoded text that - describes state. However, if it grows too large, it can become - unwieldy. Therefore, an implementor might choose for the session - information to be a key to a server-side resource. Of course, using - a database creates some problems that this state management - specification was meant to avoid, namely: - - 1. keeping real state on the server side; - - 2. how and when to garbage-collect the database entry, in case the - user agent terminates the session by, for example, exiting. - -5.2 Stateless Pages - - Caching benefits the scalability of WWW. Therefore it is important - to reduce the number of documents that have state embedded in them - inherently. For example, if a shopping-basket-style application - always displays a user's current basket contents on each page, those - pages cannot be cached, because each user's basket's contents would - be different. On the other hand, if each page contains just a link - that allows the user to "Look at My Shopping Basket", the page can be - cached. - - - - - - - - -Kristol & Montulli Standards Track [Page 18] - -RFC 2965 HTTP State Management Mechanism October 2000 - - -5.3 Implementation Limits - - Practical user agent implementations have limits on the number and - size of cookies that they can store. In general, user agents' cookie - support should have no fixed limits. They should strive to store as - many frequently-used cookies as possible. Furthermore, general-use - user agents SHOULD provide each of the following minimum capabilities - individually, although not necessarily simultaneously: - - * at least 300 cookies - - * at least 4096 bytes per cookie (as measured by the characters - that comprise the cookie non-terminal in the syntax description - of the Set-Cookie2 header, and as received in the Set-Cookie2 - header) - - * at least 20 cookies per unique host or domain name - - User agents created for specific purposes or for limited-capacity - devices SHOULD provide at least 20 cookies of 4096 bytes, to ensure - that the user can interact with a session-based origin server. - - The information in a Set-Cookie2 response header MUST be retained in - its entirety. If for some reason there is inadequate space to store - the cookie, it MUST be discarded, not truncated. - - Applications should use as few and as small cookies as possible, and - they should cope gracefully with the loss of a cookie. - - 5.3.1 Denial of Service Attacks User agents MAY choose to set an - upper bound on the number of cookies to be stored from a given host - or domain name or on the size of the cookie information. Otherwise a - malicious server could attempt to flood a user agent with many - cookies, or large cookies, on successive responses, which would force - out cookies the user agent had received from other servers. However, - the minima specified above SHOULD still be supported. - -6. PRIVACY - - Informed consent should guide the design of systems that use cookies. - A user should be able to find out how a web site plans to use - information in a cookie and should be able to choose whether or not - those policies are acceptable. Both the user agent and the origin - server must assist informed consent. - - - - - - - -Kristol & Montulli Standards Track [Page 19] - -RFC 2965 HTTP State Management Mechanism October 2000 - - -6.1 User Agent Control - - An origin server could create a Set-Cookie2 header to track the path - of a user through the server. Users may object to this behavior as - an intrusive accumulation of information, even if their identity is - not evident. (Identity might become evident, for example, if a user - subsequently fills out a form that contains identifying information.) - This state management specification therefore requires that a user - agent give the user control over such a possible intrusion, although - the interface through which the user is given this control is left - unspecified. However, the control mechanisms provided SHALL at least - allow the user - - * to completely disable the sending and saving of cookies. - - * to determine whether a stateful session is in progress. - - * to control the saving of a cookie on the basis of the cookie's - Domain attribute. - - Such control could be provided, for example, by mechanisms - - * to notify the user when the user agent is about to send a - cookie to the origin server, to offer the option not to begin a - session. - - * to display a visual indication that a stateful session is in - progress. - - * to let the user decide which cookies, if any, should be saved - when the user concludes a window or user agent session. - - * to let the user examine and delete the contents of a cookie at - any time. - - A user agent usually begins execution with no remembered state - information. It SHOULD be possible to configure a user agent never - to send Cookie headers, in which case it can never sustain state with - an origin server. (The user agent would then behave like one that is - unaware of how to handle Set-Cookie2 response headers.) - - When the user agent terminates execution, it SHOULD let the user - discard all state information. Alternatively, the user agent MAY ask - the user whether state information should be retained; the default - should be "no". If the user chooses to retain state information, it - would be restored the next time the user agent runs. - - - - - -Kristol & Montulli Standards Track [Page 20] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - NOTE: User agents should probably be cautious about using files to - store cookies long-term. If a user runs more than one instance of - the user agent, the cookies could be commingled or otherwise - corrupted. - -6.2 Origin Server Role - - An origin server SHOULD promote informed consent by adding CommentURL - or Comment information to the cookies it sends. CommentURL is - preferred because of the opportunity to provide richer information in - a multiplicity of languages. - -6.3 Clear Text - - The information in the Set-Cookie2 and Cookie headers is unprotected. - As a consequence: - - 1. Any sensitive information that is conveyed in them is exposed - to intruders. - - 2. A malicious intermediary could alter the headers as they travel - in either direction, with unpredictable results. - - These facts imply that information of a personal and/or financial - nature should only be sent over a secure channel. For less sensitive - information, or when the content of the header is a database key, an - origin server should be vigilant to prevent a bad Cookie value from - causing failures. - - A user agent in a shared user environment poses a further risk. - Using a cookie inspection interface, User B could examine the - contents of cookies that were saved when User A used the machine. - -7. SECURITY CONSIDERATIONS - -7.1 Protocol Design - - The restrictions on the value of the Domain attribute, and the rules - concerning unverifiable transactions, are meant to reduce the ways - that cookies can "leak" to the "wrong" site. The intent is to - restrict cookies to one host, or a closely related set of hosts. - Therefore a request-host is limited as to what values it can set for - Domain. We consider it acceptable for hosts host1.foo.com and - host2.foo.com to share cookies, but not a.com and b.com. - - Similarly, a server can set a Path only for cookies that are related - to the request-URI. - - - - -Kristol & Montulli Standards Track [Page 21] - -RFC 2965 HTTP State Management Mechanism October 2000 - - -7.2 Cookie Spoofing - - Proper application design can avoid spoofing attacks from related - domains. Consider: - - 1. User agent makes request to victim.cracker.edu, gets back - cookie session_id="1234" and sets the default domain - victim.cracker.edu. - - 2. User agent makes request to spoof.cracker.edu, gets back cookie - session-id="1111", with Domain=".cracker.edu". - - 3. User agent makes request to victim.cracker.edu again, and - passes - - Cookie: $Version="1"; session_id="1234", - $Version="1"; session_id="1111"; $Domain=".cracker.edu" - - The server at victim.cracker.edu should detect that the second - cookie was not one it originated by noticing that the Domain - attribute is not for itself and ignore it. - -7.3 Unexpected Cookie Sharing - - A user agent SHOULD make every attempt to prevent the sharing of - session information between hosts that are in different domains. - Embedded or inlined objects may cause particularly severe privacy - problems if they can be used to share cookies between disparate - hosts. For example, a malicious server could embed cookie - information for host a.com in a URI for a CGI on host b.com. User - agent implementors are strongly encouraged to prevent this sort of - exchange whenever possible. - -7.4 Cookies For Account Information - - While it is common practice to use them this way, cookies are not - designed or intended to be used to hold authentication information, - such as account names and passwords. Unless such cookies are - exchanged over an encrypted path, the account information they - contain is highly vulnerable to perusal and theft. - -8. OTHER, SIMILAR, PROPOSALS - - Apart from RFC 2109, three other proposals have been made to - accomplish similar goals. This specification began as an amalgam of - Kristol's State-Info proposal [DMK95] and Netscape's Cookie proposal - [Netscape]. - - - - -Kristol & Montulli Standards Track [Page 22] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - Brian Behlendorf proposed a Session-ID header that would be user- - agent-initiated and could be used by an origin server to track - "clicktrails". It would not carry any origin-server-defined state, - however. Phillip Hallam-Baker has proposed another client-defined - session ID mechanism for similar purposes. - - While both session IDs and cookies can provide a way to sustain - stateful sessions, their intended purpose is different, and, - consequently, the privacy requirements for them are different. A - user initiates session IDs to allow servers to track progress through - them, or to distinguish multiple users on a shared machine. Cookies - are server-initiated, so the cookie mechanism described here gives - users control over something that would otherwise take place without - the users' awareness. Furthermore, cookies convey rich, server- - selected information, whereas session IDs comprise user-selected, - simple information. - -9. HISTORICAL - -9.1 Compatibility with Existing Implementations - - Existing cookie implementations, based on the Netscape specification, - use the Set-Cookie (not Set-Cookie2) header. User agents that - receive in the same response both a Set-Cookie and Set-Cookie2 - response header for the same cookie MUST discard the Set-Cookie - information and use only the Set-Cookie2 information. Furthermore, a - user agent MUST assume, if it received a Set-Cookie2 response header, - that the sending server complies with this document and will - understand Cookie request headers that also follow this - specification. - - New cookies MUST replace both equivalent old- and new-style cookies. - That is, if a user agent that follows both this specification and - Netscape's original specification receives a Set-Cookie2 response - header, and the NAME and the Domain and Path attributes match (per - the Cookie Management section) a Netscape-style cookie, the - Netscape-style cookie MUST be discarded, and the user agent MUST - retain only the cookie adhering to this specification. - - Older user agents that do not understand this specification, but that - do understand Netscape's original specification, will not recognize - the Set-Cookie2 response header and will receive and send cookies - according to the older specification. - - - - - - - - -Kristol & Montulli Standards Track [Page 23] - -RFC 2965 HTTP State Management Mechanism October 2000 - - - A user agent that supports both this specification and Netscape-style - cookies SHOULD send a Cookie request header that follows the older - Netscape specification if it received the cookie in a Set-Cookie - response header and not in a Set-Cookie2 response header. However, - it SHOULD send the following request header as well: - - Cookie2: $Version="1" - - The Cookie2 header advises the server that the user agent understands - new-style cookies. If the server understands new-style cookies, as - well, it SHOULD continue the stateful session by sending a Set- - Cookie2 response header, rather than Set-Cookie. A server that does - not understand new-style cookies will simply ignore the Cookie2 - request header. - -9.2 Caching and HTTP/1.0 - - Some caches, such as those conforming to HTTP/1.0, will inevitably - cache the Set-Cookie2 and Set-Cookie headers, because there was no - mechanism to suppress caching of headers prior to HTTP/1.1. This - caching can lead to security problems. Documents transmitted by an - origin server along with Set-Cookie2 and Set-Cookie headers usually - either will be uncachable, or will be "pre-expired". As long as - caches obey instructions not to cache documents (following Expires: - <a date in the past> or Pragma: no-cache (HTTP/1.0), or Cache- - control: no-cache (HTTP/1.1)) uncachable documents present no - problem. However, pre-expired documents may be stored in caches. - They require validation (a conditional GET) on each new request, but - some cache operators loosen the rules for their caches, and sometimes - serve expired documents without first validating them. This - combination of factors can lead to cookies meant for one user later - being sent to another user. The Set-Cookie2 and Set-Cookie headers - are stored in the cache, and, although the document is stale - (expired), the cache returns the document in response to later - requests, including cached headers. - -10. ACKNOWLEDGEMENTS - - This document really represents the collective efforts of the HTTP - Working Group of the IETF and, particularly, the following people, in - addition to the authors: Roy Fielding, Yaron Goland, Marc Hedlund, - Ted Hardie, Koen Holtman, Shel Kaphan, Rohit Khare, Foteos Macrides, - David W. Morris. - - - - - - - - -Kristol & Montulli Standards Track [Page 24] - -RFC 2965 HTTP State Management Mechanism October 2000 - - -11. AUTHORS' ADDRESSES - - David M. Kristol - Bell Laboratories, Lucent Technologies - 600 Mountain Ave. Room 2A-333 - Murray Hill, NJ 07974 - - Phone: (908) 582-2250 - Fax: (908) 582-1239 - EMail: dmk@bell-labs.com - - - Lou Montulli - Epinions.com, Inc. - 2037 Landings Dr. - Mountain View, CA 94301 - - EMail: lou@montulli.org - -12. REFERENCES - - [DMK95] Kristol, D.M., "Proposed HTTP State-Info Mechanism", - available at <http://portal.research.bell- - labs.com/~dmk/state-info.html>, September, 1995. - - [Netscape] "Persistent Client State -- HTTP Cookies", available at - <http://www.netscape.com/newsref/std/cookie_spec.html>, - undated. - - [RFC2109] Kristol, D. and L. Montulli, "HTTP State Management - Mechanism", RFC 2109, February 1997. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC2279] Yergeau, F., "UTF-8, a transformation format of Unicode - and ISO-10646", RFC 2279, January 1998. - - [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform - Resource Identifiers (URI): Generic Syntax", RFC 2396, - August 1998. - - [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and T. - Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", - RFC 2616, June 1999. - - - - - - -Kristol & Montulli Standards Track [Page 25] - -RFC 2965 HTTP State Management Mechanism October 2000 - - -13. Full Copyright Statement - - Copyright (C) The Internet Society (2000). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Kristol & Montulli Standards Track [Page 26] - diff --git a/docs/specs/rfc3986.txt b/docs/specs/rfc3986.txt deleted file mode 100644 index c56ed4eb..00000000 --- a/docs/specs/rfc3986.txt +++ /dev/null @@ -1,3419 +0,0 @@ - - - - - - -Network Working Group T. Berners-Lee -Request for Comments: 3986 W3C/MIT -STD: 66 R. Fielding -Updates: 1738 Day Software -Obsoletes: 2732, 2396, 1808 L. Masinter -Category: Standards Track Adobe Systems - January 2005 - - - Uniform Resource Identifier (URI): Generic Syntax - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2005). - -Abstract - - A Uniform Resource Identifier (URI) is a compact sequence of - characters that identifies an abstract or physical resource. This - specification defines the generic URI syntax and a process for - resolving URI references that might be in relative form, along with - guidelines and security considerations for the use of URIs on the - Internet. The URI syntax defines a grammar that is a superset of all - valid URIs, allowing an implementation to parse the common components - of a URI reference without knowing the scheme-specific requirements - of every possible identifier. This specification does not define a - generative grammar for URIs; that task is performed by the individual - specifications of each URI scheme. - - - - - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 1] - -RFC 3986 URI Generic Syntax January 2005 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1.1. Overview of URIs . . . . . . . . . . . . . . . . . . . . 4 - 1.1.1. Generic Syntax . . . . . . . . . . . . . . . . . 6 - 1.1.2. Examples . . . . . . . . . . . . . . . . . . . . 7 - 1.1.3. URI, URL, and URN . . . . . . . . . . . . . . . 7 - 1.2. Design Considerations . . . . . . . . . . . . . . . . . 8 - 1.2.1. Transcription . . . . . . . . . . . . . . . . . 8 - 1.2.2. Separating Identification from Interaction . . . 9 - 1.2.3. Hierarchical Identifiers . . . . . . . . . . . . 10 - 1.3. Syntax Notation . . . . . . . . . . . . . . . . . . . . 11 - 2. Characters . . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 2.1. Percent-Encoding . . . . . . . . . . . . . . . . . . . . 12 - 2.2. Reserved Characters . . . . . . . . . . . . . . . . . . 12 - 2.3. Unreserved Characters . . . . . . . . . . . . . . . . . 13 - 2.4. When to Encode or Decode . . . . . . . . . . . . . . . . 14 - 2.5. Identifying Data . . . . . . . . . . . . . . . . . . . . 14 - 3. Syntax Components . . . . . . . . . . . . . . . . . . . . . . 16 - 3.1. Scheme . . . . . . . . . . . . . . . . . . . . . . . . . 17 - 3.2. Authority . . . . . . . . . . . . . . . . . . . . . . . 17 - 3.2.1. User Information . . . . . . . . . . . . . . . . 18 - 3.2.2. Host . . . . . . . . . . . . . . . . . . . . . . 18 - 3.2.3. Port . . . . . . . . . . . . . . . . . . . . . . 22 - 3.3. Path . . . . . . . . . . . . . . . . . . . . . . . . . . 22 - 3.4. Query . . . . . . . . . . . . . . . . . . . . . . . . . 23 - 3.5. Fragment . . . . . . . . . . . . . . . . . . . . . . . . 24 - 4. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 - 4.1. URI Reference . . . . . . . . . . . . . . . . . . . . . 25 - 4.2. Relative Reference . . . . . . . . . . . . . . . . . . . 26 - 4.3. Absolute URI . . . . . . . . . . . . . . . . . . . . . . 27 - 4.4. Same-Document Reference . . . . . . . . . . . . . . . . 27 - 4.5. Suffix Reference . . . . . . . . . . . . . . . . . . . . 27 - 5. Reference Resolution . . . . . . . . . . . . . . . . . . . . . 28 - 5.1. Establishing a Base URI . . . . . . . . . . . . . . . . 28 - 5.1.1. Base URI Embedded in Content . . . . . . . . . . 29 - 5.1.2. Base URI from the Encapsulating Entity . . . . . 29 - 5.1.3. Base URI from the Retrieval URI . . . . . . . . 30 - 5.1.4. Default Base URI . . . . . . . . . . . . . . . . 30 - 5.2. Relative Resolution . . . . . . . . . . . . . . . . . . 30 - 5.2.1. Pre-parse the Base URI . . . . . . . . . . . . . 31 - 5.2.2. Transform References . . . . . . . . . . . . . . 31 - 5.2.3. Merge Paths . . . . . . . . . . . . . . . . . . 32 - 5.2.4. Remove Dot Segments . . . . . . . . . . . . . . 33 - 5.3. Component Recomposition . . . . . . . . . . . . . . . . 35 - 5.4. Reference Resolution Examples . . . . . . . . . . . . . 35 - 5.4.1. Normal Examples . . . . . . . . . . . . . . . . 36 - 5.4.2. Abnormal Examples . . . . . . . . . . . . . . . 36 - - - -Berners-Lee, et al. Standards Track [Page 2] - -RFC 3986 URI Generic Syntax January 2005 - - - 6. Normalization and Comparison . . . . . . . . . . . . . . . . . 38 - 6.1. Equivalence . . . . . . . . . . . . . . . . . . . . . . 38 - 6.2. Comparison Ladder . . . . . . . . . . . . . . . . . . . 39 - 6.2.1. Simple String Comparison . . . . . . . . . . . . 39 - 6.2.2. Syntax-Based Normalization . . . . . . . . . . . 40 - 6.2.3. Scheme-Based Normalization . . . . . . . . . . . 41 - 6.2.4. Protocol-Based Normalization . . . . . . . . . . 42 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 43 - 7.1. Reliability and Consistency . . . . . . . . . . . . . . 43 - 7.2. Malicious Construction . . . . . . . . . . . . . . . . . 43 - 7.3. Back-End Transcoding . . . . . . . . . . . . . . . . . . 44 - 7.4. Rare IP Address Formats . . . . . . . . . . . . . . . . 45 - 7.5. Sensitive Information . . . . . . . . . . . . . . . . . 45 - 7.6. Semantic Attacks . . . . . . . . . . . . . . . . . . . . 45 - 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 - 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 46 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 46 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 46 - 10.2. Informative References . . . . . . . . . . . . . . . . . 47 - A. Collected ABNF for URI . . . . . . . . . . . . . . . . . . . . 49 - B. Parsing a URI Reference with a Regular Expression . . . . . . 50 - C. Delimiting a URI in Context . . . . . . . . . . . . . . . . . 51 - D. Changes from RFC 2396 . . . . . . . . . . . . . . . . . . . . 53 - D.1. Additions . . . . . . . . . . . . . . . . . . . . . . . 53 - D.2. Modifications . . . . . . . . . . . . . . . . . . . . . 53 - Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 60 - Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 61 - - - - - - - - - - - - - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 3] - -RFC 3986 URI Generic Syntax January 2005 - - -1. Introduction - - A Uniform Resource Identifier (URI) provides a simple and extensible - means for identifying a resource. This specification of URI syntax - and semantics is derived from concepts introduced by the World Wide - Web global information initiative, whose use of these identifiers - dates from 1990 and is described in "Universal Resource Identifiers - in WWW" [RFC1630]. The syntax is designed to meet the - recommendations laid out in "Functional Recommendations for Internet - Resource Locators" [RFC1736] and "Functional Requirements for Uniform - Resource Names" [RFC1737]. - - This document obsoletes [RFC2396], which merged "Uniform Resource - Locators" [RFC1738] and "Relative Uniform Resource Locators" - [RFC1808] in order to define a single, generic syntax for all URIs. - It obsoletes [RFC2732], which introduced syntax for an IPv6 address. - It excludes portions of RFC 1738 that defined the specific syntax of - individual URI schemes; those portions will be updated as separate - documents. The process for registration of new URI schemes is - defined separately by [BCP35]. Advice for designers of new URI - schemes can be found in [RFC2718]. All significant changes from RFC - 2396 are noted in Appendix D. - - This specification uses the terms "character" and "coded character - set" in accordance with the definitions provided in [BCP19], and - "character encoding" in place of what [BCP19] refers to as a - "charset". - -1.1. Overview of URIs - - URIs are characterized as follows: - - Uniform - - Uniformity provides several benefits. It allows different types - of resource identifiers to be used in the same context, even when - the mechanisms used to access those resources may differ. It - allows uniform semantic interpretation of common syntactic - conventions across different types of resource identifiers. It - allows introduction of new types of resource identifiers without - interfering with the way that existing identifiers are used. It - allows the identifiers to be reused in many different contexts, - thus permitting new applications or protocols to leverage a pre- - existing, large, and widely used set of resource identifiers. - - - - - - - -Berners-Lee, et al. Standards Track [Page 4] - -RFC 3986 URI Generic Syntax January 2005 - - - Resource - - This specification does not limit the scope of what might be a - resource; rather, the term "resource" is used in a general sense - for whatever might be identified by a URI. Familiar examples - include an electronic document, an image, a source of information - with a consistent purpose (e.g., "today's weather report for Los - Angeles"), a service (e.g., an HTTP-to-SMS gateway), and a - collection of other resources. A resource is not necessarily - accessible via the Internet; e.g., human beings, corporations, and - bound books in a library can also be resources. Likewise, - abstract concepts can be resources, such as the operators and - operands of a mathematical equation, the types of a relationship - (e.g., "parent" or "employee"), or numeric values (e.g., zero, - one, and infinity). - - Identifier - - An identifier embodies the information required to distinguish - what is being identified from all other things within its scope of - identification. Our use of the terms "identify" and "identifying" - refer to this purpose of distinguishing one resource from all - other resources, regardless of how that purpose is accomplished - (e.g., by name, address, or context). These terms should not be - mistaken as an assumption that an identifier defines or embodies - the identity of what is referenced, though that may be the case - for some identifiers. Nor should it be assumed that a system - using URIs will access the resource identified: in many cases, - URIs are used to denote resources without any intention that they - be accessed. Likewise, the "one" resource identified might not be - singular in nature (e.g., a resource might be a named set or a - mapping that varies over time). - - A URI is an identifier consisting of a sequence of characters - matching the syntax rule named <URI> in Section 3. It enables - uniform identification of resources via a separately defined - extensible set of naming schemes (Section 3.1). How that - identification is accomplished, assigned, or enabled is delegated to - each scheme specification. - - This specification does not place any limits on the nature of a - resource, the reasons why an application might seek to refer to a - resource, or the kinds of systems that might use URIs for the sake of - identifying resources. This specification does not require that a - URI persists in identifying the same resource over time, though that - is a common goal of all URI schemes. Nevertheless, nothing in this - - - - - -Berners-Lee, et al. Standards Track [Page 5] - -RFC 3986 URI Generic Syntax January 2005 - - - specification prevents an application from limiting itself to - particular types of resources, or to a subset of URIs that maintains - characteristics desired by that application. - - URIs have a global scope and are interpreted consistently regardless - of context, though the result of that interpretation may be in - relation to the end-user's context. For example, "http://localhost/" - has the same interpretation for every user of that reference, even - though the network interface corresponding to "localhost" may be - different for each end-user: interpretation is independent of access. - However, an action made on the basis of that reference will take - place in relation to the end-user's context, which implies that an - action intended to refer to a globally unique thing must use a URI - that distinguishes that resource from all other things. URIs that - identify in relation to the end-user's local context should only be - used when the context itself is a defining aspect of the resource, - such as when an on-line help manual refers to a file on the end- - user's file system (e.g., "file:///etc/hosts"). - -1.1.1. Generic Syntax - - Each URI begins with a scheme name, as defined in Section 3.1, that - refers to a specification for assigning identifiers within that - scheme. As such, the URI syntax is a federated and extensible naming - system wherein each scheme's specification may further restrict the - syntax and semantics of identifiers using that scheme. - - This specification defines those elements of the URI syntax that are - required of all URI schemes or are common to many URI schemes. It - thus defines the syntax and semantics needed to implement a scheme- - independent parsing mechanism for URI references, by which the - scheme-dependent handling of a URI can be postponed until the - scheme-dependent semantics are needed. Likewise, protocols and data - formats that make use of URI references can refer to this - specification as a definition for the range of syntax allowed for all - URIs, including those schemes that have yet to be defined. This - decouples the evolution of identification schemes from the evolution - of protocols, data formats, and implementations that make use of - URIs. - - A parser of the generic URI syntax can parse any URI reference into - its major components. Once the scheme is determined, further - scheme-specific parsing can be performed on the components. In other - words, the URI generic syntax is a superset of the syntax of all URI - schemes. - - - - - - -Berners-Lee, et al. Standards Track [Page 6] - -RFC 3986 URI Generic Syntax January 2005 - - -1.1.2. Examples - - The following example URIs illustrate several URI schemes and - variations in their common syntax components: - - ftp://ftp.is.co.za/rfc/rfc1808.txt - - http://www.ietf.org/rfc/rfc2396.txt - - ldap://[2001:db8::7]/c=GB?objectClass?one - - mailto:John.Doe@example.com - - news:comp.infosystems.www.servers.unix - - tel:+1-816-555-1212 - - telnet://192.0.2.16:80/ - - urn:oasis:names:specification:docbook:dtd:xml:4.1.2 - - -1.1.3. URI, URL, and URN - - A URI can be further classified as a locator, a name, or both. The - term "Uniform Resource Locator" (URL) refers to the subset of URIs - that, in addition to identifying a resource, provide a means of - locating the resource by describing its primary access mechanism - (e.g., its network "location"). The term "Uniform Resource Name" - (URN) has been used historically to refer to both URIs under the - "urn" scheme [RFC2141], which are required to remain globally unique - and persistent even when the resource ceases to exist or becomes - unavailable, and to any other URI with the properties of a name. - - An individual scheme does not have to be classified as being just one - of "name" or "locator". Instances of URIs from any given scheme may - have the characteristics of names or locators or both, often - depending on the persistence and care in the assignment of - identifiers by the naming authority, rather than on any quality of - the scheme. Future specifications and related documentation should - use the general term "URI" rather than the more restrictive terms - "URL" and "URN" [RFC3305]. - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 7] - -RFC 3986 URI Generic Syntax January 2005 - - -1.2. Design Considerations - -1.2.1. Transcription - - The URI syntax has been designed with global transcription as one of - its main considerations. A URI is a sequence of characters from a - very limited set: the letters of the basic Latin alphabet, digits, - and a few special characters. A URI may be represented in a variety - of ways; e.g., ink on paper, pixels on a screen, or a sequence of - character encoding octets. The interpretation of a URI depends only - on the characters used and not on how those characters are - represented in a network protocol. - - The goal of transcription can be described by a simple scenario. - Imagine two colleagues, Sam and Kim, sitting in a pub at an - international conference and exchanging research ideas. Sam asks Kim - for a location to get more information, so Kim writes the URI for the - research site on a napkin. Upon returning home, Sam takes out the - napkin and types the URI into a computer, which then retrieves the - information to which Kim referred. - - There are several design considerations revealed by the scenario: - - o A URI is a sequence of characters that is not always represented - as a sequence of octets. - - o A URI might be transcribed from a non-network source and thus - should consist of characters that are most likely able to be - entered into a computer, within the constraints imposed by - keyboards (and related input devices) across languages and - locales. - - o A URI often has to be remembered by people, and it is easier for - people to remember a URI when it consists of meaningful or - familiar components. - - These design considerations are not always in alignment. For - example, it is often the case that the most meaningful name for a URI - component would require characters that cannot be typed into some - systems. The ability to transcribe a resource identifier from one - medium to another has been considered more important than having a - URI consist of the most meaningful of components. - - In local or regional contexts and with improving technology, users - might benefit from being able to use a wider range of characters; - such use is not defined by this specification. Percent-encoded - octets (Section 2.1) may be used within a URI to represent characters - outside the range of the US-ASCII coded character set if this - - - -Berners-Lee, et al. Standards Track [Page 8] - -RFC 3986 URI Generic Syntax January 2005 - - - representation is allowed by the scheme or by the protocol element in - which the URI is referenced. Such a definition should specify the - character encoding used to map those characters to octets prior to - being percent-encoded for the URI. - -1.2.2. Separating Identification from Interaction - - A common misunderstanding of URIs is that they are only used to refer - to accessible resources. The URI itself only provides - identification; access to the resource is neither guaranteed nor - implied by the presence of a URI. Instead, any operation associated - with a URI reference is defined by the protocol element, data format - attribute, or natural language text in which it appears. - - Given a URI, a system may attempt to perform a variety of operations - on the resource, as might be characterized by words such as "access", - "update", "replace", or "find attributes". Such operations are - defined by the protocols that make use of URIs, not by this - specification. However, we do use a few general terms for describing - common operations on URIs. URI "resolution" is the process of - determining an access mechanism and the appropriate parameters - necessary to dereference a URI; this resolution may require several - iterations. To use that access mechanism to perform an action on the - URI's resource is to "dereference" the URI. - - When URIs are used within information retrieval systems to identify - sources of information, the most common form of URI dereference is - "retrieval": making use of a URI in order to retrieve a - representation of its associated resource. A "representation" is a - sequence of octets, along with representation metadata describing - those octets, that constitutes a record of the state of the resource - at the time when the representation is generated. Retrieval is - achieved by a process that might include using the URI as a cache key - to check for a locally cached representation, resolution of the URI - to determine an appropriate access mechanism (if any), and - dereference of the URI for the sake of applying a retrieval - operation. Depending on the protocols used to perform the retrieval, - additional information might be supplied about the resource (resource - metadata) and its relation to other resources. - - URI references in information retrieval systems are designed to be - late-binding: the result of an access is generally determined when it - is accessed and may vary over time or due to other aspects of the - interaction. These references are created in order to be used in the - future: what is being identified is not some specific result that was - obtained in the past, but rather some characteristic that is expected - to be true for future results. In such cases, the resource referred - to by the URI is actually a sameness of characteristics as observed - - - -Berners-Lee, et al. Standards Track [Page 9] - -RFC 3986 URI Generic Syntax January 2005 - - - over time, perhaps elucidated by additional comments or assertions - made by the resource provider. - - Although many URI schemes are named after protocols, this does not - imply that use of these URIs will result in access to the resource - via the named protocol. URIs are often used simply for the sake of - identification. Even when a URI is used to retrieve a representation - of a resource, that access might be through gateways, proxies, - caches, and name resolution services that are independent of the - protocol associated with the scheme name. The resolution of some - URIs may require the use of more than one protocol (e.g., both DNS - and HTTP are typically used to access an "http" URI's origin server - when a representation isn't found in a local cache). - -1.2.3. Hierarchical Identifiers - - The URI syntax is organized hierarchically, with components listed in - order of decreasing significance from left to right. For some URI - schemes, the visible hierarchy is limited to the scheme itself: - everything after the scheme component delimiter (":") is considered - opaque to URI processing. Other URI schemes make the hierarchy - explicit and visible to generic parsing algorithms. - - The generic syntax uses the slash ("/"), question mark ("?"), and - number sign ("#") characters to delimit components that are - significant to the generic parser's hierarchical interpretation of an - identifier. In addition to aiding the readability of such - identifiers through the consistent use of familiar syntax, this - uniform representation of hierarchy across naming schemes allows - scheme-independent references to be made relative to that hierarchy. - - It is often the case that a group or "tree" of documents has been - constructed to serve a common purpose, wherein the vast majority of - URI references in these documents point to resources within the tree - rather than outside it. Similarly, documents located at a particular - site are much more likely to refer to other resources at that site - than to resources at remote sites. Relative referencing of URIs - allows document trees to be partially independent of their location - and access scheme. For instance, it is possible for a single set of - hypertext documents to be simultaneously accessible and traversable - via each of the "file", "http", and "ftp" schemes if the documents - refer to each other with relative references. Furthermore, such - document trees can be moved, as a whole, without changing any of the - relative references. - - A relative reference (Section 4.2) refers to a resource by describing - the difference within a hierarchical name space between the reference - context and the target URI. The reference resolution algorithm, - - - -Berners-Lee, et al. Standards Track [Page 10] - -RFC 3986 URI Generic Syntax January 2005 - - - presented in Section 5, defines how such a reference is transformed - to the target URI. As relative references can only be used within - the context of a hierarchical URI, designers of new URI schemes - should use a syntax consistent with the generic syntax's hierarchical - components unless there are compelling reasons to forbid relative - referencing within that scheme. - - NOTE: Previous specifications used the terms "partial URI" and - "relative URI" to denote a relative reference to a URI. As some - readers misunderstood those terms to mean that relative URIs are a - subset of URIs rather than a method of referencing URIs, this - specification simply refers to them as relative references. - - All URI references are parsed by generic syntax parsers when used. - However, because hierarchical processing has no effect on an absolute - URI used in a reference unless it contains one or more dot-segments - (complete path segments of "." or "..", as described in Section 3.3), - URI scheme specifications can define opaque identifiers by - disallowing use of slash characters, question mark characters, and - the URIs "scheme:." and "scheme:..". - -1.3. Syntax Notation - - This specification uses the Augmented Backus-Naur Form (ABNF) - notation of [RFC2234], including the following core ABNF syntax rules - defined by that specification: ALPHA (letters), CR (carriage return), - DIGIT (decimal digits), DQUOTE (double quote), HEXDIG (hexadecimal - digits), LF (line feed), and SP (space). The complete URI syntax is - collected in Appendix A. - -2. Characters - - The URI syntax provides a method of encoding data, presumably for the - sake of identifying a resource, as a sequence of characters. The URI - characters are, in turn, frequently encoded as octets for transport - or presentation. This specification does not mandate any particular - character encoding for mapping between URI characters and the octets - used to store or transmit those characters. When a URI appears in a - protocol element, the character encoding is defined by that protocol; - without such a definition, a URI is assumed to be in the same - character encoding as the surrounding text. - - The ABNF notation defines its terminal values to be non-negative - integers (codepoints) based on the US-ASCII coded character set - [ASCII]. Because a URI is a sequence of characters, we must invert - that relation in order to understand the URI syntax. Therefore, the - - - - - -Berners-Lee, et al. Standards Track [Page 11] - -RFC 3986 URI Generic Syntax January 2005 - - - integer values used by the ABNF must be mapped back to their - corresponding characters via US-ASCII in order to complete the syntax - rules. - - A URI is composed from a limited set of characters consisting of - digits, letters, and a few graphic symbols. A reserved subset of - those characters may be used to delimit syntax components within a - URI while the remaining characters, including both the unreserved set - and those reserved characters not acting as delimiters, define each - component's identifying data. - -2.1. Percent-Encoding - - A percent-encoding mechanism is used to represent a data octet in a - component when that octet's corresponding character is outside the - allowed set or is being used as a delimiter of, or within, the - component. A percent-encoded octet is encoded as a character - triplet, consisting of the percent character "%" followed by the two - hexadecimal digits representing that octet's numeric value. For - example, "%20" is the percent-encoding for the binary octet - "00100000" (ABNF: %x20), which in US-ASCII corresponds to the space - character (SP). Section 2.4 describes when percent-encoding and - decoding is applied. - - pct-encoded = "%" HEXDIG HEXDIG - - The uppercase hexadecimal digits 'A' through 'F' are equivalent to - the lowercase digits 'a' through 'f', respectively. If two URIs - differ only in the case of hexadecimal digits used in percent-encoded - octets, they are equivalent. For consistency, URI producers and - normalizers should use uppercase hexadecimal digits for all percent- - encodings. - -2.2. Reserved Characters - - URIs include components and subcomponents that are delimited by - characters in the "reserved" set. These characters are called - "reserved" because they may (or may not) be defined as delimiters by - the generic syntax, by each scheme-specific syntax, or by the - implementation-specific syntax of a URI's dereferencing algorithm. - If data for a URI component would conflict with a reserved - character's purpose as a delimiter, then the conflicting data must be - percent-encoded before the URI is formed. - - - - - - - - -Berners-Lee, et al. Standards Track [Page 12] - -RFC 3986 URI Generic Syntax January 2005 - - - reserved = gen-delims / sub-delims - - gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" - - sub-delims = "!" / "$" / "&" / "'" / "(" / ")" - / "*" / "+" / "," / ";" / "=" - - The purpose of reserved characters is to provide a set of delimiting - characters that are distinguishable from other data within a URI. - URIs that differ in the replacement of a reserved character with its - corresponding percent-encoded octet are not equivalent. Percent- - encoding a reserved character, or decoding a percent-encoded octet - that corresponds to a reserved character, will change how the URI is - interpreted by most applications. Thus, characters in the reserved - set are protected from normalization and are therefore safe to be - used by scheme-specific and producer-specific algorithms for - delimiting data subcomponents within a URI. - - A subset of the reserved characters (gen-delims) is used as - delimiters of the generic URI components described in Section 3. A - component's ABNF syntax rule will not use the reserved or gen-delims - rule names directly; instead, each syntax rule lists the characters - allowed within that component (i.e., not delimiting it), and any of - those characters that are also in the reserved set are "reserved" for - use as subcomponent delimiters within the component. Only the most - common subcomponents are defined by this specification; other - subcomponents may be defined by a URI scheme's specification, or by - the implementation-specific syntax of a URI's dereferencing - algorithm, provided that such subcomponents are delimited by - characters in the reserved set allowed within that component. - - URI producing applications should percent-encode data octets that - correspond to characters in the reserved set unless these characters - are specifically allowed by the URI scheme to represent data in that - component. If a reserved character is found in a URI component and - no delimiting role is known for that character, then it must be - interpreted as representing the data octet corresponding to that - character's encoding in US-ASCII. - -2.3. Unreserved Characters - - Characters that are allowed in a URI but do not have a reserved - purpose are called unreserved. These include uppercase and lowercase - letters, decimal digits, hyphen, period, underscore, and tilde. - - unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" - - - - - -Berners-Lee, et al. Standards Track [Page 13] - -RFC 3986 URI Generic Syntax January 2005 - - - URIs that differ in the replacement of an unreserved character with - its corresponding percent-encoded US-ASCII octet are equivalent: they - identify the same resource. However, URI comparison implementations - do not always perform normalization prior to comparison (see Section - 6). For consistency, percent-encoded octets in the ranges of ALPHA - (%41-%5A and %61-%7A), DIGIT (%30-%39), hyphen (%2D), period (%2E), - underscore (%5F), or tilde (%7E) should not be created by URI - producers and, when found in a URI, should be decoded to their - corresponding unreserved characters by URI normalizers. - -2.4. When to Encode or Decode - - Under normal circumstances, the only time when octets within a URI - are percent-encoded is during the process of producing the URI from - its component parts. This is when an implementation determines which - of the reserved characters are to be used as subcomponent delimiters - and which can be safely used as data. Once produced, a URI is always - in its percent-encoded form. - - When a URI is dereferenced, the components and subcomponents - significant to the scheme-specific dereferencing process (if any) - must be parsed and separated before the percent-encoded octets within - those components can be safely decoded, as otherwise the data may be - mistaken for component delimiters. The only exception is for - percent-encoded octets corresponding to characters in the unreserved - set, which can be decoded at any time. For example, the octet - corresponding to the tilde ("~") character is often encoded as "%7E" - by older URI processing implementations; the "%7E" can be replaced by - "~" without changing its interpretation. - - Because the percent ("%") character serves as the indicator for - percent-encoded octets, it must be percent-encoded as "%25" for that - octet to be used as data within a URI. Implementations must not - percent-encode or decode the same string more than once, as decoding - an already decoded string might lead to misinterpreting a percent - data octet as the beginning of a percent-encoding, or vice versa in - the case of percent-encoding an already percent-encoded string. - -2.5. Identifying Data - - URI characters provide identifying data for each of the URI - components, serving as an external interface for identification - between systems. Although the presence and nature of the URI - production interface is hidden from clients that use its URIs (and is - thus beyond the scope of the interoperability requirements defined by - this specification), it is a frequent source of confusion and errors - in the interpretation of URI character issues. Implementers have to - be aware that there are multiple character encodings involved in the - - - -Berners-Lee, et al. Standards Track [Page 14] - -RFC 3986 URI Generic Syntax January 2005 - - - production and transmission of URIs: local name and data encoding, - public interface encoding, URI character encoding, data format - encoding, and protocol encoding. - - Local names, such as file system names, are stored with a local - character encoding. URI producing applications (e.g., origin - servers) will typically use the local encoding as the basis for - producing meaningful names. The URI producer will transform the - local encoding to one that is suitable for a public interface and - then transform the public interface encoding into the restricted set - of URI characters (reserved, unreserved, and percent-encodings). - Those characters are, in turn, encoded as octets to be used as a - reference within a data format (e.g., a document charset), and such - data formats are often subsequently encoded for transmission over - Internet protocols. - - For most systems, an unreserved character appearing within a URI - component is interpreted as representing the data octet corresponding - to that character's encoding in US-ASCII. Consumers of URIs assume - that the letter "X" corresponds to the octet "01011000", and even - when that assumption is incorrect, there is no harm in making it. A - system that internally provides identifiers in the form of a - different character encoding, such as EBCDIC, will generally perform - character translation of textual identifiers to UTF-8 [STD63] (or - some other superset of the US-ASCII character encoding) at an - internal interface, thereby providing more meaningful identifiers - than those resulting from simply percent-encoding the original - octets. - - For example, consider an information service that provides data, - stored locally using an EBCDIC-based file system, to clients on the - Internet through an HTTP server. When an author creates a file with - the name "Laguna Beach" on that file system, the "http" URI - corresponding to that resource is expected to contain the meaningful - string "Laguna%20Beach". If, however, that server produces URIs by - using an overly simplistic raw octet mapping, then the result would - be a URI containing "%D3%81%87%A4%95%81@%C2%85%81%83%88". An - internal transcoding interface fixes this problem by transcoding the - local name to a superset of US-ASCII prior to producing the URI. - Naturally, proper interpretation of an incoming URI on such an - interface requires that percent-encoded octets be decoded (e.g., - "%20" to SP) before the reverse transcoding is applied to obtain the - local name. - - In some cases, the internal interface between a URI component and the - identifying data that it has been crafted to represent is much less - direct than a character encoding translation. For example, portions - of a URI might reflect a query on non-ASCII data, or numeric - - - -Berners-Lee, et al. Standards Track [Page 15] - -RFC 3986 URI Generic Syntax January 2005 - - - coordinates on a map. Likewise, a URI scheme may define components - with additional encoding requirements that are applied prior to - forming the component and producing the URI. - - When a new URI scheme defines a component that represents textual - data consisting of characters from the Universal Character Set [UCS], - the data should first be encoded as octets according to the UTF-8 - character encoding [STD63]; then only those octets that do not - correspond to characters in the unreserved set should be percent- - encoded. For example, the character A would be represented as "A", - the character LATIN CAPITAL LETTER A WITH GRAVE would be represented - as "%C3%80", and the character KATAKANA LETTER A would be represented - as "%E3%82%A2". - -3. Syntax Components - - The generic URI syntax consists of a hierarchical sequence of - components referred to as the scheme, authority, path, query, and - fragment. - - URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - - hier-part = "//" authority path-abempty - / path-absolute - / path-rootless - / path-empty - - The scheme and path components are required, though the path may be - empty (no characters). When authority is present, the path must - either be empty or begin with a slash ("/") character. When - authority is not present, the path cannot begin with two slash - characters ("//"). These restrictions result in five different ABNF - rules for a path (Section 3.3), only one of which will match any - given URI reference. - - The following are two example URIs and their component parts: - - foo://example.com:8042/over/there?name=ferret#nose - \_/ \______________/\_________/ \_________/ \__/ - | | | | | - scheme authority path query fragment - | _____________________|__ - / \ / \ - urn:example:animal:ferret:nose - - - - - - - -Berners-Lee, et al. Standards Track [Page 16] - -RFC 3986 URI Generic Syntax January 2005 - - -3.1. Scheme - - Each URI begins with a scheme name that refers to a specification for - assigning identifiers within that scheme. As such, the URI syntax is - a federated and extensible naming system wherein each scheme's - specification may further restrict the syntax and semantics of - identifiers using that scheme. - - Scheme names consist of a sequence of characters beginning with a - letter and followed by any combination of letters, digits, plus - ("+"), period ("."), or hyphen ("-"). Although schemes are case- - insensitive, the canonical form is lowercase and documents that - specify schemes must do so with lowercase letters. An implementation - should accept uppercase letters as equivalent to lowercase in scheme - names (e.g., allow "HTTP" as well as "http") for the sake of - robustness but should only produce lowercase scheme names for - consistency. - - scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) - - Individual schemes are not specified by this document. The process - for registration of new URI schemes is defined separately by [BCP35]. - The scheme registry maintains the mapping between scheme names and - their specifications. Advice for designers of new URI schemes can be - found in [RFC2718]. URI scheme specifications must define their own - syntax so that all strings matching their scheme-specific syntax will - also match the <absolute-URI> grammar, as described in Section 4.3. - - When presented with a URI that violates one or more scheme-specific - restrictions, the scheme-specific resolution process should flag the - reference as an error rather than ignore the unused parts; doing so - reduces the number of equivalent URIs and helps detect abuses of the - generic syntax, which might indicate that the URI has been - constructed to mislead the user (Section 7.6). - -3.2. Authority - - Many URI schemes include a hierarchical element for a naming - authority so that governance of the name space defined by the - remainder of the URI is delegated to that authority (which may, in - turn, delegate it further). The generic syntax provides a common - means for distinguishing an authority based on a registered name or - server address, along with optional port and user information. - - The authority component is preceded by a double slash ("//") and is - terminated by the next slash ("/"), question mark ("?"), or number - sign ("#") character, or by the end of the URI. - - - - -Berners-Lee, et al. Standards Track [Page 17] - -RFC 3986 URI Generic Syntax January 2005 - - - authority = [ userinfo "@" ] host [ ":" port ] - - URI producers and normalizers should omit the ":" delimiter that - separates host from port if the port component is empty. Some - schemes do not allow the userinfo and/or port subcomponents. - - If a URI contains an authority component, then the path component - must either be empty or begin with a slash ("/") character. Non- - validating parsers (those that merely separate a URI reference into - its major components) will often ignore the subcomponent structure of - authority, treating it as an opaque string from the double-slash to - the first terminating delimiter, until such time as the URI is - dereferenced. - -3.2.1. User Information - - The userinfo subcomponent may consist of a user name and, optionally, - scheme-specific information about how to gain authorization to access - the resource. The user information, if present, is followed by a - commercial at-sign ("@") that delimits it from the host. - - userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) - - Use of the format "user:password" in the userinfo field is - deprecated. Applications should not render as clear text any data - after the first colon (":") character found within a userinfo - subcomponent unless the data after the colon is the empty string - (indicating no password). Applications may choose to ignore or - reject such data when it is received as part of a reference and - should reject the storage of such data in unencrypted form. The - passing of authentication information in clear text has proven to be - a security risk in almost every case where it has been used. - - Applications that render a URI for the sake of user feedback, such as - in graphical hypertext browsing, should render userinfo in a way that - is distinguished from the rest of a URI, when feasible. Such - rendering will assist the user in cases where the userinfo has been - misleadingly crafted to look like a trusted domain name - (Section 7.6). - -3.2.2. Host - - The host subcomponent of authority is identified by an IP literal - encapsulated within square brackets, an IPv4 address in dotted- - decimal form, or a registered name. The host subcomponent is case- - insensitive. The presence of a host subcomponent within a URI does - not imply that the scheme requires access to the given host on the - Internet. In many cases, the host syntax is used only for the sake - - - -Berners-Lee, et al. Standards Track [Page 18] - -RFC 3986 URI Generic Syntax January 2005 - - - of reusing the existing registration process created and deployed for - DNS, thus obtaining a globally unique name without the cost of - deploying another registry. However, such use comes with its own - costs: domain name ownership may change over time for reasons not - anticipated by the URI producer. In other cases, the data within the - host component identifies a registered name that has nothing to do - with an Internet host. We use the name "host" for the ABNF rule - because that is its most common purpose, not its only purpose. - - host = IP-literal / IPv4address / reg-name - - The syntax rule for host is ambiguous because it does not completely - distinguish between an IPv4address and a reg-name. In order to - disambiguate the syntax, we apply the "first-match-wins" algorithm: - If host matches the rule for IPv4address, then it should be - considered an IPv4 address literal and not a reg-name. Although host - is case-insensitive, producers and normalizers should use lowercase - for registered names and hexadecimal addresses for the sake of - uniformity, while only using uppercase letters for percent-encodings. - - A host identified by an Internet Protocol literal address, version 6 - [RFC3513] or later, is distinguished by enclosing the IP literal - within square brackets ("[" and "]"). This is the only place where - square bracket characters are allowed in the URI syntax. In - anticipation of future, as-yet-undefined IP literal address formats, - an implementation may use an optional version flag to indicate such a - format explicitly rather than rely on heuristic determination. - - IP-literal = "[" ( IPv6address / IPvFuture ) "]" - - IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" ) - - The version flag does not indicate the IP version; rather, it - indicates future versions of the literal format. As such, - implementations must not provide the version flag for the existing - IPv4 and IPv6 literal address forms described below. If a URI - containing an IP-literal that starts with "v" (case-insensitive), - indicating that the version flag is present, is dereferenced by an - application that does not know the meaning of that version flag, then - the application should return an appropriate error for "address - mechanism not supported". - - A host identified by an IPv6 literal address is represented inside - the square brackets without a preceding version flag. The ABNF - provided here is a translation of the text definition of an IPv6 - literal address provided in [RFC3513]. This syntax does not support - IPv6 scoped addressing zone identifiers. - - - - -Berners-Lee, et al. Standards Track [Page 19] - -RFC 3986 URI Generic Syntax January 2005 - - - A 128-bit IPv6 address is divided into eight 16-bit pieces. Each - piece is represented numerically in case-insensitive hexadecimal, - using one to four hexadecimal digits (leading zeroes are permitted). - The eight encoded pieces are given most-significant first, separated - by colon characters. Optionally, the least-significant two pieces - may instead be represented in IPv4 address textual format. A - sequence of one or more consecutive zero-valued 16-bit pieces within - the address may be elided, omitting all their digits and leaving - exactly two consecutive colons in their place to mark the elision. - - IPv6address = 6( h16 ":" ) ls32 - / "::" 5( h16 ":" ) ls32 - / [ h16 ] "::" 4( h16 ":" ) ls32 - / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32 - / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 - / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 - / [ *4( h16 ":" ) h16 ] "::" ls32 - / [ *5( h16 ":" ) h16 ] "::" h16 - / [ *6( h16 ":" ) h16 ] "::" - - ls32 = ( h16 ":" h16 ) / IPv4address - ; least-significant 32 bits of address - - h16 = 1*4HEXDIG - ; 16 bits of address represented in hexadecimal - - A host identified by an IPv4 literal address is represented in - dotted-decimal notation (a sequence of four decimal numbers in the - range 0 to 255, separated by "."), as described in [RFC1123] by - reference to [RFC0952]. Note that other forms of dotted notation may - be interpreted on some platforms, as described in Section 7.4, but - only the dotted-decimal form of four octets is allowed by this - grammar. - - IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet - - dec-octet = DIGIT ; 0-9 - / %x31-39 DIGIT ; 10-99 - / "1" 2DIGIT ; 100-199 - / "2" %x30-34 DIGIT ; 200-249 - / "25" %x30-35 ; 250-255 - - A host identified by a registered name is a sequence of characters - usually intended for lookup within a locally defined host or service - name registry, though the URI's scheme-specific semantics may require - that a specific registry (or fixed name table) be used instead. The - most common name registry mechanism is the Domain Name System (DNS). - A registered name intended for lookup in the DNS uses the syntax - - - -Berners-Lee, et al. Standards Track [Page 20] - -RFC 3986 URI Generic Syntax January 2005 - - - defined in Section 3.5 of [RFC1034] and Section 2.1 of [RFC1123]. - Such a name consists of a sequence of domain labels separated by ".", - each domain label starting and ending with an alphanumeric character - and possibly also containing "-" characters. The rightmost domain - label of a fully qualified domain name in DNS may be followed by a - single "." and should be if it is necessary to distinguish between - the complete domain name and some local domain. - - reg-name = *( unreserved / pct-encoded / sub-delims ) - - If the URI scheme defines a default for host, then that default - applies when the host subcomponent is undefined or when the - registered name is empty (zero length). For example, the "file" URI - scheme is defined so that no authority, an empty host, and - "localhost" all mean the end-user's machine, whereas the "http" - scheme considers a missing authority or empty host invalid. - - This specification does not mandate a particular registered name - lookup technology and therefore does not restrict the syntax of reg- - name beyond what is necessary for interoperability. Instead, it - delegates the issue of registered name syntax conformance to the - operating system of each application performing URI resolution, and - that operating system decides what it will allow for the purpose of - host identification. A URI resolution implementation might use DNS, - host tables, yellow pages, NetInfo, WINS, or any other system for - lookup of registered names. However, a globally scoped naming - system, such as DNS fully qualified domain names, is necessary for - URIs intended to have global scope. URI producers should use names - that conform to the DNS syntax, even when use of DNS is not - immediately apparent, and should limit these names to no more than - 255 characters in length. - - The reg-name syntax allows percent-encoded octets in order to - represent non-ASCII registered names in a uniform way that is - independent of the underlying name resolution technology. Non-ASCII - characters must first be encoded according to UTF-8 [STD63], and then - each octet of the corresponding UTF-8 sequence must be percent- - encoded to be represented as URI characters. URI producing - applications must not use percent-encoding in host unless it is used - to represent a UTF-8 character sequence. When a non-ASCII registered - name represents an internationalized domain name intended for - resolution via the DNS, the name must be transformed to the IDNA - encoding [RFC3490] prior to name lookup. URI producers should - provide these registered names in the IDNA encoding, rather than a - percent-encoding, if they wish to maximize interoperability with - legacy URI resolvers. - - - - - -Berners-Lee, et al. Standards Track [Page 21] - -RFC 3986 URI Generic Syntax January 2005 - - -3.2.3. Port - - The port subcomponent of authority is designated by an optional port - number in decimal following the host and delimited from it by a - single colon (":") character. - - port = *DIGIT - - A scheme may define a default port. For example, the "http" scheme - defines a default port of "80", corresponding to its reserved TCP - port number. The type of port designated by the port number (e.g., - TCP, UDP, SCTP) is defined by the URI scheme. URI producers and - normalizers should omit the port component and its ":" delimiter if - port is empty or if its value would be the same as that of the - scheme's default. - -3.3. Path - - The path component contains data, usually organized in hierarchical - form, that, along with data in the non-hierarchical query component - (Section 3.4), serves to identify a resource within the scope of the - URI's scheme and naming authority (if any). The path is terminated - by the first question mark ("?") or number sign ("#") character, or - by the end of the URI. - - If a URI contains an authority component, then the path component - must either be empty or begin with a slash ("/") character. If a URI - does not contain an authority component, then the path cannot begin - with two slash characters ("//"). In addition, a URI reference - (Section 4.1) may be a relative-path reference, in which case the - first path segment cannot contain a colon (":") character. The ABNF - requires five separate rules to disambiguate these cases, only one of - which will match the path substring within a given URI reference. We - use the generic term "path component" to describe the URI substring - matched by the parser to one of these rules. - - path = path-abempty ; begins with "/" or is empty - / path-absolute ; begins with "/" but not "//" - / path-noscheme ; begins with a non-colon segment - / path-rootless ; begins with a segment - / path-empty ; zero characters - - path-abempty = *( "/" segment ) - path-absolute = "/" [ segment-nz *( "/" segment ) ] - path-noscheme = segment-nz-nc *( "/" segment ) - path-rootless = segment-nz *( "/" segment ) - path-empty = 0<pchar> - - - - -Berners-Lee, et al. Standards Track [Page 22] - -RFC 3986 URI Generic Syntax January 2005 - - - segment = *pchar - segment-nz = 1*pchar - segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" ) - ; non-zero-length segment without any colon ":" - - pchar = unreserved / pct-encoded / sub-delims / ":" / "@" - - A path consists of a sequence of path segments separated by a slash - ("/") character. A path is always defined for a URI, though the - defined path may be empty (zero length). Use of the slash character - to indicate hierarchy is only required when a URI will be used as the - context for relative references. For example, the URI - <mailto:fred@example.com> has a path of "fred@example.com", whereas - the URI <foo://info.example.com?fred> has an empty path. - - The path segments "." and "..", also known as dot-segments, are - defined for relative reference within the path name hierarchy. They - are intended for use at the beginning of a relative-path reference - (Section 4.2) to indicate relative position within the hierarchical - tree of names. This is similar to their role within some operating - systems' file directory structures to indicate the current directory - and parent directory, respectively. However, unlike in a file - system, these dot-segments are only interpreted within the URI path - hierarchy and are removed as part of the resolution process (Section - 5.2). - - Aside from dot-segments in hierarchical paths, a path segment is - considered opaque by the generic syntax. URI producing applications - often use the reserved characters allowed in a segment to delimit - scheme-specific or dereference-handler-specific subcomponents. For - example, the semicolon (";") and equals ("=") reserved characters are - often used to delimit parameters and parameter values applicable to - that segment. The comma (",") reserved character is often used for - similar purposes. For example, one URI producer might use a segment - such as "name;v=1.1" to indicate a reference to version 1.1 of - "name", whereas another might use a segment such as "name,1.1" to - indicate the same. Parameter types may be defined by scheme-specific - semantics, but in most cases the syntax of a parameter is specific to - the implementation of the URI's dereferencing algorithm. - -3.4. Query - - The query component contains non-hierarchical data that, along with - data in the path component (Section 3.3), serves to identify a - resource within the scope of the URI's scheme and naming authority - (if any). The query component is indicated by the first question - mark ("?") character and terminated by a number sign ("#") character - or by the end of the URI. - - - -Berners-Lee, et al. Standards Track [Page 23] - -RFC 3986 URI Generic Syntax January 2005 - - - query = *( pchar / "/" / "?" ) - - The characters slash ("/") and question mark ("?") may represent data - within the query component. Beware that some older, erroneous - implementations may not handle such data correctly when it is used as - the base URI for relative references (Section 5.1), apparently - because they fail to distinguish query data from path data when - looking for hierarchical separators. However, as query components - are often used to carry identifying information in the form of - "key=value" pairs and one frequently used value is a reference to - another URI, it is sometimes better for usability to avoid percent- - encoding those characters. - -3.5. Fragment - - The fragment identifier component of a URI allows indirect - identification of a secondary resource by reference to a primary - resource and additional identifying information. The identified - secondary resource may be some portion or subset of the primary - resource, some view on representations of the primary resource, or - some other resource defined or described by those representations. A - fragment identifier component is indicated by the presence of a - number sign ("#") character and terminated by the end of the URI. - - fragment = *( pchar / "/" / "?" ) - - The semantics of a fragment identifier are defined by the set of - representations that might result from a retrieval action on the - primary resource. The fragment's format and resolution is therefore - dependent on the media type [RFC2046] of a potentially retrieved - representation, even though such a retrieval is only performed if the - URI is dereferenced. If no such representation exists, then the - semantics of the fragment are considered unknown and are effectively - unconstrained. Fragment identifier semantics are independent of the - URI scheme and thus cannot be redefined by scheme specifications. - - Individual media types may define their own restrictions on or - structures within the fragment identifier syntax for specifying - different types of subsets, views, or external references that are - identifiable as secondary resources by that media type. If the - primary resource has multiple representations, as is often the case - for resources whose representation is selected based on attributes of - the retrieval request (a.k.a., content negotiation), then whatever is - identified by the fragment should be consistent across all of those - representations. Each representation should either define the - fragment so that it corresponds to the same secondary resource, - regardless of how it is represented, or should leave the fragment - undefined (i.e., not found). - - - -Berners-Lee, et al. Standards Track [Page 24] - -RFC 3986 URI Generic Syntax January 2005 - - - As with any URI, use of a fragment identifier component does not - imply that a retrieval action will take place. A URI with a fragment - identifier may be used to refer to the secondary resource without any - implication that the primary resource is accessible or will ever be - accessed. - - Fragment identifiers have a special role in information retrieval - systems as the primary form of client-side indirect referencing, - allowing an author to specifically identify aspects of an existing - resource that are only indirectly provided by the resource owner. As - such, the fragment identifier is not used in the scheme-specific - processing of a URI; instead, the fragment identifier is separated - from the rest of the URI prior to a dereference, and thus the - identifying information within the fragment itself is dereferenced - solely by the user agent, regardless of the URI scheme. Although - this separate handling is often perceived to be a loss of - information, particularly for accurate redirection of references as - resources move over time, it also serves to prevent information - providers from denying reference authors the right to refer to - information within a resource selectively. Indirect referencing also - provides additional flexibility and extensibility to systems that use - URIs, as new media types are easier to define and deploy than new - schemes of identification. - - The characters slash ("/") and question mark ("?") are allowed to - represent data within the fragment identifier. Beware that some - older, erroneous implementations may not handle this data correctly - when it is used as the base URI for relative references (Section - 5.1). - -4. Usage - - When applications make reference to a URI, they do not always use the - full form of reference defined by the "URI" syntax rule. To save - space and take advantage of hierarchical locality, many Internet - protocol elements and media type formats allow an abbreviation of a - URI, whereas others restrict the syntax to a particular form of URI. - We define the most common forms of reference syntax in this - specification because they impact and depend upon the design of the - generic syntax, requiring a uniform parsing algorithm in order to be - interpreted consistently. - -4.1. URI Reference - - URI-reference is used to denote the most common usage of a resource - identifier. - - URI-reference = URI / relative-ref - - - -Berners-Lee, et al. Standards Track [Page 25] - -RFC 3986 URI Generic Syntax January 2005 - - - A URI-reference is either a URI or a relative reference. If the - URI-reference's prefix does not match the syntax of a scheme followed - by its colon separator, then the URI-reference is a relative - reference. - - A URI-reference is typically parsed first into the five URI - components, in order to determine what components are present and - whether the reference is relative. Then, each component is parsed - for its subparts and their validation. The ABNF of URI-reference, - along with the "first-match-wins" disambiguation rule, is sufficient - to define a validating parser for the generic syntax. Readers - familiar with regular expressions should see Appendix B for an - example of a non-validating URI-reference parser that will take any - given string and extract the URI components. - -4.2. Relative Reference - - A relative reference takes advantage of the hierarchical syntax - (Section 1.2.3) to express a URI reference relative to the name space - of another hierarchical URI. - - relative-ref = relative-part [ "?" query ] [ "#" fragment ] - - relative-part = "//" authority path-abempty - / path-absolute - / path-noscheme - / path-empty - - The URI referred to by a relative reference, also known as the target - URI, is obtained by applying the reference resolution algorithm of - Section 5. - - A relative reference that begins with two slash characters is termed - a network-path reference; such references are rarely used. A - relative reference that begins with a single slash character is - termed an absolute-path reference. A relative reference that does - not begin with a slash character is termed a relative-path reference. - - A path segment that contains a colon character (e.g., "this:that") - cannot be used as the first segment of a relative-path reference, as - it would be mistaken for a scheme name. Such a segment must be - preceded by a dot-segment (e.g., "./this:that") to make a relative- - path reference. - - - - - - - - -Berners-Lee, et al. Standards Track [Page 26] - -RFC 3986 URI Generic Syntax January 2005 - - -4.3. Absolute URI - - Some protocol elements allow only the absolute form of a URI without - a fragment identifier. For example, defining a base URI for later - use by relative references calls for an absolute-URI syntax rule that - does not allow a fragment. - - absolute-URI = scheme ":" hier-part [ "?" query ] - - URI scheme specifications must define their own syntax so that all - strings matching their scheme-specific syntax will also match the - <absolute-URI> grammar. Scheme specifications will not define - fragment identifier syntax or usage, regardless of its applicability - to resources identifiable via that scheme, as fragment identification - is orthogonal to scheme definition. However, scheme specifications - are encouraged to include a wide range of examples, including - examples that show use of the scheme's URIs with fragment identifiers - when such usage is appropriate. - -4.4. Same-Document Reference - - When a URI reference refers to a URI that is, aside from its fragment - component (if any), identical to the base URI (Section 5.1), that - reference is called a "same-document" reference. The most frequent - examples of same-document references are relative references that are - empty or include only the number sign ("#") separator followed by a - fragment identifier. - - When a same-document reference is dereferenced for a retrieval - action, the target of that reference is defined to be within the same - entity (representation, document, or message) as the reference; - therefore, a dereference should not result in a new retrieval action. - - Normalization of the base and target URIs prior to their comparison, - as described in Sections 6.2.2 and 6.2.3, is allowed but rarely - performed in practice. Normalization may increase the set of same- - document references, which may be of benefit to some caching - applications. As such, reference authors should not assume that a - slightly different, though equivalent, reference URI will (or will - not) be interpreted as a same-document reference by any given - application. - -4.5. Suffix Reference - - The URI syntax is designed for unambiguous reference to resources and - extensibility via the URI scheme. However, as URI identification and - usage have become commonplace, traditional media (television, radio, - newspapers, billboards, etc.) have increasingly used a suffix of the - - - -Berners-Lee, et al. Standards Track [Page 27] - -RFC 3986 URI Generic Syntax January 2005 - - - URI as a reference, consisting of only the authority and path - portions of the URI, such as - - www.w3.org/Addressing/ - - or simply a DNS registered name on its own. Such references are - primarily intended for human interpretation rather than for machines, - with the assumption that context-based heuristics are sufficient to - complete the URI (e.g., most registered names beginning with "www" - are likely to have a URI prefix of "http://"). Although there is no - standard set of heuristics for disambiguating a URI suffix, many - client implementations allow them to be entered by the user and - heuristically resolved. - - Although this practice of using suffix references is common, it - should be avoided whenever possible and should never be used in - situations where long-term references are expected. The heuristics - noted above will change over time, particularly when a new URI scheme - becomes popular, and are often incorrect when used out of context. - Furthermore, they can lead to security issues along the lines of - those described in [RFC1535]. - - As a URI suffix has the same syntax as a relative-path reference, a - suffix reference cannot be used in contexts where a relative - reference is expected. As a result, suffix references are limited to - places where there is no defined base URI, such as dialog boxes and - off-line advertisements. - -5. Reference Resolution - - This section defines the process of resolving a URI reference within - a context that allows relative references so that the result is a - string matching the <URI> syntax rule of Section 3. - -5.1. Establishing a Base URI - - The term "relative" implies that a "base URI" exists against which - the relative reference is applied. Aside from fragment-only - references (Section 4.4), relative references are only usable when a - base URI is known. A base URI must be established by the parser - prior to parsing URI references that might be relative. A base URI - must conform to the <absolute-URI> syntax rule (Section 4.3). If the - base URI is obtained from a URI reference, then that reference must - be converted to absolute form and stripped of any fragment component - prior to its use as a base URI. - - - - - - -Berners-Lee, et al. Standards Track [Page 28] - -RFC 3986 URI Generic Syntax January 2005 - - - The base URI of a reference can be established in one of four ways, - discussed below in order of precedence. The order of precedence can - be thought of in terms of layers, where the innermost defined base - URI has the highest precedence. This can be visualized graphically - as follows: - - .----------------------------------------------------------. - | .----------------------------------------------------. | - | | .----------------------------------------------. | | - | | | .----------------------------------------. | | | - | | | | .----------------------------------. | | | | - | | | | | <relative-reference> | | | | | - | | | | `----------------------------------' | | | | - | | | | (5.1.1) Base URI embedded in content | | | | - | | | `----------------------------------------' | | | - | | | (5.1.2) Base URI of the encapsulating entity | | | - | | | (message, representation, or none) | | | - | | `----------------------------------------------' | | - | | (5.1.3) URI used to retrieve the entity | | - | `----------------------------------------------------' | - | (5.1.4) Default Base URI (application-dependent) | - `----------------------------------------------------------' - -5.1.1. Base URI Embedded in Content - - Within certain media types, a base URI for relative references can be - embedded within the content itself so that it can be readily obtained - by a parser. This can be useful for descriptive documents, such as - tables of contents, which may be transmitted to others through - protocols other than their usual retrieval context (e.g., email or - USENET news). - - It is beyond the scope of this specification to specify how, for each - media type, a base URI can be embedded. The appropriate syntax, when - available, is described by the data format specification associated - with each media type. - -5.1.2. Base URI from the Encapsulating Entity - - If no base URI is embedded, the base URI is defined by the - representation's retrieval context. For a document that is enclosed - within another entity, such as a message or archive, the retrieval - context is that entity. Thus, the default base URI of a - representation is the base URI of the entity in which the - representation is encapsulated. - - - - - - -Berners-Lee, et al. Standards Track [Page 29] - -RFC 3986 URI Generic Syntax January 2005 - - - A mechanism for embedding a base URI within MIME container types - (e.g., the message and multipart types) is defined by MHTML - [RFC2557]. Protocols that do not use the MIME message header syntax, - but that do allow some form of tagged metadata to be included within - messages, may define their own syntax for defining a base URI as part - of a message. - -5.1.3. Base URI from the Retrieval URI - - If no base URI is embedded and the representation is not encapsulated - within some other entity, then, if a URI was used to retrieve the - representation, that URI shall be considered the base URI. Note that - if the retrieval was the result of a redirected request, the last URI - used (i.e., the URI that resulted in the actual retrieval of the - representation) is the base URI. - -5.1.4. Default Base URI - - If none of the conditions described above apply, then the base URI is - defined by the context of the application. As this definition is - necessarily application-dependent, failing to define a base URI by - using one of the other methods may result in the same content being - interpreted differently by different types of applications. - - A sender of a representation containing relative references is - responsible for ensuring that a base URI for those references can be - established. Aside from fragment-only references, relative - references can only be used reliably in situations where the base URI - is well defined. - -5.2. Relative Resolution - - This section describes an algorithm for converting a URI reference - that might be relative to a given base URI into the parsed components - of the reference's target. The components can then be recomposed, as - described in Section 5.3, to form the target URI. This algorithm - provides definitive results that can be used to test the output of - other implementations. Applications may implement relative reference - resolution by using some other algorithm, provided that the results - match what would be given by this one. - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 30] - -RFC 3986 URI Generic Syntax January 2005 - - -5.2.1. Pre-parse the Base URI - - The base URI (Base) is established according to the procedure of - Section 5.1 and parsed into the five main components described in - Section 3. Note that only the scheme component is required to be - present in a base URI; the other components may be empty or - undefined. A component is undefined if its associated delimiter does - not appear in the URI reference; the path component is never - undefined, though it may be empty. - - Normalization of the base URI, as described in Sections 6.2.2 and - 6.2.3, is optional. A URI reference must be transformed to its - target URI before it can be normalized. - -5.2.2. Transform References - - For each URI reference (R), the following pseudocode describes an - algorithm for transforming R into its target URI (T): - - -- The URI reference is parsed into the five URI components - -- - (R.scheme, R.authority, R.path, R.query, R.fragment) = parse(R); - - -- A non-strict parser may ignore a scheme in the reference - -- if it is identical to the base URI's scheme. - -- - if ((not strict) and (R.scheme == Base.scheme)) then - undefine(R.scheme); - endif; - - - - - - - - - - - - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 31] - -RFC 3986 URI Generic Syntax January 2005 - - - if defined(R.scheme) then - T.scheme = R.scheme; - T.authority = R.authority; - T.path = remove_dot_segments(R.path); - T.query = R.query; - else - if defined(R.authority) then - T.authority = R.authority; - T.path = remove_dot_segments(R.path); - T.query = R.query; - else - if (R.path == "") then - T.path = Base.path; - if defined(R.query) then - T.query = R.query; - else - T.query = Base.query; - endif; - else - if (R.path starts-with "/") then - T.path = remove_dot_segments(R.path); - else - T.path = merge(Base.path, R.path); - T.path = remove_dot_segments(T.path); - endif; - T.query = R.query; - endif; - T.authority = Base.authority; - endif; - T.scheme = Base.scheme; - endif; - - T.fragment = R.fragment; - -5.2.3. Merge Paths - - The pseudocode above refers to a "merge" routine for merging a - relative-path reference with the path of the base URI. This is - accomplished as follows: - - o If the base URI has a defined authority component and an empty - path, then return a string consisting of "/" concatenated with the - reference's path; otherwise, - - - - - - - - -Berners-Lee, et al. Standards Track [Page 32] - -RFC 3986 URI Generic Syntax January 2005 - - - o return a string consisting of the reference's path component - appended to all but the last segment of the base URI's path (i.e., - excluding any characters after the right-most "/" in the base URI - path, or excluding the entire base URI path if it does not contain - any "/" characters). - -5.2.4. Remove Dot Segments - - The pseudocode also refers to a "remove_dot_segments" routine for - interpreting and removing the special "." and ".." complete path - segments from a referenced path. This is done after the path is - extracted from a reference, whether or not the path was relative, in - order to remove any invalid or extraneous dot-segments prior to - forming the target URI. Although there are many ways to accomplish - this removal process, we describe a simple method using two string - buffers. - - 1. The input buffer is initialized with the now-appended path - components and the output buffer is initialized to the empty - string. - - 2. While the input buffer is not empty, loop as follows: - - A. If the input buffer begins with a prefix of "../" or "./", - then remove that prefix from the input buffer; otherwise, - - B. if the input buffer begins with a prefix of "/./" or "/.", - where "." is a complete path segment, then replace that - prefix with "/" in the input buffer; otherwise, - - C. if the input buffer begins with a prefix of "/../" or "/..", - where ".." is a complete path segment, then replace that - prefix with "/" in the input buffer and remove the last - segment and its preceding "/" (if any) from the output - buffer; otherwise, - - D. if the input buffer consists only of "." or "..", then remove - that from the input buffer; otherwise, - - E. move the first path segment in the input buffer to the end of - the output buffer, including the initial "/" character (if - any) and any subsequent characters up to, but not including, - the next "/" character or the end of the input buffer. - - 3. Finally, the output buffer is returned as the result of - remove_dot_segments. - - - - - -Berners-Lee, et al. Standards Track [Page 33] - -RFC 3986 URI Generic Syntax January 2005 - - - Note that dot-segments are intended for use in URI references to - express an identifier relative to the hierarchy of names in the base - URI. The remove_dot_segments algorithm respects that hierarchy by - removing extra dot-segments rather than treat them as an error or - leaving them to be misinterpreted by dereference implementations. - - The following illustrates how the above steps are applied for two - examples of merged paths, showing the state of the two buffers after - each step. - - STEP OUTPUT BUFFER INPUT BUFFER - - 1 : /a/b/c/./../../g - 2E: /a /b/c/./../../g - 2E: /a/b /c/./../../g - 2E: /a/b/c /./../../g - 2B: /a/b/c /../../g - 2C: /a/b /../g - 2C: /a /g - 2E: /a/g - - STEP OUTPUT BUFFER INPUT BUFFER - - 1 : mid/content=5/../6 - 2E: mid /content=5/../6 - 2E: mid/content=5 /../6 - 2C: mid /6 - 2E: mid/6 - - Some applications may find it more efficient to implement the - remove_dot_segments algorithm by using two segment stacks rather than - strings. - - Note: Beware that some older, erroneous implementations will fail - to separate a reference's query component from its path component - prior to merging the base and reference paths, resulting in an - interoperability failure if the query component contains the - strings "/../" or "/./". - - - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 34] - -RFC 3986 URI Generic Syntax January 2005 - - -5.3. Component Recomposition - - Parsed URI components can be recomposed to obtain the corresponding - URI reference string. Using pseudocode, this would be: - - result = "" - - if defined(scheme) then - append scheme to result; - append ":" to result; - endif; - - if defined(authority) then - append "//" to result; - append authority to result; - endif; - - append path to result; - - if defined(query) then - append "?" to result; - append query to result; - endif; - - if defined(fragment) then - append "#" to result; - append fragment to result; - endif; - - return result; - - Note that we are careful to preserve the distinction between a - component that is undefined, meaning that its separator was not - present in the reference, and a component that is empty, meaning that - the separator was present and was immediately followed by the next - component separator or the end of the reference. - -5.4. Reference Resolution Examples - - Within a representation with a well defined base URI of - - http://a/b/c/d;p?q - - a relative reference is transformed to its target URI as follows. - - - - - - - -Berners-Lee, et al. Standards Track [Page 35] - -RFC 3986 URI Generic Syntax January 2005 - - -5.4.1. Normal Examples - - "g:h" = "g:h" - "g" = "http://a/b/c/g" - "./g" = "http://a/b/c/g" - "g/" = "http://a/b/c/g/" - "/g" = "http://a/g" - "//g" = "http://g" - "?y" = "http://a/b/c/d;p?y" - "g?y" = "http://a/b/c/g?y" - "#s" = "http://a/b/c/d;p?q#s" - "g#s" = "http://a/b/c/g#s" - "g?y#s" = "http://a/b/c/g?y#s" - ";x" = "http://a/b/c/;x" - "g;x" = "http://a/b/c/g;x" - "g;x?y#s" = "http://a/b/c/g;x?y#s" - "" = "http://a/b/c/d;p?q" - "." = "http://a/b/c/" - "./" = "http://a/b/c/" - ".." = "http://a/b/" - "../" = "http://a/b/" - "../g" = "http://a/b/g" - "../.." = "http://a/" - "../../" = "http://a/" - "../../g" = "http://a/g" - -5.4.2. Abnormal Examples - - Although the following abnormal examples are unlikely to occur in - normal practice, all URI parsers should be capable of resolving them - consistently. Each example uses the same base as that above. - - Parsers must be careful in handling cases where there are more ".." - segments in a relative-path reference than there are hierarchical - levels in the base URI's path. Note that the ".." syntax cannot be - used to change the authority component of a URI. - - "../../../g" = "http://a/g" - "../../../../g" = "http://a/g" - - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 36] - -RFC 3986 URI Generic Syntax January 2005 - - - Similarly, parsers must remove the dot-segments "." and ".." when - they are complete components of a path, but not when they are only - part of a segment. - - "/./g" = "http://a/g" - "/../g" = "http://a/g" - "g." = "http://a/b/c/g." - ".g" = "http://a/b/c/.g" - "g.." = "http://a/b/c/g.." - "..g" = "http://a/b/c/..g" - - Less likely are cases where the relative reference uses unnecessary - or nonsensical forms of the "." and ".." complete path segments. - - "./../g" = "http://a/b/g" - "./g/." = "http://a/b/c/g/" - "g/./h" = "http://a/b/c/g/h" - "g/../h" = "http://a/b/c/h" - "g;x=1/./y" = "http://a/b/c/g;x=1/y" - "g;x=1/../y" = "http://a/b/c/y" - - Some applications fail to separate the reference's query and/or - fragment components from the path component before merging it with - the base path and removing dot-segments. This error is rarely - noticed, as typical usage of a fragment never includes the hierarchy - ("/") character and the query component is not normally used within - relative references. - - "g?y/./x" = "http://a/b/c/g?y/./x" - "g?y/../x" = "http://a/b/c/g?y/../x" - "g#s/./x" = "http://a/b/c/g#s/./x" - "g#s/../x" = "http://a/b/c/g#s/../x" - - Some parsers allow the scheme name to be present in a relative - reference if it is the same as the base URI scheme. This is - considered to be a loophole in prior specifications of partial URI - [RFC1630]. Its use should be avoided but is allowed for backward - compatibility. - - "http:g" = "http:g" ; for strict parsers - / "http://a/b/c/g" ; for backward compatibility - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 37] - -RFC 3986 URI Generic Syntax January 2005 - - -6. Normalization and Comparison - - One of the most common operations on URIs is simple comparison: - determining whether two URIs are equivalent without using the URIs to - access their respective resource(s). A comparison is performed every - time a response cache is accessed, a browser checks its history to - color a link, or an XML parser processes tags within a namespace. - Extensive normalization prior to comparison of URIs is often used by - spiders and indexing engines to prune a search space or to reduce - duplication of request actions and response storage. - - URI comparison is performed for some particular purpose. Protocols - or implementations that compare URIs for different purposes will - often be subject to differing design trade-offs in regards to how - much effort should be spent in reducing aliased identifiers. This - section describes various methods that may be used to compare URIs, - the trade-offs between them, and the types of applications that might - use them. - -6.1. Equivalence - - Because URIs exist to identify resources, presumably they should be - considered equivalent when they identify the same resource. However, - this definition of equivalence is not of much practical use, as there - is no way for an implementation to compare two resources unless it - has full knowledge or control of them. For this reason, - determination of equivalence or difference of URIs is based on string - comparison, perhaps augmented by reference to additional rules - provided by URI scheme definitions. We use the terms "different" and - "equivalent" to describe the possible outcomes of such comparisons, - but there are many application-dependent versions of equivalence. - - Even though it is possible to determine that two URIs are equivalent, - URI comparison is not sufficient to determine whether two URIs - identify different resources. For example, an owner of two different - domain names could decide to serve the same resource from both, - resulting in two different URIs. Therefore, comparison methods are - designed to minimize false negatives while strictly avoiding false - positives. - - In testing for equivalence, applications should not directly compare - relative references; the references should be converted to their - respective target URIs before comparison. When URIs are compared to - select (or avoid) a network action, such as retrieval of a - representation, fragment components (if any) should be excluded from - the comparison. - - - - - -Berners-Lee, et al. Standards Track [Page 38] - -RFC 3986 URI Generic Syntax January 2005 - - -6.2. Comparison Ladder - - A variety of methods are used in practice to test URI equivalence. - These methods fall into a range, distinguished by the amount of - processing required and the degree to which the probability of false - negatives is reduced. As noted above, false negatives cannot be - eliminated. In practice, their probability can be reduced, but this - reduction requires more processing and is not cost-effective for all - applications. - - If this range of comparison practices is considered as a ladder, the - following discussion will climb the ladder, starting with practices - that are cheap but have a relatively higher chance of producing false - negatives, and proceeding to those that have higher computational - cost and lower risk of false negatives. - -6.2.1. Simple String Comparison - - If two URIs, when considered as character strings, are identical, - then it is safe to conclude that they are equivalent. This type of - equivalence test has very low computational cost and is in wide use - in a variety of applications, particularly in the domain of parsing. - - Testing strings for equivalence requires some basic precautions. - This procedure is often referred to as "bit-for-bit" or - "byte-for-byte" comparison, which is potentially misleading. Testing - strings for equality is normally based on pair comparison of the - characters that make up the strings, starting from the first and - proceeding until both strings are exhausted and all characters are - found to be equal, until a pair of characters compares unequal, or - until one of the strings is exhausted before the other. - - This character comparison requires that each pair of characters be - put in comparable form. For example, should one URI be stored in a - byte array in EBCDIC encoding and the second in a Java String object - (UTF-16), bit-for-bit comparisons applied naively will produce - errors. It is better to speak of equality on a character-for- - character basis rather than on a byte-for-byte or bit-for-bit basis. - In practical terms, character-by-character comparisons should be done - codepoint-by-codepoint after conversion to a common character - encoding. - - False negatives are caused by the production and use of URI aliases. - Unnecessary aliases can be reduced, regardless of the comparison - method, by consistently providing URI references in an already- - normalized form (i.e., a form identical to what would be produced - after normalization is applied, as described below). - - - - -Berners-Lee, et al. Standards Track [Page 39] - -RFC 3986 URI Generic Syntax January 2005 - - - Protocols and data formats often limit some URI comparisons to simple - string comparison, based on the theory that people and - implementations will, in their own best interest, be consistent in - providing URI references, or at least consistent enough to negate any - efficiency that might be obtained from further normalization. - -6.2.2. Syntax-Based Normalization - - Implementations may use logic based on the definitions provided by - this specification to reduce the probability of false negatives. - This processing is moderately higher in cost than character-for- - character string comparison. For example, an application using this - approach could reasonably consider the following two URIs equivalent: - - example://a/b/c/%7Bfoo%7D - eXAMPLE://a/./b/../b/%63/%7bfoo%7d - - Web user agents, such as browsers, typically apply this type of URI - normalization when determining whether a cached response is - available. Syntax-based normalization includes such techniques as - case normalization, percent-encoding normalization, and removal of - dot-segments. - -6.2.2.1. Case Normalization - - For all URIs, the hexadecimal digits within a percent-encoding - triplet (e.g., "%3a" versus "%3A") are case-insensitive and therefore - should be normalized to use uppercase letters for the digits A-F. - - When a URI uses components of the generic syntax, the component - syntax equivalence rules always apply; namely, that the scheme and - host are case-insensitive and therefore should be normalized to - lowercase. For example, the URI <HTTP://www.EXAMPLE.com/> is - equivalent to <http://www.example.com/>. The other generic syntax - components are assumed to be case-sensitive unless specifically - defined otherwise by the scheme (see Section 6.2.3). - -6.2.2.2. Percent-Encoding Normalization - - The percent-encoding mechanism (Section 2.1) is a frequent source of - variance among otherwise identical URIs. In addition to the case - normalization issue noted above, some URI producers percent-encode - octets that do not require percent-encoding, resulting in URIs that - are equivalent to their non-encoded counterparts. These URIs should - be normalized by decoding any percent-encoded octet that corresponds - to an unreserved character, as described in Section 2.3. - - - - - -Berners-Lee, et al. Standards Track [Page 40] - -RFC 3986 URI Generic Syntax January 2005 - - -6.2.2.3. Path Segment Normalization - - The complete path segments "." and ".." are intended only for use - within relative references (Section 4.1) and are removed as part of - the reference resolution process (Section 5.2). However, some - deployed implementations incorrectly assume that reference resolution - is not necessary when the reference is already a URI and thus fail to - remove dot-segments when they occur in non-relative paths. URI - normalizers should remove dot-segments by applying the - remove_dot_segments algorithm to the path, as described in - Section 5.2.4. - -6.2.3. Scheme-Based Normalization - - The syntax and semantics of URIs vary from scheme to scheme, as - described by the defining specification for each scheme. - Implementations may use scheme-specific rules, at further processing - cost, to reduce the probability of false negatives. For example, - because the "http" scheme makes use of an authority component, has a - default port of "80", and defines an empty path to be equivalent to - "/", the following four URIs are equivalent: - - http://example.com - http://example.com/ - http://example.com:/ - http://example.com:80/ - - In general, a URI that uses the generic syntax for authority with an - empty path should be normalized to a path of "/". Likewise, an - explicit ":port", for which the port is empty or the default for the - scheme, is equivalent to one where the port and its ":" delimiter are - elided and thus should be removed by scheme-based normalization. For - example, the second URI above is the normal form for the "http" - scheme. - - Another case where normalization varies by scheme is in the handling - of an empty authority component or empty host subcomponent. For many - scheme specifications, an empty authority or host is considered an - error; for others, it is considered equivalent to "localhost" or the - end-user's host. When a scheme defines a default for authority and a - URI reference to that default is desired, the reference should be - normalized to an empty authority for the sake of uniformity, brevity, - and internationalization. If, however, either the userinfo or port - subcomponents are non-empty, then the host should be given explicitly - even if it matches the default. - - Normalization should not remove delimiters when their associated - component is empty unless licensed to do so by the scheme - - - -Berners-Lee, et al. Standards Track [Page 41] - -RFC 3986 URI Generic Syntax January 2005 - - - specification. For example, the URI "http://example.com/?" cannot be - assumed to be equivalent to any of the examples above. Likewise, the - presence or absence of delimiters within a userinfo subcomponent is - usually significant to its interpretation. The fragment component is - not subject to any scheme-based normalization; thus, two URIs that - differ only by the suffix "#" are considered different regardless of - the scheme. - - Some schemes define additional subcomponents that consist of case- - insensitive data, giving an implicit license to normalizers to - convert this data to a common case (e.g., all lowercase). For - example, URI schemes that define a subcomponent of path to contain an - Internet hostname, such as the "mailto" URI scheme, cause that - subcomponent to be case-insensitive and thus subject to case - normalization (e.g., "mailto:Joe@Example.COM" is equivalent to - "mailto:Joe@example.com", even though the generic syntax considers - the path component to be case-sensitive). - - Other scheme-specific normalizations are possible. - -6.2.4. Protocol-Based Normalization - - Substantial effort to reduce the incidence of false negatives is - often cost-effective for web spiders. Therefore, they implement even - more aggressive techniques in URI comparison. For example, if they - observe that a URI such as - - http://example.com/data - - redirects to a URI differing only in the trailing slash - - http://example.com/data/ - - they will likely regard the two as equivalent in the future. This - kind of technique is only appropriate when equivalence is clearly - indicated by both the result of accessing the resources and the - common conventions of their scheme's dereference algorithm (in this - case, use of redirection by HTTP origin servers to avoid problems - with relative references). - - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 42] - -RFC 3986 URI Generic Syntax January 2005 - - -7. Security Considerations - - A URI does not in itself pose a security threat. However, as URIs - are often used to provide a compact set of instructions for access to - network resources, care must be taken to properly interpret the data - within a URI, to prevent that data from causing unintended access, - and to avoid including data that should not be revealed in plain - text. - -7.1. Reliability and Consistency - - There is no guarantee that once a URI has been used to retrieve - information, the same information will be retrievable by that URI in - the future. Nor is there any guarantee that the information - retrievable via that URI in the future will be observably similar to - that retrieved in the past. The URI syntax does not constrain how a - given scheme or authority apportions its namespace or maintains it - over time. Such guarantees can only be obtained from the person(s) - controlling that namespace and the resource in question. A specific - URI scheme may define additional semantics, such as name persistence, - if those semantics are required of all naming authorities for that - scheme. - -7.2. Malicious Construction - - It is sometimes possible to construct a URI so that an attempt to - perform a seemingly harmless, idempotent operation, such as the - retrieval of a representation, will in fact cause a possibly damaging - remote operation. The unsafe URI is typically constructed by - specifying a port number other than that reserved for the network - protocol in question. The client unwittingly contacts a site running - a different protocol service, and data within the URI contains - instructions that, when interpreted according to this other protocol, - cause an unexpected operation. A frequent example of such abuse has - been the use of a protocol-based scheme with a port component of - "25", thereby fooling user agent software into sending an unintended - or impersonating message via an SMTP server. - - Applications should prevent dereference of a URI that specifies a TCP - port number within the "well-known port" range (0 - 1023) unless the - protocol being used to dereference that URI is compatible with the - protocol expected on that well-known port. Although IANA maintains a - registry of well-known ports, applications should make such - restrictions user-configurable to avoid preventing the deployment of - new services. - - - - - - -Berners-Lee, et al. Standards Track [Page 43] - -RFC 3986 URI Generic Syntax January 2005 - - - When a URI contains percent-encoded octets that match the delimiters - for a given resolution or dereference protocol (for example, CR and - LF characters for the TELNET protocol), these percent-encodings must - not be decoded before transmission across that protocol. Transfer of - the percent-encoding, which might violate the protocol, is less - harmful than allowing decoded octets to be interpreted as additional - operations or parameters, perhaps triggering an unexpected and - possibly harmful remote operation. - -7.3. Back-End Transcoding - - When a URI is dereferenced, the data within it is often parsed by - both the user agent and one or more servers. In HTTP, for example, a - typical user agent will parse a URI into its five major components, - access the authority's server, and send it the data within the - authority, path, and query components. A typical server will take - that information, parse the path into segments and the query into - key/value pairs, and then invoke implementation-specific handlers to - respond to the request. As a result, a common security concern for - server implementations that handle a URI, either as a whole or split - into separate components, is proper interpretation of the octet data - represented by the characters and percent-encodings within that URI. - - Percent-encoded octets must be decoded at some point during the - dereference process. Applications must split the URI into its - components and subcomponents prior to decoding the octets, as - otherwise the decoded octets might be mistaken for delimiters. - Security checks of the data within a URI should be applied after - decoding the octets. Note, however, that the "%00" percent-encoding - (NUL) may require special handling and should be rejected if the - application is not expecting to receive raw data within a component. - - Special care should be taken when the URI path interpretation process - involves the use of a back-end file system or related system - functions. File systems typically assign an operational meaning to - special characters, such as the "/", "\", ":", "[", and "]" - characters, and to special device names like ".", "..", "...", "aux", - "lpt", etc. In some cases, merely testing for the existence of such - a name will cause the operating system to pause or invoke unrelated - system calls, leading to significant security concerns regarding - denial of service and unintended data transfer. It would be - impossible for this specification to list all such significant - characters and device names. Implementers should research the - reserved names and characters for the types of storage device that - may be attached to their applications and restrict the use of data - obtained from URI components accordingly. - - - - - -Berners-Lee, et al. Standards Track [Page 44] - -RFC 3986 URI Generic Syntax January 2005 - - -7.4. Rare IP Address Formats - - Although the URI syntax for IPv4address only allows the common - dotted-decimal form of IPv4 address literal, many implementations - that process URIs make use of platform-dependent system routines, - such as gethostbyname() and inet_aton(), to translate the string - literal to an actual IP address. Unfortunately, such system routines - often allow and process a much larger set of formats than those - described in Section 3.2.2. - - For example, many implementations allow dotted forms of three - numbers, wherein the last part is interpreted as a 16-bit quantity - and placed in the right-most two bytes of the network address (e.g., - a Class B network). Likewise, a dotted form of two numbers means - that the last part is interpreted as a 24-bit quantity and placed in - the right-most three bytes of the network address (Class A), and a - single number (without dots) is interpreted as a 32-bit quantity and - stored directly in the network address. Adding further to the - confusion, some implementations allow each dotted part to be - interpreted as decimal, octal, or hexadecimal, as specified in the C - language (i.e., a leading 0x or 0X implies hexadecimal; a leading 0 - implies octal; otherwise, the number is interpreted as decimal). - - These additional IP address formats are not allowed in the URI syntax - due to differences between platform implementations. However, they - can become a security concern if an application attempts to filter - access to resources based on the IP address in string literal format. - If this filtering is performed, literals should be converted to - numeric form and filtered based on the numeric value, and not on a - prefix or suffix of the string form. - -7.5. Sensitive Information - - URI producers should not provide a URI that contains a username or - password that is intended to be secret. URIs are frequently - displayed by browsers, stored in clear text bookmarks, and logged by - user agent history and intermediary applications (proxies). A - password appearing within the userinfo component is deprecated and - should be considered an error (or simply ignored) except in those - rare cases where the 'password' parameter is intended to be public. - -7.6. Semantic Attacks - - Because the userinfo subcomponent is rarely used and appears before - the host in the authority component, it can be used to construct a - URI intended to mislead a human user by appearing to identify one - (trusted) naming authority while actually identifying a different - authority hidden behind the noise. For example - - - -Berners-Lee, et al. Standards Track [Page 45] - -RFC 3986 URI Generic Syntax January 2005 - - - ftp://cnn.example.com&story=breaking_news@10.0.0.1/top_story.htm - - might lead a human user to assume that the host is 'cnn.example.com', - whereas it is actually '10.0.0.1'. Note that a misleading userinfo - subcomponent could be much longer than the example above. - - A misleading URI, such as that above, is an attack on the user's - preconceived notions about the meaning of a URI rather than an attack - on the software itself. User agents may be able to reduce the impact - of such attacks by distinguishing the various components of the URI - when they are rendered, such as by using a different color or tone to - render userinfo if any is present, though there is no panacea. More - information on URI-based semantic attacks can be found in [Siedzik]. - -8. IANA Considerations - - URI scheme names, as defined by <scheme> in Section 3.1, form a - registered namespace that is managed by IANA according to the - procedures defined in [BCP35]. No IANA actions are required by this - document. - -9. Acknowledgements - - This specification is derived from RFC 2396 [RFC2396], RFC 1808 - [RFC1808], and RFC 1738 [RFC1738]; the acknowledgements in those - documents still apply. It also incorporates the update (with - corrections) for IPv6 literals in the host syntax, as defined by - Robert M. Hinden, Brian E. Carpenter, and Larry Masinter in - [RFC2732]. In addition, contributions by Gisle Aas, Reese Anschultz, - Daniel Barclay, Tim Bray, Mike Brown, Rob Cameron, Jeremy Carroll, - Dan Connolly, Adam M. Costello, John Cowan, Jason Diamond, Martin - Duerst, Stefan Eissing, Clive D.W. Feather, Al Gilman, Tony Hammond, - Elliotte Harold, Pat Hayes, Henry Holtzman, Ian B. Jacobs, Michael - Kay, John C. Klensin, Graham Klyne, Dan Kohn, Bruce Lilly, Andrew - Main, Dave McAlpin, Ira McDonald, Michael Mealling, Ray Merkert, - Stephen Pollei, Julian Reschke, Tomas Rokicki, Miles Sabin, Kai - Schaetzl, Mark Thomson, Ronald Tschalaer, Norm Walsh, Marc Warne, - Stuart Williams, and Henry Zongaro are gratefully acknowledged. - -10. References - -10.1. Normative References - - [ASCII] American National Standards Institute, "Coded Character - Set -- 7-bit American Standard Code for Information - Interchange", ANSI X3.4, 1986. - - - - - -Berners-Lee, et al. Standards Track [Page 46] - -RFC 3986 URI Generic Syntax January 2005 - - - [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 2234, November 1997. - - [STD63] Yergeau, F., "UTF-8, a transformation format of - ISO 10646", STD 63, RFC 3629, November 2003. - - [UCS] International Organization for Standardization, - "Information Technology - Universal Multiple-Octet Coded - Character Set (UCS)", ISO/IEC 10646:2003, December 2003. - -10.2. Informative References - - [BCP19] Freed, N. and J. Postel, "IANA Charset Registration - Procedures", BCP 19, RFC 2978, October 2000. - - [BCP35] Petke, R. and I. King, "Registration Procedures for URL - Scheme Names", BCP 35, RFC 2717, November 1999. - - [RFC0952] Harrenstien, K., Stahl, M., and E. Feinler, "DoD Internet - host table specification", RFC 952, October 1985. - - [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", - STD 13, RFC 1034, November 1987. - - [RFC1123] Braden, R., "Requirements for Internet Hosts - Application - and Support", STD 3, RFC 1123, October 1989. - - [RFC1535] Gavron, E., "A Security Problem and Proposed Correction - With Widely Deployed DNS Software", RFC 1535, - October 1993. - - [RFC1630] Berners-Lee, T., "Universal Resource Identifiers in WWW: A - Unifying Syntax for the Expression of Names and Addresses - of Objects on the Network as used in the World-Wide Web", - RFC 1630, June 1994. - - [RFC1736] Kunze, J., "Functional Recommendations for Internet - Resource Locators", RFC 1736, February 1995. - - [RFC1737] Sollins, K. and L. Masinter, "Functional Requirements for - Uniform Resource Names", RFC 1737, December 1994. - - [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform - Resource Locators (URL)", RFC 1738, December 1994. - - [RFC1808] Fielding, R., "Relative Uniform Resource Locators", - RFC 1808, June 1995. - - - - -Berners-Lee, et al. Standards Track [Page 47] - -RFC 3986 URI Generic Syntax January 2005 - - - [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part Two: Media Types", RFC 2046, - November 1996. - - [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. - - [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform - Resource Identifiers (URI): Generic Syntax", RFC 2396, - August 1998. - - [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. - Jensen, "HTTP Extensions for Distributed Authoring -- - WEBDAV", RFC 2518, February 1999. - - [RFC2557] Palme, J., Hopmann, A., and N. Shelness, "MIME - Encapsulation of Aggregate Documents, such as HTML - (MHTML)", RFC 2557, March 1999. - - [RFC2718] Masinter, L., Alvestrand, H., Zigmond, D., and R. Petke, - "Guidelines for new URL Schemes", RFC 2718, November 1999. - - [RFC2732] Hinden, R., Carpenter, B., and L. Masinter, "Format for - Literal IPv6 Addresses in URL's", RFC 2732, December 1999. - - [RFC3305] Mealling, M. and R. Denenberg, "Report from the Joint - W3C/IETF URI Planning Interest Group: Uniform Resource - Identifiers (URIs), URLs, and Uniform Resource Names - (URNs): Clarifications and Recommendations", RFC 3305, - August 2002. - - [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, - "Internationalizing Domain Names in Applications (IDNA)", - RFC 3490, March 2003. - - [RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version 6 - (IPv6) Addressing Architecture", RFC 3513, April 2003. - - [Siedzik] Siedzik, R., "Semantic Attacks: What's in a URL?", - April 2001, <http://www.giac.org/practical/gsec/ - Richard_Siedzik_GSEC.pdf>. - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 48] - -RFC 3986 URI Generic Syntax January 2005 - - -Appendix A. Collected ABNF for URI - - URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - - hier-part = "//" authority path-abempty - / path-absolute - / path-rootless - / path-empty - - URI-reference = URI / relative-ref - - absolute-URI = scheme ":" hier-part [ "?" query ] - - relative-ref = relative-part [ "?" query ] [ "#" fragment ] - - relative-part = "//" authority path-abempty - / path-absolute - / path-noscheme - / path-empty - - scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) - - authority = [ userinfo "@" ] host [ ":" port ] - userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) - host = IP-literal / IPv4address / reg-name - port = *DIGIT - - IP-literal = "[" ( IPv6address / IPvFuture ) "]" - - IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" ) - - IPv6address = 6( h16 ":" ) ls32 - / "::" 5( h16 ":" ) ls32 - / [ h16 ] "::" 4( h16 ":" ) ls32 - / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32 - / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 - / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 - / [ *4( h16 ":" ) h16 ] "::" ls32 - / [ *5( h16 ":" ) h16 ] "::" h16 - / [ *6( h16 ":" ) h16 ] "::" - - h16 = 1*4HEXDIG - ls32 = ( h16 ":" h16 ) / IPv4address - IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet - - - - - - - -Berners-Lee, et al. Standards Track [Page 49] - -RFC 3986 URI Generic Syntax January 2005 - - - dec-octet = DIGIT ; 0-9 - / %x31-39 DIGIT ; 10-99 - / "1" 2DIGIT ; 100-199 - / "2" %x30-34 DIGIT ; 200-249 - / "25" %x30-35 ; 250-255 - - reg-name = *( unreserved / pct-encoded / sub-delims ) - - path = path-abempty ; begins with "/" or is empty - / path-absolute ; begins with "/" but not "//" - / path-noscheme ; begins with a non-colon segment - / path-rootless ; begins with a segment - / path-empty ; zero characters - - path-abempty = *( "/" segment ) - path-absolute = "/" [ segment-nz *( "/" segment ) ] - path-noscheme = segment-nz-nc *( "/" segment ) - path-rootless = segment-nz *( "/" segment ) - path-empty = 0<pchar> - - segment = *pchar - segment-nz = 1*pchar - segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" ) - ; non-zero-length segment without any colon ":" - - pchar = unreserved / pct-encoded / sub-delims / ":" / "@" - - query = *( pchar / "/" / "?" ) - - fragment = *( pchar / "/" / "?" ) - - pct-encoded = "%" HEXDIG HEXDIG - - unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" - reserved = gen-delims / sub-delims - gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" - sub-delims = "!" / "$" / "&" / "'" / "(" / ")" - / "*" / "+" / "," / ";" / "=" - -Appendix B. Parsing a URI Reference with a Regular Expression - - As the "first-match-wins" algorithm is identical to the "greedy" - disambiguation method used by POSIX regular expressions, it is - natural and commonplace to use a regular expression for parsing the - potential five components of a URI reference. - - The following line is the regular expression for breaking-down a - well-formed URI reference into its components. - - - -Berners-Lee, et al. Standards Track [Page 50] - -RFC 3986 URI Generic Syntax January 2005 - - - ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))? - 12 3 4 5 6 7 8 9 - - The numbers in the second line above are only to assist readability; - they indicate the reference points for each subexpression (i.e., each - paired parenthesis). We refer to the value matched for subexpression - <n> as $<n>. For example, matching the above expression to - - http://www.ics.uci.edu/pub/ietf/uri/#Related - - results in the following subexpression matches: - - $1 = http: - $2 = http - $3 = //www.ics.uci.edu - $4 = www.ics.uci.edu - $5 = /pub/ietf/uri/ - $6 = <undefined> - $7 = <undefined> - $8 = #Related - $9 = Related - - where <undefined> indicates that the component is not present, as is - the case for the query component in the above example. Therefore, we - can determine the value of the five components as - - scheme = $2 - authority = $4 - path = $5 - query = $7 - fragment = $9 - - Going in the opposite direction, we can recreate a URI reference from - its components by using the algorithm of Section 5.3. - -Appendix C. Delimiting a URI in Context - - URIs are often transmitted through formats that do not provide a - clear context for their interpretation. For example, there are many - occasions when a URI is included in plain text; examples include text - sent in email, USENET news, and on printed paper. In such cases, it - is important to be able to delimit the URI from the rest of the text, - and in particular from punctuation marks that might be mistaken for - part of the URI. - - In practice, URIs are delimited in a variety of ways, but usually - within double-quotes "http://example.com/", angle brackets - <http://example.com/>, or just by using whitespace: - - - -Berners-Lee, et al. Standards Track [Page 51] - -RFC 3986 URI Generic Syntax January 2005 - - - http://example.com/ - - These wrappers do not form part of the URI. - - In some cases, extra whitespace (spaces, line-breaks, tabs, etc.) may - have to be added to break a long URI across lines. The whitespace - should be ignored when the URI is extracted. - - No whitespace should be introduced after a hyphen ("-") character. - Because some typesetters and printers may (erroneously) introduce a - hyphen at the end of line when breaking it, the interpreter of a URI - containing a line break immediately after a hyphen should ignore all - whitespace around the line break and should be aware that the hyphen - may or may not actually be part of the URI. - - Using <> angle brackets around each URI is especially recommended as - a delimiting style for a reference that contains embedded whitespace. - - The prefix "URL:" (with or without a trailing space) was formerly - recommended as a way to help distinguish a URI from other bracketed - designators, though it is not commonly used in practice and is no - longer recommended. - - For robustness, software that accepts user-typed URI should attempt - to recognize and strip both delimiters and embedded whitespace. - - For example, the text - - Yes, Jim, I found it under "http://www.w3.org/Addressing/", - but you can probably pick it up from <ftp://foo.example. - com/rfc/>. Note the warning in <http://www.ics.uci.edu/pub/ - ietf/uri/historical.html#WARNING>. - - contains the URI references - - http://www.w3.org/Addressing/ - ftp://foo.example.com/rfc/ - http://www.ics.uci.edu/pub/ietf/uri/historical.html#WARNING - - - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 52] - -RFC 3986 URI Generic Syntax January 2005 - - -Appendix D. Changes from RFC 2396 - -D.1. Additions - - An ABNF rule for URI has been introduced to correspond to one common - usage of the term: an absolute URI with optional fragment. - - IPv6 (and later) literals have been added to the list of possible - identifiers for the host portion of an authority component, as - described by [RFC2732], with the addition of "[" and "]" to the - reserved set and a version flag to anticipate future versions of IP - literals. Square brackets are now specified as reserved within the - authority component and are not allowed outside their use as - delimiters for an IP literal within host. In order to make this - change without changing the technical definition of the path, query, - and fragment components, those rules were redefined to directly - specify the characters allowed. - - As [RFC2732] defers to [RFC3513] for definition of an IPv6 literal - address, which, unfortunately, lacks an ABNF description of - IPv6address, we created a new ABNF rule for IPv6address that matches - the text representations defined by Section 2.2 of [RFC3513]. - Likewise, the definition of IPv4address has been improved in order to - limit each decimal octet to the range 0-255. - - Section 6, on URI normalization and comparison, has been completely - rewritten and extended by using input from Tim Bray and discussion - within the W3C Technical Architecture Group. - -D.2. Modifications - - The ad-hoc BNF syntax of RFC 2396 has been replaced with the ABNF of - [RFC2234]. This change required all rule names that formerly - included underscore characters to be renamed with a dash instead. In - addition, a number of syntax rules have been eliminated or simplified - to make the overall grammar more comprehensible. Specifications that - refer to the obsolete grammar rules may be understood by replacing - those rules according to the following table: - - - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 53] - -RFC 3986 URI Generic Syntax January 2005 - - - +----------------+--------------------------------------------------+ - | obsolete rule | translation | - +----------------+--------------------------------------------------+ - | absoluteURI | absolute-URI | - | relativeURI | relative-part [ "?" query ] | - | hier_part | ( "//" authority path-abempty / | - | | path-absolute ) [ "?" query ] | - | | | - | opaque_part | path-rootless [ "?" query ] | - | net_path | "//" authority path-abempty | - | abs_path | path-absolute | - | rel_path | path-rootless | - | rel_segment | segment-nz-nc | - | reg_name | reg-name | - | server | authority | - | hostport | host [ ":" port ] | - | hostname | reg-name | - | path_segments | path-abempty | - | param | *<pchar excluding ";"> | - | | | - | uric | unreserved / pct-encoded / ";" / "?" / ":" | - | | / "@" / "&" / "=" / "+" / "$" / "," / "/" | - | | | - | uric_no_slash | unreserved / pct-encoded / ";" / "?" / ":" | - | | / "@" / "&" / "=" / "+" / "$" / "," | - | | | - | mark | "-" / "_" / "." / "!" / "~" / "*" / "'" | - | | / "(" / ")" | - | | | - | escaped | pct-encoded | - | hex | HEXDIG | - | alphanum | ALPHA / DIGIT | - +----------------+--------------------------------------------------+ - - Use of the above obsolete rules for the definition of scheme-specific - syntax is deprecated. - - Section 2, on characters, has been rewritten to explain what - characters are reserved, when they are reserved, and why they are - reserved, even when they are not used as delimiters by the generic - syntax. The mark characters that are typically unsafe to decode, - including the exclamation mark ("!"), asterisk ("*"), single-quote - ("'"), and open and close parentheses ("(" and ")"), have been moved - to the reserved set in order to clarify the distinction between - reserved and unreserved and, hopefully, to answer the most common - question of scheme designers. Likewise, the section on - percent-encoded characters has been rewritten, and URI normalizers - are now given license to decode any percent-encoded octets - - - -Berners-Lee, et al. Standards Track [Page 54] - -RFC 3986 URI Generic Syntax January 2005 - - - corresponding to unreserved characters. In general, the terms - "escaped" and "unescaped" have been replaced with "percent-encoded" - and "decoded", respectively, to reduce confusion with other forms of - escape mechanisms. - - The ABNF for URI and URI-reference has been redesigned to make them - more friendly to LALR parsers and to reduce complexity. As a result, - the layout form of syntax description has been removed, along with - the uric, uric_no_slash, opaque_part, net_path, abs_path, rel_path, - path_segments, rel_segment, and mark rules. All references to - "opaque" URIs have been replaced with a better description of how the - path component may be opaque to hierarchy. The relativeURI rule has - been replaced with relative-ref to avoid unnecessary confusion over - whether they are a subset of URI. The ambiguity regarding the - parsing of URI-reference as a URI or a relative-ref with a colon in - the first segment has been eliminated through the use of five - separate path matching rules. - - The fragment identifier has been moved back into the section on - generic syntax components and within the URI and relative-ref rules, - though it remains excluded from absolute-URI. The number sign ("#") - character has been moved back to the reserved set as a result of - reintegrating the fragment syntax. - - The ABNF has been corrected to allow the path component to be empty. - This also allows an absolute-URI to consist of nothing after the - "scheme:", as is present in practice with the "dav:" namespace - [RFC2518] and with the "about:" scheme used internally by many WWW - browser implementations. The ambiguity regarding the boundary - between authority and path has been eliminated through the use of - five separate path matching rules. - - Registry-based naming authorities that use the generic syntax are now - defined within the host rule. This change allows current - implementations, where whatever name provided is simply fed to the - local name resolution mechanism, to be consistent with the - specification. It also removes the need to re-specify DNS name - formats here. Furthermore, it allows the host component to contain - percent-encoded octets, which is necessary to enable - internationalized domain names to be provided in URIs, processed in - their native character encodings at the application layers above URI - processing, and passed to an IDNA library as a registered name in the - UTF-8 character encoding. The server, hostport, hostname, - domainlabel, toplabel, and alphanum rules have been removed. - - The resolving relative references algorithm of [RFC2396] has been - rewritten with pseudocode for this revision to improve clarity and - fix the following issues: - - - -Berners-Lee, et al. Standards Track [Page 55] - -RFC 3986 URI Generic Syntax January 2005 - - - o [RFC2396] section 5.2, step 6a, failed to account for a base URI - with no path. - - o Restored the behavior of [RFC1808] where, if the reference - contains an empty path and a defined query component, the target - URI inherits the base URI's path component. - - o The determination of whether a URI reference is a same-document - reference has been decoupled from the URI parser, simplifying the - URI processing interface within applications in a way consistent - with the internal architecture of deployed URI processing - implementations. The determination is now based on comparison to - the base URI after transforming a reference to absolute form, - rather than on the format of the reference itself. This change - may result in more references being considered "same-document" - under this specification than there would be under the rules given - in RFC 2396, especially when normalization is used to reduce - aliases. However, it does not change the status of existing - same-document references. - - o Separated the path merge routine into two routines: merge, for - describing combination of the base URI path with a relative-path - reference, and remove_dot_segments, for describing how to remove - the special "." and ".." segments from a composed path. The - remove_dot_segments algorithm is now applied to all URI reference - paths in order to match common implementations and to improve the - normalization of URIs in practice. This change only impacts the - parsing of abnormal references and same-scheme references wherein - the base URI has a non-hierarchical path. - -Index - - A - ABNF 11 - absolute 27 - absolute-path 26 - absolute-URI 27 - access 9 - authority 17, 18 - - B - base URI 28 - - C - character encoding 4 - character 4 - characters 8, 11 - coded character set 4 - - - -Berners-Lee, et al. Standards Track [Page 56] - -RFC 3986 URI Generic Syntax January 2005 - - - D - dec-octet 20 - dereference 9 - dot-segments 23 - - F - fragment 16, 24 - - G - gen-delims 13 - generic syntax 6 - - H - h16 20 - hier-part 16 - hierarchical 10 - host 18 - - I - identifier 5 - IP-literal 19 - IPv4 20 - IPv4address 19, 20 - IPv6 19 - IPv6address 19, 20 - IPvFuture 19 - - L - locator 7 - ls32 20 - - M - merge 32 - - N - name 7 - network-path 26 - - P - path 16, 22, 26 - path-abempty 22 - path-absolute 22 - path-empty 22 - path-noscheme 22 - path-rootless 22 - path-abempty 16, 22, 26 - path-absolute 16, 22, 26 - path-empty 16, 22, 26 - - - -Berners-Lee, et al. Standards Track [Page 57] - -RFC 3986 URI Generic Syntax January 2005 - - - path-rootless 16, 22 - pchar 23 - pct-encoded 12 - percent-encoding 12 - port 22 - - Q - query 16, 23 - - R - reg-name 21 - registered name 20 - relative 10, 28 - relative-path 26 - relative-ref 26 - remove_dot_segments 33 - representation 9 - reserved 12 - resolution 9, 28 - resource 5 - retrieval 9 - - S - same-document 27 - sameness 9 - scheme 16, 17 - segment 22, 23 - segment-nz 23 - segment-nz-nc 23 - sub-delims 13 - suffix 27 - - T - transcription 8 - - U - uniform 4 - unreserved 13 - URI grammar - absolute-URI 27 - ALPHA 11 - authority 18 - CR 11 - dec-octet 20 - DIGIT 11 - DQUOTE 11 - fragment 24 - gen-delims 13 - - - -Berners-Lee, et al. Standards Track [Page 58] - -RFC 3986 URI Generic Syntax January 2005 - - - h16 20 - HEXDIG 11 - hier-part 16 - host 19 - IP-literal 19 - IPv4address 20 - IPv6address 20 - IPvFuture 19 - LF 11 - ls32 20 - OCTET 11 - path 22 - path-abempty 22 - path-absolute 22 - path-empty 22 - path-noscheme 22 - path-rootless 22 - pchar 23 - pct-encoded 12 - port 22 - query 24 - reg-name 21 - relative-ref 26 - reserved 13 - scheme 17 - segment 23 - segment-nz 23 - segment-nz-nc 23 - SP 11 - sub-delims 13 - unreserved 13 - URI 16 - URI-reference 25 - userinfo 18 - URI 16 - URI-reference 25 - URL 7 - URN 7 - userinfo 18 - - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 59] - -RFC 3986 URI Generic Syntax January 2005 - - -Authors' Addresses - - Tim Berners-Lee - World Wide Web Consortium - Massachusetts Institute of Technology - 77 Massachusetts Avenue - Cambridge, MA 02139 - USA - - Phone: +1-617-253-5702 - Fax: +1-617-258-5999 - EMail: timbl@w3.org - URI: http://www.w3.org/People/Berners-Lee/ - - - Roy T. Fielding - Day Software - 5251 California Ave., Suite 110 - Irvine, CA 92617 - USA - - Phone: +1-949-679-2960 - Fax: +1-949-679-2972 - EMail: fielding@gbiv.com - URI: http://roy.gbiv.com/ - - - Larry Masinter - Adobe Systems Incorporated - 345 Park Ave - San Jose, CA 95110 - USA - - Phone: +1-408-536-3024 - EMail: LMM@acm.org - URI: http://larry.masinter.net/ - - - - - - - - - - - - - - - -Berners-Lee, et al. Standards Track [Page 60] - -RFC 3986 URI Generic Syntax January 2005 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2005). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, - INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE - INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED - WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the IETF's procedures with respect to rights in IETF Documents can - be found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at ietf- - ipr@ietf.org. - - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - -Berners-Lee, et al. Standards Track [Page 61] - |
