arm_register_application (3) - Linux Man Pages
arm_register_application: describe application
NAMEarm_register_application - describe application
DESCRIPTIONarm_register_application() describes metadata about an application.
The application uses arm_register_application() to inform the ARM library of metadata about the application. This metadata does not change from one application instance to another. It contains part of the function of the ARM 2.0 call arm_init(); arm_start_application() contains the other part.
ARM generates an ID that is passed in arm_register_transaction() and arm_start_application().
app_name is a pointer to a null-terminated string containing the name of the application. The maximum length of the name is 128 characters, including the termination character. It serves no purpose and is illegal to make this call if the pointer is null. A name should be chosen that is unique, so generic names that might be used by a different development team, such as "Payroll Application", should not be used. The name should not contain trailing blank characters or consist of only blank characters. If the application has a copyrighted product name, the copyrighted name would be a good choice.
buffer4 is a pointer to the user data buffer, if any. If the pointer is null (ARM_BUF4_NONE),
there is no buffer. The sub-buffer formats that might be used are
arm_subbuffer_app_identity_t and arm_subbuffer_encoding_t.
flags contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
input_app_id is a pointer to an optional 128-bit ID (16 bytes) that is unique and that can be treated as
an alias for the other metadata. It can be any value except all zeros or all ones. If the
pointer is null (ARM_ID_NONE), no ID is provided.
An ID is unique if the probability of the ID being associated with more than one set of metadata is vanishingly small. The selection of 128-bit IDs yields 3.4 x 10**38 unique IDs, so the objective is to select an ID that makes use of all 128 bits and is reasonably likely to not be selected by another person creating an ID of the same form. Two suggested algorithms that generate 128-bit values with these characteristics are:
The Universal Unique Identifier (UUID) algorithm that is part of The Open
Group specification: DCE 1.1: Remote Procedure Call. A developer could use the
algorithm at the time the application is developed using a utility on his or her
system, and be reasonably certain that nobody else would generate the same 128-bit
The MD5 Message-Digest Algorithm, described in IETF RFC 1321. Applying
this algorithm to a concatenation of all the metadata properties would almost
certainly result in a value that would not collide with any other ID created with a
different set of metadata properties.
If an ARM implementation is passed an ID that was previously registered within
this process, the implementation can ignore the other metadata parameters and
assume they are identical to the previously registered metadata. The application
metadata consists of the following fields: app_name and the
arm_subbuffer_app_identity_t sub-buffer passed in buffer4.
output_app_id is a pointer to a 16-byte field. ARM will store a 16-byte value. There are no requirements on what value it is set to, except that it must be possible to pass it on other calls, such as arm_start_application(), without the application needing to do any error checking.
RETURN VALUEOn success, the function returns ARM_SUCCESS. A non-zero value indicates an error.
ERRORSIf the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging.
The following errors are recognized by this implementation, but may not be portable to other implementations:
- The output_app_id must not be null.
- The app_name parameter is invalid.
- The character set value passed in as a arm_subbuffer_encoding_t isn't supported.
- The alias provided contains all 0's or all 1's.
- The alias provided already refers to an application with different metadata.
- An internal error has occurred that prevented the application from being registered. Check your system log for more details.
CONFORMING TOARM Issue 4.0 C Language Bindings, Version 2
SEE ALSOarm_destroy_application(3), arm_register_transaction(3), arm_start_application(3)
Linux man pages generated by: SysTutorials