1arm_register_application(3)ARM 4 Programmer's Manualarm_register_application(3)
2
3
4
6 arm_register_application - describe application
7
9 #include <arm4.h>
10
11 arm_error_t
12 arm_register_application(
13 const arm_char_t *app_name,
14 const arm_id_t *input_app_id,
15 const arm_int32_t flags,
16 const arm_buffer4_t *buffer4,
17 arm_id_t *output_app_id);
18
20 arm_register_application() describes metadata about an application.
21
22 The application uses arm_register_application() to inform the ARM
23 library of metadata about the application. This metadata does not
24 change from one application instance to another. It contains part of
25 the function of the ARM 2.0 call arm_init(); arm_start_application()
26 contains the other part.
27
28 ARM generates an ID that is passed in arm_register_transaction() and
29 arm_start_application().
30
31 app_name is a pointer to a null-terminated string containing the name
32 of the application. The maximum length of the name is 128 characters,
33 including the termination character. It serves no purpose and is ille‐
34 gal to make this call if the pointer is null. A name should be chosen
35 that is unique, so generic names that might be used by a different
36 development team, such as "Payroll Application", should not be used.
37 The name should not contain trailing blank characters or consist of
38 only blank characters. If the application has a copyrighted product
39 name, the copyrighted name would be a good choice.
40
41 buffer4 is a pointer to the user data buffer, if any. If the pointer is
42 null (ARM_BUF4_NONE), there is no buffer. The sub-buffer formats that
43 might be used are arm_subbuffer_app_identity_t and arm_subbuffer_encod‐
44 ing_t.
45
46 flags contains 32-bit flags. No values are currently defined. The field
47 should be zero (ARM_FLAG_NONE).
48
49 input_app_id is a pointer to an optional 128-bit ID (16 bytes) that is
50 unique and that can be treated as an alias for the other metadata. It
51 can be any value except all zeros or all ones. If the pointer is null
52 (ARM_ID_NONE), no ID is provided.
53
54 An ID is unique if the probability of the ID being associated with more
55 than one set of metadata is vanishingly small. The selection of 128-bit
56 IDs yields 3.4 x 10**38 unique IDs, so the objective is to select an ID
57 that makes use of all 128 bits and is reasonably likely to not be
58 selected by another person creating an ID of the same form. Two sug‐
59 gested algorithms that generate 128-bit values with these characteris‐
60 tics are:
61
62
63 1. The Universal Unique Identifier (UUID) algorithm that is part of
64 The Open Group specification: DCE 1.1: Remote Procedure Call. A
65 developer could use the algorithm at the time the application is
66 developed using a utility on his or her system, and be reason‐
67 ably certain that nobody else would generate the same 128-bit
68 ID.
69
70
71 2. The MD5 Message-Digest Algorithm, described in IETF RFC 1321.
72 Applying this algorithm to a concatenation of all the metadata
73 properties would almost certainly result in a value that would
74 not collide with any other ID created with a different set of
75 metadata properties.
76
77 If an ARM implementation is passed an ID that was previously registered
78 within this process, the implementation can ignore the other metadata
79 parameters and assume they are identical to the previously registered
80 metadata. The application metadata consists of the following fields:
81 app_name and the arm_subbuffer_app_identity_t sub-buffer passed in buf‐
82 fer4.
83
84 output_app_id is a pointer to a 16-byte field. ARM will store a 16-byte
85 value. There are no requirements on what value it is set to, except
86 that it must be possible to pass it on other calls, such as
87 arm_start_application(), without the application needing to do any
88 error checking.
89
91 On success, the function returns ARM_SUCCESS. A non-zero value indi‐
92 cates an error.
93
95 If the return code is negative, an error occurred. If the return code
96 is not negative, an error may or may not have occurred - the determina‐
97 tion of what is an error and whether an error code is returned is at
98 the discretion of the ARM implementation. The application can test the
99 return code if it wants to provide its own error logging.
100
101 The following errors are recognized by this implementation, but may not
102 be portable to other implementations:
103
104
105 ARM_FAILURE_NULL_ARGUMENT
106 The output_app_id must not be null.
107
108 ARM_FAILURE_INVALID_ARGUMENT
109 The app_name parameter is invalid.
110
111 ARM_FAILURE_UNSUPPORTED_CHARSET
112 The character set value passed in as a arm_subbuffer_encoding_t
113 isn't supported.
114
115 ARM_FAILURE_BAD_ALIAS
116 The alias provided contains all 0's or all 1's.
117
118 ARM_FAILURE_DUPLICATE_ALIAS
119 The alias provided already refers to an application with differ‐
120 ent metadata.
121
122 ARM_FAILURE_INTERNAL_ERROR
123 An internal error has occurred that prevented the application
124 from being registered. Check your system log for more details.
125
127 ARM Issue 4.0 C Language Bindings, Version 2
128
130 None.
131
133 arm_destroy_application(3), arm_register_transaction(3),
134 arm_start_application(3)
135
136
137
138arm4.org August 2008 arm_register_application(3)