arm_register_application(3)

1arm_register_application(3)ARM 4 Programmer's Manualarm_register_application(3)
2
3
4

NAME

6       arm_register_application - describe application
7

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

91       On  success,  the  function returns ARM_SUCCESS. A non-zero value indi‐
92       cates an error.
93

ERRORS

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

CONFORMING TO

127       ARM Issue 4.0 C Language Bindings, Version 2
128

EXAMPLE

130       None.
131