NASD Programmer's Documentation
Drive handles

NASD drives are represented in the client API with type nasd_drive_handle_t. Each nasd_drive_handle_t represents a communication channel with a drive. Any number of requests may be outstanding on this logical channel at a given time, but all requests on the channel will use the same transport mechanism, and must go to the same drive. The actual transport mechanism is referred to as the binding type of a particular drive handle. For instance, DCE RPC is one such transport mechanism.

A nasd_drive_handle_t is created by calling nasd_bind_to_drive(), which has the signature:

nasd_status_t
nasd_bind_to_drive(
  char                 *drive_name,
  char                 *portnum,
  int                   binding_type,
  void                 *binding_param,
  int                   binding_param_len,
  nasd_drive_handle_t  *handlep)
The first argument, drive_name, is a logical name of the drive to bind to. This is a null-terminated string, which is meaningful for the the binding type. For example, most network-based transports will desire a hostname for this argument. The next argument, portnum, is a port number. Like drive_name, this is a null-terminated string whose interpretation is dependent upon the drive binding type.

The binding_type argument indicates what transport mechanism should be used by the nasd_drive_handle_t that is to result from this call. Some binding types require additional information. This is passed opaquely by reference as binding_param. The number of bytes provided at the address indictaed by binding_param is indicated by binding_param_len.

Each successful call to nasd_bind_to_drive() yields a nasd_drive_handle_t, which is stored at the location indicated by handlep.

The following table lists some of the binding types available, and describes how the other arguments of nasd_bind_to_drive() are interpreted, and what values are expected.
Binding typeTransportdrive_nameportnumbinding_param and binding_param_len
NASD_BIND_DCE_DIRECT DCE/UDP calls are made from the current context hostname of the drive to bind to udp port number of the drive to bind to N/A, N/A
NASD_BIND_DCE_KPDEV Each drive operation results in a system call, and DCE/UDP calls are made from the kernel context hostname of the drive to bind to udp port number of the drive to bind to nasd_drive_param_dce_kpdev_t
The devname field of this structure should name a valid kpdev (ie /dev/nasdkp0), which will be used to generate this binding
binding_param_len should be sizeof(nasd_drive_param_dce_kpdev_t)
NASD_BIND_DCE_DIRECT_TCP DCE/TCP calls are made from the current context hostname of the drive to bind to tcp port number of the drive to bind to N/A, N/A
NASD_BIND_COLOCATE Assumes the drive is running in the kernel context on the same host as the client. Each drive operation results in a system call which directly executes the relevant drive code. N/A N/A nasd_drive_param_dce_kpdev_t
The devname field of this structure should name a valid kpdev (ie /dev/nasdkp0), which will be used to generate this binding
binding_param_len should be sizeof(nasd_drive_param_dce_kpdev_t)

If nasd_bind_to_drive() returns NASD_BAD_HANDLE_TYPE, it means that binding_type was not valid for your NASD configuration (a combination of your platform and what compile-time options were enabled).

When a drive handle is no longer needed, nasd_unbind_drive() is used to destroy it and any associated resources. nasd_unbind_drive() takes as its sole argument a pointer to the nasd_drive_handle_t to destroy, and returns nasd_status_t.
<--- ---> ^<br>|<br>|
Client programming overview Drive operation calling convention NASD Programmer's Documentation