Intranet/Hosting Toolkit | [table of contents]

`v1.10 November 30th 2001` | CFX_NetworkTopology OPEN-SOURCE NT DLL for Cold Fusion 4.0.1 and up Lewis A. Sellers http://www.intrafoundation.com/ihtk.asp products@intrafoundation.com

FOREWORD This is an Allaire Cold Fusion Extension Tag (CFX). It is for use with Allaire Cold Fusion Servers 4.01 (and up) running on Microsoft NT. It was written by Lewis A. Sellers of Intrafoundation Software. CFX_NetworkTopology is a read-only tag used to determine what is on your network and where it is in relationship to everything else. It is meant to be used to set up operations with the other tags (to find domain controllers, domains, computer names, etc). Thus it also superceeds some of the now redundant functions grafted onto CFX_UserManager, CFX_NFS, etc in their youth. Please read the version history for current tag status before emailing questions. | C O N T E N T S `Foreword` General Basic Composite `Version History`

`top`

## G E N E R A L

### ABOUT

#### <CFX_NetworkTopology ACTION="ABOUT">

The tag itself returns a couple variables back no matter what you do (NetworkTopology Description, NetworkTopology Version and NetworkTopology Error). These are always available unless there is a catastrophic failure of the tag.

Additionally you can use the ABOUT function to return more detailed information on the tag. The fields returned are mostly only of interest for curiosity or in debugging a situation.

Note below that though the tag returns it's SerialNumber, it's not used currently, and hasn't been for a very long time, but probably will be again soon.

For the curious, it also proves the total number of lines of c/c++ that the current build was using. This includes the scant comments in the source code. For instance, this build of the tag has 5298 lines of code.

Description
  The general product description.
Version
  The version number of the software, ie 2.0.
Quality

  The quality field will be one of the following four: "Alpha", "Beta", "Gamma" or "Omega". Quality relates the quality control status of the version of the tag you're currently using.

  Alpha code is highly unstable and shouldn't be trusted for anything. Do not use on production machines.

  Beta code is close to being finish and it is in a debugging phase. Do not use on production machines.

  Gamma code is for use on production machines. As far as the beta testers have determined it works as it should.

  When a product goes Omega that generally means it is long used Gamma code that is now no longer being maintained.

SubVersion
  The subversion number of the software, ie 4 for "2.0beta4".
SerialNumber
  Currently unused.
Lines
  The total lines of c/c++ code in the software.
BuildDate
  The ODBC DATETIME when the tag was last compiled (built).
Evaluation
  Boolean field (0 or 1). 1 indicates the version of the tag you're using is a time-limited evaluation version. 0 is full commercial.
ExpirationDate
  The ODBC DATETIME date when the tag will stop working.

`top`

## B A S I C

### THISSYSTEM

#### <CFX_NetworkTopology ACTION="THISSYSTEM">

FIELDS
Computer | string
Debug | boolean
Network | boolean
Mouse | boolean
Pen | boolean
FontSmoothing | boolean
ScreenSaver | boolean
Keyboard | boolean
SystemDirectory | string
WindowsDirectory | string
CurrentDirectory | string
MajorVersion | number
MinorVersion | number
BuildVersion | number
PatformVersion | number
ServiceVersion | string
NumberOfProcessors | number
ProcessorType | number
ProcessorLevel | number
ProcessorRevision | number
ProcessorFeatures | string
MemoryLoad | percentage
TotalPhysicalMemory | number
AvailablePhysicalMemory | number
TotalPageFileMemory | number
AvailablePageFileMemory | number
TotalVirtualMemory | number
AvailableVirtualMemory | number
MaxUsernameLength | number
MaxPasswordLength | number
MaxPathLength | number
User | string
UpTime | days:hours:minutes:seconds
PID | number
CPUTime | days:hours:minutes:seconds

REQUIRED
Action | THISSYSTEM

Provides general real-time information about the system. Most of this can be can be used to monitor the health and status of server CF is installed on remotely.

Relative to the CF Service itself are a few details.... UpTime and CPUTime are in the format days:hours:minutes:seconds. (It was thought a weeks field would be pointless because we are talking about Windows here afterall.) UpTime is how long the cfserver.exe has been alive (since boot or service restart). CPUTime is how long cfserver has been using the cpu for computations (time slicing, etc). PID is the cfservers's process ID (same as in the Task Manager). Username is the current account cfserver is running under. By default this is SYSTEM (Local System).

Of the other fields most are either general toggles to the setup of the system, reflections on current memory usage or some relatively useless info on the processsor build.

Optional parameter "AudioAlert" will cause the speaker of the machine to sound a 911* if memoryload is over the specified percentage. Currently the parameter is ignored if it is less than 50 to avoid accidentally annoying co-location techs.

