1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
Some things are mentioned here to help any potential gnutls coder.
The rules here are not always used, although we try to stick to them.
*** File names:
Files are split to directories according to the subsystem
they belong to. Examples are x509/, minitasn1/, openpgp/,
opencdk/ etc. The files in the root directory are of concern
to the main TLS protocol implementation.
*** Indentation style:
In general, use the Linux coding style. You may indent the source
using GNU indent, e.g. "indent -linux *.c".
*** Git commits:
The original author of the changes should be the author of the commit.
The "Signed-off-by" git flag is used to indicate a commit according to
the project's DCO.
*** Function names:
All the function names use underscore "_", to separate words,
functions like gnutlsDoThat are not used. The exported function names
usually start with "gnutls_" prefix, and the words that follow
specify the exact part of gnutls that this function refers to.
E.g. "gnutls_x509_crt_get_dn", refers to the X.509
certificate parsing part of gnutls. Currently used prefixes are:
"gnutls_x509_crt_" for the X.509 certificate part
"gnutls_openpgp_key_" for the openpgp key part
"gnutls_session_" for the TLS session part (but this may be omited)
"gnutls_handshake_" for the TLS handshake part
"gnutls_record_" for the TLS record protocol part
"gnutls_alert_" for the TLS alert protocol part
"gnutls_credentials_" for the credentials structures
"gnutls_global_" for the global structures handling
and probably more.
Internal functions -- that are not exported in the API -- should
be prefixed with an underscore. E.g. _gnutls_handshake_begin()
Internal structures should not be exported. Especially pointers to
internal data. Doing so harms future reorganization/rewrite of subsystems.
All exported functions must be listed in libgnutls.map and libgnutls-extra.map
in order to be exported.
*** Constructed types:
The constructed types in gnutls always have the "gnutls_" prefix.
Definitions, value defaults and enumerated values should be in
capitals. E.g. GNUTLS_CIPHER_3DES_CBC
Structures should have the '_st' suffix in their name even
if they are a typedef. One can use the sizeof() on types with
'_st' as suffix.
Other constructed types should have the '_t' suffix. A pointer
to a structure also has the '_t' suffix.
*** Function parameters:
The gnutls functions accept parameters in the order:
1. Input parameters
2. Output parameters
When data and size is expected, a gnutls_datum structure should be
used (or more precisely a pointer to the structure).
*** Callback function parameters:
Callback functions should be avoided, if this is possible.
Callbacks that refer to a TLS session should include the
current session as a parameter, in order for the called function to
be able to retrieve the data associated with the session.
This is not always done though -- see the push/pull callbacks.
*** Return values:
Functions in gnutls return an int type, when possible. In that
case 0 should be returned in case of success, or maybe a positive
value, if some other indication is needed.
A negative value always indicates failure. All the available
error codes are defined in gnutls.h and a description
is available in gnutls_errors.c
*** Guile bindings:
Parts of the Guile bindings, such as types (aka. "SMOBs"), enum values,
constants, are automatically generated. This is handled by the modules
under `guile/modules/gnutls/build/'; these modules are only used at
build-time and are not installed.
The Scheme variables they generate (e.g., constants, type predicates,
etc.) are exported to user programs through `gnutls.scm' and
`gnutls/extra.scm', both of which are installed.
For instance, when adding/removing/renaming enumerates or constants,
two things must be done:
1. Update the enum list in `build/enums.scm' (currently dependencies
are not tracked, so you have to run "make clean all" in `guile/'
after).
2. Update the export list of `gnutls.scm' (or `extra.scm').
Note that, for constants and enums, "schemefied" names are used, as
noted under the "Guile API Conventions" node of the manual.
|
