summaryrefslogtreecommitdiffabout
Unidiff
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--include/opkele/consumer.h5
1 files changed, 5 insertions, 0 deletions
diff --git a/include/opkele/consumer.h b/include/opkele/consumer.h
index 3c0ed5f..9932315 100644
--- a/include/opkele/consumer.h
+++ b/include/opkele/consumer.h
@@ -1,137 +1,142 @@
1#ifndef __OPKELE_CONSUMER_H 1#ifndef __OPKELE_CONSUMER_H
2#define __OPKELE_CONSUMER_H 2#define __OPKELE_CONSUMER_H
3 3
4#include <opkele/types.h> 4#include <opkele/types.h>
5 5
6/** 6/**
7 * @file 7 * @file
8 * @brief OpenID consumer-side functionality 8 * @brief OpenID consumer-side functionality
9 */ 9 */
10 10
11/** 11/**
12 * @brief the main opkele namespace 12 * @brief the main opkele namespace
13 */ 13 */
14namespace opkele { 14namespace opkele {
15 15
16 /** 16 /**
17 * implementation of basic consumer functionality 17 * implementation of basic consumer functionality
18 */ 18 */
19 class consumer_t { 19 class consumer_t {
20 public: 20 public:
21 21
22 /** 22 /**
23 * store association. The function should be overridden in the real 23 * store association. The function should be overridden in the real
24 * implementation to provide persistent associations store. 24 * implementation to provide persistent associations store.
25 * @param server the OpenID server 25 * @param server the OpenID server
26 * @param handle association handle 26 * @param handle association handle
27 * @param secret the secret associated with the server and handle 27 * @param secret the secret associated with the server and handle
28 * @param expires_in the number of seconds until the handle is expired 28 * @param expires_in the number of seconds until the handle is expired
29 * @return the auto_ptr<> for the newly allocated association_t object 29 * @return the auto_ptr<> for the newly allocated association_t object
30 */ 30 */
31 virtual assoc_t store_assoc(const string& server,const string& handle,const secret_t& secret,int expires_in) = 0; 31 virtual assoc_t store_assoc(const string& server,const string& handle,const secret_t& secret,int expires_in) = 0;
32 /** 32 /**
33 * retrieve stored association. The function should be overridden 33 * retrieve stored association. The function should be overridden
34 * in the real implementation to provide persistent assocations 34 * in the real implementation to provide persistent assocations
35 * store. 35 * store.
36 * @param server the OpenID server 36 * @param server the OpenID server
37 * @param handle association handle 37 * @param handle association handle
38 * @return the autho_ptr<> for the newly allocated association_t object 38 * @return the autho_ptr<> for the newly allocated association_t object
39 * @throw failed_lookup in case of error 39 * @throw failed_lookup in case of error
40 */ 40 */
41 virtual assoc_t retrieve_assoc(const string& server,const string& handle) = 0; 41 virtual assoc_t retrieve_assoc(const string& server,const string& handle) = 0;
42 /** 42 /**
43 * invalidate stored association. The function should be overridden 43 * invalidate stored association. The function should be overridden
44 * in the real implementation of the consumer. 44 * in the real implementation of the consumer.
45 * @param server the OpenID server 45 * @param server the OpenID server
46 * @param handle association handle 46 * @param handle association handle
47 */ 47 */
48 virtual void invalidate_assoc(const string& server,const string& handle) = 0; 48 virtual void invalidate_assoc(const string& server,const string& handle) = 0;
49 /** 49 /**
50 * retrieve any unexpired association for the server. If the 50 * retrieve any unexpired association for the server. If the
51 * function is not overridden in the real implementation, the new 51 * function is not overridden in the real implementation, the new
52 * association will be established for each request. 52 * association will be established for each request.
53 * @param server the OpenID server 53 * @param server the OpenID server
54 * @return the auto_ptr<> for the newly allocated association_t object 54 * @return the auto_ptr<> for the newly allocated association_t object
55 * @throw failed_lookup in case of absence of the handle 55 * @throw failed_lookup in case of absence of the handle
56 */ 56 */
57 virtual assoc_t find_assoc(const string& server); 57 virtual assoc_t find_assoc(const string& server);
58 58
59 /** 59 /**
60 * retrieve the metainformation contained in link tags from the 60 * retrieve the metainformation contained in link tags from the
61 * page pointed by url. the function may implement caching of the 61 * page pointed by url. the function may implement caching of the
62 * information. 62 * information.
63 * @param url url to harvest for link tags 63 * @param url url to harvest for link tags
64 * @param server reference to the string object where to put 64 * @param server reference to the string object where to put
65 * openid.server value 65 * openid.server value
66 * @param delegate reference to the string object where to put the 66 * @param delegate reference to the string object where to put the
67 * openid.delegate value (if any) 67 * openid.delegate value (if any)
68 */ 68 */
69 virtual void retrieve_links(const string& url,string& server,string& delegate); 69 virtual void retrieve_links(const string& url,string& server,string& delegate);
70 70
71 /** 71 /**
72 * perform the associate request to OpenID server. 72 * perform the associate request to OpenID server.
73 * @param server the OpenID server 73 * @param server the OpenID server
74 * @return the auto_ptr<> for the newly allocated association_t 74 * @return the auto_ptr<> for the newly allocated association_t
75 * object, representing established association 75 * object, representing established association
76 * @throw exception in case of error 76 * @throw exception in case of error
77 */ 77 */
78 assoc_t associate(const string& server); 78 assoc_t associate(const string& server);
79 /** 79 /**
80 * prepare the parameters for the checkid_immediate 80 * prepare the parameters for the checkid_immediate
81 * request. 81 * request.
82 * @param identity the identity to verify 82 * @param identity the identity to verify
83 * @param return_to the return_to url to pass with the request 83 * @param return_to the return_to url to pass with the request
84 * @param trust_root the trust root to advertise with the request 84 * @param trust_root the trust root to advertise with the request
85 * @return the location string 85 * @return the location string
86 * @throw exception in case of error 86 * @throw exception in case of error
87 */ 87 */
88 string checkid_immediate(const string& identity,const string& return_to,const string& trust_root=""); 88 string checkid_immediate(const string& identity,const string& return_to,const string& trust_root="");
89 /** 89 /**
90 * prepare the parameters for the checkid_setup 90 * prepare the parameters for the checkid_setup
91 * request. 91 * request.
92 * @param identity the identity to verify 92 * @param identity the identity to verify
93 * @param return_to the return_to url to pass with the request 93 * @param return_to the return_to url to pass with the request
94 * @param trust_root the trust root to advertise with the request 94 * @param trust_root the trust root to advertise with the request
95 * @return the location string 95 * @return the location string
96 * @throw exception in case of error 96 * @throw exception in case of error
97 */ 97 */
98 string checkid_setup(const string& identity,const string& return_to,const string& trust_root=""); 98 string checkid_setup(const string& identity,const string& return_to,const string& trust_root="");
99 /** 99 /**
100 * the actual implementation behind checkid_immediate() and 100 * the actual implementation behind checkid_immediate() and
101 * checkid_setup() functions. 101 * checkid_setup() functions.
102 * @param mode checkid_* mode - either mode_checkid_immediate or mode_checkid_setup 102 * @param mode checkid_* mode - either mode_checkid_immediate or mode_checkid_setup
103 * @param identity the identity to verify 103 * @param identity the identity to verify
104 * @param return_to the return_to url to pass with the request 104 * @param return_to the return_to url to pass with the request
105 * @param trust_root the trust root to advertise with the request 105 * @param trust_root the trust root to advertise with the request
106 * @return the location string 106 * @return the location string
107 * @throw exception in case of error 107 * @throw exception in case of error
108 */ 108 */
109 string checkid_(mode_t mode,const string& identity,const string& return_to,const string& trust_root=""); 109 string checkid_(mode_t mode,const string& identity,const string& return_to,const string& trust_root="");
110 /** 110 /**
111 * verify the id_res response 111 * verify the id_res response
112 * @param pin the response parameters 112 * @param pin the response parameters
113 * @param identity the identity being checked (if not specified, extracted 113 * @param identity the identity being checked (if not specified, extracted
114 * from the openid.identity parameter 114 * from the openid.identity parameter
115 * @throw id_res_mismatch in case of signature 115 * @throw id_res_mismatch in case of signature
116 * mismatch 116 * mismatch
117 * @throw id_res_setup in case of 117 * @throw id_res_setup in case of
118 * openid.user_setup_url failure (supposedly 118 * openid.user_setup_url failure (supposedly
119 * checkid_immediate only) 119 * checkid_immediate only)
120 * @throw id_res_failed in case of failure 120 * @throw id_res_failed in case of failure
121 * @throw exception in case of other failures 121 * @throw exception in case of other failures
122 */ 122 */
123 void id_res(const params_t& pin,const string& identity=""); 123 void id_res(const params_t& pin,const string& identity="");
124 /** 124 /**
125 * perform a check_authentication request. 125 * perform a check_authentication request.
126 * @param server the OpenID server 126 * @param server the OpenID server
127 * @param p request parameters 127 * @param p request parameters
128 */ 128 */
129 void check_authentication(const string& server,const params_t& p); 129 void check_authentication(const string& server,const params_t& p);
130 130
131 /**
132 * make URL canonical, by adding http:// and trailing slash, if needed.
133 * @param url
134 * @return canonicalized url
135 */
131 static string canonicalize(const string& url); 136 static string canonicalize(const string& url);
132 137
133 }; 138 };
134 139
135} 140}
136 141
137#endif /* __OPKELE_CONSUMER_H */ 142#endif /* __OPKELE_CONSUMER_H */