(*Or something close. The piezo-electric buzzers in most cases simply aren't capable of the dual-tones emitted by phone systems.)

User. Note that, to fall in line with the look-and-feel of W2K, Username is now called User. You can still use Username as well, however.

### DOMAINCONTROLLERS

#### <CFX_NetworkTopology ACTION="DOMAINCONTROLLERS">

FIELDS
Domain | string
Computer | string
Role | string

REQUIRED
Action | DOMAINCONTROLLERS

Lists domain controllers by computer.

Role is for display only. Currently is either "Domain Controller" or "Other".

### THISDOMAIN

#### <CFX_NetworkTopology ACTION="THISDOMAIN">

FIELDS
Domain | string
Mode | string

REQUIRED
Action | THISDOMAIN

Returns the name of the local domain.

Mode can be "Mixed", "Native" or "Unknown". It relates to how Windows 2000 interacts with the older NT4-style domain system. In Mixed mode it does, and in Native mode it doesn't (interact with NT4 domains that is).

### THISCOMPUTER

#### <CFX_NetworkTopology ACTION="THISCOMPUTER">

FIELDS
Computer | string

REQUIRED
Action | THISCOMPUTER

Returns the name of this computer. Note that computer names do not use the traditional prepended double slashes such as "\\SASHA". We'd use "SASHA" instead. (All currently supported tags automatically handle this internally, as needed.)

### DOMAINS

#### <CFX_NetworkTopology ACTION="DOMAINS">

FIELDS
Domain | string

REQUIRED
Action | DOMAINS

Lists all domains we can see.

### COMPUTERS

#### <CFX_NetworkTopology ACTION="COMPUTERS">

FIELDS
Domain | string
Computer | string

REQUIRED
Action | COMPUTERS

Lists all computers that we can see and their domains.

### USERS

#### <CFX_NetworkTopology ACTION="USERS">

FIELDS
Domain | string
Computer | string
User | string
FullName | string
Description | string
Status | string

REQUIRED
Action | USERS

Lists all users in all the domains we can see.

Status is "Enabled" or "Disabled".

### GROUPS

#### <CFX_NetworkTopology ACTION="GROUPS">

FIELDS
Domain | string
Computer | string
Scope | string
Type | string
Group | string
Description | string

REQUIRED
Action | GROUPS

Lists all groups. Scope will be "Local" or "Global". Type will be "Security". (At some point later I'll add in the W2K Universal Groups and Distribution types, but the code is very tedoius. Use CFX_Groups for now ifyou really need to know.)

( NOTE: There was a short-lived pre-ihtk3.x "localgroups" function. That was deprecated for W2K-aware SCOPE usage used through-out all the other tags and Windows in general these days. The function was completely removed. Shocking I know, but... the tag was already 6,000 lines of code.... )

### SERVICES

#### <CFX_NetworkTopology ACTION="SERVICES">

FIELDS
Domain | string
Computer | string
Service | string
Description | string
Account | string
Status | string

REQUIRED
Action | SERVICES

Lists all services in all the domains. Determining the status of NT services is a little slow usually, so be forewarned.

Status can be: Enabled, Disabled, Pending, Error or Unknown.

### PRINTERS

#### <CFX_NetworkTopology ACTION="PRINTERS">

FIELDS
Domain | string
Computer | string
Printer | string
FullName | string
Description | string
LocalName | string

REQUIRED
Action | PRINTERS

Lists all printers in all the domains.

### SHARES

#### <CFX_NetworkTopology ACTION="SHARES">

FIELDS
Domain | string
Computer | string
Share | string
Description | string
Hidden | boolean

REQUIRED
Action | SHARES

Lists all shares in all the domains.

### DRIVES

#### <CFX_NetworkTopology ACTION="DRIVES">

FIELDS
Domain | string
Computer | string
Drive | string
Description | string
TotalSize | number
FreeSpace | number
SerialNumber | string
IsCompressed | boolean
IsRemovable | boolean
IsACL | boolean
IsUnicode | boolean
FileSystem | string
FilenameLengthLimit | number

REQUIRED
Action | DRIVES

Lists all (logical) drives on all known computers. Full information on the local computer can always be retrieved, however remote computers may or may not be configured so as to allow remote interrogation. In these cases FileSystem will be "Unknown" and only Domain, Computer and Drive will be valid.

FileSystem may currently be either "FAT", "FAT32", "NTFS", "CDFS", "Unknown", etc.

FilenameLengthLimit indicates the maximum length of all file names on the drive volume. IsUnicode is "1" if it is using 16-bit Unicode filenames (or old 8-bit ANSI style).

If IsACL is boolean "1" then the drive supports ACL (Access Control List) permissions.

As an aside, the usual way to find out about the local hard drives is to do a ThisComputer and compare it's Computer field to the Computer field of a drives query, looking for those that match. Generally you'll be looking for the appropriate filesystem (such as NTFS) as well.

Only members of the Administrators or Account Operators local group can successfully use "DRIVES" on remote computers. No special group membership is required to list local drives.

### SESSIONS

#### <CFX_NetworkTopology ACTION="SESSIONS">

FIELDS
Domain | string
Computer | string
User | string
Client | string
ConnectTime | days:hours:minutes:seconds
IdleTime | days:hours:minutes:seconds

REQUIRED
Action | SESSIONS

Lists all active sessions involving file services across the network on all known computers.

### LANS

#### <CFX_NetworkTopology ACTION="LANS">

FIELDS
Computer | string
LANA | number
MAC | machine address string
Type | string
Unavailable | number
Inactivity | number
Pending | number
MaximumPending | number
MaximumDatagramSize | number
Names | number
Description | string

REQUIRED
Action | LANS

Lists the local ethernet and token ring cards. Windows creates a "virtual" ethernet connection that includes a fake MAC address when an analog modem connection is established.

### COMErrorLookup

#### <CFX_NetworkTopology ACTION="COMErrorLookup">

FIELDS
HRESULT | hexidecimal number

Sends the error code off to the error reporting functions. Useful in having the tag decode COM related error codes you may encounter outside of the tag.

`top`

## C O M P O S I T E

### TOPOLOGY

#### <CFX_NetworkTopology ACTION="TOPOLOGY">

FIELDS
Domain | string
Computer | string
Name | string
Type | string
Status | string
Description | string

REQUIRED
Action | TOPOLOGY

Lists everything in all the domains as a flat sql query. This function is a bit network intensive. As I understand it, if you're on a dev machine testing you probably might want to go off line if you're using an analog modem, etc to speed things up.

Type can be: User, Group, LocalGroup, Printer, Service or Share.

Status can be: Enabled, Disabled, Pending, Error or Unknown. The default is Unknown.

`top`

## VERSION HISTORY

- 1.9 January 3rd 2001.

  Added IHTKPASSWORD. Upgraded reporting code.

- 1.8 December 3rd 2000.

  Added COMErrorLookup and upgraded error reporting to v1.3.

  CFX_NetworkTopology is released as FREEWARE. The full c/c++ source is now included.

- 1.7 October 2nd 2000.

  - Muted some cross-domain Services error messages.
  - Muted some cross-domain Topology error messages.
  - Added additional error messages to Drives to correctly report "access denied" situations.
- 1.6 September 29th 2000.

  - Fixed slight Drives bug that would not list remotes in some situations. Added several new features to drives while I was at it.
  - Fixed bug that let non-domain servers be listed.
  - Misc other things I forgot to log :)
  - Added the previously experimental LANs. It still needs work to make it robust, but otherwise seems stable.
  - Muted some error messages that would occur when a computer would go down off the lan.
- 1.5 September 19th 2000.

  Upgraded error reporting code to v1.2.

- 1.4 September 8th 2000.

  - Added misc experimentals. Do not use. Some may be added later. Some may not. They do not share code (except internal error handling) with any other functions.
  - Deprecated LocalGroups for SCOPE-aware Groups function.
  - Added Drives
  - Added Sessions
  - Added mode to ThisDomain

  Be aware that when playing with these functions over a modem-connected internet connection they can be a bit sluggished.

- 1.3 August 30nd 2000.

  Added NoStatus for Topology and cleaned up some of the functions' code.

- 1.2 August 26nd 2000.

  Added AudioAlert option to ThisSystem.

- 1.1 August 23nd 2000.

  - CPUTime was more properly the uptime of the computer, so renamed it.
  - Added CPUTime.
  - Misc doc fixes.
  - DomainControllers was not properly reporting roles. Fixed. added docs.
  - Tightened some code. In some cases functions are four times faster now. As to the question of if they are as stable as before... something we just have to wait and see.

  Univeral security groups and OUs might make an appearance later on.

  `Go Rudy.`
  `semper fi`

- 1.0 August 22nd 2000.

  Gamma. Drives, Network cards and Processes to be added one of these days when I have the time. Goal for next reversion is simply to prune the code and make it tighter and faster. It's a bit overly verbose at the moment.

- 0.0 August 18th 2000.

  First alpha. Next release adds docs, shares, drives, network adapters w/ MACs and IP bindings. Plus a general polish for gamma.

  Obsoletes thisserver, servers, domains, getprimarydomaincontrol, etc of CFX_UserManager and CFX_NFS.

`top`
`f i n i`
`-{ts '2001-12-03 03:35:33'} /ihtkdocs/NetworkTopology/index.cfm-`