====== accessCount() ======

The ''accessCount()'' function is used to limit incorrect entries in a code query. Without a parameter, the function returns the number of previous attempts. If the parameter ''ban time'' is specified, the counter is incremented by one.

''int **accessCount**([int //ban time//])''

  * //ban time// -- If a ban time (in seconds) is entered, the function creates a baning entry or increments it by one. After the ban time has elapsed (calculated from the first call of the function), the failed attempts are reset to 0.

**Note:** When querying [[:en:survey:serials|participation codes]], SoSci Survey automatically counts failed attempts. The ''accessCount()'' function is only required if the query and check of codes is implemented manually.

**Note:** The function checks the multiple entry using both the current interview and the IP address. The ban entries are stored separately from the data collected, so that usually no personal data is processed within the meaning of the GDPR. However, the ban can be circumvented by an Internet proxy that accesses the questionnaire via different IP addresses.

**Note:** The function also creates an entry in the external blacklist, which may be used by the server to completely block an IP address for a longer period of time (server configuration: [[:en:server:security:fail2ban]]).


===== Application example =====

This application example requires the following prerequisites:

  * Valid participation codes have been generated.
  * Entries were created for the participation codes in the [[:en:create:databank]], the key is made up of “Code-” and the participation code, e.g. “Code-abcde12345”.
  * The participation code is requested on page 1 with a text input question, the variable for the input field has the identifier “TC01_01”.
  * In the event that an incorrect code was entered, an error message was created as text TC02; in the event that too many invalid entries were attempted, a second text TC03 exists.

On page 1 of the questionnaire, ''accessCount()'' is first used to check whether a maximum of 5 failed attempts have been made. Depending on this, the input field or an error message is displayed. In the latter case, there is no “Next” button.

<code php>
if (accessCount() > 5) {
    show('TC03');  // error message " too many attempts"
    buttonHide();  // hide buttons
    pageStop();
} else {
    show('TC01');  // Questions about the participation code
}
</code>

On the second page, the code is counterchecked the content database. Depending on the check, either a failed attempt is counted or an error message is displayed and the previous page is repeated.

<code php>
$code = strtolower(value('TC03'));  // convert input to lower case
$key = 'Code-'.$code;  // add prefix for the database entry
$data = dbGet($key);   // reading the database entry

// If no database entry is found
if (!$data) {
  accessCount(600);  // Create ban entry for 10 minutes and increment by one
  repeatPage('TC02');  // Show error message and repeat page
}
</code>