adding content for .htaccess; important because of include
[cacert-codedocs.git] / source / DIR-includes.rst
1 .. index:: includes
2 .. index:: PHP
3
4 ==========================
5 Directory :file:`includes`
6 ==========================
7
8 .. sourcefile:: includes/.cvsignore
9
10 :file:`.cvsignore` includes the parameters for CVS, which files to ignore by
11 versioning
12
13 .. note:: CVS is long dead, is this still used?
14
15 .. sourcefile:: includes/.gitignore
16
17 :file:`.gitignore` contains file patterns to be ignored by Git.
18
19 .. sourcefile:: includes/about_menu.php
20 :links:
21 http://blog.cacert.org/
22 http://wiki.CAcert.org/
23 www/policy/
24 //wiki.cacert.org/FAQ/Privileges
25 www/index.php?id=47
26 www/logos.php
27 www/stats.php
28 http://blog.CAcert.org/feed/
29 www/index.php?id=7
30 //wiki.cacert.org/Board
31 https://lists.cacert.org/wws
32 www/src-lic.php
33
34 :file:`about_menu.php` is a part (<div>) of a PHP-Page, containing most of
35 the CAcert-related links.
36
37 .. sourcefile:: includes/account_stuff.php
38
39 :file:`includes/account_stuff.php` provides two procedures to be used for building the output of some HTML-pages.
40
41 .. php:function:: showheader($title = "CAcert.org", $title2 = "")
42
43 This function renders a page depending on the calling file. It is expected that only files
44
45 www/wot.php (web-of-trust),
46
47 www/gpg.php (gpg-key),
48
49 www/disputes.php (disputes) and
50
51 www/advertising.php (advertising)
52
53 are using this function.
54
55 :param string $title:
56 :param string $title2:
57 :global: * *(int)* - $id:
58 :global: * *(string)* - $PHP_SELF:
59
60 .. php:function:: showfooter()
61
62 This function renders a page-footer.
63
64
65 .. sourcefile:: includes/account.php
66 :uses:
67 includes/loggedin.php
68 includes/lib/l10n.php
69 includes/lib/check_weak_key.php
70 includes/notary.inc.php
71
72 .. php:function:: buildSubject(array $domains, $include_xmpp_addr = true)
73
74 Build a subject string as needed by the signer
75
76 :param array(string) $domains: First domain is used as CN and repeated in subjectAltName. Duplicates should already been removed
77 :param bool $include_xmpp_addr: [default: true] Whether to include the XmppAddr in the subjectAltName. This is needed if the Jabber server is jabber.example.com but a Jabber ID on that server would be alice@example.com
78 :return: * (string) - subject string as needed by the signer
79
80 .. php:function:: buildSubjectFromSession()
81
82 Builds the subject string from the session variables $_SESSION['_config']['rows'] and $_SESSION['_config']['altrows']
83
84 :return: * (string) -
85
86 .. sourcefile:: includes/general_stuff.php
87
88 .. sourcefile:: includes/general.php
89
90 .. sourcefile:: includes/keygen.php
91
92 .. sourcefile:: includes/loggedin.php
93
94 .. sourcefile:: includes/mysql.php
95
96 :file:`includes/mysql.php` is not contained in the :cacertgit:`cacert-devel`
97 repository but is used by several other files. The file is copied from
98 :sourcefile:`includes/mysql.php.sample` and defines the database connection
99 information.
100
101 This file is parsed directly by :sourcefile:`CommModule/client.pl`
102 format changes might break the CommModule code.
103
104 .. sourcefile:: includes/mysql.php.sample
105
106 :file:`mysql.php.sample` is a template for the database connection handling
107 code that is meant to be copied to :file:`mysql.php`.
108
109 The template defines the MySQL connection as a session variable `mconn` and
110 tries to connect to that database. It also defines the session variables
111 `normalhostname`, `securehostname` and `tverify`.
112
113 The template defines a function :php:func:`sendmail` for sending mails.
114
115 .. php:function:: sendmail($to, $subject, $message, $from, $replyto="", \
116 $toname="", $fromname="", $errorsto="returns@cacert.org", \
117 $use_utf8=true)
118
119 Send an email. The function reimplements functionality that is readily
120 available in PHP. The function does not properly escape headers and
121 sends raw SMTP commands.
122
123 :param string $to: recipient email address
124 :param string $subject: subject
125 :param string $message: email body
126 :param string $from: from email address
127 :param string $replyto: reply-to email address
128 :param string $fromname: unused in the code
129 :param string $toname: unused in the code
130 :param string $errorsto: email address used for Sender and Errors-To
131 headers
132 :param bool $use_utf8: decides whether the Content-Type header uses
133 a charset parameter of utf-8 or iso-8859-1
134
135 Configuration and actual code are mixed. It would be better to have a
136 separate file that just includes configuration.
137
138 .. sourcefile:: includes/notary.inc.php
139
140 :file:`includes/notary.inc.php` provides a set of funktions; here listed in the given order:
141
142 .. php:function:: query_init ($query)
143
144 Accesss the database to execute the passed query.
145
146 :param string $query: query to execute
147 :return: * (resource) - result of the passed query.
148
149 .. php:function:: query_getnextrow ($res)
150
151 Return the next row of a previous received result of a database query.
152
153 :param resource $res: Result of a previous database query.
154 :return: * (object) - next row in the passed resource
155
156 .. php:function:: query_get_number_of_rows ($resultset)
157
158 Return the number of rows of the passed $resource which has to be the result of a previous database query, select-statement
159
160 :param resource $resultset: Result of a previous database query
161 :return: * (int) - number of rows in the passed resource
162
163 .. php:function:: get_number_of_assurances ($userid)
164
165 Returns the number of assurances the user with the passed userid has given.
166
167 :param int $userid: userid of be controled
168 :return: * (int) - number of given assurances
169
170 .. php:function:: get_number_of_ttpassurances ($userid)
171
172 Returns the number of TTP-assurances the user with the passed userid has received.
173
174 :param int $userid: userid of be controled
175 :return: * (int) - number of received TTP-assurances
176
177 .. php:function:: get_number_of_assurees ($userid)
178
179 Returns the number of assurances the user with the passed userid has received.
180
181 :param int $userid: userid of be controled
182 :return: * (int) - number of received assurances
183
184 .. php:function:: get_top_assurer_position ($no_of_assurances)
185
186 Returns the ranking of an assurer with the passed number of given assurances.
187
188 :param int $no_of_assurances: number of assurances
189 :return: * (int) - position at the list of top assurers
190
191 .. php:function:: get_top_assuree_position ($no_of_assurees)
192
193 Returns the ranking of an assuree with the passed number of received assurances.
194
195 :param int $no_of_assurances: number of assurances
196 :return: * (int) - position at the list of top assurees
197
198 .. php:function:: get_given_assurances($userid, $log=0)
199
200 Get the list of assurances given by the user
201
202 :param int $userid: id of the assurer
203 :param int $log: if set to 1 also includes deleted assurances
204 :return: * (resource) - a MySQL result set
205
206 .. php:function:: get_received_assurances($userid, $log=0)
207
208 Get the list of assurances received by the user
209
210 :param int $userid: id of the assuree
211 :param int $log: if set to 1 also includes deleted assurances
212 :return: * (resource) - a MySQL result set
213
214 .. php:function:: get_given_assurances_summary ($userid)
215
216 Get the count of given assurances of the user with the passed userid grouped by points, awarded, method
217
218 :param int $userid: id of the assurer
219 :return: * (resource) - list of number of given assurances grouped by points, awarded, method
220
221 .. php:function:: get_received_assurances_summary ($userid)
222
223 Get the count of received assurances of the user with the passed userid grouped by points, awarded, method
224
225 :param int $userid: id of the assuree
226 :return: * (resource) - list of number of received assurances grouped by points, awarded, method
227
228 .. php:function:: get_user ($userid)
229
230 Get data of user with the passed userid.
231
232 :param int $userid: id of the user
233 :return: * (resource) - data frum table users belonging to passed userid.
234
235 .. php:function:: get_cats_state ($userid)
236
237 Get the number of passed CATS for the given userid.
238
239 :param int $userid: id of a user
240 :return: * (int) - number of passed CATS
241
242 .. php:function:: calc_awarded($row)
243
244 Calculate awarded points (corrects some issues like out of range points or points that were issued by means that have been deprecated)
245
246 :param array $row: associative array containing the data from the `notary` table
247 :return: * (int) - the awarded points for this assurance
248
249 .. php:function:: calc_experience(&$row, &$sum_points, &$sum_experience)
250
251 Calculate the experience points from a given Assurance.
252
253 :param array $row: [inout] associative array containing the data from the `notary` table, the keys 'experience' and 'calc_awarded' will be added
254 :param int $sum_points: [inout] the sum of already counted assurance points the assurer issued
255 :param int $sum_experience: [inout] the sum of already counted experience points that were awarded to the assurer
256
257 .. php:function:: calc_assurances(&$row, &$sum_points, &$sum_experience)
258
259 Calculate the points received from a received Assurance.
260
261 :param array $row: [inout] associative array containing the data from the `notary` table, the keys 'experience' and 'calc_awarded' will be added
262 :param int $sum_points: [inout] the sum of already counted assurance points the assuree received
263 :param int $sum_experience: [inout] the sum of already counted experience points that were awarded to the assurer
264
265 .. php:function:: show_user_link($user)
266
267 Generate a link to the support engineer page for the user with the name of the user as link text
268
269 :param array $user: associative array containing the data from the `user` table
270 :return: * (string) - name of the user with the passed userid or System or deleted
271
272 .. php:function:: show_email_link($user)
273
274 Generate a link to the support engineer page for the user with the email address as link text
275
276 :param array $user: associative array containing the data from the `user` table
277 :return: * (string) - email-address
278
279 .. php:function:: get_assurer_ranking($userid,&$num_of_assurances,&$rank_of_assurer)
280
281 Getting the number of given assurances and the rank of the user with the passed userid.
282
283 :param int $userid: id of an user
284 :param int $num_of_assurances: [inout] number of given assurances
285 :param int $rank_of_assurer: [inout] rank in assurer-list
286
287 .. php:function:: get_assuree_ranking($userid,&$num_of_assurees,&$rank_of_assuree)
288
289 Getting the number of received assurances and the rank of the user with the passed userid.
290
291 :param int $userid: id of an user
292 :param int $num_of_assurees: [inout] number of received assurances
293 :param int $rank_of_assuree: [inout] rank in assuree-list
294
295 .. php:function:: output_ranking($userid)
296
297 Generating HTML-code for showing the assurer/assuree data
298
299 :param int $userid: userid to build the page format
300
301 .. php:function:: output_assurances_header($title, $support, $log)
302
303 Render header for the assurance table (same for given/received)
304
305 :param string $title: The title for the table
306 :param int $support: set to 1 if the output is for the support interface
307 :param int $log: if set to 1 also includes deleted assurances
308
309 .. php:function:: output_assurances_footer($points_txt,$sumpoints,$experience_txt,$sumexperience,$support,$log)
310
311 Render footer for the assurance table (same for given/received)
312
313 :param string $points_txt: Description for sum of assurance points
314 :param int $sumpoints: sum of assurance points
315 :param string $experience_txt: Description for sum of experience points
316 :param int $sumexperience: sum of experience points
317 :param int $support: set to 1 if the output is for the support interface
318 :param int $log: if set to 1 also includes deleted assurances
319
320 .. php:function:: output_assurances_row($assurance,$userid,$other_user,$support,$ticketno,$log)
321
322 Render an assurance for a view
323
324 :param array $assurance: associative array containing the data from the `notary` table
325 :param int $userid: Id of the user whichs given/received assurances are displayed
326 :param array $other_user: associative array containing the other users data from the `users` table
327 :param int $support: set to 1 if the output is for the support interface
328 :param string $ticketno: ticket number currently set in the support interface
329 :param int $log: if set to 1 also includes deleted assurances
330
331 .. php:function:: output_summary_header()
332
333 Render the header for the summary.
334
335 .. php:function:: output_summary_footer()
336
337 Render the footer for the summary.
338
339 .. php:function:: output_summary_row($title,$points,$points_countable,$remark)
340
341 Render a row of the summary of points
342
343 :param string $title: The description of the row
344 :param inf $points:
345 :param int $points_countable:
346 :param string $remark:
347
348 .. todo:: check points and points_countable
349
350 .. php:function:: output_given_assurances_content($userid,&$sum_points,&$sum_experience,$support,$ticketno,$log)
351
352 Helper function to render assurances given by the user
353
354 :param int $userid: id of a user
355 :param int &$sum_points: [out] sum of given points
356 :param int &$sum_experience: [out] sum of experience points gained
357 :param int $support: set to 1 if the output is for the support interface
358 :param string $ticketno: the ticket number set in the support interface
359 :param int $log: if set to 1 also includes deleted assurances
360
361 .. php:function:: output_received_assurances_content($userid,&$sum_points,&$sum_experience,$support,$ticketno,$log)
362
363 Helper function to render assurances received by the user
364
365 :param int $userid: id of a user
366 :param int& $sum_points: [out] sum of received points
367 :param int& $sum_experience: [out] sum of experience points the assurers gained
368 :param int $support: set to 1 if the output is for the support interface
369 :param string $ticketno: the ticket number set in the support interface
370 :param int $log: if set to 1 also includes deleted assurances
371
372 .. php:function:: check_date_limit ($userid,$age)
373
374 Checks if the user with the passed userid has reached a given age.
375
376 :param int $userid: id of a user
377 :param int $age: the age to be checked against
378 :return: * (int) - 1: if the given age is reached; 0 else
379
380 .. php:function:: max_points($userid)
381
382 Determin, how many points the user can issue at most.
383
384 :param int $userid: id of a user
385 :return: * (int) - max to issue points
386
387 .. php:function:: output_summary_content($userid,$display_output)
388
389 Calculate points and render them for output.
390
391 :param int $userid: id of a user
392 :param int $display_output: flag if to display (1) or not (0)
393 :retur: * (int) - max to issue points
394
395 .. php:function:: output_given_assurances($userid, $support=0, $ticketno='', $log=0)
396
397 Render assurances given by the user
398
399 :param int $userid:
400 :param int $support: set to 1 if the output is for the support interface
401 :param string $ticketno: the ticket number set in the support interface
402 :param int $log: if set to 1 also includes deleted assurances
403
404 .. php:function:: output_received_assurances($userid, $support=0, $ticketno='', $log=0)
405
406 Render assurances received by the user
407
408 :param int $userid:
409 :param int $support: set to 1 if the output is for the support interface
410 :param string $ticketno: the ticket number set in the support interface
411 :param int $log: if set to 1 also includes deleted assurances
412
413 .. php:function:: output_summary($userid)
414
415 Render the page output for a user.
416
417 :param int $userid:
418
419 .. todo:: more documentation from line 833 on
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439 .. sourcefile:: includes/shutdown.php
440
441 .. sourcefile:: includes/sponsorinfo.php
442
443 .. sourcefile:: includes/tverify_stuff.php
444
445
446 .. index:: includes/lib
447 .. index:: PHP
448
449 Directory :file:`includes/lib`
450 ==============================
451
452 .. sourcefile:: includes/lib/account.php
453
454 .. sourcefile:: includes/lib/check_weak_key.php
455
456 .. sourcefile:: includes/lib/general.php
457
458 .. sourcefile:: includes/lib/l10n.php