All cross-platform functions have now been ported to run on the NLM platform through the library CALNLM32.NLM, also included in this NDK.
These functions provide a rich API set for developing NLMs, especially for applications designed as utilities. Such applications can take advantage both of the rich and varied function set provided in the cross-platform libraries and of the speed and server-centric functionality of CLIB.
This module provides the conceptual information necessary to understand NLM development with cross-platform functions. For general development instructions, see Section 4.4, Developing NLMs with Cross-Platform Functions.
Central to understanding the cross-platform world in NLM development are two key concepts:
Differences in assumptions between cross-platform functions and CLIB functions
Differences in the connection model between these two environments
The cross-platform functions are developed under the assumption that a client needs access to services provided by the network, rather than services provided by a specific server. Ultimately, of course, all services are provided by one server or another, but it is entirely possible to be connected to the network, receive the needed services, and not know which server is providing those services. This development assumption is necessary for technologies such as NDS® to be implemented. NDS provides services through replicas that reside on servers, but the emphasis is on the NDS tree, not on the server on which the replica of that tree resides. This assumption provides for a wide array of services with the capability of enterprise level management and functionality.
In contrast, CLIB has always been designed to provide services on a specific server, often the server on which the NLM is loaded. Because of this emphasis, CLIB does not have the concept of a directory (other than a file system directory). All requests are directed to a specified server, and all communication is server-centric. This assumption provides for very fast, very efficient access to services on a server. It also allows for operations that deal specifically with files and directories residing on a specific server.
Understanding these differences in connection model is central to successful development of NLMs with cross-platform functions.
Cross-platform functions use a connection handle.
CLIB functions use a connection ID.
Connection handles are valid only for cross-platform functions, and connection IDs are valid only for CLIB functions.
A connection handle is a number returned from any of a number of cross-platform functions that make an initial connection, such as NWCCOpenConnByName. A connection handle ultimately resolves to a connection on a specific server, but it is possible to make such a connection and not know which server the handle specifies. That would be the case if a connection were opened with NWCCOpenConnByPref, which makes a connection with a preferred transport type and returns a connection handle. However, it does not identify the server to which that connection is made.
IMPORTANT:You need a connection handle to call virtually every cross-platform function, but never attempt to pass a connection handle to a CLIB function as a connection ID.
A connection ID is a number that refers to a connection on a specific server. A connection ID is returned from any CLIB function that make a connection, such as LoginToFileServer. A connection ID can refer to a connection to the server on which the NLM is loaded or to a connection to a remote server. This model incorporates the concept of a current connection, which remains in force until some function changes the connection to specify a different server, which then becomes the current connection.
IMPORTANT:Before a CLIB function that uses the services on or makes changes to the system of a particular server can be called, a connection ID must be returned by calling a function such as GetCurrentConnection.