Index of /xtras/curl_xtra

 Name                    Last modified      Size  Description
 Parent Directory                             -   
 class/                  2016-05-13 18:23    -   
 demos/                  2020-10-03 11:01    -   
 mac/                    2017-12-22 20:27    -   
 manager/                2019-03-18 23:59    -   
 win/                    2018-01-10 18:07    -   
 readme.txt              2018-01-10 18:17  4.6K  

-- xtra Curl
-- v0.16 (c) 2017 Valentin Schmidt

Interface:
==========

new object me, *autoDetachFlag -- default=0

-- INSTANCE FUNCTIONS
exec object me, *returnMode  -- 0=return error code (=default), 1=return data
execAsync object me, symbol cbHandler, *cbTarget, returnMode -- 0=return error code(=default), 1=return data, 2=return chunks immediately
getInfo object me, integer type
setForm object me, object form
setOption object me, integer option, *
setDestinationFile object me, *file
execSocket object me, integer port -- windows only
setSourceFile object me, string file, *
setHeaderCallback object me, symbol cbHandler, *cbTarget
setProgressCallback object me, symbol cbHandler, *cbTarget
setSourceDataCallback object me, *cbHandler, cbTarget
close object me -- after calling this, don't use any instance function anymore!

-- STATIC FUNCTIONS
*curl_error integer CURLcode
*curl_escape string str
*curl_hfs2posix string hfsPath -- mac only


Description
===========

libcurl is a free and easy-to-use client-side URL transfer library, supporting
DICT, FILE, FTP, FTPS, Gopher, HTTP, HTTPS, IMAP, IMAPS, POP3,
POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, Telnet and TFTP. libcurl supports SSL
certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload,
proxies, cookies, user+password authentication (Basic, Digest, NTLM, Negotiate,
Kerberos), file transfer resume, http proxy tunneling and more!

For details of the libcurl C API check out:
https://curl.haxx.se/libcurl/c/

Curl xtra ports libcurl to Director, usage is basically the same as for other
libcurl ports. But it implements some Director-specific high-level functions
that wrap stuff that would be hard to implement in the direct low-lewel C-way.
Those Director-specific high-level functions are:
- execAsync
- execSocket -- windows only
- setForm object me, object form
- setSourceFile object me, string file, *
- setHeaderCallback object me, symbol cbHandler, *cbTarget
- setProgressCallback object me, symbol cbHandler, *cbTarget
- setSourceDataCallback object me, *cbHandler, cbTarget


Note about the Windows version
==============================

Curl xtra for Windows depends on "msvcr100.dll", so put the enclosed DLL file next to your
<projector>.exe when distributing a projector (and also next to your Director.exe if
your development system doesn't have the "Microsoft Visual C++ 2010 Redistributable
Package (x86)" installed).


About HTTPS support
===================

When using HTTPS you have 2 options:

a) If you don't care about verification of peers, just add the following to your code:

    -- ch = curl xtra instance
    CURLOPT_SSL_VERIFYPEER = 64
    ch.setOption(CURLOPT_SSL_VERIFYPEER, 0)

b) If you do care, instead put the enclosed "ca-certificates.crt" file next to your movie (or
   anywhere else), and use to following code to tell curl xtra where to find it:

    -- ch = curl xtra instance
    CURLOPT_CAINFO = 10065
    ch.setOption(CURLOPT_CAINFO, _movie.path & "ca-certificates.crt")


New feature in v0.15:
=====================

If you pass TRUE to the constructor 'new', all asynchronous callbacks for
'setHeaderCallback', 'setProgressCallback' and 'execAsync' (ie the final result)
are automatically "detached" from the original callback thread. This is
implemented like this:

- a temporary parent script is created (maybe for a millisecond or so)
- a 1 millisecond timeout object is created, with an instance of this parent
  script as target
- the temporary parent script is deleted

NOTE: function 'setSourceDataCallback' - which allows to "feed" curl with dynamically
created data via Lingo - is not "auto-detached" yet, so still be careful with this one.

Background info:

It's a fact of life that in Director all Lingo functions (callbacks) called from
a scripting xtra "fail silently" if some scripting error was triggered in the
callback execution stack, i.e. either inside the code of the callback function
itself or any other function that was called from it. This "silent failure" also
means that such errors can't be debugged in Director.

A way to solve this problem is to always "detach" such xtra callbacks, by using
1-millisecond-single-shot-timeouts which then call the actual callback
functions. That way, the actual callback code is then fully debuggable.

The best/most economical way to implement this is using a single/static Lingo
wrapper script, which automatically "detaches" all flavors of curl xtra's
callback functions.

But now you can instead also use this new 'autoDetachFlag', which achieves the
same, albeit with some small memory/processing time overhead.