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