1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_HSTSREADFUNCTION
5Section: 3
6Source: libcurl
7Protocol:
8  - HTTP
9See-also:
10  - CURLOPT_HSTS (3)
11  - CURLOPT_HSTSREADDATA (3)
12  - CURLOPT_HSTSWRITEFUNCTION (3)
13  - CURLOPT_HSTS_CTRL (3)
14---
15
16# NAME
17
18CURLOPT_HSTSREADFUNCTION - read callback for HSTS hosts
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24
25struct curl_hstsentry {
26  char *name;
27  size_t namelen;
28  unsigned int includeSubDomains:1;
29  char expire[18]; /* YYYYMMDD HH:MM:SS [null-terminated] */
30};
31
32CURLSTScode hstsread(CURL *easy, struct curl_hstsentry *sts, void *clientp);
33
34CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADFUNCTION, hstsread);
35~~~
36
37# DESCRIPTION
38
39Pass a pointer to your callback function, as the prototype shows above.
40
41This callback function gets called by libcurl repeatedly when it populates the
42in-memory HSTS cache.
43
44Set the *clientp* argument with the CURLOPT_HSTSREADDATA(3) option
45or it is NULL.
46
47When this callback is invoked, the *sts* pointer points to a populated
48struct: Copy the hostname to *name* (no longer than *namelen*
49bytes). Make it null-terminated. Set *includeSubDomains* to TRUE or
50FALSE. Set *expire* to a date stamp or a zero length string for *forever*
51(wrong date stamp format might cause the name to not get accepted)
52
53The callback should return *CURLSTS_OK* if it returns a name and is
54prepared to be called again (for another host) or *CURLSTS_DONE* if it has
55no entry to return. It can also return *CURLSTS_FAIL* to signal
56error. Returning *CURLSTS_FAIL* stops the transfer from being performed
57and make *CURLE_ABORTED_BY_CALLBACK* get returned.
58
59This option does not enable HSTS, you need to use CURLOPT_HSTS_CTRL(3) to
60do that.
61
62# DEFAULT
63
64NULL - no callback.
65
66# EXAMPLE
67
68~~~c
69struct priv {
70  void *custom;
71};
72
73static CURLSTScode hsts_cb(CURL *easy, struct curl_hstsentry *sts,
74                           void *clientp)
75{
76  /* populate the struct as documented */
77  return CURLSTS_OK;
78}
79
80int main(void)
81{
82  CURL *curl = curl_easy_init();
83  if(curl) {
84    struct priv my_stuff;
85    CURLcode res;
86
87    /* set HSTS read callback */
88    curl_easy_setopt(curl, CURLOPT_HSTSREADFUNCTION, hsts_cb);
89
90    /* pass in suitable argument to the callback */
91    curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &my_stuff);
92
93    res = curl_easy_perform(curl);
94  }
95}
96~~~
97
98# AVAILABILITY
99
100Added in 7.74.0
101
102# RETURN VALUE
103
104This returns CURLE_OK.
105