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