send_string.h

  1/* Copyright 2021
  2 *
  3 * This program is free software: you can redistribute it and/or modify
  4 * it under the terms of the GNU General Public License as published by
  5 * the Free Software Foundation, either version 2 of the License, or
  6 * (at your option) any later version.
  7 *
  8 * This program is distributed in the hope that it will be useful,
  9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 11 * GNU General Public License for more details.
 12 *
 13 * You should have received a copy of the GNU General Public License
 14 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 15 */
 16
 17/**
 18 * \file
 19 *
 20 * \defgroup send_string Send String API
 21 *
 22 * \brief These functions allow you to create macros by typing out sequences of keystrokes.
 23 * \{
 24 */
 25
 26#include <stdint.h>
 27
 28#include "progmem.h"
 29#include "send_string_keycodes.h"
 30
 31// Look-Up Tables (LUTs) to convert ASCII character to keycode sequence.
 32extern const uint8_t ascii_to_shift_lut[16];
 33extern const uint8_t ascii_to_altgr_lut[16];
 34extern const uint8_t ascii_to_dead_lut[16];
 35extern const uint8_t ascii_to_keycode_lut[128];
 36
 37// clang-format off
 38#define KCLUT_ENTRY(a, b, c, d, e, f, g, h) \
 39    ( ((a) ? 1 : 0) << 0 \
 40    | ((b) ? 1 : 0) << 1 \
 41    | ((c) ? 1 : 0) << 2 \
 42    | ((d) ? 1 : 0) << 3 \
 43    | ((e) ? 1 : 0) << 4 \
 44    | ((f) ? 1 : 0) << 5 \
 45    | ((g) ? 1 : 0) << 6 \
 46    | ((h) ? 1 : 0) << 7 )
 47// clang-format on
 48
 49/**
 50 * \brief Type out a string of ASCII characters.
 51 *
 52 * This function simply calls `send_string_with_delay(string, TAP_CODE_DELAY)`.
 53 *
 54 * Most keycodes from the basic keycode range are also supported by way of a special sequence - see `send_string_keycodes.h`.
 55 *
 56 * \param string The string to type out.
 57 */
 58void send_string(const char *string);
 59
 60/**
 61 * \brief Type out a string of ASCII characters, with a delay between each character.
 62 *
 63 * \param string The string to type out.
 64 * \param interval The amount of time, in milliseconds, to wait before typing the next character. Note this can be set to 0 to ensure no delay, regardless of what TAP_CODE_DELAY is set to.
 65 */
 66void send_string_with_delay(const char *string, uint8_t interval);
 67
 68/**
 69 * \brief Type out an ASCII character.
 70 *
 71 * This function simply calls `send_char_with_delay(string, TAP_CODE_DELAY)`.
 72 *
 73 * \param ascii_code The character to type.
 74 */
 75void send_char(char ascii_code);
 76
 77/**
 78 * \brief Type out an ASCII character, with a delay between any modifiers.
 79 *
 80 * \param ascii_code The character to type.
 81 * \param interval The amount of time, in milliseconds, to wait in between key presses. Note this can be set to 0 to ensure no delay, regardless of what TAP_CODE_DELAY is set to.
 82 */
 83void send_char_with_delay(char ascii_code, uint8_t interval);
 84
 85/**
 86 * \brief Type out an eight digit (unsigned 32-bit) hexadecimal value.
 87 *
 88 * The format is `[0-9a-f]{8}`, eg. `00000000` through `ffffffff`.
 89 *
 90 * \param number The value to type, from 0 to 4,294,967,295.
 91 */
 92void send_dword(uint32_t number);
 93
 94/**
 95 * \brief Type out a four digit (unsigned 16-bit) hexadecimal value.
 96 *
 97 * The format is `[0-9a-f]{4}`, eg. `0000` through `ffff`.
 98 *
 99 * \param number The value to type, from 0 to 65,535.
100 */
101void send_word(uint16_t number);
102
103/**
104 * \brief Type out a two digit (8-bit) hexadecimal value.
105 *
106 * The format is `[0-9a-f]{2}`, eg. `00` through `ff`.
107 *
108 * \param number The value to type, from 0 to 255.
109 */
110void send_byte(uint8_t number);
111
112/**
113 * \brief Type out a single hexadecimal digit.
114 *
115 * The format is `[0-9a-f]{1}`, eg. `0` through `f`.
116 *
117 * \param number The value to type, from 0 to 15.
118 */
119void send_nibble(uint8_t number);
120
121/**
122 * \brief Type a pseudorandom character from the set `A-Z`, `a-z`, `0-9`, `+` and `/`.
123 */
124void tap_random_base64(void);
125
126#if defined(__AVR__) || defined(__DOXYGEN__)
127/**
128 * \brief Type out a PROGMEM string of ASCII characters.
129 *
130 * On ARM devices, this function is simply an alias for send_string_with_delay(string, 0).
131 *
132 * \param string The string to type out.
133 */
134void send_string_P(const char *string);
135
136/**
137 * \brief Type out a PROGMEM string of ASCII characters, with a delay between each character.
138 *
139 * On ARM devices, this function is simply an alias for send_string_with_delay(string, interval).
140 *
141 * \param string The string to type out.
142 * \param interval The amount of time, in milliseconds, to wait before typing the next character.
143 */
144void send_string_with_delay_P(const char *string, uint8_t interval);
145#else
146#    define send_string_P(string) send_string_with_delay(string, 0)
147#    define send_string_with_delay_P(string, interval) send_string_with_delay(string, interval)
148#endif
149
150/**
151 * \brief Shortcut macro for send_string_with_delay_P(PSTR(string), 0).
152 *
153 * On ARM devices, this define evaluates to send_string_with_delay(string, 0).
154 */
155#define SEND_STRING(string) send_string_with_delay_P(PSTR(string), 0)
156
157/**
158 * \brief Shortcut macro for send_string_with_delay_P(PSTR(string), interval).
159 *
160 * On ARM devices, this define evaluates to send_string_with_delay(string, interval).
161 */
162#define SEND_STRING_DELAY(string, interval) send_string_with_delay_P(PSTR(string), interval)
163
164/** \} */