NPFormatNetworkName

DWORD NPFormatNetworkName(
  LPTSTR lpRemoteName,
  LPTSTR lpFormattedName,
  LPDWORD lpnLength,
  DWORD dwFlags,
  DWORD dwAveCharPerLine
  );

lpRemoteName

Network name to be formatted.

lpFormattedName

Pointer to string buffer that will receive the formatted name.

lpnLength

Pointer to DWORD that specifies the size of the buffer (in bytes) passed in. If the result is WN_MORE_DATA, this will contain the buffer size required (in bytes).

dwFlags

Bit mask indicating the type of format being requested. Can be one of the following:

WNFMT_MULTILINE (0x01) - The provider should place the '\n' character where line breaks should appear in the name. The full name should be expressed.

WNFMT_ABBREVIATED (0x02) - The provider should ellipsize or otherwise shorten the network name such that the most useful information will be available to the user in the space provided.

In addition, the following flags can be used with the logical OR operator to modify the flags listed above:

WNFMT_INENUM (0x10) - The network name is being presented in the context of an enumeration where the "container" of this object is presented immediately prior to this object. This may allow NPs to remove redundant information from the formatted name, providing a less cluttered display for the user.

WNFMT_CONNECTION (0x20) - The network name is in the form returned from NPGetConnection and is being formatted so that it can be returned as the result to a WNetGetConnection call. Note: this call is made only if the NP claims to have the WNNC_CON_FORMATCONNECTION capability. The purpose of this is so that an NP can have rich names for network connections and preserve compatibility with the existing WNetGetConnection return result, which some applications prepend to a file name before making a file system request.

dwAveCharPerLine

The maximum number of characters to try fit on a single line (including any ellipses added) where the network name is being presented. If this parameter is zero, then no character limit is being applied.

WN_SUCCESS if the call is successful.
WN_MORE_DATA if input buffer is too small.

All other errors will be ignored and the unformatted network name will be used.

This SPI allows network vendors to trim or modify network names before they are presented to the user. For example, in the File Open common dialog box, the Drives combo box presents all connected resources and the associated network name. Before each item is displayed, NPFormatNetworkName will be called and the NP will have the option of editing the name so it will fit in the combo box and more importantly, present the most significant portion of the network name to the user.

Note that NPFormatNetworkName is not routed to each NP as most of the other NP SPIs are. Each network vendor need worry about formatting only their own network name and can assume that only names produced by their NP driver will be passed to NPFormatNetworkName.