Initializes the library by allocating space on a per task/thread-group basis to identify the accessor and maintain copies of global values
#include <nwdp_lib.h>
N_EXTERN_LIBRARY (NWDPInitCode) NWDPLibInit (
nuint expectedMajorVersion,
nuint expectedMinorVersion,
nuint expectedBugfixRevision,
nuint expectedPrereleaseVersion,
nuint taskID,
nuint subTaskID,
pNWDPAccessorRef accessorRefPtr,
pnuint returnedMajorVersionPtr,
pnuint returnedMinorVersionPtr,
pnuint returnedBugfixRevisionPtr,
pnuint returnedPrereleaseVersionPtr);(IN) Specifies the NWDP_LIBRARY_MAJOR_VERSION constant.
(IN) Specifies the NWDP_LIBRARY_MINOR_VERSION constant.
(IN) Specifies the NWDP_LIBRARY_BUGFIX_REVISION constant.
(IN) Specifies the NWDP_LIBRARY_PREREL_VERSION constant.
(IN) Specifies an operating system unique identifier for the current task/thread-group process that needs its own instance of the data for this session.
(IN) Specifies a subordinate identifier to the taskID parameter.
(OUT) Points to the NWDPAccessorRef containing the accessor to be initialized.
(OUT) Points to the unsigned integer containing the major version of this library.
(OUT) Points to the unsigned integer containing the resulting minor version of this library.
(OUT) Points to the unsigned integer containing the resulting bug-fix revision of this library.
(OUT) Points to the unsigned integer containing the resulting prerelease version of this library.
NWDPLibInit can block if the server must wait for allocation.
NWDPLibInit initializes the unicode tables for you. It also contains localToUnicode and unicodeToLocal handles for unicode functions, which can be accessed by using the NWDPLocalToUnicodeHandleMac (accessorRef) and NWDPUnicodeToLocalHandleMac (accessorRef) macros.
The following is an explanation of what version is older:
The oldest prerelease version is 0xD001 (the first development prerelease)
After subsequent development prereleases, the next newest is 0xA001 (the first Alpha release)
After subsequent Alpha releases, the next newest is 0xB001 (the first Beta release). After the Beta releases comes the final prerelease value. For the expectedMajorVersion, expectedMinorVersion, and expectedBugfixRevision parameters, the value is 0, (indicating that it is not a prerelease).
If the expectedPrereleaseVersion parameter is zero and the library is older than this, NWDP_IC_ERR_IS_PRERELEASE is returned.
If the expectedMajorVersion parameter matches that of the library, functionality is guaranteed to be supported. If the major versions do not match, certain entry points are no longer supported and NWDP_IC_ERR_WRONG_MAJOR_VERSION is returned.
If the expectedMajorVersion parameter matches, but the expectedMinorVersion parameter is less than that of the library, the expected library may contain newly obsoleted entry points. If the library contains obsoleted entry points, NWDP_IC_WARN_VER_OBSOLETE is returned. This error is non-fatal because the entry points continue to be supported with all libraries of the same major version. If the expectedMinorVersion parameter is greater than that of the Library, NWDP_IC_ERR_OLD_MINOR_VERSION is returned.
If tests on the expectedMajorVersion and expectedMinorVersion parameters succeed, but the expectedBugfixRevision parameter is greater than the current one, NWDP_IC_ERR_OLD_REVISION is returned.
If tests on the expectedMajorVersion, expectedMinorVersion and expectedBugfixRevision parameters all succeed, but the expectedPrereleaseVersion parameter is "newer" than the one in the library, NWDP_IC_ERR_OLD_PRERELEASE is returned.
The subTaskID parameter allows an application to create multiple accessor references per task/thread-group process. Repeat usage of a taskID / subTaskID pair parameter causes the same accessor reference to be returned and a usage count to be incremented. It also provokes a warning error code, NWDP_IC_WARN_REPEAT_ID. This indicates that NWDPLibTerm must be called with the same accessorRef parameter a number of times equal to the number of times NWDPLibInit is called.
A macro named NWDPLibInitMac has been defined with explicit error handling so that only the address of the accessor reference to be returned needs to be provided and all other parameters can have defaults. This may be used as a code example, but since it contains a reference to exit(), it should not be used in production code.