Skip to content
This repository
Newer
Older
100644 400 lines (348 sloc) 27.369 kb
26725f99 »
2011-10-05 Add the GCC4TI documentation under the form of Github Pages.
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <HTML>
3 <HEAD>
4 <TITLE>cert.h</TITLE>
5 <STYLE TYPE="TEXT/CSS">
6 <!--
7 .IE3-DUMMY { CONT-SIZE: 100%; }
8 BODY { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; }
9 P { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
10 H1 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
11 H2 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
12 H3 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
13 H4 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
14 H5 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
15 H6 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
16 UL { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }
17 TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #FFFFFF; }
18 .NOBORDER { BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
19 .NOBORDER TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }
20 .CODE { FONT-FAMILY: Courier New; }
21 -->
22 </STYLE>
23 </HEAD>
24 <BODY TEXT="#000000" BGCOLOR="#E0E0E0">
25 <FONT SIZE="5"><B>The &lt;cert.h&gt; Header File</B></FONT>
26 <HR>
27 <P><B>Routines for accessing certificates and other memory-mapped files</B></P>
28
29 <H3><U>Functions</U></H3>
30 <DL INDENT="20"><DT><B><A HREF="#ceof">ceof</A></B><DD>Returns end-of-file status of the context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cfindfield">cfindfield</A></B><DD>Finds a matching field from a context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cgetc">cgetc</A></B><DD>Gets a character from a context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cgetcertrevno">cgetcertrevno</A></B><DD>Gets a certificate revision number.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cgetflen">cgetflen</A></B><DD>Gets the length of a field.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cgetfnl">cgetfnl</A></B><DD>Gets a non-aligned long integer from a field.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cgetnl">cgetnl</A></B><DD>Gets a non-aligned long integer from a context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cgetns">cgetns</A></B><DD>Gets a non-aligned short integer from a context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cgetsn">cgetsn</A></B><DD>Gets the calculator serial number from the Flash ROM certificate.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#copen">copen</A></B><DD>Opens a certificate file context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#copensub">copensub</A></B><DD>Opens a subcontext.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cputhdr">cputhdr</A></B><DD>Puts a field header to a context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cputnl">cputnl</A></B><DD>Puts a non-aligned long integer to a context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cputns">cputns</A></B><DD>Puts a non-aligned short integer to a context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cread">cread</A></B><DD>Reads a field from a context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ctell">ctell</A></B><DD>Returns the current position relative to the start of a context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#cwrite">cwrite</A></B><DD>Puts a field to a context.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#freeIdList">freeIdList</A></B><DD>Releases and deletes the RAM copy of the ID list, if it exists.</DL>
31 <H3><U>Global Variables</U></H3>
32 <DL INDENT="20"><DT><B><A HREF="#CertificateMemory">CertificateMemory</A></B><DD>A pointer to the certificate memory.</DL>
33 <H3><U>Constants</U></H3>
34 <DL INDENT="20"><DT><B><A HREF="alloc.html#H_NULL">H_NULL</A></B><DD>A null-handle value.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="alloc.html#NULL">NULL</A></B><DD>A null-pointer value.</DL>
35 <H3><U>Predefined Types</U></H3>
36 <DL INDENT="20"><DT><B><A HREF="alloc.html#Bool">Bool</A></B><DD>An enumeration to describe true or false values.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#CERT_FIELD">CERT_FIELD</A></B><DD>A structure describing the records of certificate files.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#CFILE">CFILE</A></B><DD>A structure representing the context of a memory-mapped file.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="alloc.html#HANDLE">HANDLE</A></B><DD>Represents a handle associated with an allocated memory block.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="stddef.html#size_t">size_t</A></B><DD>A type to define sizes of strings and memory blocks.</DL>
37 <P><B>Note:</B> The functions <B>caddcert</B>, <B>cgetcert</B>, <B>cgetvernum</B>
38 and <B>cfindcertfield</B>, which were present in the AMS 1.xx TIOS jump table, don't
39 exist in the AMS 2.xx TIOS jump table any more. Fortunately, all of them are only internal routines;
40 you need to use <A HREF="flash.html#FL_addCert">FL_addCert</A>, <A HREF="flash.html#FL_getCert">FL_getCert</A>
41 and <A HREF="flash.html#FL_getVerNum">FL_getVerNum</A> from <A HREF="flash.html">flash.h</A> instead.
42 <BR><BR>
43 In AMS 2.xx, the function replacing ROM_CALL 12C (cgetcert in AMS 1.xx), is <A HREF="alloc.html#HeapWalk">HeapWalk</A>.</P>
44
45 <HR>
46 <H3><A NAME="ceof"><U>ceof</U></A></H3>
47 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> ceof (<A HREF="#CFILE">CFILE</A> *context);</TD></TR></TABLE></P>
48 <P><B>Returns end-of-file status of the context.</B></P>
49
50 <P>ceof returns <A HREF="alloc.html#Bool">TRUE</A> if the end-of-file indicator of the file associated
51 with the file context pointed to by <I>context</I> is set, otherwise it returns <A HREF="alloc.html#Bool">FALSE</A>.</P>
52
53 <HR>
54 <H3><A NAME="cfindfield"><U>cfindfield</U></A></H3>
55 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> cfindfield (<A HREF="#CFILE">CFILE</A> *context, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> FieldID, <A HREF="#CERT_FIELD">CERT_FIELD</A> *dest);</TD></TR></TABLE></P>
56 <P><B>Finds a matching field from a context.</B></P>
57
58 <P>cfindfield searches a file associated with the file context pointed to by <I>context</I> for a
59 field which has field ID number equal to <I>FieldID</I> (length bits should be set to 0).
60 If such field is found, cfindfield fills the field descriptor structure pointed to by <I>dest</I>
61 and returns <A HREF="alloc.html#Bool">TRUE</A>, else returns <A HREF="alloc.html#Bool">FALSE</A>.
62 <BR><BR>
63 cfindfield is used often in TIOS to access particular data in a certificate file. Usually,
64 function <A HREF="#copensub">copensub</A> is called immediately after cfindfield to get
65 access to the content of the field. If the field contains subfields, this procedure may be
66 repeated several times if necessary.
67 <BR><BR>
68 As an illustration of layout of certificate files, the layout of certificate files used in TIOS
69 is given below. First, the field ID number is shown, then the short description of the field
70 follows. Indentation shows that a particular field is a subfield of the field with smaller indentation.</P>
71 <UL>
72 <LI><P><B>Layout of AMS header</B> (AMS is part of TIOS which may be replaced, unlike Boot Code);
73 it starts at address <CODE>ROM_base+0x12000</CODE>, i.e. 0x212000 on TI-89 and V200, 0x412000 on
74 TI-92 Plus and 0x812000 on TI-89T.
75 </P>
76 <PRE>0x8000 AMS header (organized as a certificate file, although it is not
77 read-protected like "real" certificates)
78
79 0x8010 First part of Product ID
80 0x8020 Third part of Product ID
81 0x8030 Fourth part of Product ID
82 0x80A0 Second part of Product ID
83 0x8040 Product Name: "Advanced Mathematics Software"
84 0x0320 Product code (6 bytes)
85 0x0200 Signature - encrypted MD5 (see <A HREF="rsa.html">rsa.h</A>) of 0x320 field
86 (including header)
87 0x8070 Actual AMS code
88
89 0x0200 Signature of entire AMS
90 </PRE>
91 <P>Fields with ID numbers 0x0320 and 0x0200 contains an authenticated number.
92 More precisely, field with ID number 0x0320 contains a 4-byte field with ID 0x0900, itself
93 containing a 32-bit timestamp: number of seconds elapsed since January 1st 1997, 00:00 in
94 some timezone (GMT ?), and the time the OS image was signed.
95 Field with ID 0x0200 is the encrypted digital signature of it.<BR>
96 Product ID is formed by applying format string "%02lX-%lX-%lx-%lX" to the content of
97 fields with ID numbers 0x8010, 0x80A0, 0x8020 and 0x8030.
98 </P></LI>
99 <LI><P>Layout of Flash ROM certificate (stored in the part of the Flash ROM which is read-protected
100 when the Protection is enabled); it starts at address <CODE>ROM_base+0x10004</CODE>, i.e.
101 0x210004 on TI-89 and V200, 0x410004 on TI-92 Plus and 0x810004 on TI-89T:
102 </P>
103 <PRE>0x0330 Flash ROM certificate
104
105 0xA10 Five-byte Serial Number (used as "pass phrase")
106 0xA20 Certificate Key
107 </PRE>
108 <P>Serial number has layout #sssss&nbsp;sssss&nbsp;cccc (all digits are in hex). First ten digits
109 are picked up from the field with ID number 0xA10. Then, the Certificate Key is used to decrypt
110 the MD5 (see <A HREF="rsa.html">rsa.h</A> for more info about RSA encryption) of the Serial Number to get cccc. In fact,
111 decrypting the Serial Number in this way creates a 40 byte number. Only first two bytes (in
112 little endian) are taken for cccc. This method ensures that only TI can create valid Serial
113 Numbers, as both the Serial Number and Key are unique for each machine.
114 </P></LI>
115 <LI><P>Layout of .cer files, which are attached to the start of Flash applications:
116 </P>
117 <PRE>0x0300 Flash application certificate
118
119 0x0100 Certificate Revision Number
120 0x0400 Five-byte Serial Number
121 0x0500 Optional field in .cer files
122
123 0x0510 Author name
124
125 0x0320 Product code - same construction and meaning as the field in AMS itself, see above
126 0x0200 Product code signature - see above
127 0x0700 Unknown certificate data
128
129 0x0710 Unknown byte data
130 0x0730 Signature
131 0x0710 Unknown word data
132 0x0730 Signature
133 0x0710 Unknown word data
134 0x0730 Signature
135
136 0x0200 Signature of all certificate data</PRE>
137 <P>Of course, such data are present in the certificate memory only if you have installed
138 additional Flash applications. Function <A HREF="flash.html#FL_addCert">FL_addCert</A> is
139 used to add such data to the certificate memory (this routine performs
140 very strong checking of what may be written there and under what conditions, so it is not
141 possible to write a garbage in this area by calling this routine).</P></LI></UL>
142 <P>As it is not possible to access the certificate part of Flash ROM <I>directly</I>, because this
143 area of Flash is read-protected when the Protection is enabled, the <I>usual</I> method (there's
144 an <I>unusual</I> method that doesn't even require disabling the Protection from the client
145 program) for reading certificates is to call <A HREF="flash.html#FL_getCert">FL_getCert</A>
146 first. This function will copy all data from the certificate area which may be shown to the
147 public into the RAM, so that the certificate can be read later from the RAM. For example, if you
148 need to access the certificate data which shows the name of the author of an Flash application
149 (assuming that such data is present in the certificate), the usual procedure is:</P>
150 <PRE>HANDLE handle;
151 unsigned long size;
152 CFILE context;
153 CERT_FIELD field;
154 ...
155 FL_getCert (&amp;handle, &amp;size, FALSE);
156 copen (&amp;context, HeapDeref (handle), size);
157 cfindfield (&amp;context, 0x300, &amp;field);
158 copensub (&amp;context, &amp;field);
159 cfindfield (&amp;context, 0x500, &amp;field);
160 copensub (&amp;context, &amp;field);
161 cfindfield (&amp;context, 0x510, &amp;field);
162 copensub (&amp;context, &amp;field);
163 </PRE>
164 <P>After this, context<B>.</B>Pos will point to the author name. Alternatively, you can pick the name
165 character-by-character using <A HREF="#cgetc">cgetc</A>. If any of calls to cfindfield
166 functions fail (i.e. return <A HREF="alloc.html#Bool">FALSE</A>), then such data are not present in
167 the certificate area.</P>
168
169 <HR>
170 <H3><A NAME="cgetc"><U>cgetc</U></A></H3>
171 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#int">char</A></B> cgetc (<A HREF="#CFILE">CFILE</A> *context);</TD></TR></TABLE></P>
172 <P><B>Gets a character from a context.</B></P>
173
174 <P>cgetc gets a character from the file associated with the file context pointed to by
175 <I>context</I>, and moves the file pointer to the next character. This function
176 is functionally equal to</P>
177 <PRE>*(char*) <I>context</I>-&gt;Pos++;
178 </PRE>
179
180 <HR>
181 <H3><A NAME="cgetcertrevno"><U>cgetcertrevno</U></A></H3>
182 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> cgetcertrevno (<B><A HREF="keywords.html#short">long</A></B> *dest);</TD></TR></TABLE></P>
183 <P><B>Gets a certificate revision number.</B></P>
184
185 <P>cgetcertrevno fills the variable pointed to by <I>dest</I> with the certificate
186 revision number. Returns <A HREF="alloc.html#Bool">TRUE</A> if the operation was
187 successful, otherwise it returns <A HREF="alloc.html#Bool">FALSE</A>.</P>
188
189 <HR>
190 <H3><A NAME="cgetflen"><U>cgetflen</U></A></H3>
191 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">long</A></B> cgetflen (<A HREF="#CFILE">CFILE</A> *context, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> FieldIDWord);</TD></TR></TABLE></P>
192 <P><B>Gets the length of a field.</B></P>
193
194 <P>cgetflen returns length of the field which has ID word (see <A HREF="#cread">cread</A>) equal to
195 <I>FieldIDWord</I>. This information is present in lower 4 bits of <I>FieldIDWord</I>
196 if these bits are smaller or equal to 0xC. If not, necessary information needed to
197 calculate the length are read from the context pointed to by <I>context</I>. cgetflen
198 returns 0 if the end of the file is reached.</P>
199
200 <HR>
201 <H3><A NAME="cgetfnl"><U>cgetfnl</U></A></H3>
202 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">long</A></B> cgetfnl (<A HREF="#CERT_FIELD">CERT_FIELD</A> *field);</TD></TR></TABLE></P>
203 <P><B>Gets a non-aligned long integer from a field.</B></P>
204
205 <P>cgetfnl gets a long integer (which does not necessarily need to be aligned on an even address)
206 from the field described by the structure pointed to by <I>field</I>. The field need
207 not to be exactly four bytes long; it can be of any length, and cgetfnl gets as many
208 bytes as are available, up to the size of a long.</P>
209
210 <HR>
211 <H3><A NAME="cgetnl"><U>cgetnl</U></A></H3>
212 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">long</A></B> cgetnl (<A HREF="#CFILE">CFILE</A> *context);</TD></TR></TABLE></P>
213 <P><B>Gets a non-aligned long integer from a context.</B></P>
214
215 <P>cgetnl gets a long integer (which does not necessarily need to be aligned on an even address)
216 from the file associated with the file context pointed to by <I>context</I>, and moves
217 the file pointer forward by four characters. In fact, it calls <A HREF="#cgetc">cgetc</A>
218 four times, and combines four returned bytes into one doubleword.</P>
219
220 <HR>
221 <H3><A NAME="cgetns"><U>cgetns</U></A></H3>
222 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> cgetns (<A HREF="#CFILE">CFILE</A> *context);</TD></TR></TABLE></P>
223 <P><B>Gets a non-aligned short integer from a context.</B></P>
224
225 <P>cgetns gets a short integer (which does not necessarily need to be aligned on an even address)
226 from the file associated with the file context pointed to by <I>context</I>, and moves
227 the file pointer forward by two characters. In fact, it calls <A HREF="#cgetc">cgetc</A>
228 twice, and combines two returned bytes into one word.</P>
229
230 <HR>
231 <H3><A NAME="cgetsn"><U>cgetsn</U></A></H3>
232 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> cgetsn (<B><A HREF="keywords.html#int">char</A></B> *dest);</TD></TR></TABLE></P>
233 <P><B>Gets the calculator serial number from the Flash ROM certificate.</B></P>
234
235 <P>cgetsn fills the buffer pointed to by <I>dest</I> with the calculator serial
236 number picked from the Flash ROM certificate. It has the form "pphnnnnnnn", where "pp"
237 is the platform number (01 for TI-92 Plus, 03 for TI-89, 08 for V200, 09 for TI-89T),
238 "h" is hardware revision level, and "nnnnnnn" is an ID number which is unique to each
239 calculator.
240 All the above fields consist of hexadecimal digits.
241 <I>buffer</I> must be at least 17 bytes long to accept the serial number.</P>
242
243 <HR>
244 <H3><A NAME="copen"><U>copen</U></A></H3>
245 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> copen (<A HREF="#CFILE">CFILE</A> *context, <B><A HREF="keywords.html#int">char</A></B> *data, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">long</A></B> size);</TD></TR></TABLE></P>
246 <P><B>Opens a certificate file context.</B></P>
247
248 <P>copen opens a memory mapped file which starts at address <I>data</I>,
249 and which is <I>size</I> bytes long. It also initializes file context (this is a file
250 control structure of type <A HREF="#CFILE">CFILE</A>) pointed to by
251 <I>context</I>. It does not reserve any memory. In fact, copen does nothing more than</P>
252 <PRE><I>context</I>-&gt;Start = <I>context</I>-&gt;Pos = <I>data</I>;
253 <I>context</I>-&gt;End = <I>data</I> + <I>size</I>;
254 <I>context</I>-&gt;EOF = FALSE;
255 </PRE>
256 <P><B>Note:</B> All functions from this header file are used in TIOS exclusively for accessing certificate
257 files, which are stored in the protected area of Flash ROM, and which contain certificate data.
258 However, these functions are not limited to such files. They may be used with any memory mapped
259 file (i.e. a "headerless" file which does not have an entry in the VAT table), which does not need to be
260 a file which really contains certificate data.</P>
261
262 <HR>
263 <H3><A NAME="copensub"><U>copensub</U></A></H3>
264 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> copensub (<A HREF="#CFILE">CFILE</A> *context, <A HREF="#CERT_FIELD">CERT_FIELD</A> *subfield);</TD></TR></TABLE></P>
265 <P><B>Opens a subcontext.</B></P>
266
267 <P>As the certificate file is usually consist of various field, this function is used for initializing
268 the context pointed to by <I>context</I> to point to the actual content of the field described
269 in the structure pointed to by <I>subfield</I>. This function is equal to</P>
270 <PRE>copen (<I>context</I>, <I>subfield</I>-&gt;Data, <I>subfield</I>-&gt;Len);
271 </PRE>
272 <P>copen is used mainly to reset the file pointer to the start of a group of items. See
273 <A HREF="#cfindfield">cfindfield</A> for more info.</P>
274
275 <HR>
276 <H3><A NAME="cputhdr"><U>cputhdr</U></A></H3>
277 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> cputhdr (<A HREF="#CFILE">CFILE</A> *context, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> FieldID, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> len);</TD></TR></TABLE></P>
278 <P><B>Puts a field header to a context.</B></P>
279
280 <P>cputhdr puts a field header to the file associated with the file context pointed to by
281 <I>context</I> and moves the file pointer accordingly. The field header includes
282 ID word (i.e. field ID number and four length bits), and up to four length bytes if
283 necessary (see <A HREF="#cread">cread</A> for more info about fields). Required data
284 for forming the header are taken from parameters <I>FieldID</I> and <I>len</I>.
285 cputhdr returns <A HREF="alloc.html#Bool">TRUE</A> if the operation was successful, otherwise it returns
286 <A HREF="alloc.html#Bool">FALSE</A>.</P>
287
288 <HR>
289 <H3><A NAME="cputnl"><U>cputnl</U></A></H3>
290 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> cputnl (<A HREF="#CFILE">CFILE</A> *context, <B><A HREF="keywords.html#short">long</A></B> l);</TD></TR></TABLE></P>
291 <P><B>Puts a non-aligned long integer to a context.</B></P>
292
293 <P>cputnl puts a long integer <I>l</I> to the file associated with the file context
294 pointed to by <I>context</I>, and moves the file pointer forward by four characters.
295 The stored integer will not always be aligned on an even address.</P>
296
297 <HR>
298 <H3><A NAME="cputns"><U>cputns</U></A></H3>
299 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> cputns (<A HREF="#CFILE">CFILE</A> *context, <B><A HREF="keywords.html#short">short</A></B> s);</TD></TR></TABLE></P>
300 <P><B>Puts a non-aligned short integer to a context.</B></P>
301
302 <P>cputns puts a short integer <I>s</I> to the file associated with the file context
303 pointed to by <I>context</I>, and moves the file pointer forward by two characters.
304 The stored integer will not always be aligned on an even address.</P>
305
306 <HR>
307 <H3><A NAME="cread"><U>cread</U></A></H3>
308 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> cread (<A HREF="#CFILE">CFILE</A> *context, <A HREF="#CERT_FIELD">CERT_FIELD</A> *dest);</TD></TR></TABLE></P>
309 <P><B>Reads a field from a context.</B></P>
310
311 <P>Certificate files in TIOS (which packages up all the data required to perform
312 authentification) are well-organized as files of variable-length records called
313 "fields". So, the different components are split up into various fields, which can
314 be accessed fairly easily. Each field begins with ID word. High 12 bits of ID
315 are used as field ID number, and lower 4 bits are used to encode size of the field
316 (as the length of the field can be a variable size). If these bits are smaller or
317 equal to 0xC, this value is just the length of the field. If these bits are 0xD,
318 0xE or 0xF, then the following byte, word or doubleword contains the actual length
319 of the field. Fields in the file are stored sequentially. They may contain various
320 data, including other fields (i.e. "subfields"), which are usually opened with
321 <A HREF="#copensub">copensub</A>.
322 <BR><BR>
323 cread reads a field from the file associated with the file context pointed to by
324 <I>context</I> and collects necessary information (field ID number, length
325 of the field, and the pointer to the actual content of the field) into the
326 <A HREF="#CERT_FIELD">CERT_FIELD</A> structure pointed to by <I>dest</I>. It also
327 moves the field pointer to the next field, and sets the EOF indicator in the
328 context if the end of the file is reached. cread returns <A HREF="alloc.html#Bool">TRUE</A>
329 if the operation was successful, otherwise it returns <A HREF="alloc.html#Bool">FALSE</A> (this usually
330 means end-of-file error).</P>
331
332 <HR>
333 <H3><A NAME="ctell"><U>ctell</U></A></H3>
334 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">long</A></B> ctell (<A HREF="#CFILE">CFILE</A> *context);</TD></TR></TABLE></P>
335 <P><B>Returns the current position relative to the start of a context.</B></P>
336
337 <P>ctell returns the current position of the file pointer associated with the file
338 context pointed to by <I>context</I>, measured from the start address of the file.</P>
339
340 <HR>
341 <H3><A NAME="cwrite"><U>cwrite</U></A></H3>
342 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> cwrite (<A HREF="#CFILE">CFILE</A> *context, <A HREF="#CERT_FIELD">CERT_FIELD</A> *source);</TD></TR></TABLE></P>
343 <P><B>Puts a field to a context.</B></P>
344
345 <P>cwrite writes a field described with <A HREF="#CERT_FIELD">CERT_FIELD</A> structure pointed to by
346 <I>source</I> to the file associated with the file context pointed to by <I>context</I>.
347 cwrite is the reverse of <A HREF="#cread">cread</A>. Returns <A HREF="alloc.html#Bool">TRUE</A> if the
348 operation was successful, otherwise it returns <A HREF="alloc.html#Bool">FALSE</A>.</P>
349
350 <HR>
351 <H3><A NAME="freeIdList"><U>freeIdList</U></A></H3>
352 <P><A HREF="httigcc.html#minams">AMS 2.00 or higher</A></P>
353 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> freeIdList (<B><A HREF="keywords.html#void">void</A></B>);</TD></TR></TABLE></P>
354 <P><B>Releases and deletes the RAM copy of the ID list, if it exists.</B></P>
355
356 <P>See also: <A HREF="link.html#LIO_SendIdList">LIO_SendIdList</A></P>
357 <HR>
358 <H3><A NAME="CertificateMemory"><U>CertificateMemory</U></A></H3>
359 <P><A HREF="httigcc.html#minams">AMS 2.00 or higher</A></P>
360 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#int">char</A></B> *<B><A HREF="keywords.html#const">const</A></B> CertificateMemory;</TD></TR></TABLE></P>
361 <P><B>A pointer to the certificate memory.</B></P>
362
363 <P>This variable contains a pointer to the first byte of the certificate memory.
364 Note that it always has a value of <CODE>(unsigned char *const) (ROM_base + 0x10000)</CODE>.</P>
365
366 <HR>
367 <H3><A NAME="CERT_FIELD"><U>CERT_FIELD</U></A></H3>
368 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#typedef">typedef</A></B> <B><A HREF="keywords.html#struct">struct</A></B> {
369 <TABLE><TR><TD WIDTH="12"></TD><TD CLASS="CODE">
370 <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> Field; <I>/* Field ID number (without the length) */</I><BR>
371 <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> HdrLen; <I>/* Size of the header (ID word &amp;<BR>
372 optional length bytes: 0, 1, 2 or 4) */</I><BR>
373 <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">long</A></B> Len; <I>/* Total length of the field */</I><BR>
374 <B><A HREF="keywords.html#void">void</A></B> *Data; <I>/* Pointer to an actual data */</I><BR>
375 </TD></TR></TABLE>
376 } CERT_FIELD;</TD></TR></TABLE></P>
377 <P><B>A structure describing the records of certificate files.</B></P>
378
379 <P>CERT_FIELD is a structure which describes the variable-length records (usually called "fields") of
380 certificate files. Each field has its ID number, and some ID numbers have predefined meanings
381 in the TIOS (see <A HREF="#cfindfield">cfindfield</A>).</P>
382
383 <HR>
384 <H3><A NAME="CFILE"><U>CFILE</U></A></H3>
385 <P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#typedef">typedef</A></B> <B><A HREF="keywords.html#struct">struct</A></B> {
386 <TABLE><TR><TD WIDTH="12"></TD><TD CLASS="CODE">
387 <B><A HREF="keywords.html#void">void</A></B> *Start, *Pos, *End; <I>/* Start, current and end position of the file pointer */</I><BR>
388 <B><A HREF="keywords.html#short">short</A></B> EOFVal; <I>/* Boolean value indicating end of file */</I><BR>
389 </TD></TR></TABLE>
390 } CFILE;</TD></TR></TABLE></P>
391 <P><B>A structure representing the context of a memory-mapped file.</B></P>
392
393 <P>CFILE is a structure which represents the context of a memory-mapped file (usually a certificate
394 file).</P>
395
396 <HR>
397 <H3><A HREF="index.html">Return to the main index</A></H3>
398 </BODY>
399 </HTML>
Something went wrong with that request. Please try again.