Python2/PyMuPDF: mupdf-source/thirdparty/curl/docs/libcurl/libcurl-tutorial.3 annotate

annotate mupdf-source/thirdparty/curl/docs/libcurl/libcurl-tutorial.3 @ 2:b50eed0cc0ef upstream

ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.

author	Franz Glasner <fzglas.hg@dom66.de>
date	Mon, 15 Sep 2025 11:43:07 +0200
parents
children

rev	line source
2 b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1 .\" **************************************************************************
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	2 .\" * _ _ ____ _
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	3 .\" * Project ___\| \| \| \| _ \\| \|
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	4 .\" * / __\| \| \| \| \|_) \| \|
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	5 .\" * \| (__\| \|_\| \| _ <\| \|___
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	6 .\" * \___\|\___/\|_\| \_\_____\|
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	7 .\" *
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	8 .\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	9 .\" *
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	10 .\" * This software is licensed as described in the file COPYING, which
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	11 .\" * you should have received as part of this distribution. The terms
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	13 .\" *
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	15 .\" * copies of the Software, and permit persons to whom the Software is
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	16 .\" * furnished to do so, under the terms of the COPYING file.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	17 .\" *
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	19 .\" * KIND, either express or implied.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	20 .\" *
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	21 .\" **************************************************************************
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	22 .\"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	23 .TH libcurl-tutorial 3 "19 Sep 2014" "libcurl" "libcurl programming"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	24 .SH NAME
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	25 libcurl-tutorial \- libcurl programming tutorial
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	26 .SH "Objective"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	27 This document attempts to describe the general principles and some basic
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	28 approaches to consider when programming with libcurl. The text will focus
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	29 mainly on the C interface but might apply fairly well on other interfaces as
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	30 well as they usually follow the C one pretty closely.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	31
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	32 This document will refer to 'the user' as the person writing the source code
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	33 that uses libcurl. That would probably be you or someone in your position.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	34 What will be generally referred to as 'the program' will be the collected
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	35 source code that you write that is using libcurl for transfers. The program
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	36 is outside libcurl and libcurl is outside of the program.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	37
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	38 To get more details on all options and functions described herein, please
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	39 refer to their respective man pages.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	40
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	41 .SH "Building"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	42 There are many different ways to build C programs. This chapter will assume a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	43 Unix style build process. If you use a different build system, you can still
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	44 read this to get general information that may apply to your environment as
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	45 well.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	46 .IP "Compiling the Program"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	47 Your compiler needs to know where the libcurl headers are located. Therefore
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	48 you must set your compiler's include path to point to the directory where you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	49 installed them. The 'curl-config'[3] tool can be used to get this information:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	50
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	51 $ curl-config --cflags
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	52
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	53 .IP "Linking the Program with libcurl"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	54 When having compiled the program, you need to link your object files to create
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	55 a single executable. For that to succeed, you need to link with libcurl and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	56 possibly also with other libraries that libcurl itself depends on. Like the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	57 OpenSSL libraries, but even some standard OS libraries may be needed on the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	58 command line. To figure out which flags to use, once again the 'curl-config'
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	59 tool comes to the rescue:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	60
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	61 $ curl-config --libs
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	62
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	63 .IP "SSL or Not"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	64 libcurl can be built and customized in many ways. One of the things that
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	65 varies from different libraries and builds is the support for SSL-based
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	66 transfers, like HTTPS and FTPS. If a supported SSL library was detected
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	67 properly at build-time, libcurl will be built with SSL support. To figure out
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	68 if an installed libcurl has been built with SSL support enabled, use
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	69 \&'curl-config' like this:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	70
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	71 $ curl-config --feature
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	72
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	73 And if SSL is supported, the keyword 'SSL' will be written to stdout,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	74 possibly together with a few other features that could be either on or off on
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	75 for different libcurls.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	76
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	77 See also the "Features libcurl Provides" further down.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	78 .IP "autoconf macro"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	79 When you write your configure script to detect libcurl and setup variables
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	80 accordingly, we offer a prewritten macro that probably does everything you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	81 need in this area. See docs/libcurl/libcurl.m4 file - it includes docs on how
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	82 to use it.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	83
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	84 .SH "Portable Code in a Portable World"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	85 The people behind libcurl have put a considerable effort to make libcurl work
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	86 on a large amount of different operating systems and environments.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	87
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	88 You program libcurl the same way on all platforms that libcurl runs on. There
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	89 are only very few minor considerations that differ. If you just make sure to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	90 write your code portable enough, you may very well create yourself a very
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	91 portable program. libcurl shouldn't stop you from that.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	92
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	93 .SH "Global Preparation"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	94 The program must initialize some of the libcurl functionality globally. That
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	95 means it should be done exactly once, no matter how many times you intend to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	96 use the library. Once for your program's entire life time. This is done using
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	97
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	98 curl_global_init()
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	99
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	100 and it takes one parameter which is a bit pattern that tells libcurl what to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	101 initialize. Using \fICURL_GLOBAL_ALL\fP will make it initialize all known
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	102 internal sub modules, and might be a good default option. The current two bits
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	103 that are specified are:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	104 .RS
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	105 .IP "CURL_GLOBAL_WIN32"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	106 which only does anything on Windows machines. When used on
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	107 a Windows machine, it'll make libcurl initialize the win32 socket
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	108 stuff. Without having that initialized properly, your program cannot use
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	109 sockets properly. You should only do this once for each application, so if
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	110 your program already does this or of another library in use does it, you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	111 should not tell libcurl to do this as well.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	112 .IP CURL_GLOBAL_SSL
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	113 which only does anything on libcurls compiled and built SSL-enabled. On these
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	114 systems, this will make libcurl initialize the SSL library properly for this
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	115 application. This only needs to be done once for each application so if your
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	116 program or another library already does this, this bit should not be needed.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	117 .RE
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	118
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	119 libcurl has a default protection mechanism that detects if
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	120 \fIcurl_global_init(3)\fP hasn't been called by the time
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	121 \fIcurl_easy_perform(3)\fP is called and if that is the case, libcurl runs the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	122 function itself with a guessed bit pattern. Please note that depending solely
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	123 on this is not considered nice nor very good.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	124
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	125 When the program no longer uses libcurl, it should call
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	126 \fIcurl_global_cleanup(3)\fP, which is the opposite of the init call. It will
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	127 then do the reversed operations to cleanup the resources the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	128 \fIcurl_global_init(3)\fP call initialized.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	129
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	130 Repeated calls to \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	131 should be avoided. They should only be called once each.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	132
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	133 .SH "Features libcurl Provides"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	134 It is considered best-practice to determine libcurl features at run-time
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	135 rather than at build-time (if possible of course). By calling
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	136 \fIcurl_version_info(3)\fP and checking out the details of the returned
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	137 struct, your program can figure out exactly what the currently running libcurl
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	138 supports.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	139
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	140 .SH "Two Interfaces"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	141 libcurl first introduced the so called easy interface. All operations in the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	142 easy interface are prefixed with 'curl_easy'. The easy interface lets you do
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	143 single transfers with a synchronous and blocking function call.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	144
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	145 libcurl also offers another interface that allows multiple simultaneous
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	146 transfers in a single thread, the so called multi interface. More about that
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	147 interface is detailed in a separate chapter further down. You still need to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	148 understand the easy interface first, so please continue reading for better
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	149 understanding.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	150 .SH "Handle the Easy libcurl"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	151 To use the easy interface, you must first create yourself an easy handle. You
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	152 need one handle for each easy session you want to perform. Basically, you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	153 should use one handle for every thread you plan to use for transferring. You
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	154 must never share the same handle in multiple threads.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	155
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	156 Get an easy handle with
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	157
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	158 easyhandle = curl_easy_init();
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	159
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	160 It returns an easy handle. Using that you proceed to the next step: setting
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	161 up your preferred actions. A handle is just a logic entity for the upcoming
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	162 transfer or series of transfers.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	163
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	164 You set properties and options for this handle using
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	165 \fIcurl_easy_setopt(3)\fP. They control how the subsequent transfer or
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	166 transfers will be made. Options remain set in the handle until set again to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	167 something different. They are sticky. Multiple requests using the same handle
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	168 will use the same options.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	169
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	170 If you at any point would like to blank all previously set options for a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	171 single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	172 make a clone of an easy handle (with all its set options) using
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	173 \fIcurl_easy_duphandle(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	174
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	175 Many of the options you set in libcurl are "strings", pointers to data
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	176 terminated with a zero byte. When you set strings with
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	177 \fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they don't need
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	178 to be kept around in your application after being set[4].
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	179
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	180 One of the most basic properties to set in the handle is the URL. You set your
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	181 preferred URL to transfer with \fICURLOPT_URL(3)\fP in a manner similar to:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	182
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	183 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	184 curl_easy_setopt(handle, CURLOPT_URL, "http://domain.com/");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	185 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	186
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	187 Let's assume for a while that you want to receive data as the URL identifies a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	188 remote resource you want to get here. Since you write a sort of application
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	189 that needs this transfer, I assume that you would like to get the data passed
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	190 to you directly instead of simply getting it passed to stdout. So, you write
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	191 your own function that matches this prototype:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	192
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	193 size_t write_data(void buffer, size_t size, size_t nmemb, void userp);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	194
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	195 You tell libcurl to pass all data to this function by issuing a function
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	196 similar to this:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	197
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	198 curl_easy_setopt(easyhandle, CURLOPT_WRITEFUNCTION, write_data);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	199
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	200 You can control what data your callback function gets in the fourth argument
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	201 by setting another property:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	202
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	203 curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	204
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	205 Using that property, you can easily pass local data between your application
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	206 and the function that gets invoked by libcurl. libcurl itself won't touch the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	207 data you pass with \fICURLOPT_WRITEDATA(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	208
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	209 libcurl offers its own default internal callback that will take care of the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	210 data if you don't set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	211 will then simply output the received data to stdout. You can have the default
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	212 callback write the data to a different file handle by passing a 'FILE *' to a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	213 file opened for writing with the \fICURLOPT_WRITEDATA(3)\fP option.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	214
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	215 Now, we need to take a step back and have a deep breath. Here's one of those
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	216 rare platform-dependent nitpicks. Did you spot it? On some platforms[2],
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	217 libcurl won't be able to operate on files opened by the program. Thus, if you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	218 use the default callback and pass in an open file with
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	219 \fICURLOPT_WRITEDATA(3)\fP, it will crash. You should therefore avoid this to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	220 make your program run fine virtually everywhere.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	221
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	222 (\fICURLOPT_WRITEDATA(3)\fP was formerly known as \fICURLOPT_FILE\fP. Both
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	223 names still work and do the same thing).
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	224
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	225 If you're using libcurl as a win32 DLL, you MUST use the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	226 \fICURLOPT_WRITEFUNCTION(3)\fP if you set \fICURLOPT_WRITEDATA(3)\fP - or you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	227 will experience crashes.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	228
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	229 There are of course many more options you can set, and we'll get back to a few
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	230 of them later. Let's instead continue to the actual transfer:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	231
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	232 success = curl_easy_perform(easyhandle);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	233
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	234 \fIcurl_easy_perform(3)\fP will connect to the remote site, do the necessary
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	235 commands and receive the transfer. Whenever it receives data, it calls the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	236 callback function we previously set. The function may get one byte at a time,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	237 or it may get many kilobytes at once. libcurl delivers as much as possible as
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	238 often as possible. Your callback function should return the number of bytes it
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	239 \&"took care of". If that is not the exact same amount of bytes that was
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	240 passed to it, libcurl will abort the operation and return with an error code.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	241
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	242 When the transfer is complete, the function returns a return code that informs
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	243 you if it succeeded in its mission or not. If a return code isn't enough for
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	244 you, you can use the \fICURLOPT_ERRORBUFFER(3)\fP to point libcurl to a buffer
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	245 of yours where it'll store a human readable error message as well.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	246
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	247 If you then want to transfer another file, the handle is ready to be used
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	248 again. Mind you, it is even preferred that you re-use an existing handle if
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	249 you intend to make another transfer. libcurl will then attempt to re-use the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	250 previous connection.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	251
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	252 For some protocols, downloading a file can involve a complicated process of
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	253 logging in, setting the transfer mode, changing the current directory and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	254 finally transferring the file data. libcurl takes care of all that
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	255 complication for you. Given simply the URL to a file, libcurl will take care
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	256 of all the details needed to get the file moved from one machine to another.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	257
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	258 .SH "Multi-threading Issues"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	259 libcurl is thread safe but there are a few exceptions. Refer to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	260 \fIlibcurl-thread(3)\fP for more information.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	261
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	262 .SH "When It Doesn't Work"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	263 There will always be times when the transfer fails for some reason. You might
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	264 have set the wrong libcurl option or misunderstood what the libcurl option
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	265 actually does, or the remote server might return non-standard replies that
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	266 confuse the library which then confuses your program.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	267
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	268 There's one golden rule when these things occur: set the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	269 \fICURLOPT_VERBOSE(3)\fP option to 1. It'll cause the library to spew out the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	270 entire protocol details it sends, some internal info and some received
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	271 protocol data as well (especially when using FTP). If you're using HTTP,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	272 adding the headers in the received output to study is also a clever way to get
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	273 a better understanding why the server behaves the way it does. Include headers
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	274 in the normal body output with \fICURLOPT_HEADER(3)\fP set 1.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	275
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	276 Of course, there are bugs left. We need to know about them to be able to fix
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	277 them, so we're quite dependent on your bug reports! When you do report
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	278 suspected bugs in libcurl, please include as many details as you possibly can:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	279 a protocol dump that \fICURLOPT_VERBOSE(3)\fP produces, library version, as
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	280 much as possible of your code that uses libcurl, operating system name and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	281 version, compiler name and version etc.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	282
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	283 If \fICURLOPT_VERBOSE(3)\fP is not enough, you increase the level of debug
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	284 data your application receive by using the \fICURLOPT_DEBUGFUNCTION(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	285
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	286 Getting some in-depth knowledge about the protocols involved is never wrong,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	287 and if you're trying to do funny things, you might very well understand
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	288 libcurl and how to use it better if you study the appropriate RFC documents
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	289 at least briefly.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	290
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	291 .SH "Upload Data to a Remote Site"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	292 libcurl tries to keep a protocol independent approach to most transfers, thus
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	293 uploading to a remote FTP site is very similar to uploading data to an HTTP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	294 server with a PUT request.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	295
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	296 Of course, first you either create an easy handle or you re-use one existing
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	297 one. Then you set the URL to operate on just like before. This is the remote
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	298 URL, that we now will upload.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	299
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	300 Since we write an application, we most likely want libcurl to get the upload
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	301 data by asking us for it. To make it do that, we set the read callback and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	302 the custom pointer libcurl will pass to our read callback. The read callback
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	303 should have a prototype similar to:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	304
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	305 size_t function(char bufptr, size_t size, size_t nitems, void userp);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	306
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	307 Where bufptr is the pointer to a buffer we fill in with data to upload and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	308 size*nitems is the size of the buffer and therefore also the maximum amount
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	309 of data we can return to libcurl in this call. The 'userp' pointer is the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	310 custom pointer we set to point to a struct of ours to pass private data
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	311 between the application and the callback.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	312
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	313 curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, read_function);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	314
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	315 curl_easy_setopt(easyhandle, CURLOPT_READDATA, &filedata);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	316
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	317 Tell libcurl that we want to upload:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	318
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	319 curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, 1L);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	320
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	321 A few protocols won't behave properly when uploads are done without any prior
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	322 knowledge of the expected file size. So, set the upload file size using the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	323 \fICURLOPT_INFILESIZE_LARGE(3)\fP for all known file sizes like this[1]:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	324
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	325 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	326 /* in this example, file_size must be an curl_off_t variable */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	327 curl_easy_setopt(easyhandle, CURLOPT_INFILESIZE_LARGE, file_size);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	328 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	329
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	330 When you call \fIcurl_easy_perform(3)\fP this time, it'll perform all the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	331 necessary operations and when it has invoked the upload it'll call your
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	332 supplied callback to get the data to upload. The program should return as much
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	333 data as possible in every invoke, as that is likely to make the upload perform
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	334 as fast as possible. The callback should return the number of bytes it wrote
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	335 in the buffer. Returning 0 will signal the end of the upload.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	336
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	337 .SH "Passwords"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	338 Many protocols use or even require that user name and password are provided
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	339 to be able to download or upload the data of your choice. libcurl offers
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	340 several ways to specify them.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	341
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	342 Most protocols support that you specify the name and password in the URL
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	343 itself. libcurl will detect this and use them accordingly. This is written
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	344 like this:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	345
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	346 protocol://user:password@example.com/path/
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	347
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	348 If you need any odd letters in your user name or password, you should enter
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	349 them URL encoded, as %XX where XX is a two-digit hexadecimal number.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	350
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	351 libcurl also provides options to set various passwords. The user name and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	352 password as shown embedded in the URL can instead get set with the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	353 \fICURLOPT_USERPWD(3)\fP option. The argument passed to libcurl should be a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	354 char * to a string in the format "user:password". In a manner like this:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	355
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	356 curl_easy_setopt(easyhandle, CURLOPT_USERPWD, "myname:thesecret");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	357
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	358 Another case where name and password might be needed at times, is for those
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	359 users who need to authenticate themselves to a proxy they use. libcurl offers
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	360 another option for this, the \fICURLOPT_PROXYUSERPWD(3)\fP. It is used quite
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	361 similar to the \fICURLOPT_USERPWD(3)\fP option like this:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	362
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	363 curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:thesecret");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	364
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	365 There's a long time Unix "standard" way of storing FTP user names and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	366 passwords, namely in the $HOME/.netrc file. The file should be made private
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	367 so that only the user may read it (see also the "Security Considerations"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	368 chapter), as it might contain the password in plain text. libcurl has the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	369 ability to use this file to figure out what set of user name and password to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	370 use for a particular host. As an extension to the normal functionality,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	371 libcurl also supports this file for non-FTP protocols such as HTTP. To make
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	372 curl use this file, use the \fICURLOPT_NETRC(3)\fP option:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	373
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	374 curl_easy_setopt(easyhandle, CURLOPT_NETRC, 1L);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	375
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	376 And a very basic example of how such a .netrc file may look like:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	377
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	378 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	379 machine myhost.mydomain.com
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	380 login userlogin
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	381 password secretword
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	382 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	383
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	384 All these examples have been cases where the password has been optional, or
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	385 at least you could leave it out and have libcurl attempt to do its job
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	386 without it. There are times when the password isn't optional, like when
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	387 you're using an SSL private key for secure transfers.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	388
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	389 To pass the known private key password to libcurl:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	390
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	391 curl_easy_setopt(easyhandle, CURLOPT_KEYPASSWD, "keypassword");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	392
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	393 .SH "HTTP Authentication"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	394 The previous chapter showed how to set user name and password for getting
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	395 URLs that require authentication. When using the HTTP protocol, there are
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	396 many different ways a client can provide those credentials to the server and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	397 you can control which way libcurl will (attempt to) use them. The default HTTP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	398 authentication method is called 'Basic', which is sending the name and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	399 password in clear-text in the HTTP request, base64-encoded. This is insecure.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	400
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	401 At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	402 Negotiate (SPNEGO). You can tell libcurl which one to use
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	403 with \fICURLOPT_HTTPAUTH(3)\fP as in:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	404
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	405 curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	406
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	407 And when you send authentication to a proxy, you can also set authentication
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	408 type the same way but instead with \fICURLOPT_PROXYAUTH(3)\fP:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	409
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	410 curl_easy_setopt(easyhandle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	411
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	412 Both these options allow you to set multiple types (by ORing them together),
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	413 to make libcurl pick the most secure one out of the types the server/proxy
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	414 claims to support. This method does however add a round-trip since libcurl
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	415 must first ask the server what it supports:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	416
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	417 curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	418 CURLAUTH_DIGEST\|CURLAUTH_BASIC);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	419
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	420 For convenience, you can use the 'CURLAUTH_ANY' define (instead of a list
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	421 with specific types) which allows libcurl to use whatever method it wants.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	422
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	423 When asking for multiple types, libcurl will pick the available one it
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	424 considers "best" in its own internal order of preference.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	425
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	426 .SH "HTTP POSTing"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	427 We get many questions regarding how to issue HTTP POSTs with libcurl the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	428 proper way. This chapter will thus include examples using both different
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	429 versions of HTTP POST that libcurl supports.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	430
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	431 The first version is the simple POST, the most common version, that most HTML
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	432 pages using the <form> tag uses. We provide a pointer to the data and tell
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	433 libcurl to post it all to the remote site:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	434
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	435 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	436 char *data="name=daniel&project=curl";
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	437 curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, data);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	438 curl_easy_setopt(easyhandle, CURLOPT_URL, "http://posthere.com/");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	439
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	440 curl_easy_perform(easyhandle); /* post away! */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	441 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	442
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	443 Simple enough, huh? Since you set the POST options with the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	444 \fICURLOPT_POSTFIELDS(3)\fP, this automatically switches the handle to use
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	445 POST in the upcoming request.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	446
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	447 Ok, so what if you want to post binary data that also requires you to set the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	448 Content-Type: header of the post? Well, binary posts prevent libcurl from
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	449 being able to do strlen() on the data to figure out the size, so therefore we
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	450 must tell libcurl the size of the post data. Setting headers in libcurl
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	451 requests are done in a generic way, by building a list of our own headers and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	452 then passing that list to libcurl.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	453
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	454 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	455 struct curl_slist *headers=NULL;
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	456 headers = curl_slist_append(headers, "Content-Type: text/xml");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	457
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	458 /* post binary data */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	459 curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, binaryptr);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	460
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	461 /* set the size of the postfields data */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	462 curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23L);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	463
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	464 /* pass our list of custom made headers */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	465 curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	466
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	467 curl_easy_perform(easyhandle); /* post away! */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	468
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	469 curl_slist_free_all(headers); /* free the header list */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	470 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	471
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	472 While the simple examples above cover the majority of all cases where HTTP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	473 POST operations are required, they don't do multi-part formposts. Multi-part
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	474 formposts were introduced as a better way to post (possibly large) binary data
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	475 and were first documented in the RFC1867 (updated in RFC2388). They're called
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	476 multi-part because they're built by a chain of parts, each part being a single
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	477 unit of data. Each part has its own name and contents. You can in fact create
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	478 and post a multi-part formpost with the regular libcurl POST support described
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	479 above, but that would require that you build a formpost yourself and provide
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	480 to libcurl. To make that easier, libcurl provides a MIME API consisting in
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	481 several functions: using those, you can create and fill a multi-part form.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	482 Function \fIcurl_mime_init(3)\fP creates a multi-part body; you can then
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	483 append new parts to a multi-part body using \fIcurl_mime_addpart(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	484 There are three possible data sources for a part: memory using
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	485 \fIcurl_mime_data(3)\fP, file using \fIcurl_mime_filedata(3)\fP and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	486 user-defined data read callback using \fIcurl_mime_data_cb(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	487 \fIcurl_mime_name(3)\fP sets a part's (i.e.: form field) name, while
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	488 \fIcurl_mime_filename(3)\fP fills in the remote file name. With
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	489 \fIcurl_mime_type(3)\fP, you can tell the MIME type of a part,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	490 \fIcurl_mime_headers(3)\fP allows defining the part's headers. When a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	491 multi-part body is no longer needed, you can destroy it using
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	492 \fIcurl_mime_free(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	493
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	494 The following example sets two simple text parts with plain textual contents,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	495 and then a file with binary contents and uploads the whole thing.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	496
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	497 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	498 curl_mime *multipart = curl_mime_init(easyhandle);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	499 curl_mimepart *part = curl_mime_addpart(multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	500 curl_mime_name(part, "name");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	501 curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	502 part = curl_mime_addpart(multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	503 curl_mime_name(part, "project");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	504 curl_mime_data(part, "curl", CURL_ZERO_TERMINATED);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	505 part = curl_mime_addpart(multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	506 curl_mime_name(part, "logotype-image");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	507 curl_mime_filedata(part, "curl.png");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	508
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	509 /* Set the form info */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	510 curl_easy_setopt(easyhandle, CURLOPT_MIMEPOST, multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	511
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	512 curl_easy_perform(easyhandle); /* post away! */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	513
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	514 /* free the post data again */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	515 curl_mime_free(multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	516 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	517
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	518 To post multiple files for a single form field, you must supply each file in
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	519 a separate part, all with the same field name. Although function
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	520 \fIcurl_mime_subparts(3)\fP implements nested multi-parts, this way of
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	521 multiple files posting is deprecated by RFC 7578, chapter 4.3.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	522
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	523 To set the data source from an already opened FILE pointer, use:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	524
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	525 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	526 curl_mime_data_cb(part, filesize, (curl_read_callback) fread,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	527 (curl_seek_callback) fseek, NULL, filepointer);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	528 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	529
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	530 A deprecated \fIcurl_formadd(3)\fP function is still supported in libcurl.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	531 It should however not be used anymore for new designs and programs using it
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	532 ought to be converted to the MIME API. It is however described here as an
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	533 aid to conversion.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	534
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	535 Using \fIcurl_formadd\fP, you add parts to the form. When you're done adding
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	536 parts, you post the whole form.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	537
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	538 The MIME API example above is expressed as follows using this function:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	539
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	540 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	541 struct curl_httppost *post=NULL;
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	542 struct curl_httppost *last=NULL;
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	543 curl_formadd(&post, &last,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	544 CURLFORM_COPYNAME, "name",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	545 CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	546 curl_formadd(&post, &last,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	547 CURLFORM_COPYNAME, "project",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	548 CURLFORM_COPYCONTENTS, "curl", CURLFORM_END);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	549 curl_formadd(&post, &last,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	550 CURLFORM_COPYNAME, "logotype-image",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	551 CURLFORM_FILECONTENT, "curl.png", CURLFORM_END);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	552
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	553 /* Set the form info */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	554 curl_easy_setopt(easyhandle, CURLOPT_HTTPPOST, post);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	555
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	556 curl_easy_perform(easyhandle); /* post away! */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	557
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	558 /* free the post data again */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	559 curl_formfree(post);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	560 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	561
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	562 Multipart formposts are chains of parts using MIME-style separators and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	563 headers. It means that each one of these separate parts get a few headers set
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	564 that describe the individual content-type, size etc. To enable your
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	565 application to handicraft this formpost even more, libcurl allows you to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	566 supply your own set of custom headers to such an individual form part. You can
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	567 of course supply headers to as many parts as you like, but this little example
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	568 will show how you set headers to one specific part when you add that to the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	569 post handle:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	570
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	571 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	572 struct curl_slist *headers=NULL;
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	573 headers = curl_slist_append(headers, "Content-Type: text/xml");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	574
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	575 curl_formadd(&post, &last,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	576 CURLFORM_COPYNAME, "logotype-image",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	577 CURLFORM_FILECONTENT, "curl.xml",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	578 CURLFORM_CONTENTHEADER, headers,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	579 CURLFORM_END);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	580
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	581 curl_easy_perform(easyhandle); /* post away! */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	582
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	583 curl_formfree(post); /* free post */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	584 curl_slist_free_all(headers); /* free custom header list */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	585 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	586
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	587 Since all options on an easyhandle are "sticky", they remain the same until
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	588 changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	589 curl to go back to a plain GET request if you intend to do one as your next
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	590 request. You force an easyhandle to go back to GET by using the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	591 \fICURLOPT_HTTPGET(3)\fP option:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	592
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	593 curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	594
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	595 Just setting \fICURLOPT_POSTFIELDS(3)\fP to "" or NULL will not stop libcurl
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	596 from doing a POST. It will just make it POST without any data to send!
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	597
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	598 .SH "Converting from deprecated form API to MIME API"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	599 Four rules have to be respected in building the multi-part:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	600 .br
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	601 - The easy handle must be created before building the multi-part.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	602 .br
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	603 - The multi-part is always created by a call to curl_mime_init(easyhandle).
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	604 .br
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	605 - Each part is created by a call to curl_mime_addpart(multipart).
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	606 .br
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	607 - When complete, the multi-part must be bound to the easy handle using
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	608 \fICURLOPT_MIMEPOST(3)\fP instead of \fICURLOPT_HTTPPOST(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	609
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	610 Here are some example of \fIcurl_formadd\fP calls to MIME API sequences:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	611
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	612 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	613 curl_formadd(&post, &last,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	614 CURLFORM_COPYNAME, "id",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	615 CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	616 CURLFORM_CONTENTHEADER, headers,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	617 CURLFORM_END);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	618 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	619 becomes:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	620 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	621 part = curl_mime_addpart(multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	622 curl_mime_name(part, "id");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	623 curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	624 curl_mime_headers(part, headers, FALSE);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	625 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	626
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	627 Setting the last \fIcurl_mime_headers\fP argument to TRUE would have caused
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	628 the headers to be automatically released upon destroyed the multi-part, thus
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	629 saving a clean-up call to \fIcurl_slist_free_all(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	630
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	631 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	632 curl_formadd(&post, &last,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	633 CURLFORM_PTRNAME, "logotype-image",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	634 CURLFORM_FILECONTENT, "-",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	635 CURLFORM_END);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	636 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	637 becomes:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	638 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	639 part = curl_mime_addpart(multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	640 curl_mime_name(part, "logotype-image");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	641 curl_mime_data_cb(part, (curl_off_t) -1, fread, fseek, NULL, stdin);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	642 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	643
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	644 \fIcurl_mime_name\fP always copies the field name. The special file name "-"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	645 is not supported by \fIcurl_mime_file\fP: to read an open file, use
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	646 a callback source using fread(). The transfer will be chunked since the data
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	647 size is unknown.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	648
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	649 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	650 curl_formadd(&post, &last,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	651 CURLFORM_COPYNAME, "datafile[]",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	652 CURLFORM_FILE, "file1",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	653 CURLFORM_FILE, "file2",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	654 CURLFORM_END);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	655 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	656 becomes:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	657 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	658 part = curl_mime_addpart(multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	659 curl_mime_name(part, "datafile[]");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	660 curl_mime_filedata(part, "file1");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	661 part = curl_mime_addpart(multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	662 curl_mime_name(part, "datafile[]");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	663 curl_mime_filedata(part, "file2");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	664 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	665
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	666 The deprecated multipart/mixed implementation of multiple files field is
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	667 translated to two distinct parts with the same name.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	668
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	669 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	670 curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, myreadfunc);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	671 curl_formadd(&post, &last,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	672 CURLFORM_COPYNAME, "stream",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	673 CURLFORM_STREAM, arg,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	674 CURLFORM_CONTENTLEN, (curl_off_t) datasize,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	675 CURLFORM_FILENAME, "archive.zip",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	676 CURLFORM_CONTENTTYPE, "application/zip",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	677 CURLFORM_END);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	678 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	679 becomes:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	680 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	681 part = curl_mime_addpart(multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	682 curl_mime_name(part, "stream");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	683 curl_mime_data_cb(part, (curl_off_t) datasize,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	684 myreadfunc, NULL, NULL, arg);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	685 curl_mime_filename(part, "archive.zip");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	686 curl_mime_type(part, "application/zip");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	687 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	688
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	689 \fICURLOPT_READFUNCTION\fP callback is not used: it is replace by directly
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	690 setting the part source data from the callback read function.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	691
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	692 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	693 curl_formadd(&post, &last,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	694 CURLFORM_COPYNAME, "memfile",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	695 CURLFORM_BUFFER, "memfile.bin",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	696 CURLFORM_BUFFERPTR, databuffer,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	697 CURLFORM_BUFFERLENGTH, (long) sizeof databuffer,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	698 CURLFORM_END);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	699 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	700 becomes:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	701 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	702 part = curl_mime_addpart(multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	703 curl_mime_name(part, "memfile");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	704 curl_mime_data(part, databuffer, (curl_off_t) sizeof databuffer);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	705 curl_mime_filename(part, "memfile.bin");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	706 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	707
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	708 \fIcurl_mime_data\fP always copies the initial data: data buffer is thus
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	709 free for immediate reuse.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	710
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	711 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	712 curl_formadd(&post, &last,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	713 CURLFORM_COPYNAME, "message",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	714 CURLFORM_FILECONTENT, "msg.txt",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	715 CURLFORM_END);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	716 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	717 becomes:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	718 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	719 part = curl_mime_addpart(multipart);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	720 curl_mime_name(part, "message");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	721 curl_mime_filedata(part, "msg.txt");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	722 curl_mime_filename(part, NULL);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	723 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	724
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	725 Use of \fIcurl_mime_filedata\fP sets the remote file name as a side effect: it
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	726 is therefore necessary to clear it for \fICURLFORM_FILECONTENT\fP emulation.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	727
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	728 .SH "Showing Progress"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	729
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	730 For historical and traditional reasons, libcurl has a built-in progress meter
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	731 that can be switched on and then makes it present a progress meter in your
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	732 terminal.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	733
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	734 Switch on the progress meter by, oddly enough, setting
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	735 \fICURLOPT_NOPROGRESS(3)\fP to zero. This option is set to 1 by default.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	736
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	737 For most applications however, the built-in progress meter is useless and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	738 what instead is interesting is the ability to specify a progress
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	739 callback. The function pointer you pass to libcurl will then be called on
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	740 irregular intervals with information about the current transfer.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	741
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	742 Set the progress callback by using \fICURLOPT_PROGRESSFUNCTION(3)\fP. And pass
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	743 a pointer to a function that matches this prototype:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	744
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	745 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	746 int progress_callback(void *clientp,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	747 double dltotal,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	748 double dlnow,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	749 double ultotal,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	750 double ulnow);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	751 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	752
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	753 If any of the input arguments is unknown, a 0 will be passed. The first
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	754 argument, the 'clientp' is the pointer you pass to libcurl with
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	755 \fICURLOPT_PROGRESSDATA(3)\fP. libcurl won't touch it.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	756
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	757 .SH "libcurl with C++"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	758
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	759 There's basically only one thing to keep in mind when using C++ instead of C
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	760 when interfacing libcurl:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	761
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	762 The callbacks CANNOT be non-static class member functions
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	763
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	764 Example C++ code:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	765
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	766 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	767 class AClass {
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	768 static size_t write_data(void *ptr, size_t size, size_t nmemb,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	769 void *ourpointer)
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	770 {
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	771 /* do what you want with the data */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	772 }
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	773 }
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	774 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	775
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	776 .SH "Proxies"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	777
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	778 What "proxy" means according to Merriam-Webster: "a person authorized to act
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	779 for another" but also "the agency, function, or office of a deputy who acts as
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	780 a substitute for another".
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	781
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	782 Proxies are exceedingly common these days. Companies often only offer Internet
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	783 access to employees through their proxies. Network clients or user-agents ask
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	784 the proxy for documents, the proxy does the actual request and then it returns
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	785 them.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	786
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	787 libcurl supports SOCKS and HTTP proxies. When a given URL is wanted, libcurl
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	788 will ask the proxy for it instead of trying to connect to the actual host
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	789 identified in the URL.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	790
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	791 If you're using a SOCKS proxy, you may find that libcurl doesn't quite support
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	792 all operations through it.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	793
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	794 For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	795 restrictions on what can actually happen. A requested URL that might not be a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	796 HTTP URL will be still be passed to the HTTP proxy to deliver back to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	797 libcurl. This happens transparently, and an application may not need to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	798 know. I say "may", because at times it is very important to understand that
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	799 all operations over an HTTP proxy use the HTTP protocol. For example, you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	800 can't invoke your own custom FTP commands or even proper FTP directory
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	801 listings.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	802
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	803 .IP "Proxy Options"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	804
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	805 To tell libcurl to use a proxy at a given port number:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	806
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	807 curl_easy_setopt(easyhandle, CURLOPT_PROXY, "proxy-host.com:8080");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	808
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	809 Some proxies require user authentication before allowing a request, and you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	810 pass that information similar to this:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	811
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	812 curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "user:password");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	813
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	814 If you want to, you can specify the host name only in the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	815 \fICURLOPT_PROXY(3)\fP option, and set the port number separately with
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	816 \fICURLOPT_PROXYPORT(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	817
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	818 Tell libcurl what kind of proxy it is with \fICURLOPT_PROXYTYPE(3)\fP (if not,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	819 it will default to assume an HTTP proxy):
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	820
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	821 curl_easy_setopt(easyhandle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	822
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	823 .IP "Environment Variables"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	824
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	825 libcurl automatically checks and uses a set of environment variables to know
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	826 what proxies to use for certain protocols. The names of the variables are
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	827 following an ancient de facto standard and are built up as "[protocol]_proxy"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	828 (note the lower casing). Which makes the variable \&'http_proxy' checked for a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	829 name of a proxy to use when the input URL is HTTP. Following the same rule,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	830 the variable named 'ftp_proxy' is checked for FTP URLs. Again, the proxies are
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	831 always HTTP proxies, the different names of the variables simply allows
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	832 different HTTP proxies to be used.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	833
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	834 The proxy environment variable contents should be in the format
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	835 \&"[protocol://][user:password@]machine[:port]". Where the protocol:// part is
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	836 simply ignored if present (so http://proxy and bluerk://proxy will do the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	837 same) and the optional port number specifies on which port the proxy operates
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	838 on the host. If not specified, the internal default port number will be used
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	839 and that is most likely not the one you would like it to be.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	840
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	841 There are two special environment variables. 'all_proxy' is what sets proxy
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	842 for any URL in case the protocol specific variable wasn't set, and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	843 \&'no_proxy' defines a list of hosts that should not use a proxy even though a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	844 variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	845 hosts.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	846
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	847 To explicitly disable libcurl's checking for and using the proxy environment
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	848 variables, set the proxy name to "" - an empty string - with
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	849 \fICURLOPT_PROXY(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	850 .IP "SSL and Proxies"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	851
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	852 SSL is for secure point-to-point connections. This involves strong encryption
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	853 and similar things, which effectively makes it impossible for a proxy to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	854 operate as a "man in between" which the proxy's task is, as previously
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	855 discussed. Instead, the only way to have SSL work over an HTTP proxy is to ask
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	856 the proxy to tunnel trough everything without being able to check or fiddle
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	857 with the traffic.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	858
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	859 Opening an SSL connection over an HTTP proxy is therefore a matter of asking the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	860 proxy for a straight connection to the target host on a specified port. This
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	861 is made with the HTTP request CONNECT. ("please mr proxy, connect me to that
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	862 remote host").
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	863
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	864 Because of the nature of this operation, where the proxy has no idea what kind
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	865 of data that is passed in and out through this tunnel, this breaks some of the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	866 very few advantages that come from using a proxy, such as caching. Many
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	867 organizations prevent this kind of tunneling to other destination port numbers
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	868 than 443 (which is the default HTTPS port number).
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	869
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	870 .IP "Tunneling Through Proxy"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	871 As explained above, tunneling is required for SSL to work and often even
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	872 restricted to the operation intended for SSL; HTTPS.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	873
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	874 This is however not the only time proxy-tunneling might offer benefits to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	875 you or your application.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	876
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	877 As tunneling opens a direct connection from your application to the remote
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	878 machine, it suddenly also re-introduces the ability to do non-HTTP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	879 operations over an HTTP proxy. You can in fact use things such as FTP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	880 upload or FTP custom commands this way.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	881
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	882 Again, this is often prevented by the administrators of proxies and is
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	883 rarely allowed.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	884
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	885 Tell libcurl to use proxy tunneling like this:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	886
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	887 curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, 1L);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	888
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	889 In fact, there might even be times when you want to do plain HTTP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	890 operations using a tunnel like this, as it then enables you to operate on
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	891 the remote server instead of asking the proxy to do so. libcurl will not
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	892 stand in the way for such innovative actions either!
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	893
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	894 .IP "Proxy Auto-Config"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	895
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	896 Netscape first came up with this. It is basically a web page (usually using a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	897 \&.pac extension) with a Javascript that when executed by the browser with the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	898 requested URL as input, returns information to the browser on how to connect
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	899 to the URL. The returned information might be "DIRECT" (which means no proxy
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	900 should be used), "PROXY host:port" (to tell the browser where the proxy for
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	901 this particular URL is) or "SOCKS host:port" (to direct the browser to a SOCKS
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	902 proxy).
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	903
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	904 libcurl has no means to interpret or evaluate Javascript and thus it doesn't
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	905 support this. If you get yourself in a position where you face this nasty
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	906 invention, the following advice have been mentioned and used in the past:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	907
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	908 - Depending on the Javascript complexity, write up a script that translates it
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	909 to another language and execute that.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	910
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	911 - Read the Javascript code and rewrite the same logic in another language.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	912
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	913 - Implement a Javascript interpreter; people have successfully used the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	914 Mozilla Javascript engine in the past.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	915
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	916 - Ask your admins to stop this, for a static proxy setup or similar.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	917
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	918 .SH "Persistence Is The Way to Happiness"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	919
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	920 Re-cycling the same easy handle several times when doing multiple requests is
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	921 the way to go.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	922
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	923 After each single \fIcurl_easy_perform(3)\fP operation, libcurl will keep the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	924 connection alive and open. A subsequent request using the same easy handle to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	925 the same host might just be able to use the already open connection! This
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	926 reduces network impact a lot.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	927
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	928 Even if the connection is dropped, all connections involving SSL to the same
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	929 host again, will benefit from libcurl's session ID cache that drastically
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	930 reduces re-connection time.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	931
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	932 FTP connections that are kept alive save a lot of time, as the command-
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	933 response round-trips are skipped, and also you don't risk getting blocked
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	934 without permission to login again like on many FTP servers only allowing N
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	935 persons to be logged in at the same time.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	936
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	937 libcurl caches DNS name resolving results, to make lookups of a previously
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	938 looked up name a lot faster.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	939
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	940 Other interesting details that improve performance for subsequent requests
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	941 may also be added in the future.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	942
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	943 Each easy handle will attempt to keep the last few connections alive for a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	944 while in case they are to be used again. You can set the size of this "cache"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	945 with the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is very
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	946 seldom any point in changing this value, and if you think of changing this it
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	947 is often just a matter of thinking again.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	948
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	949 To force your upcoming request to not use an already existing connection (it
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	950 will even close one first if there happens to be one alive to the same host
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	951 you're about to operate on), you can do that by setting
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	952 \fICURLOPT_FRESH_CONNECT(3)\fP to 1. In a similar spirit, you can also forbid
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	953 the upcoming request to be "lying" around and possibly get re-used after the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	954 request by setting \fICURLOPT_FORBID_REUSE(3)\fP to 1.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	955
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	956 .SH "HTTP Headers Used by libcurl"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	957 When you use libcurl to do HTTP requests, it'll pass along a series of headers
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	958 automatically. It might be good for you to know and understand these. You
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	959 can replace or remove them by using the \fICURLOPT_HTTPHEADER(3)\fP option.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	960
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	961 .IP "Host"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	962 This header is required by HTTP 1.1 and even many 1.0 servers and should be
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	963 the name of the server we want to talk to. This includes the port number if
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	964 anything but default.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	965
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	966 .IP "Accept"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	967 \&"/".
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	968
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	969 .IP "Expect"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	970 When doing POST requests, libcurl sets this header to \&"100-continue" to ask
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	971 the server for an "OK" message before it proceeds with sending the data part
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	972 of the post. If the POSTed data amount is deemed "small", libcurl will not use
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	973 this header.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	974
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	975 .SH "Customizing Operations"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	976 There is an ongoing development today where more and more protocols are built
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	977 upon HTTP for transport. This has obvious benefits as HTTP is a tested and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	978 reliable protocol that is widely deployed and has excellent proxy-support.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	979
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	980 When you use one of these protocols, and even when doing other kinds of
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	981 programming you may need to change the traditional HTTP (or FTP or...)
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	982 manners. You may need to change words, headers or various data.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	983
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	984 libcurl is your friend here too.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	985
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	986 .IP CUSTOMREQUEST
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	987 If just changing the actual HTTP request keyword is what you want, like when
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	988 GET, HEAD or POST is not good enough for you, \fICURLOPT_CUSTOMREQUEST(3)\fP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	989 is there for you. It is very simple to use:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	990
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	991 curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	992
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	993 When using the custom request, you change the request keyword of the actual
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	994 request you are performing. Thus, by default you make a GET request but you can
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	995 also make a POST operation (as described before) and then replace the POST
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	996 keyword if you want to. You're the boss.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	997
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	998 .IP "Modify Headers"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	999 HTTP-like protocols pass a series of headers to the server when doing the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1000 request, and you're free to pass any amount of extra headers that you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1001 think fit. Adding headers is this easy:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1002
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1003 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1004 struct curl_slist headers=NULL; / init to NULL is important */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1005
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1006 headers = curl_slist_append(headers, "Hey-server-hey: how are you?");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1007 headers = curl_slist_append(headers, "X-silly-content: yes");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1008
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1009 /* pass our list of custom made headers */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1010 curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1011
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1012 curl_easy_perform(easyhandle); /* transfer http */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1013
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1014 curl_slist_free_all(headers); /* free the header list */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1015 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1016
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1017 \&... and if you think some of the internally generated headers, such as
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1018 Accept: or Host: don't contain the data you want them to contain, you can
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1019 replace them by simply setting them too:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1020
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1021 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1022 headers = curl_slist_append(headers, "Accept: Agent-007");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1023 headers = curl_slist_append(headers, "Host: munged.host.line");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1024 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1025
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1026 .IP "Delete Headers"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1027 If you replace an existing header with one with no contents, you will prevent
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1028 the header from being sent. For instance, if you want to completely prevent the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1029 \&"Accept:" header from being sent, you can disable it with code similar to this:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1030
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1031 headers = curl_slist_append(headers, "Accept:");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1032
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1033 Both replacing and canceling internal headers should be done with careful
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1034 consideration and you should be aware that you may violate the HTTP protocol
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1035 when doing so.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1036
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1037 .IP "Enforcing chunked transfer-encoding"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1038
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1039 By making sure a request uses the custom header "Transfer-Encoding: chunked"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1040 when doing a non-GET HTTP operation, libcurl will switch over to "chunked"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1041 upload, even though the size of the data to upload might be known. By default,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1042 libcurl usually switches over to chunked upload automatically if the upload
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1043 data size is unknown.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1044
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1045 .IP "HTTP Version"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1046
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1047 All HTTP requests includes the version number to tell the server which version
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1048 we support. libcurl speaks HTTP 1.1 by default. Some very old servers don't
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1049 like getting 1.1-requests and when dealing with stubborn old things like that,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1050 you can tell libcurl to use 1.0 instead by doing something like this:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1051
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1052 curl_easy_setopt(easyhandle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1053
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1054 .IP "FTP Custom Commands"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1055
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1056 Not all protocols are HTTP-like, and thus the above may not help you when
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1057 you want to make, for example, your FTP transfers to behave differently.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1058
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1059 Sending custom commands to an FTP server means that you need to send the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1060 commands exactly as the FTP server expects them (RFC959 is a good guide
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1061 here), and you can only use commands that work on the control-connection
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1062 alone. All kinds of commands that require data interchange and thus need
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1063 a data-connection must be left to libcurl's own judgement. Also be aware
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1064 that libcurl will do its very best to change directory to the target
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1065 directory before doing any transfer, so if you change directory (with CWD
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1066 or similar) you might confuse libcurl and then it might not attempt to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1067 transfer the file in the correct remote directory.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1068
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1069 A little example that deletes a given file before an operation:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1070
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1071 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1072 headers = curl_slist_append(headers, "DELE file-to-remove");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1073
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1074 /* pass the list of custom commands to the handle */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1075 curl_easy_setopt(easyhandle, CURLOPT_QUOTE, headers);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1076
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1077 curl_easy_perform(easyhandle); /* transfer ftp data! */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1078
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1079 curl_slist_free_all(headers); /* free the header list */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1080 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1081
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1082 If you would instead want this operation (or chain of operations) to happen
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1083 _after_ the data transfer took place the option to \fIcurl_easy_setopt(3)\fP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1084 would instead be called \fICURLOPT_POSTQUOTE(3)\fP and used the exact same
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1085 way.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1086
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1087 The custom FTP command will be issued to the server in the same order they are
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1088 added to the list, and if a command gets an error code returned back from the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1089 server, no more commands will be issued and libcurl will bail out with an
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1090 error code (CURLE_QUOTE_ERROR). Note that if you use \fICURLOPT_QUOTE(3)\fP to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1091 send commands before a transfer, no transfer will actually take place when a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1092 quote command has failed.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1093
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1094 If you set the \fICURLOPT_HEADER(3)\fP to 1, you will tell libcurl to get
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1095 information about the target file and output "headers" about it. The headers
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1096 will be in "HTTP-style", looking like they do in HTTP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1097
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1098 The option to enable headers or to run custom FTP commands may be useful to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1099 combine with \fICURLOPT_NOBODY(3)\fP. If this option is set, no actual file
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1100 content transfer will be performed.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1101
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1102 .IP "FTP Custom CUSTOMREQUEST"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1103 If you do want to list the contents of an FTP directory using your own defined
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1104 FTP command, \fICURLOPT_CUSTOMREQUEST(3)\fP will do just that. "NLST" is the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1105 default one for listing directories but you're free to pass in your idea of a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1106 good alternative.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1107
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1108 .SH "Cookies Without Chocolate Chips"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1109 In the HTTP sense, a cookie is a name with an associated value. A server sends
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1110 the name and value to the client, and expects it to get sent back on every
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1111 subsequent request to the server that matches the particular conditions
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1112 set. The conditions include that the domain name and path match and that the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1113 cookie hasn't become too old.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1114
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1115 In real-world cases, servers send new cookies to replace existing ones to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1116 update them. Server use cookies to "track" users and to keep "sessions".
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1117
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1118 Cookies are sent from server to clients with the header Set-Cookie: and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1119 they're sent from clients to servers with the Cookie: header.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1120
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1121 To just send whatever cookie you want to a server, you can use
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1122 \fICURLOPT_COOKIE(3)\fP to set a cookie string like this:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1123
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1124 curl_easy_setopt(easyhandle, CURLOPT_COOKIE, "name1=var1; name2=var2;");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1125
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1126 In many cases, that is not enough. You might want to dynamically save
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1127 whatever cookies the remote server passes to you, and make sure those cookies
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1128 are then used accordingly on later requests.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1129
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1130 One way to do this, is to save all headers you receive in a plain file and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1131 when you make a request, you tell libcurl to read the previous headers to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1132 figure out which cookies to use. Set the header file to read cookies from with
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1133 \fICURLOPT_COOKIEFILE(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1134
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1135 The \fICURLOPT_COOKIEFILE(3)\fP option also automatically enables the cookie
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1136 parser in libcurl. Until the cookie parser is enabled, libcurl will not parse
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1137 or understand incoming cookies and they will just be ignored. However, when
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1138 the parser is enabled the cookies will be understood and the cookies will be
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1139 kept in memory and used properly in subsequent requests when the same handle
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1140 is used. Many times this is enough, and you may not have to save the cookies
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1141 to disk at all. Note that the file you specify to \fICURLOPT_COOKIEFILE(3)\fP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1142 doesn't have to exist to enable the parser, so a common way to just enable the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1143 parser and not read any cookies is to use the name of a file you know doesn't
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1144 exist.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1145
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1146 If you would rather use existing cookies that you've previously received with
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1147 your Netscape or Mozilla browsers, you can make libcurl use that cookie file
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1148 as input. The \fICURLOPT_COOKIEFILE(3)\fP is used for that too, as libcurl
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1149 will automatically find out what kind of file it is and act accordingly.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1150
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1151 Perhaps the most advanced cookie operation libcurl offers, is saving the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1152 entire internal cookie state back into a Netscape/Mozilla formatted cookie
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1153 file. We call that the cookie-jar. When you set a file name with
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1154 \fICURLOPT_COOKIEJAR(3)\fP, that file name will be created and all received
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1155 cookies will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1156 enables cookies to get passed on properly between multiple handles without any
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1157 information getting lost.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1158
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1159 .SH "FTP Peculiarities We Need"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1160
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1161 FTP transfers use a second TCP/IP connection for the data transfer. This is
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1162 usually a fact you can forget and ignore but at times this fact will come
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1163 back to haunt you. libcurl offers several different ways to customize how the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1164 second connection is being made.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1165
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1166 libcurl can either connect to the server a second time or tell the server to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1167 connect back to it. The first option is the default and it is also what works
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1168 best for all the people behind firewalls, NATs or IP-masquerading setups.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1169 libcurl then tells the server to open up a new port and wait for a second
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1170 connection. This is by default attempted with EPSV first, and if that doesn't
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1171 work it tries PASV instead. (EPSV is an extension to the original FTP spec
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1172 and does not exist nor work on all FTP servers.)
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1173
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1174 You can prevent libcurl from first trying the EPSV command by setting
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1175 \fICURLOPT_FTP_USE_EPSV(3)\fP to zero.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1176
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1177 In some cases, you will prefer to have the server connect back to you for the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1178 second connection. This might be when the server is perhaps behind a firewall
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1179 or something and only allows connections on a single port. libcurl then
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1180 informs the remote server which IP address and port number to connect to.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1181 This is made with the \fICURLOPT_FTPPORT(3)\fP option. If you set it to "-",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1182 libcurl will use your system's "default IP address". If you want to use a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1183 particular IP, you can set the full IP address, a host name to resolve to an
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1184 IP address or even a local network interface name that libcurl will get the IP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1185 address from.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1186
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1187 When doing the "PORT" approach, libcurl will attempt to use the EPRT and the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1188 LPRT before trying PORT, as they work with more protocols. You can disable
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1189 this behavior by setting \fICURLOPT_FTP_USE_EPRT(3)\fP to zero.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1190
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1191 .SH "MIME API revisited for SMTP and IMAP"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1192 In addition to support HTTP multi-part form fields, the MIME API can be used
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1193 to build structured e-mail messages and send them via SMTP or append such
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1194 messages to IMAP directories.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1195
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1196 A structured e-mail message may contain several parts: some are displayed
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1197 inline by the MUA, some are attachments. Parts can also be structured as
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1198 multi-part, for example to include another e-mail message or to offer several
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1199 text formats alternatives. This can be nested to any level.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1200
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1201 To build such a message, you prepare the nth-level multi-part and then include
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1202 it as a source to the parent multi-part using function
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1203 \fIcurl_mime_subparts(3)\fP. Once it has been
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1204 bound to its parent multi-part, a nth-level multi-part belongs to it and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1205 should not be freed explicitly.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1206
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1207 E-mail messages data is not supposed to be non-ascii and line length is
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1208 limited: fortunately, some transfer encodings are defined by the standards
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1209 to support the transmission of such incompatible data. Function
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1210 \fIcurl_mime_encoder(3)\fP tells a part that its source data must be encoded
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1211 before being sent. It also generates the corresponding header for that part.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1212 If the part data you want to send is already encoded in such a scheme,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1213 do not use this function (this would over-encode it), but explicitly set the
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1214 corresponding part header.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1215
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1216 Upon sending such a message, libcurl prepends it with the header list
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1217 set with \fICURLOPT_HTTPHEADER(3)\fP, as 0th-level mime part headers.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1218
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1219 Here is an example building an e-mail message with an inline plain/html text
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1220 alternative and a file attachment encoded in base64:
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1221
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1222 .nf
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1223 curl_mime *message = curl_mime_init(easyhandle);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1224
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1225 /* The inline part is an alternative proposing the html and the text
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1226 versions of the e-mail. */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1227 curl_mime *alt = curl_mime_init(easyhandle);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1228
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1229 /* HTML message. */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1230 curl_mimepart *part = curl_mime_addpart(alt);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1231 curl_mime_data(part, "<html><body><p>This is HTML</p></body></html>",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1232 CURL_ZERO_TERMINATED);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1233 curl_mime_type(part, "text/html");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1234
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1235 /* Text message. */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1236 part = curl_mime_addpart(alt);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1237 curl_mime_data(part, "This is plain text message",
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1238 CURL_ZERO_TERMINATED);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1239
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1240 /* Create the inline part. */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1241 part = curl_mime_addpart(message);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1242 curl_mime_subparts(part, alt);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1243 curl_mime_type(part, "multipart/alternative");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1244 struct curl_slist *headers = curl_slist_append(NULL,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1245 "Content-Disposition: inline");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1246 curl_mime_headers(part, headers, TRUE);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1247
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1248 /* Add the attachment. */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1249 part = curl_mime_addpart(message);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1250 curl_mime_filedata(part, "manual.pdf");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1251 curl_mime_encoder(part, "base64");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1252
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1253 /* Build the mail headers. */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1254 headers = curl_slist_append(NULL, "From: me@example.com");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1255 headers = curl_slist_append(headers, "To: you@example.com");
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1256
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1257 /* Set these into the easy handle. */
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1258 curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1259 curl_easy_setopt(easyhandle, CURLOPT_MIMEPOST, mime);
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1260 .fi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1261
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1262 It should be noted that appending a message to an IMAP directory requires
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1263 the message size to be known prior upload. It is therefore not possible to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1264 include parts with unknown data size in this context.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1265
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1266 .SH "Headers Equal Fun"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1267
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1268 Some protocols provide "headers", meta-data separated from the normal
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1269 data. These headers are by default not included in the normal data stream, but
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1270 you can make them appear in the data stream by setting \fICURLOPT_HEADER(3)\fP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1271 to 1.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1272
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1273 What might be even more useful, is libcurl's ability to separate the headers
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1274 from the data and thus make the callbacks differ. You can for example set a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1275 different pointer to pass to the ordinary write callback by setting
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1276 \fICURLOPT_HEADERDATA(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1277
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1278 Or, you can set an entirely separate function to receive the headers, by using
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1279 \fICURLOPT_HEADERFUNCTION(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1280
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1281 The headers are passed to the callback function one by one, and you can
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1282 depend on that fact. It makes it easier for you to add custom header parsers
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1283 etc.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1284
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1285 \&"Headers" for FTP transfers equal all the FTP server responses. They aren't
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1286 actually true headers, but in this case we pretend they are! ;-)
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1287
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1288 .SH "Post Transfer Information"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1289 See \fIcurl_easy_getinfo(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1290 .SH "The multi Interface"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1291 The easy interface as described in detail in this document is a synchronous
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1292 interface that transfers one file at a time and doesn't return until it is
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1293 done.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1294
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1295 The multi interface, on the other hand, allows your program to transfer
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1296 multiple files in both directions at the same time, without forcing you to use
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1297 multiple threads. The name might make it seem that the multi interface is for
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1298 multi-threaded programs, but the truth is almost the reverse. The multi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1299 interface allows a single-threaded application to perform the same kinds of
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1300 multiple, simultaneous transfers that multi-threaded programs can perform. It
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1301 allows many of the benefits of multi-threaded transfers without the complexity
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1302 of managing and synchronizing many threads.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1303
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1304 To complicate matters somewhat more, there are even two versions of the multi
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1305 interface. The event based one, also called multi_socket and the "normal one"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1306 designed for using with select(). See the libcurl-multi.3 man page for details
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1307 on the multi_socket event based API, this description here is for the select()
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1308 oriented one.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1309
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1310 To use this interface, you are better off if you first understand the basics
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1311 of how to use the easy interface. The multi interface is simply a way to make
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1312 multiple transfers at the same time by adding up multiple easy handles into
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1313 a "multi stack".
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1314
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1315 You create the easy handles you want, one for each concurrent transfer, and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1316 you set all the options just like you learned above, and then you create a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1317 multi handle with \fIcurl_multi_init(3)\fP and add all those easy handles to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1318 that multi handle with \fIcurl_multi_add_handle(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1319
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1320 When you've added the handles you have for the moment (you can still add new
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1321 ones at any time), you start the transfers by calling
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1322 \fIcurl_multi_perform(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1323
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1324 \fIcurl_multi_perform(3)\fP is asynchronous. It will only perform what can be
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1325 done now and then return back control to your program. It is designed to never
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1326 block. You need to keep calling the function until all transfers are
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1327 completed.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1328
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1329 The best usage of this interface is when you do a select() on all possible
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1330 file descriptors or sockets to know when to call libcurl again. This also
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1331 makes it easy for you to wait and respond to actions on your own application's
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1332 sockets/handles. You figure out what to select() for by using
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1333 \fIcurl_multi_fdset(3)\fP, that fills in a set of fd_set variables for you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1334 with the particular file descriptors libcurl uses for the moment.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1335
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1336 When you then call select(), it'll return when one of the file handles signal
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1337 action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1338 what it wants to do. Take note that libcurl does also feature some time-out
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1339 code so we advise you to never use very long timeouts on select() before you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1340 call \fIcurl_multi_perform(3)\fP again. \fIcurl_multi_timeout(3)\fP is
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1341 provided to help you get a suitable timeout period.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1342
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1343 Another precaution you should use: always call \fIcurl_multi_fdset(3)\fP
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1344 immediately before the select() call since the current set of file descriptors
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1345 may change in any curl function invoke.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1346
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1347 If you want to stop the transfer of one of the easy handles in the stack, you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1348 can use \fIcurl_multi_remove_handle(3)\fP to remove individual easy
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1349 handles. Remember that easy handles should be \fIcurl_easy_cleanup(3)\fPed.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1350
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1351 When a transfer within the multi stack has finished, the counter of running
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1352 transfers (as filled in by \fIcurl_multi_perform(3)\fP) will decrease. When
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1353 the number reaches zero, all transfers are done.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1354
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1355 \fIcurl_multi_info_read(3)\fP can be used to get information about completed
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1356 transfers. It then returns the CURLcode for each easy transfer, to allow you
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1357 to figure out success on each individual transfer.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1358
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1359 .SH "SSL, Certificates and Other Tricks"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1360
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1361 [ seeding, passwords, keys, certificates, ENGINE, ca certs ]
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1362
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1363 .SH "Sharing Data Between Easy Handles"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1364 You can share some data between easy handles when the easy interface is used,
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1365 and some data is share automatically when you use the multi interface.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1366
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1367 When you add easy handles to a multi handle, these easy handles will
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1368 automatically share a lot of the data that otherwise would be kept on a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1369 per-easy handle basis when the easy interface is used.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1370
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1371 The DNS cache is shared between handles within a multi handle, making
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1372 subsequent name resolving faster, and the connection pool that is kept to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1373 better allow persistent connections and connection re-use is also shared. If
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1374 you're using the easy interface, you can still share these between specific
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1375 easy handles by using the share interface, see \fIlibcurl-share(3)\fP.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1376
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1377 Some things are never shared automatically, not within multi handles, like for
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1378 example cookies so the only way to share that is with the share interface.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1379 .SH "Footnotes"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1380
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1381 .IP "[1]"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1382 libcurl 7.10.3 and later have the ability to switch over to chunked
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1383 Transfer-Encoding in cases where HTTP uploads are done with data of an unknown
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1384 size.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1385 .IP "[2]"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1386 This happens on Windows machines when libcurl is built and used as a
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1387 DLL. However, you can still do this on Windows if you link with a static
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1388 library.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1389 .IP "[3]"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1390 The curl-config tool is generated at build-time (on Unix-like systems) and
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1391 should be installed with the 'make install' or similar instruction that
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1392 installs the library, header files, man pages etc.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1393 .IP "[4]"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1394 This behavior was different in versions before 7.17.0, where strings had to
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1395 remain valid past the end of the \fIcurl_easy_setopt(3)\fP call.
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1396 .SH "SEE ALSO"
b50eed0cc0ef ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	1397 .BR libcurl-errors "(3), " libcurl-multi "(3), " libcurl-easy "(3) "

Mercurial > hgrepos > Python2 > PyMuPDF

annotate mupdf-source/thirdparty/curl/docs/libcurl/libcurl-tutorial.3 @ 2:b50eed0cc0ef upstream