Microsoft Programmer's Library 1.3

home *** CD-ROM | disk | FTP | other *** search

/ Microsoft Programmer's Library 1.3 / Microsoft_Programmers_Library.7z / MPL / net / lanpgmr.txt < prev next >

Wrap

Text File | 2013-11-08 | 1.7 MB | 46,508 lines

Text Truncated. Only the first 1MB is shown below. Download the file for the complete contents. Microsoft LAN Manager - Programmer's Reference ──────────────────────────────────────────────────────────────────────────── Microsoft(R) LAN Manager - Programmer's Reference Covers version 2.0 ──────────────────────────────────────────────────────────────────────────── Network APIs for MS(R) OS/2 and MS-DOS(R) Microsoft Corporation PUBLISHED BY Microsoft Press A Division of Microsoft Corporation One Microsoft Way, Redmond, Washington 98052-6399 Copyright (C)1990 by Microsoft Corporation. All rights reserved. Information in this document is subject to change without notice and does not represent a commitment on the part of Microsoft Corporation. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the license or nondisclosure agreement. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the written permission of Microsoft Corporation. Library of Congress Cataloging-in-Publication Data Microsoft LAN manager programmer's reference : network APIs for OS/2 and MS-DOS / Microsoft Corporation. p. cm. ─ (Microsoft OS/2 programmer's reference library) Includes index. ISBN 1-55615-313-9 1. Local area networks (Computer networks) ─ Computer programs. 2. Microsoft LAN manager (Computer program) 3. OS/2 (Computer operating system) 4. MS DOS (Computer operating system) I. Microsoft. II. Series. TK5105.7.M53 1990 90-41578 004.6'8'02855369 ─ dc20 CIP Printed and bound in the United States of America. 123456789FGFG43210 Distributed to the book trade in Canada by General Publishing Company, Ltd. Distributed to the book trade outside the U.S. and Canada by Penguin Books Ltd. Penguin Books Ltd., Harmondsworth, Middlesex, England Penguin Books Australia Ltd., Ringwood, Victoria, Australia Penguin Books N.Z. Ltd., 182-190 Wairau Road, Auckland 10, New Zealand British Cataloging in Publication Data available CodeView(R), Microsoft(R), MS(R), MS-DOS(R), XENIX(R), and the Microsoft logo are registered trademarks and Windows(tm) is a trademark of Microsoft Corporation. Apple(R) is a registered trademark of Apple Computer, Inc. 386(tm) is a trademark of Intel Corporation. IBM(R) is a registered trademark of International Business Machines Corporation. Novell(R) is a registered trademark of Novell, Inc. Writers: Lewis Campbell, Bruce Legge, John Murray, Barry Potter Contributors: Alec Barker, Paul Canniff, Liz Chalmers, Chuck Chan, Brendan Dixon, Helen Dolmas, Diane Friedman, Danny Glasser, Andy Held, Joe Holman, Jim Horne, Jeffery Howard, Jan Keller, Rustan Leino, Mark Lewin, Lesley Link, Pradyumna Misra, Yuval Neeman, Judy Nessen, Larry Osterman, Thomas Payne, Eric Peterson, A. J. Rizer, Kevin Schofield, Bharat Shah, Alok Sinha, Ed Stubbs, Lori Walker, Manny Weiser, William Wu, Sue Wyble, LAN Manager development team Document Number: OEM-D/P787-2Z Table of Contents ──────────────────────────────────────────────────────────────────────────── Before You Begin How to Use This Manual Notational Conventions For More Information Chapter 1 Overview of the LAN Manager API Identifying API Components API Function Names API Data Structure Names API Variable Names Including LAN Manager API Definitions Calling a LAN Manager API Function Calling Privileges Parameter Formats Using Buffers with API Functions Interpreting Return Codes Compiling and Linking Applications Debugging Tips Stack Overflow Errors in Hard-Coded Values Errors During Pointer Type Conversion MS OS/2 Protection Violations and Faults MS-DOS, Windows 2.x, and Real-Mode Windows 3.0 Applications Windows 3.0 Protected-Mode Applications Chapter 2 API Function Descriptions Format Reference Pages Access Permissions Category Description Data Structures NetAccessAdd NetAccessCheck NetAccessDel NetAccessEnum NetAccessGetInfo NetAccessGetUserPerms NetAccessSetInfo Access Permissions Category Example Alert Category Description Data Structures NetAlertRaise NetAlertStart NetAlertStop Alert Category Example Auditing Category Description Data Structures NetAuditClear NetAuditRead NetAuditWrite Auditing Category Example Character Device Category Description Data Structures NetCharDevControl NetCharDevEnum NetCharDevGetInfo NetCharDevQEnum NetCharDevQGetInfo NetCharDevQPurge NetCharDevQPurgeSelf NetCharDevQSetInfo Character Device Category Example Configuration Category Description NetConfigGet2 NetConfigGetAll2 Configuration Category Example Connection Category Description Data Structures NetConnectionEnum Connection Category Example Domain Category Description Data Structures NetGetDCName NetLogonEnum Domain Category Example Error Logging Category Description Data Structure Error Log Codes NetErrorLogClear NetErrorLogRead NetErrorLogWrite Error Logging Category Example File Category Description Data Structures NetFileClose2 NetFileEnum2 NetFileGetInfo2 File Category Example Group Category Description Data Structures NetGroupAdd NetGroupAddUser NetGroupDel NetGroupDelUser NetGroupEnum NetGroupGetInfo NetGroupGetUsers NetGroupSetInfo NetGroupSetUsers Group Category Example Handle Category Description Data Structures NetHandleGetInfo NetHandleSetInfo Handle Category Example Mailslot Category Description DosDeleteMailslot DosMailslotInfo DosMakeMailslot DosPeekMailslot DosReadMailslot DosWriteMailslot Mailslot Category Example Message Category Description Data Structures NetMessageBufferSend NetMessageFileSend NetMessageLogFileGet NetMessageLogFileSet NetMessageNameAdd NetMessageNameDel NetMessageNameEnum NetMessageNameFwd NetMessageNameGetInfo NetMessageNameUnFwd Message Category Example Print Destination Category Description Data Structures DosPrintDestAdd DosPrintDestControl DosPrintDestDel DosPrintDestEnum DosPrintDestGetInfo DosPrintDestSetInfo Print Destination Category Example Print Job Category Description Data Structures DosPrintJobContinue DosPrintJobDel DosPrintJobEnum DosPrintJobGetId DosPrintJobGetInfo DosPrintJobPause DosPrintJobSetInfo Print Job Category Example Printer Queue Category Description Data Structures DosPrintQAdd DosPrintQContinue DosPrintQDel DosPrintQEnum DosPrintQGetInfo DosPrintQPause DosPrintQPurge DosPrintQSetInfo Printer Queue Category Example Remote Utility Category Description Data Structures NetRemoteCopy NetRemoteExec NetRemoteMove NetRemoteTOD Remote Utility Category Example Server Category Description Data Structures NetServerAdminCommand NetServerDiskEnum NetServerEnum2 NetServerGetInfo NetServerSetInfo Server Category Example Session Category Description Data Structures NetSessionDel NetSessionEnum NetSessionGetInfo Session Category Example Share Category Description Data Structures NetShareAdd NetShareCheck NetShareDel NetShareEnum NetShareGetInfo NetShareSetInfo Share Category Example Statistics Category Description Data Structures NetStatisticsGet2 Statistics Category Example Service Category Description Data Structures NetServiceControl NetServiceEnum NetServiceGetInfo NetServiceInstall NetServiceStatus Service Category Example Use Category Description Data Structures NetUseAdd NetUseDel NetUseEnum NetUseGetInfo Use Category Example User Category Description Data Structures NetUserAdd NetUserDel NetUserEnum NetUserGetGroups NetUserGetInfo NetUserModalsGet NetUserModalsSet NetUserPasswordSet NetUserSetGroups NetUserSetInfo NetUserValidate2 User Category Example Workstation Category Description Data Structures NetWkstaGetInfo NetWkstaSetInfo NetWkstaSetUID2 Workstation Category Example Appendix A Return Codes Return Codes by Class LAN Manager and MS OS/2 Return Codes Appendix B Upgrading LAN Manager 1.0 Applications Table of API Changes Superseded API Functions Superseded Function Descriptions NetAuditOpen NetErrorLogOpen NetStatisticsClear NetStatisticsGet NetUserValidate NetWkstaSetUID Appendix C Creating LAN Manager Services A Simple Service How a Service Works Installing a Service Reporting Installation Status Disabling Standard Input and Output Parsing Service Parameters Installing the Signal Handler Spawning the Application Thread Completing Installation Handling Signals Example Service Appendix D Building the Sample Programs Building SAMPLES.LIB Building the Sample Programs Binding the Sample Programs Running the Programs SAMPLES.C SAMPLES.H Appendix E NetBIOS Category Description Data Structures NetBiosClose NetBiosEnum NetBiosGetInfo NetBiosOpen NetBiosSubmit NetBIOS Category Example Appendix F Network Considerations for Named Pipes Description MS-DOS Considerations Named Pipes Category Example Appendix G Workstation and Server Heuristics Workstation Heuristics Server Heuristics Appendix H Defined Constants Glossary Index Before You Begin ──────────────────────────────────────────────────────────────────────────── The Microsoft(R) LAN Manager application programming interface (API) is the set of functions, datatypes, structures, and constants that enable applications to use and control network resources. The Microsoft LAN Manager Programmer's Reference describes the components of the LAN Manager API. To use this book effectively, you should have a sound working knowledge of Microsoft Operating System/2 (MS(R) OS/2) and be familiar with systems programming in C or in assembly language. LAN Manager API functions work in essentially the same way with both the MS OS/2 and MS-DOS(R) operating systems. However, this book primarily addresses the MS OS/2 programming environment. Where appropriate, specific notes about MS-DOS are included. How to Use This Manual The Microsoft LAN Manager Programmer's Reference is intended to be your master reference for Microsoft LAN Manager API functions. For background information about using LAN Manager API functions, read Chapter 1, "Overview of the LAN Manager API," which provides an introduction to the LAN Manager API. Read Chapter 2, "API Function Descriptions," for information about specific LAN Manager API function categories and individual functions. The categories, and the functions within them, are arranged alphabetically. Read the appendixes for reference information about additional topics, such as return codes, constants, named pipes, workstation and server heuristics, and upgrading LAN Manager 1.0 applications. Use the glossary to find definitions of general network terms and specific LAN Manager terms. Notational Conventions This manual uses different type styles and special characters to distinguish elements of text: ╓┌─────────────────────────────────┌─────────────────────────────────────────╖ Convention Description ──────────────────────────────────────────────────────────────────────────── bold Represents function names and portions of syntax that must be typed exactly as shown. italics Used for variables (such as parameter names) and text that represents the type of text to be entered rather than a literal series of characters. Also used for data structure names and names of data structure elements. monospace Used for data structure syntax, API function syntax, and code examples. FULL CAPITALS Represent filenames and pathnames. SMALL CAPITALS Used for return codes and constants. Convention Description ──────────────────────────────────────────────────────────────────────────── [brackets] Represent optional items in syntax statements. For example, [password] indicates a password can be used with the command but is not required. Type only the information within the brackets, not the brackets themselves. . . . (ellipsis) Indicates that you can repeat the previous item(s). For example, devicename [. . .] indicates that you can specify more than one device, separating the devicenames with a space. ──────────────────────────────────────────────────────────────────────────── For More Information This manual gives general information about using the LAN Manager API, and it details the individual components of the LAN Manager API. For information about LAN Manager features, see your LAN Manager administrator's manual(s). For information about MS OS/2, see your MS OS/2 programming manual(s). For information about Microsoft Windows(tm), see your Microsoft Windows programming manual(s). Chapter 1 Overview of the LAN Manager API ──────────────────────────────────────────────────────────────────────────── The Microsoft LAN Manager application programming interface (API) is the set of functions, datatypes, structures, and constants that allow applications to use and control network resources. This chapter describes how to create applications that call the LAN Manager API functions. You will learn the following: ■ How to identify API functions, data structures, and variables ■ How to include API definitions in your application ■ How to call a LAN Manager API function ■ How to compile and link LAN Manager applications ■ Tips for debugging LAN Manager applications For a detailed description of each LAN Manager API function and data structure, see Chapter 2, "API Function Descriptions." Identifying API Components The purpose of LAN Manager API functions, data structures, and variables is encoded in their names. All function names and data structure names include the name of the network resource. LAN Manager API functions and data structures (and this manual) are organized by these categories of network resources: (This figure may be found in the printed book.) API Function Names LAN Manager API function names have at least three parts: a keyword (Dos or Net), the name of the network resource manipulated by the function, and a verb that identifies the action performed on the network resource. For example, the API function name NetUserAdd consists of the keyword Net, the category User, and the verb Add. Functions in the User category control user accounts. Add indicates that the NetUserAdd function adds a user to the user accounts database. Some verbs appear in many categories: Add adds a resource, Del deletes a resource, Enum lists all resources of a particular type, GetInfo returns information about one particular resource, and SetInfo sets one or all parameters for a particular resource. Other verbs describe familiar operations, such as Read, Write, Open, Clear, and Close. Some verbs describe tasks that are specific to network resources, such as Purge (for a communication-device or printer queue), Forward (for a message name), and Raise (for an alert). An API function name can also contain an optional fourth part: the object of the action. For example, the API function NetGroupDelUser deletes a user from the specified group. This function differs from NetGroupDel, which deletes the specified group from the user accounts database. API Data Structure Names LAN Manager API functions use one or more data structures associated with each network resource. A data structure name usually contains three parts: the name of the resource, the word info, and the level of detail. For example, the name share_info_0 indicates that the data structure contains information about a share (shared resource) at level 0. LAN Manager API functions can accept or return information at different levels of detail. Level 0 usually means the least detailed information (often a single element). Level 1 usually includes all information provided at level 0 plus additional data. A higher level of detail often (but not always) indicates that the data structure is a superset of data structures provided at lower levels of detail. For complete information about available levels and data structures, see the "Data Structures" section for each function category in Chapter 2, "API Function Descriptions." The three data structures of the Share category illustrate the levels of detail. The share_info_0 data structure contains only the sharename of a particular resource: struct share_info_0 { char shi0_netname[NNLEN+1]; }; The constant NNLEN is defined in the NETCONS.H header file, along with other constants that also specify string lengths. The share_info_1 data structure contains not only the sharename of the resource, as provided at level 0, but also its type and an optional remark. The shi1_pad1 element is used only to align the next structure element (shi1_type) on a word boundary. Pad elements should not be used to store data. struct share_info_1 { char shi1_netname[NNLEN+1]; char shi1_pad1; unsigned short shi1_type; char far * shi1_remark; }; The share_info_2 data structure contains all information present in the share_info_1 data structure plus additional information about the sharename permissions, path, password, and the number of current and maximum uses: struct share_info_2 { char shi2_netname[NNLEN+1]; char shi2_pad1; unsigned short shi2_type; char far * shi2_remark; unsigned short shi2_permissions; unsigned short shi2_max_uses; unsigned short shi2_current_uses; char far * shi2_path; char shi2_passwd[SHPWLEN+1]; char shi2_pad2; }; API Variable Names The variable names used in the API function prototypes follow the Microsoft LAN Manager naming convention. These rules help anyone reading the code identify the type and purpose of the variable. Although this naming convention is not required to success- fully call the API functions, it is recommended because it helps make applications more readable and improves programming quality. Using the LAN Manager naming convention, variable names have three parts: a prefix, a base type, and a qualifier. The prefix and base type are always written in lowercase characters. From the prefix and base type, you can easily determine the type of a variable. Prefix - The prefix provides information about the variable type, such as whether it is an array, count, index, or pointer. Prefixes can be combined (for example, an array of pointers to indexes). If the base type completely describes the variable, the variable name does not need a prefix. The following prefixes are used in this manual: Prefix Description Example ──────────────────────────────────────────────────────────────────────────── a Array char achFileName[ ] c Count unsigned short cbAvail i Index unsigned short iArgv p Pointer unsigned char * pszServer ──────────────────────────────────────────────────────────────────────────── Base Type - The base type corresponds to the C-language type. For example, ch is used for character, l for long, and s for short. The following base types are used in this manual: ╓┌──────────┌───────────────────────┌───────────────┌────────────────────────╖ Base Type Description Example ──────────────────────────────────────────────────────────────────────────── b Byte unsigned char bMenuSel ch Character char chDriveLetter f Boolean flag unsigned short fSuccess h Handle unsigned short hLogFile l Long integer long lSeconds s Short integer short sIdNumber sz Zero-terminated string char szRemark[ ] uch Unsigned character unsigned char uchBitMask ul Unsigned long unsigned long ulSeconds us Unsigned short unsigned short usReturnCode ──────────────────────────────────────────────────────────────────────────── Qualifier - The qualifier is a short word or phrase that indicates how the variable is used. The qualifier can use both uppercase and lowercase characters; the first letter of each word is capitalized. For example, the qualifier Available suggests that the variable has to do with some resource that is available. The prefix and base type help pinpoint the variable's meaning. If the complete variable name is cbAvailable, the name suggests the variable contains a count of available bytes. The variable name fAvailable suggests that the variable is a Boolean flag that indicates whether the resource is available. For a description of the naming convention used with MS OS/2, see your MS OS/2 programming manual(s). Including LAN Manager API Definitions LAN Manager API function and data structure definitions are organized by category. Your source program can include all the definitions needed for a particular category of network resources by using the C-language #define statement for that category and the #include <lan.h> statement. The LAN.H header file is the master file of the set of LAN Manager header files. LAN.H is the LAN Manager equivalent of OS2.H, the MS OS/2 master header file. When a constant is defined in your source file, the LAN.H file includes all the header files associated with that category. You should define constants for only those resource categories used in your application. For example, use these statements to provide access to all functions, datatypes, structures, and constants associated with workstations, and to all LAN Manager error codes: #define INCL_NETWKSTA #define INCL_NETERRORS #include <lan.h> Programs that use the LAN.H master header file can be more easily maintained than programs that specify individual header files. For examples of how to use the LAN.H header file, see the "Example" section at the end of each category in Chapter 2, "API Function Descriptions." The following table lists each LAN Manager API category and the constants that must be defined to include definitions associated with that category: ╓┌──────────────────────────────────┌────────────────────────────────────────╖ Category #define Constant ──────────────────────────────────────────────────────────────────────────── All categories except print INCL_NET Errors for all categories INCL_NETERRORS Access Permissions INCL_NETACCESS Alert INCL_NETALERT Audit INCL_NETAUDIT Character Device INCL_NETCHARDEV Configuration INCL_NETCONFIG Connection INCL_NETCONNECTION Domain INCL_NETDOMAIN Error Logging INCL_NETERRORLOG File INCL_NETFILE Group INCL_NETGROUP Handle INCL_NETHANDLE Mailslot INCL_NETMAILSLOT Message INCL_NETMESSAGE Category #define Constant ──────────────────────────────────────────────────────────────────────────── Message INCL_NETMESSAGE NetBIOS INCL_NETBIOS Print (Uses #include <pmspl.h>) Remote Utility INCL_NETREMUTIL Server INCL_NETSERVER Service INCL_NETSERVICE Session INCL_NETSESSION Share INCL_NETSHARE Statistics INCL_NETSTATS Use INCL_NETUSE User INCL_NETUSER Workstation INCL_NETWKSTA ──────────────────────────────────────────────────────────────────────────── Note that the categories relating to printer resources cannot be included using this method. The structures and definitions for printer resources are defined in the PMSPL.H header file. An application should include this header file by using an #include statement: #include <pmspl.h> Calling a LAN Manager API Function An API function call can succeed if the application has privilege to call that API function and if the application provides all necessary parameters in the correct format. One parameter required by many API functions is a pointer to a buffer. If the buffer is used for input data, it must contain the correct data; if the buffer is used for output data, it must be large enough to contain the data returned by the API function. The application may need to examine the codes returned by the API function and take specific action. Calling Privileges LAN Manager API functions check security on servers that have local security enabled and on remote servers. If local security is not enabled, LAN Manager does no local checking. The accounts database, NET.ACC, contains information about all users who are allowed access to the computer's resources. Three privilege levels are defined: admin, user, and guest. An account with user privilege can also have up to four types of operator privilege (an operator privilege allows a user to perform some limited administrative functions). An account with user privilege can have the print, comm, server, and accounts operator privileges. For remote computers and local computers running a secure shell or other form of local security, each API function verifies that the user has sufficient privilege to execute the function. For more information about security and privilege levels, see your Microsoft LAN Manager administrator's manual(s). If your account does not have correct privilege levels, contact your system administrator. The privilege level required for each API function is specified in Chapter 2, "API Function Descriptions." Parameter Formats The parameters needed to successfully call each LAN Manager API function are defined in Chapter 2, "API Function Descriptions." Many parameters required by the API functions are ASCIIZ strings that represent names such as computernames, sharenames, usernames, and pathnames. (An ASCIIZ string is a sequence of ASCII characters terminated by the ASCII character NUL, the C-language character constant '\0'. Remember to allow for the final NUL when calculating string and buffer lengths.) One of the most common parameters required by LAN Manager API functions is a servername. This parameter usually appears first in the API function call and is specified in the function prototypes as pszServer. The servername parameter specifies whether the function call is a local or remote call. A null pointer or null string indicates that the operation is to be performed on the local computer. An ASCIIZ string containing the servername must start with two backslash characters (\\). Because the backslash is a special character in the C language, you must use additional backslashes when specifying servernames. For example, to specify the remote server named MARKETING in a C-language program, use the following: pszServer = "\\\\MARKETING"; Other parameters in LAN Manager API functions follow two naming conventions: one for pathnames and one for all other names. Pathnames generally follow the naming convention of the installed file system. The convention for all other names is very similar to the convention used for file allocation table (FAT) file system names. These naming conventions are usually enforced only by Add functions. For example, if the supplied name is incorrect, Add functions return an error message that indicates an improper name was used; GetInfo functions usually return an error that indicates the resource was not found. Length Restrictions - The file system defines the maximum length of the pathname. The FAT file system supports names that have up to eight characters, an optional period (.), and an optional filename extension with as many as three characters. This is often called the "8.3" format. The high-performance file system (HPFS) supports longer names. The MS OS/2 function DosQSysInfo can be used to determine the maximum path length. For more information, see your MS OS/2 programming manual(s). The maximum lengths of other names are defined by constants in the NETCONS.H header file. For example, sharenames are limited to the number of characters specified by the constant value NNLEN, defined in NETCONS.H. For more information, see Appendix H, "Defined Constants." Character Restrictions - The file system also defines the set of characters allowed in network names. The FAT file system has the most restrictive rules and HPFS has the least restrictive rules. Network names cannot use nonprinting ASCII characters (characters 0x00 through 0x1F) or any characters recognized as special characters by the operating system command shell. The following characters are not allowed in network names on a computer that has the FAT file system installed: \ / : * ? " < > | , + = [ ] ; The following characters are not allowed in network names on a computer that has HPFS installed: \ / : * ? " < > | The period (.) is allowed in pathnames as permitted by the file system. It is also allowed in other network names. The asterisk (*) is allowed as part of the network name by some Mailslot category API functions. For more information, see the Mailslot category functions in Chapter 2, "API Function Descriptions." Using Buffers with API Functions Many API functions require a pointer to a buffer. This pointer parameter is often associated with other parameters that indicate the level of detail provided in the buffer, the size of the buffer, the amount of data successfully returned in the buffer, and the amount of data that was available to be returned in the buffer. The buffer can be used for both output and input. GetInfo and Enum functions use the buffer for return data; Add and SetInfo functions use the buffer for input. Buffers for Return Data - GetInfo and Enum functions return data in the supplied buffer. GetInfo functions return information about a single resource; Enum functions return information about all instances of the resource type. The supplied buffer should be large enough to contain all data returned by the API function. This data usually consists of fixed-length and variable-length elements. Fixed-length elements have a known, defined size; variable-length elements are allowed to vary, up to a maximum length. (For example, ASCIIZ strings are variable-length elements.) If the buffer cannot hold all available data, the API function returns a code that indicates more information is available. Even if the buffer is too small, GetInfo functions report the available number of bytes, and Enum functions return the number of records. Applications that must optimize memory use can make two calls to these functions. So that the application can allocate a buffer large enough to hold the return data, the first call determines the size of the buffer needed to hold the return data. The second call can then fill the buffer with data. For example, if the application supplies a null buffer pointer and a buffer length of 0, the first GetInfo call returns the code NERR_BufTooSmall, but also returns a pcbTotalAvail value that indicates the size of the return data (in bytes). The application can then allocate a buffer this size and make a second GetInfo call with valid buffer pointer and size values. GetInfo and SetInfo functions are commonly used together. You can call the GetInfo function to learn the value of the parameters associated with the resource, then change the values of the parameters and call the SetInfo function to set the new values. Buffers for Input Data - Add and SetInfo functions set information about a network resource. These functions require a parameter that points to a buffer (pbBuffer); this buffer parameter is associated with other parameters that represent the level of detail (sLevel) and the buffer size (cbBuffer). SetInfo functions also require a parameter number code (sParmNum) that specifies whether to set a single element or all elements of the data structure for the resource. If sParmNum is PARMNUM_ALL, all elements are to be set, and pbBuffer should point to a buffer that contains the complete data structure at the specified level. If sParmNum is any other defined value, it should contain a code that specifies the single element of the data structure to be set, and pbBuffer should point to a variable that contains the new value for that element. Add and SetInfo functions that specify a remote server will successfully transmit variable-length data only if the pointers point outside the supplied data buffer. This optimizing technique for remote calls minimizes the amount of data transmitted over the network. The buffer is determined by the pbBuffer and cbBuffer parameters. To assure that the data is transmitted, the buffer size can be set to the size of the fixed-length data structure, or all pointers can be reset to point to data that is not within the buffer. To change a string to an empty string, you must use a valid pointer to an empty string rather than using a null pointer. If a null pointer is used in a SetInfo call, the string is not changed. Interpreting Return Codes The name of the return code suggests the result. For example, NERR_ServerNotStarted means, as the name suggests, that the Server service must be started for the API function to succeed. The return code NERR_BadTransactConfig indicates that a server is not configured to allow interprocess communication. The description for this return code explains that to allow remote API function requests, the server must share IPC$ (the special interprocess communication resource). Typical return codes for each function are included with that function's description in Chapter 2, "API Function Descriptions." Appendix A, "LAN Manager Return Codes," lists all codes that can be returned by LAN Manager API functions. For your con- venience, some MS OS/2 return codes are given; for more information about MS OS/2 return codes, see your MS OS/2 programming manual(s). Descriptions of return codes are also available using the MS OS/2 DosGetMessage function. If you supply the return code and the LAN Manager error message file NET.MSG as parameters, DosGetMessage returns a string that contains a description of the return code. For more information about DosGetMessage, see your MS OS/2 programming manual(s). For an example, see the Session category example program in Chapter 2, "API Function Descriptions." In a few cases, a code returned by an API function has a meaning that is relevant only for that API function. The "Remarks" section of each API function description in Chapter 2, "API Function Descriptions," describes how to interpret the return codes in these special cases. Return Codes Relating to the Buffer - The return codes NERR_BufTooSmall and ERROR_MORE_DATA are related not only to the buffer, but also to the buffer size and the byte count or record count parameters. If the buffer is too small to store the fixed-length part of the data record, GetInfo functions return NERR_BufTooSmall. In this case, all data in the return buffer is invalid, but the count of available data bytes, pcbTotalAvail, is valid. The application can use the value of pcbTotalAvail to allocate a buffer large enough to contain the return data, and then make another GetInfo call to obtain the data. If the fixed-length part of the data record does fit but the variable-length part does not fit, GetInfo functions return ERROR_MORE_DATA, and all pointers to variable-length parts are set to NULL. If the available data cannot fit in the supplied buffer, Enum functions return the code ERROR_MORE_DATA. In this case, the Enum function stores in the return buffer as many complete data records as possible (both the fixed-length and variable-length parts). If the complete data record cannot be returned, the function tries to store its fixed-length part in the buffer. If only the fixed-length part fits, the function sets all pointers to variable-length parts to NULL, and then returns ERROR_MORE_DATA. When ERROR_MORE_DATA is returned by an Enum function, the value returned in pcEntriesRead does not necessarily represent the number of complete records in the buffer; it may represent the number of complete records and records that contain only the fixed-length element. In this case, all fixed-length data in the buffer is valid and the value of pcTotalEntries is valid, but some pointers to variable-length data may have been set to NULL if the variable-length data did not fit in the buffer. Compiling and Linking Applications LAN Manager applications can be compiled like any other applications for the target operating system. For example, Microsoft Windows applications compiled with the Microsoft C Optimizing Compiler should use the -Gw switch. The application should be linked with the libraries that contain the LAN Manager API functions. These functions reside in static-link or dynamic-link libraries. The type of link library used depends on the operating system used by the application (MS-DOS, Microsoft Windows 2.x, Microsoft Windows 3.0, MS OS/2 1.1, or MS OS/2 1.2). LAN Manager operates in similar ways with MS OS/2, MS-DOS, and Windows, although the operating system allows more functionality when LAN Manager operates with MS OS/2. MS OS/2 supports multiple program threads and all LAN Manager services; when installed with HPFS, MS OS/2 also supports long file names. MS-DOS and Windows support only one program thread, FAT "8.3" filenames, and the Messenger, Netpopup, and Workstation services. In systems with MS-DOS, the LAN Manager API functions reside in the static-link library DOSLAN.LIB. MS-DOS applications are linked with static-link libraries in one step at link time. Only one library is needed. In systems with MS OS/2 and Windows, the LAN Manager API functions reside in the dynamic-link library (.DLL) file. Note that Microsoft Windows 2.x dynamic-link libraries use the file extension .EXE instead of .DLL. More than one link library may be needed for these operating system platforms, depending on the platform and the LAN Manager API functions called by the application. The Print category API functions reside in the PMSPL library; all other API functions reside in the LAN library. These are the link libraries: Dynamic-Link Platform Import Library Library Function Category ──────────────────────────────────────────────────────────────────────────── MS OS/2 1.2 PMSPL.LIB PMSPL.DLL Print categories. LAN.LIB NETAPI.DLL All other categories. MAILSLOT.DLL NETOEM.DLL MS OS/2 1.1 NETSPOOL.LIB NETSPOOL.DLL Print categories. LAN.LIB NETAPI.DLL All other categories. MAILSLOT.DLL NETOEM.DLL Windows 3.0 PMSPL.LIB PMSPL.DLL Print categories. LAN.LIB NETAPI.DLL All other categories. Windows 2.x PMSPL.LIB PMSPL.EXE Print categories. LAN.LIB NETAPI.EXE All other categories. ──────────────────────────────────────────────────────────────────────────── Debugging Tips Incorrect buffer sizes and incorrect input parameters often cause software flaws in applications that call LAN Manager API functions. The following sections discuss some common problems and give some tips for debugging LAN Manager applications. Stack Overflow When calling LAN Manager API functions, be sure that at least 4 kilobytes (K) of stack is available, or the API function may exceed the stack limits and cause the application to fail. MS OS/2, MS OS/2 Presentation Manager, and Microsoft Windows also have their own minimum stack size requirements. LAN Manager applications using these platforms require an additional 4K of stack. Errors in Hard-Coded Values The LAN Manager header files define symbolic constants for bit values, mask values, and return codes. You should always use these defined constants instead of hard-coded numeric values. The use of symbolic constants makes an application program easier to debug and maintain. Errors During Pointer Type Conversion LAN Manager API functions, like MS OS/2 API functions, must be referenced using far calls. LAN Manager API function pointer parameters are defined as far pointers in the function prototypes. Other common software flaws can be avoided if you use LAN.H to access the LAN Manager header files. If you include the LAN Manager header files in small or medium memory model programs, all pointer parameters to LAN Manager API functions are promoted to far pointers. You should be aware that values for null pointers can be different for far and near pointers. Null far pointers have the segment:offset value 00:00; most compilers promote near pointers that have the value NULL to far pointers that have the value DS:00. Even when the program explicitly casts the near pointer as a far pointer before the LAN Manager API function call, the pointer is converted to the value DS:00. LAN Manager API functions have been designed to avoid many bugs resulting from pointer promotion. The API functions accept either a null string or a null pointer for the servername parameter. This takes advantage of a feature of many compilers: the compiler places four bytes containing the value 0 at the location DS:00. Although the near pointer promoted to a far pointer may no longer be a null pointer, it points to the location DS:00, which contains a null string. To avoid software flaws, use the symbolic constant NULL rather than the value 0, as shown in the following example: if ((p = malloc(SOME_SIZE)) == NULL) ... MS OS/2 Protection Violations and Faults MS OS/2 runs under protected mode. In protected mode, each process on a computer is protected from errors generated by another process. Software flaws in an application that might crash a system with MS-DOS are trapped by MS OS/2 as process-specific protection violations and faults. This fault may stop that process but will not affect other programs. Protection violations and faults in the LAN Manager API dynamic-link libraries are often caused by invalid input parameters and invalid buffer length values. When API functions access invalid data, MS OS/2 generates a protection fault. For example, a fault can occur if a pointer points beyond the end of a segment or outside a valid memory region. If a fault occurs within a LAN Manager dynamic-link library, check the values of the parameters passed to the API function. MS-DOS, Windows 2.x, and Real-Mode Windows 3.0 Applications Invalid pointer data can cause unpredictable results in LAN Manager applications with MS-DOS, Microsoft Windows 2.x, and real-mode Microsoft Windows 3.0 applications. Windows manages memory resources to optimize memory use and performance. Like any other Windows application, a LAN Manager application should carefully monitor its use of pointers. If Windows moves a data segment as part of its memory management, pointers may no longer be valid; you should lock all buffers before passing them to LAN Manager API functions. For more information, see your Microsoft Windows programming manual(s). Windows 3.0 Protected-Mode Applications Applications written for Microsoft Windows 3.0 can be executed in protected mode. Software flaws in applications running with Windows 3.0 protected mode cause the application to terminate, and control is returned to Windows 3.0. The user is notified of an unrecoverable program error. Software flaws in LAN Manager applications running with Microsoft Windows 3.0 protected mode are often caused by invalid input parameters, invalid buffer lengths, and invalid pointer values. If an error occurs, check the values of the parameters passed to the API functions. Chapter 2 API Function Descriptions ──────────────────────────────────────────────────────────────────────────── This chapter provides detailed information about each LAN Manager application programming interface (API) function. It describes the syntax of each API function, describes operations the API function performs, and lists the data structures and header files the function uses. This chapter is divided into sections according to API function category. The following function categories are presented in this chapter: (This figure may be found in the printed book.) Each category begins with an overview that explains how the API functions in that category interrelate and how they work with LAN Manager. Data structures common to several or all of the functions are described. A detailed description of each API function follows the overview, and includes the operating system platforms supported by the API function, the privilege level required to successfully execute the API function, the function's syntax, and a detailed description of each parameter. The most common error codes returned by the function are also listed. A list of all error codes returned by the LAN Manager API functions is provided in Appendix A, "Return Codes." At the end of each section you will find an example that demonstrates calls to the API functions in that category. The category sections and the entries within them are ordered alphabetically. To make information easy to find and use, each category and each API within the category begins on a new page. The functionality of some LAN Manager API functions is different in LAN Manager 2.0 from LAN Manager 1.0. Some 1.0 functions are no longer supported, and some 1.0 functions, although still supported by LAN Manager 2.0, have been superseded by new functions and should not be used. For information about the functions that have changed, see Appendix B, "Upgrading LAN Manager 1.0 Applications." The NetBIOS category is presented in Appendix E, "NetBIOS Category." It is recommended that you use Mailslot and Named Pipe API functions in LAN Manager 2.0 instead of the NetBIOS API functions. Format Reference Pages This section illustrates what you will see in each API function description. API Function The description of each API function begins with a general description of the purpose of the API function. Operating Systems Supported This section indicates whether the API function can be used remotely, locally only, or if it is not supported by a particular operating system. Privilege Level This section indicates the privilege level a user must have to execute this particular API function. Syntax This section lists the constants that must be defined so that the LAN.H header file will include the appropriate definitions. It also describes, in sequence, each of the parameters required to successfully call the API function. Return Codes This section lists the return codes the API function is most likely to return. Note that this list is not exhaustive. For a complete list of LAN Manager return codes, see Appendix A, "Return Codes." Remarks This section describes important details about the performance of the API function. You should take these details into consideration so your application can successfully call the API function and efficiently use its results. See Also This section refers you to other sections or chapters in this manual or to other manuals that may help you better understand and use the API function. Access Permissions Category Access Permissions API functions examine or modify user or group access permissions for specified resources. Access Permissions API functions require that the user account subsystem (UAS) be started. On most computers the UAS is started when the Workstation service is started, provided a valid user accounts database file exists. On computers using the high-performance file system 386 (HPFS386) with local security enabled, the UAS is started automatically as part of the boot process. The Access Permissions category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and ACCESS.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETACCESS, and including the master header file, LAN.H. For more information, see the "Example" section, later in this category. These are the Access Permissions API functions: ■ NetAccessAdd ■ NetAccessCheck ■ NetAccessDel ■ NetAccessEnum ■ NetAccessGetInfo ■ NetAccessGetUserPerms ■ NetAccessSetInfo Description An access control list (ACL) contains the name of a resource, an audit attribute field, and a list of access control entries. An access control entry (ACE) is a username or groupname and its corresponding access permissions. The audit attribute field defines what type of events will be audited for that resource. It is possible to audit various types of events, depending on whether the resource is a file or a directory. It is possible to audit events such as opening, writing, and deleting a file; creating or deleting a directory; and changing the ACL of the resource. There is no restriction on the number of ACLs for computers using HPFS386. Computers not using HPFS386 can have as many as 8192 ACLs defined. Each ACL can have as many as 64 ACEs. By default, non-admin class users have no access permissions. For a non-admin class user to access a resource on a remote server that has user-level security enabled or on a computer that has local security, there must be an ACL for the resource and there must be an ACE for the user. If local security is not enabled, non-admin class users can access all local resources. A user with admin privilege can access all resources, both local and remote, because LAN Manager does not check ACLs for this class of user. Access permission for a resource is determined according to the following rules: ■ File permissions override directory permissions. If a user is assigned specific permissions for a file, directory level permissions no longer apply to that file. ■ Individual permissions override group permissions. If a user is assigned specific individual permissions, group permissions no longer apply. ■ Group permissions are combined. If a user belongs to more than one group, the permissions are all the permissions for the groups to which the user belongs. ■ Access is checked for the guest user when there is no ACE for the user or for any groups to which the user belongs. If the guest account exists and has access to the resource, the user is granted that same level of access. Access permission is checked on three levels for file-system resources: first, the resource itself; then the parent of the resource; then the drive on which the resource is located. For example, in checking permission for the resource C:\XXX\YYY\ZZZ, the resource C:\XXX\YYY\ZZZ is searched for, then C:\XXX\YYY is searched for, and finally C: is searched for. Note that the last check is on the drive-level permissions, not the root directory of the drive. Access permission is also checked on three levels for logical resources: first, the resource itself; then the parent of the resource; then the root of the resource. For example, in checking permission for the resource \PIPE\XXX\YYY\ZZZ, the resource \PIPE\XXX\YYY\ZZZ is searched for, then \PIPE\XXX\YYY is searched for, and finally \PIPE is searched for. NetAccessAdd creates an ACL for a resource and sets username or groupname access permissions. NetAccessDel deletes the ACL for a resource. NetAccessGetInfo returns the ACL for a particular resource. NetAccessEnum returns information about all ACLs. Only users or applications with admin privilege or special permission for the resource can define or examine access permissions on a remote server or on a computer that has local security. Users have special permissions for a resource when they are granted ACCESS_PERM permission for that resource; this is also known as P permission. NetAccessCheck verifies whether a user has permission to perform a specified operation on a particular resource. If access permission is needed, you can use NetAccessSetInfo to change the ACL. NetAccessGetUserPerms returns a specified user's or group's permission for a specified resource. Note that the ACL does not specify permissions on a server that has share-level security. Each resource is verified on a share-by-share basis (each shared resource has its own password). After establishing a connection to a shared resource (by providing the appropriate password), users can access the resource any way they choose, as defined by the resource. All Access Permissions API functions executed on a remote server require that the server have user-level security. An attempt to execute an Access Permissions API function on a remote server that has share-level security returns the ERROR_NOT_SUPPORTED error code. Data Structures The sLevel parameter controls the level of information provided to or returned from the NetAccessAdd, NetAccessEnum, NetAccessGetInfo, and NetAccessSetInfo functions. NetAccessEnum and NetAccessGetInfo use either an access_info_0 or access_info_1 data structure. NetAccessAdd and NetAccessSetInfo use only an access_info_1 data structure. Access Permissions Information (level 0) The access_info_0 data structure has this format: struct access_info_0 { char far * acc0_resource_name; }; where acc0_resource_name Points to an ASCIIZ string that contains the name of a resource. The resource name cannot be a null string. Resources can be of the following types, and are specified using the associated name format: ╓┌────────────────────────┌────────────────────────┌─────────────────────────╖ Resource Type Name Format Comment ──────────────────────────────────────────────────────────────────────────── Drive drive: No path is specified; the drive must exist. Path \path No drive is specified; the path need not exist. Directory drive:\pathname The path must exist. File drive:\pathname The file must exist. UNC \\server\sharename\path The path must exist. Pipe \pipe\pipename Printer queue \print\queuename Communication-device \comm\chardevqueue queue Resource Type Name Format Comment ──────────────────────────────────────────────────────────────────────────── queue ──────────────────────────────────────────────────────────────────────────── Calls to Access Permissions functions can also use the universal naming convention (UNC) to access a device, computer, or resource over the network (for example, \\server\sharename\file.ext is a UNC name). If a UNC name is given, the function ignores any servername given in the pszServer parameter. Access Permissions Information (level 1) The access_info_1 data structure has this format: struct access_info_1 { char far * acc1_resource_name; short acc1_attr; short acc1_count; }; where acc1_resource_name Points to an ASCIIZ string that specifies the name of a particular resource. For more information, see the preceding section. acc1_attr Specifies the auditing attributes of acc1_resource_name. If acc1_attr is 0, no auditing is required. If acc1_attr is 1, all access events should be audited. Other values indicate auditing of specific access events, as defined by the bits of acc1_attr, as follows: ╓┌──────┌──────────────────────────────────────────────┌─────────────────────╖ Bit Files Directories ──────────────────────────────────────────────────────────────────────────── 0 Audit all. When this bit is set, all access Same. attempts are audited. No other bits in the Bit Files Directories ──────────────────────────────────────────────────────────────────────────── attempts are audited. No other bits in the field can be set at the same time. 1-2 Reserved; must be 0. Reserved; must be 0. 3 Ignored. Reserved. 4 Successful opens. Reserved. 5 Successful writes. Successful creates. 6 Successful deletes/truncates. Successful deletes. 7 Successful ACL changes. Same. 8 Failed opens. Reserved. 9 Failed writes. Failed creates. Bit Files Directories ──────────────────────────────────────────────────────────────────────────── 10 Failed deletes/truncates. Failed deletes. 11 Failed ACL changes. Same. 12-15 Reserved; must be 0. Reserved; must be 0. ──────────────────────────────────────────────────────────────────────────── Other resources that can be accessed over the network, including printer queues, communication-device queues, and pipes, are audited the same way as files. When write auditing is enabled, the write audit record is generated the first time the record is opened with write permission. File size changes (including truncation) are audited under the control of the write audit bits, 5 and 9. acc1_count Specifies the number of access_list data structures that follow the access_info_1 data structure. As many as 64 access_list data structures can follow. The access_list structures define resource permissions for individual users or groups. Resource Permissions The access_list data structure has this format: struct access_list { char acl_ugname[UNLEN+1]; char acl_ugname_pad_1; short acl_access; }; where acl_ugname Specifies an ASCIIZ string that contains a particular username or groupname. The constant UNLEN is defined in the NETCONS.H header file. acl_ugname_pad_1 Aligns the next data structure element on a word boundary. acl_access Specifies the permissions for the username or groupname. The ACCESS.H header file defines these possible values: ╓┌──────────────┌───────┌────────────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ACCESS_READ 0x01 Permission to read data from a resource and, by default, execute the resource. ACCESS_WRITE 0x02 Permission to write data to the resource. ACCESS_CREATE 0x04 Permission to create an instance of the resource (for example, a file); data can be written to the Code Value Meaning ──────────────────────────────────────────────────────────────────────────── (for example, a file); data can be written to the resource when creating it. ACCESS_EXEC 0x08 Permission to execute the resource. ACCESS_DELETE 0x10 Permission to delete the resource. ACCESS_ATRIB 0x20 Permission to modify the resource's attributes (for example, the date and time a file was last modified). ACCESS_PERM 0x40 Permission to modify the permissions (read, write, create, execute, and delete) assigned to a resource for a user or an application. ACCESS_ALL 0x7F Permission to read, write, create, execute, or delete a resource, or to modify attributes or permissions. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ACCESS_GROUP 0x8000 Permission for a particular group; this value indicates that the entry is for a group. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Connecting to resources Use Category Sharing resources Share Category NetAccessAdd ──────────────────────────────────────────────────────────────────────────── NetAccessAdd creates a new access control list (ACL) for a resource. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege is required to successfully execute NetAccessAdd on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETACCESS #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAccessAdd (const char far * pszServer, short sLevel, char far * pbBuffer, unsigned short cbBuffer ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetAccessAdd. A null pointer or null string specifies the local computer. sLevel Specifies the level of detail provided; must be 1. pbBuffer Points to the buffer that contains the data to be added. The buffer should contain an access_info_1 data structure that specifies the name of the resource for which to create an ACL, the resource's audit attributes, and a count of the number of access control entries that follow. The structure can be followed by access_list data structures that specify a username or groupname and associated access permissions for the resource. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_RemoteOnly 2106 This operation can be performed only on a server. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_ACFNotFound 2219 LAN Manager could not find the user accounts database file, NET.ACC. This file should be in the ACCOUNTS subdirectory of the LANMAN directory. NERR_UserNotFound 2221 The username was not found. NERR_ResourceNotFound 2222 The resource name was not found. NERR_ResourceExists 2225 The resource access record Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_ResourceExists 2225 The resource access record already exists. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_ACFNoRoom 2228 The user accounts database is full. NERR_ACFTooManyLists 2230 Each resource can have no more than 64 access records defined. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── invalid. NERR_CanNotGrowUASFile 2456 The user accounts database cannot be enlarged because the server's hard disk is full. ──────────────────────────────────────────────────────────────────────────── Remarks NetAccessAdd returns ERROR_NOT_SUPPORTED when executed remotely on a server that has share-level security. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Add functions Chapter 1, "Overview of the LAN Manager API" Deleting an access control list NetAccessDel Listing permissions and NetAccessEnum resources Remote calls Chapter 1, "Overview of the LAN Manager API" NetAccessCheck ──────────────────────────────────────────────────────────────────────────── NetAccessCheck verifies that a user has permission to perform a specified operation on a particular resource. Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1 not supported ■ MS-DOS not supported Privilege Level Admin privilege is required to successfully execute NetAccessCheck on a computer that has local security enabled. Syntax #define INCL_NETACCESS #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAccessCheck (char far * pszReserved, char far * pszUserName, char far * pszResource, unsigned short usOperation, unsigned short far * pusResult ); where pszReserved Reserved; must be set to NULL. pszUserName Points to an ASCIIZ string that contains a username. If pszUserName specifies a groupname, NetAccessCheck returns NERR_UserNotFound. pszResource Points to an ASCIIZ string that contains the name of the resource. usOperation Specifies the type of access operation requested. Any combination of the following operations can be requested, as defined in the ACCESS.H header file: ╓┌──────────────┌──────┌─────────────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ACCESS_READ 0x01 Permission to read data from a resource and, by default, execute the resource. ACCESS_WRITE 0x02 Permission to write data to the resource. ACCESS_CREATE 0x04 Permission to create an instance of the resource (for example, a file); data can be written to the resource when creating it. ACCESS_EXEC 0x08 Permission to execute the resource. ACCESS_DELETE 0x10 Permission to delete the resource. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ACCESS_ATRIB 0x20 Permission to modify the resource's attributes (for example, the date and time a file was last modified). ACCESS_PERM 0x40 Permission to modify the permissions (read, write, create, execute, and delete) assigned to a resource for a user, group, or application. ACCESS_ALL 0x7F Permission to read, write, create, execute, or delete a resource, or to modify attributes or permissions. ──────────────────────────────────────────────────────────────────────────── pusResult Points to an unsigned short integer that specifies whether or not the operation is allowed. This parameter is valid only when NetAccessCheck returns NERR_Success. If the username has the requested permissions and the operation is allowed, pusResult is 0; otherwise, pusResult is set to ERROR_ACCESS_DENIED. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_ACFNotFound 2219 LAN Manager could not find the user accounts database file, NET.ACC. This file should be in the ACCOUNTS subdirectory of the LANMAN directory. NERR_UserNotFound 2221 The username was not found, or a groupname was specified instead of a username. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Remarks If NetAccessCheck cannot find an entry for the resource/username combination on the specified server, it searches for an entry for the guest account, a special account set up for temporary users of the resource. In this case, the user has the same access permissions as the guest account. The guest account can be defined in the LANMAN.INI file, or it can be specified at server startup time. For more information about guest accounts, see your LAN Manager administrator's manual(s). See Also For information about See ──────────────────────────────────────────────────────────────────────────── Defining username or groupname NetAccessAdd access permissions Listing all permissions and NetAccessEnum resources NetAccessDel ──────────────────────────────────────────────────────────────────────────── NetAccessDel deletes the access control list (ACL) for a particular resource. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or P permission for the resource is required to successfully execute NetAccessDel on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETACCESS #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAccessDel (const char far * pszServer, char far * pszResource ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetAccessDel. A null pointer or null string specifies the local computer. pszResource Points to an ASCIIZ string that contains the name of the resource to delete. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_ACFNotFound 2219 LAN Manager could not find the user accounts database file, Code Value Meaning ──────────────────────────────────────────────────────────────────────────── user accounts database file, NET.ACC. This file should be in the ACCOUNTS subdirectory of the LANMAN directory. NERR_ResourceNotFound 2222 The resource name was not found. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── Remarks NetAccessDel returns ERROR_NOT_SUPPORTED when executed remotely on a server that has share-level security. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Defining username or groupname NetAccessAdd access permissions Listing all permissions and NetAccessEnum resources NetAccessEnum ──────────────────────────────────────────────────────────────────────────── NetAccessEnum lists all access permissions records. It is recommended that you not use NetAccessEnum because it is unlikely to be supported in future releases of LAN Manager. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or P permission for the resource is required to successfully execute NetAccessEnum on a remote server or on a computer that has local security enabled. If NetAccessEnum is called by a non-admin class user, only those resources for which the user has P permission will be listed. Syntax #define INCL_NETACCESS #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAccessEnum (const char far * pszServer, char far * pszBasePath, short fsRecursive, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetAccessEnum. A null pointer or null string specifies the local computer. pszBasePath Points to an ASCIIZ string that contains a base pathname for the resources. A null pointer or null string means no base path is to be used. The path can be specified as a universal naming convention (UNC) pathname. fsRecursive Enables or disables recursive searching. If fsRecursive is 0, NetAccessEnum returns entries only for the resource named as the base path by pszBasePath and for the resources directly below that base path. If fsRecursive is nonzero, NetAccessEnum returns entries for all access control lists (ACLs) that have pszBasePath at the beginning of the resource name. The fsRecursive parameter interacts with pszBasePath in the following way: fsRecursive pszBasePath = NULL pszBasePath set ──────────────────────────────────────────────────────────────────────────── 0 Nondirectory and nonfile The path itself and all resources are listed (\comm, resources immediately below \pipe, \print). the path are listed. 1 All resources are listed. The path itself and all resources anywhere below the path are listed. ──────────────────────────────────────────────────────────────────────────── sLevel Specifies the level of detail (0 or 1) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a sequence of access_info_X data structures, where X is 0 or 1, depending on the level of detail requested. If called at level 1, each access_info_1 data structure is followed by as many access_list data structures as specified in the acc1_count element of that access_info_1 data structure. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer that specifies how many entries were returned. This count is valid only if NetAccessEnum returns NERR_Success or ERROR_MORE_DATA. pcTotalAvail Points to an unsigned short integer that specifies how many entries were available. This count is valid only if NetAccessEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_ACFNotFound 2219 LAN Manager could not find the user accounts database file, NET.ACC. This file should be in the ACCOUNTS subdirectory of the LANMAN directory. NERR_ResourceNotFound 2222 The resource name was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks The pszBasePath parameter limits the entries returned by NetAccessEnum. If pszBasePath points to a string that is not null, it serves as a prefix for the pathname. For example, if pszBasePath is C:\PROG, NetAccessEnum returns access permissions records for resources that begin with C:\PROG (such as C:\PROGRAM, C:\PROG\TEST.EXE, and C:\PROGDIR\SUBDIR\SUBTEST.EXE). The resource names are returned with the base path omitted from the front of the name, and the resource names are not returned in any particular order. The pcTotalAvail parameter points to an unsigned short integer that specifies how many entries were available for the given pszBasePath and fsRecursive parameters, not the total number of entries in the access file. NetAccessEnum can provide as many as 64K of data for any given base path. If more data is available than can fit in the buffer, NetAccessEnum returns the code ERROR_MORE_DATA. More data can be read by increasing the size of the buffer or by calling NetAccessEnum with the same size buffer but different base paths. With computers using the high-performance file system 386 (HPFS386), HPFS files have their associated ACL information stored on the disk with the file. This is unlike non-HPFS386 systems, where the ACL information is grouped in the resource database. If NetAccessEnum is used with the recursive switch set and no pszBasePath, a complete downward traversal of each HPFS drive is necessary. This can cause the call to be substantially slower on an HPFS386 system than on a non-HPFS386 system. It is recommended that a base path be provided when using NetAccessEnum with the recursive flag enabled, so that only the information needed is returned. NetAccessEnum returns ERROR_NOT_SUPPORTED when executed remotely on a server that has share-level security. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Defining access permissions NetAccessAdd Enum functions Chapter 1, "Overview of the LAN Manager API" Retrieving the access NetAccessGetInfo permissions for a specific resource Verifying the access permissions NetAccessCheck for a resource NetAccessGetInfo ──────────────────────────────────────────────────────────────────────────── NetAccessGetInfo retrieves the access control list (ACL) for a specific resource. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or P permission for the resource is required to successfully execute NetAccessGetInfo on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETACCESS #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAccessGetInfo (const char far * pszServer, char far * pszResource, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetAccessGetInfo. A null pointer or null string specifies the local computer. pszResource Points to an ASCIIZ string that contains the name of the resource. sLevel Specifies the level of detail (0 or 1) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains an access_info_X data structure, where X is 0 or 1, depending on the level of detail requested. If called at level 1, the access_info_1 data structure is followed by as many access_list data structures as specified in the acc1_count element of that access_info_1 data structure. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcbTotalAvail Points to an unsigned short integer that specifies how many bytes of information are available to be returned in the buffer. This count is valid only if NetAccessGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_ACFNotFound 2219 LAN Manager could not find the user accounts database file, NET.ACC. This file should be in the ACCOUNTS subdirectory of the LANMAN directory. NERR_ResourceNotFound 2222 The resource name was not found. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_InvalidDatabase 2247 The user accounts database file, Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks One way to determine the size of the data buffer required is to first call NetAccessGetInfo with cbBuffer set to 0. NetAccessGetInfo then returns in pcbTotalAvail the buffer size required (in bytes). NetAccessGetInfo returns ERROR_NOT_SUPPORTED when executed remotely on a server that has share-level security. See Also For information about See ──────────────────────────────────────────────────────────────────────────── GetInfo functions Chapter 1, "Overview of the LAN Manager API" Listing all resources and NetAccessEnum permissions on a server Modifying the current NetAccessSetInfo permissions for a resource NetAccessGetUserPerms ──────────────────────────────────────────────────────────────────────────── NetAccessGetUserPerms returns a specified user's or group's access permissions for a particular resource. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or P permission for the resource is required to successfully execute NetAccessGetUserPerms on a remote server or on a computer that has local security enabled, except when users request their own access permissions. In this case, no special privilege is required. Syntax #define INCL_NETACCESS #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAccessGetUserPerms (char far * pszServer, char far * pszUgName, char far * pszResource, unsigned short far * pusPerms ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetAccessGetUserPerms. A null pointer or null string specifies the local computer. pszUgName Points to an ASCIIZ string that contains the name of the user or group to query. pszResource Points to an ASCIIZ string that contains the name of the resource. pusPerms Points to a field in which the permission bit field is returned. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_ACFNotFound 2219 LAN Manager could not find the user accounts database file, NET.ACC. This file should be in Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NET.ACC. This file should be in the ACCOUNTS subdirectory of the LANMAN directory. NERR_UserNotFound 2221 The username was not found. NERR_ResourceNotFound 2222 The resource name was not found. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Remarks The permissions returned are based on the user's entry in the access control list. If the user does not have an entry, the permissions for any groups to which the user belongs are returned. NetAccessGetUserPerms returns ERROR_NOT_SUPPORTED when executed remotely on a server that has share-level security. NetAccessSetInfo ──────────────────────────────────────────────────────────────────────────── NetAccessSetInfo changes the access control list (ACL) for a resource. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or P permission for the resource is required to successfully execute NetAccessSetInfo on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETACCESS #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAccessSetInfo (const char far * pszServer, char far * pszResource, short sLevel, char far * pbBuffer, unsigned short cbBuffer, short sParmNum ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetAccessSetInfo. A null pointer or null string specifies the local computer. pszResource Points to an ASCIIZ string that contains the name of the resource. sLevel Specifies the level of detail provided; must be 1. pbBuffer Points to the data to be set. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. sParmNum Specifies whether to reset the entire ACL or to change only the attribute element. If sParmNum is PARMNUM_ALL, pbBuffer must point to an access_info_1 data structure that can be followed by access_list data structures. The entire set of access control entries (ACEs) in the ACL is then replaced by this new data. The only other valid value for sParmNum is ACCESS_ATTR_PARMNUM, which indicates that the acc1_attr element of the access_info_1 data structure is to be set (acc1_attr is the only element of the structure that can be set individually). When sParmNum is ACCESS_ATTR_PARMNUM, pbBuffer must point to a valid value for acc1_attr, and the ACL remains unaltered. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_ACFNotFound 2219 LAN Manager could not find the user accounts database file, NET.ACC. This file should be in Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NET.ACC. This file should be in the ACCOUNTS subdirectory of the LANMAN directory. NERR_UserNotFound 2221 The username was not found. NERR_ResourceNotFound 2222 The resource name was not found. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_ACFNoRoom 2228 The user accounts database is full. NERR_ACFTooManyLists 2230 Each resource can have no more than 64 access records defined. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. NERR_CanNotGrowUASFile 2456 The user accounts database cannot be enlarged because the server's hard disk is full. ──────────────────────────────────────────────────────────────────────────── Remarks NetAccessSetInfo returns ERROR_NOT_SUPPORTED when executed remotely on a server that has share-level security. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing permissions and NetAccessEnum resources Remote calls Chapter 1, "Overview of the LAN Manager API" Retrieving the access NetAccessGetInfo permissions for a specific resource SetInfo functions Chapter 1, "Overview of the LAN Manager API" Access Permissions Category Example /* NETACC.C -- a sample program demonstrating NetAccess API functions. This program requires that you have admin privilege if a servername parameter is supplied. usage: netacc [-s \\server] [-u username] [-r resource] [-b basepath] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). username = Name of the user. resource = Name of the resource. basepath = Enumerate resources with this base path. API Used to... ================ ================================================ NetAccessEnum Display a list of access permissions NetAccessCheck Check a user's write access to the resource NetAccessGetInfo Check that an ACL exists for the resource NetAccessAdd Add an ACL for the resource if one does not exist NetAccessSetInfo Give all users read/write access to the resource NetAccessDel Delete the ACL for the resource This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_BASE #include <os2.h> // MS OS/2 base header files #define INCL_NETACCESS #define INCL_NETERRORS #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include "samples.h" // Internal routine header file #define DEFAULT_USER "ADMIN" #define DEFAULT_RESOURCE "\\pipe\\restrict" #define BIG_BUFFER 32768 void Usage (char * pszProgram); void main(int argc, char *argv[]) { API_RET_TYPE uReturnCode; // API return code char * pszServer = NULL; // Servername char * pszUserName = DEFAULT_USER; // Username char * pszResource = DEFAULT_RESOURCE; // Resource to check char * pszBasePath = NULL; // No default base path char * pbBuffer; // Pointer to data buffer struct access_info_1 *pAclBuf; // Pointer to ACL info struct access_list *pAceInfo; // Pointer to ACE info int iArgv; // Index for arguments short iACE; // Index for ACEs unsigned short iACL; // Index for ACLs unsigned short cAclRead; // Count of ACLs read unsigned short cAclTotal; // Count of ACLs available unsigned short cbAvail; // Count of bytes available unsigned short cbBuffer; // Size of buffer, in bytes unsigned short usResult; // Result of access check unsigned short fAttrib; // Auditing attribute flag char cGroup; BOOL fResourceFound = FALSE; for (iArgv = 1; iArgv < argc; iArgv++) { if ((*argv[iArgv] == '-') || (*argv[iArgv] == '/')) { switch (tolower(*(argv[iArgv]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iArgv]; break; case 'u': // -u username pszUserName = argv[++iArgv]; break; case 'r': // -r resource pszResource = argv[++iArgv]; break; case 'b': // -b base path pszBasePath = argv[++iArgv]; break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } //======================================================================== // NetAccessEnum // // This API displays the list of resource access permissions. // Note: Details other than resource name are available only at info // level 1. If all resources are wanted, then no base pathname should // be supplied. Recursive searching is enabled. //======================================================================== cbBuffer = BIG_BUFFER; // Can be up to 64K /* * You can determine the number of entries by calling NetAccessEnum * with pbBuffer=NULL and cbBuffer=0. The size of the buffer needed * to enumerate the users is, however, larger than * cAclTotal * sizeof(struct access_info_1) because of the * variable-length data (referenced by pointers in the structure). * It is easiest to use a big buffer. */ pbBuffer = SafeMalloc(cbBuffer); // Start of memory block uReturnCode = NetAccessEnum( pszServer, // Servername pszBasePath, // Base path to search from 1, // Nonzero, recursive search 1, // Information level pbBuffer, // Data returned here cbBuffer, // Size of buffer, in bytes &cAclRead, // Count of ACLs read &cAclTotal); // Count of ACLs available printf("NetAccessEnum returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) { pAclBuf = (struct access_info_1 *) pbBuffer; for (iACL = 0; iACL < cAclRead; iACL++) { printf(" resource = %Fs\n", pAclBuf->acc1_resource_name); pAceInfo = (struct access_list *)(pAclBuf + 1); for (iACE = 0; iACE < pAclBuf->acc1_count; iACE++) { // Print a * before groupnames cGroup = ' '; if (pAceInfo->acl_access & ACCESS_GROUP) { // Strip group access bit pAceInfo->acl_access &= ACCESS_ALL; cGroup = '*'; } printf("\t%c%s:%x \n", cGroup, pAceInfo->acl_ugname, pAceInfo->acl_access); pAceInfo++; } pAclBuf = (struct access_info_1 *)pAceInfo; } printf("%hu out of %hu entries returned\n", cAclRead, cAclTotal); } //======================================================================== // NetAccessCheck // // This API checks that a user has permission to write to a resource. // Unlike other Access Category API functions, NetAccessCheck input can // specify only a username; it cannot specify a groupname. // Note: NetAccessCheck cannot be executed remotely. //======================================================================== uReturnCode = NetAccessCheck( NULL, // Reserved field pszUserName, // Check for user pszResource, // Resource to check ACCESS_WRITE, // Check for write permission &usResult); /* * The result field is valid only if the API returns NERR_Success. * If there is no ACL for the resource, its parent directory, or * the drive label, the API sets the result field to NERR_Success * for an admin-class user and ERROR_ACCESS_DENIED for any other * type of user. */ printf("\nNetAccessCheck for write permission returned %u\n", uReturnCode); printf(" User name = %s, Resource = %s\n", pszUserName, pszResource); if (uReturnCode == NERR_Success) { printf(" Result field returned = %hu\n", usResult); } //======================================================================== // NetAccessGetInfo // // Call NetAccessGetInfo at level 0 to see if the resource exists. //======================================================================== uReturnCode = NetAccessGetInfo( pszServer, // Servername pszResource, // Pointer to resource name 0, // Only want to know if it exists pbBuffer, // Data returned here cbBuffer, // Size of buffer, in bytes &cbAvail); // Count of bytes available printf("\nNetAccessGetInfo of %s returned %u\n", pszResource, uReturnCode); switch (uReturnCode) { case NERR_Success: printf(" Resource %s exists\n\n", pszResource); fResourceFound = TRUE; break; case NERR_ResourceNotFound: printf(" Resource %s does not exist\n\n", pszResource); break; } //======================================================================== // NetAccessAdd // // This API adds an ACL for the resource (if one does not exist) // and sets the attribute flag so all access attempts are audited. //======================================================================== if (!fResourceFound) { // Set up access permission info pAclBuf = (struct access_info_1 *) pbBuffer; pAclBuf->acc1_resource_name = (char far *) pszResource; pAclBuf->acc1_attr = 1; // Audit all access attempts pAclBuf->acc1_count = 0; // Set no user/group info uReturnCode = NetAccessAdd( pszServer, // Servername 1, // Info level; must be 1 (char far *)pAclBuf, // Data to be set cbBuffer); // Size of buffer, in bytes printf("NetAccessAdd of %s returned %u\n\n", pszResource, uReturnCode); } //======================================================================== // NetAccessSetInfo // // This API changes the access record for the resource so that // any user who has user permission has read permission only. This // can be overwritten by setting special access permissions for // individual usernames. //======================================================================== /* * There are two ways to call NetAccessSetInfo. * If sParmNum == PARMNUM_ALL, you must pass it a whole structure. * Otherwise, you can set sParmNum to the element of the structure * you want to change. Both ways are shown here. */ // Set up access permission info pAclBuf = (struct access_info_1 *) pbBuffer; pAclBuf->acc1_resource_name = (char far *) pszResource; pAclBuf->acc1_attr = 1; // Audit all access attempts pAclBuf->acc1_count = 1; // Set up access_list structure pAceInfo = (struct access_list *)(pAclBuf+1), strcpy(pAceInfo->acl_ugname, "USERS"); pAceInfo->acl_access = ACCESS_READ; uReturnCode = NetAccessSetInfo( pszServer, // Servername pszResource, // Pointer to resource name 1, // Info level; must be 1 (char far *)pAclBuf, // Data to be set cbBuffer, // Size of buffer, in bytes PARMNUM_ALL); // Supply full set of info printf("NetAccessSetInfo with full buffer returned %u\n", uReturnCode); /* * Sets sParmNum to ACCESS_ATTR_PARMNUM to change the acc1_attr element * of the access_info_1 structure. To specify no audit logging, set * acc1_attr to 0. */ fAttrib = 0; uReturnCode = NetAccessSetInfo( pszServer, // Servername pszResource, // Pointer to resource name 1, // Info level (char far *)&fAttrib, // Turn off all auditing sizeof(short), // Size of buffer, in bytes ACCESS_ATTR_PARMNUM); // Give audit attribute only printf("NetAccessSetInfo with audit bit only returned %u\n\n", uReturnCode); //======================================================================== // NetAccessDel // // This API deletes the access record for the resource. //======================================================================== uReturnCode = NetAccessDel( pszServer, // Servername pszResource); // Pointer to resource name printf("NetAccessDel of %s returned %u\n", pszResource, uReturnCode); free(pbBuffer); exit(0); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s [-s \\\\server] [-u username]"\ " [-r resource] [-b basepath]\n", pszProgram); exit(1); } Alert Category Alert API functions notify network service programs and applications of network events. They require that the Workstation service be started. The Alert category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and ALERT.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETALERT, and including the master header file, LAN.H. For more information, see the "Example" section, later in this category. These are the Alert API functions: ■ NetAlertRaise ■ NetAlertStart ■ NetAlertStop Description An event is a particular instance of a process or state of hardware as defined by an application. The Alert API functions allow applications to indicate when predefined events occur. The ALERT.H header file defines the following types of events for alerts sent by the LAN Manager services: ╓┌─────────────────────┌──────────────┌──────────────────────────────────────╖ Code ASCIIZ String Meaning ──────────────────────────────────────────────────────────────────────────── ALERT_ADMIN_EVENT ADMIN Notify an administrator. ALERT_ERRORLOG_EVENT ERRORLOG An entry is added to the error log. ALERT_MESSAGE_EVENT MESSAGE A user or application received a message. ALERT_PRINT_EVENT PRINTING A print job completed or a print error occurred. Code ASCIIZ String Meaning ──────────────────────────────────────────────────────────────────────────── error occurred. ALERT_USER_EVENT USER An application or resource was used. ──────────────────────────────────────────────────────────────────────────── Other types of alerts can be defined as needed by applications. For example, you could define the new alert type ALERT_CHANGE_EVENT as the ASCIIZ string CHANGE. A monitor program could check for ALERT_CHANGE_EVENT alerts by calling NetAlertStart with the new alert. If an application that modified a resource then called NetAlertRaise with the ALERT_CHANGE_EVENT alert, the monitor program would be notified. An application can receive alert messages through one of two delivery mechanisms: a mailslot (registered as \mailslot\mailslotname) or a system semaphore (registered as \sem\semaphorename). If an application requires detailed information about an event, it should use a mailslot. The mailslot can receive data; the semaphore can only indicate the occurrence of an event. The number of alerts a system can handle is determined by the numalerts entry in the [workstation] section of the LANMAN.INI file. To change this number, alter the numalerts entry and stop and restart the workstation. NetAlertStart indicates that an application is checking for events of a particular type to occur, and indicates whether the application is monitoring a mailslot or waiting for a semaphore to be cleared. An application can register to monitor several alert types by calling NetAlertStart multiple times. NetAlertRaise is used to indicate that an event has occurred. Any applications checking for the event then receive the data sent by the alert being raised, or they have their semaphore cleared. The LAN Manager Alerter service is an example of an application that has registered to receive LAN Manager alerts. To discontinue checking for alerts of a particular type, call NetAlertStop with the appropriate alert type specified. If an application calls NetAlertStart to start checking for an alert, and then exits without ever calling NetAlertStop, the entry remains in the table of alerts until the Workstation service stops; the alert table may fill up. To avoid this, applications should always call NetAlertStop when they are done checking for the alert. Data Structures An application registered as a mailslot client receives information about each type of alert for which it is registered. This information consists of a fixed-length header followed by variable-length information specific to the type of alert. The LAN Manager alert data structures are defined in the ALERT.H header file. Header Structure The fixed-length header contains the standard alert data structure. The std_alert data structure has the following format: struct std_alert { long alrt_timestamp; char alrt_eventname[EVLEN+1]; char alrt_pad1; char alrt_servicename[SNLEN+1]; }; where alrt_timestamp Specifies the time and date when the alert event was raised. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. alrt_eventname Contains an ASCIIZ string that specifies the type of alert. The constant EVLEN is defined in the NETCONS.H header file. alrt_pad1 Aligns the next data structure element on a word boundary. alrt_servicename Contains an ASCIIZ string that specifies which application raised the alert. The constant SNLEN is defined in the NETCONS.H header file. Alert Structures The ALERT.H header file contains data structures for predefined alert classes. These structures define only the fixed-length part of the information, not the ASCIIZ strings that follow some of the structures. These alert data structures are described in the following sections. ALERT_ADMIN_EVENT Alert - The admin_other_info data structure has this format: struct admin_other_info { short alrtad_errcode; short alrtad_numstrings; }; /* Followed by consecutive ASCIIZ strings; the count is in the alrtad_numstrings element. */ char mergestrings[]; where alrtad_errcode Specifies the error code for the new message in the message log. alrtad_numstrings Specifies the number (0-9) of consecutive ASCIIZ strings contained in mergestrings. mergestrings Contains a series of consecutive ASCIIZ strings that make up the error message indicated by alrtad_errcode. ALERT_ERRORLOG_EVENT Alert - The errlog_other_info data structure has this format: struct errlog_other_info { short alrter_errcode; long alrter_offset; }; where alrter_errcode Specifies the error code that was written to the error log. alrter_offset Specifies the offset for the new entry in the error log. ALERT_MESSAGE_EVENT Alert - This alert does not define a data structure; the text from the received message is in this format: char msg_text[]; where msg_text Specifies an ASCIIZ string that contains message text. ALERT_PRINT_EVENT Alert - The print_other_info data structure has this format: struct print_other_info { short alrtpr_jobid; short alrtpr_status; long alrtpr_submitted; long alrtpr_size; }; /* Followed by consecutive ASCIIZ strings. */ char computername[]; char username[]; char queuename[]; char destname[]; char status_string[]; where alrtpr_jobid Specifies the print job's identification number. alrtpr_status Specifies the status of the print job. alrtpr_submitted Specifies the time when the print job was submitted. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. alrtpr_size Specifies the size (in bytes) of the print job. computername Contains an ASCIIZ string that specifies which workstation or server submitted the print job. username Contains an ASCIIZ string that specifies which user requested the printing. queuename Contains an ASCIIZ string that specifies which queue handled the print job. destname Contains an ASCIIZ string that specifies which printer handled the job. status_string Specifies information the print processor returns. This string corresponds to the pszStatus component of the PRJINFO data structure for the print job. For more information, see the Print Job category API functions. ALERT_USER_EVENT Alert - The user_other_info data structure has this format: struct user_other_info { short alrtus_errcode; short alrtus_numstrings; }; /* * Followed by a number of consecutive ASCIIZ strings; * the count is in the alrtus_numstrings element. */ */ char mergestrings[]; /* Further followed by two more consecutive ASCIIZ strings. */ char username[]; char computername[]; where alrtus_errcode Specifies the error code for the new message in the message log. alrtus_numstrings Specifies the number (0-9) of consecutive ASCIIZ strings contained in mergestrings. mergestrings Specifies a series of consecutive ASCIIZ strings that make up the error message specified by alrtus_errcode. username Specifies the name of the user or application affected by the alert. computername Specifies the name of the computer that the user or application is accessing. ALERT.H Header File Macros The ALERT.H header file contains the following macros that simplify access to the variable-length elements in the alert data structure: Macro Description ──────────────────────────────────────────────────────────────────────────── ALERT_OTHER_INFO(ptr) Given a pointer to the start of the ALERT_OTHER_INFO_F(ptr) std_alert data structure (designated by ptr), the ALERT_OTHER_INFO macro returns a pointer to the variable-length part of the alert message (the information specific to the alert class). Use ALERT_OTHER_INFO_F when a far pointer is required. ALERT_VAR_DATA(ptr) Given a pointer to the address of the ALERT_VAR_DATA_F(ptr) alert data structure (for example, a pointer to an admin_other_info data structure, designated by ptr), ALERT_VAR_DATA returns a pointer to the first variable-length ASCIIZ string. Use ALERT_VAR_DATA_F when a far pointer is required. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Creating mailslots Mailslot Category Error log Error Logging Category Message API functions Message Category Printer API functions Print Destination Category, Print Job Category, and Printer Queue Category NetAlertRaise ──────────────────────────────────────────────────────────────────────────── NetAlertRaise notifies all registered clients that a particular event occurred. Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1, local only ■ MS-DOS not supported Privilege Level No special privilege level is required to successfully execute NetAlertRaise. Syntax #define INCL_NETALERT #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAlertRaise (const char far * pszEvent, const char far * pbBuffer, unsigned short cbBuffer, unsigned long ulTimeout ); where pszEvent Points to an ASCIIZ string that specifies which type of alert to raise. pbBuffer Points to the data to be sent to the clients listening for this alert. The data should consist of the std_alert data structure followed by any additional alert data. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. ulTimeout Specifies how many milliseconds to wait for alert information to be written to the mailslot. The ALERT.H header file defines these three time intervals: Code Value Time Interval ──────────────────────────────────────────────────────────────────────────── ALERT_SHORT_WAIT 100L 0.1 second ALERT_MED_WAIT 1000L 1 second ALERT_LONG_WAIT 10000L 10 seconds ──────────────────────────────────────────────────────────────────────────── Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_NoSuchAlert 2432 An invalid or nonexistent alertname was raised. ──────────────────────────────────────────────────────────────────────────── Remarks NetAlertRaise clears the client's semaphore or sends messages to mailslots. For mailslot clients, NetAlertRaise writes information from pbBuffer to the client's mailslot. For semaphore clients, NetAlertRaise clears and automatically resets the semaphore. The alert types defined in ALERT.H are raised by LAN Manager services. Applications using the Alert category functions should define their own alert types and associated data structures. One exception is the use of the ALERT_ADMIN_EVENT code to generate messages. An application can use the ALERT_ADMIN_EVENT alert type together with the Alerter service to generate messages. If the alert is raised with the alrtad_errcode element of the admin_other_info data structure set to -1, the alert is received by the Alerter service. The message text in mergestrings is then sent as a message to all names listed in the alertnames entry of the local LANMAN.INI file. For a demonstration of this, see the "Example" section at the end of this category. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Mailslots DosMakeMailslot and DosReadMailslot in MSOS/2 programming manual(s) Registering a client for an NetAlertStart alert Semaphores DosCreateSem, DosMuxSemWait, and DosSemSet in MSOS/2 programming manual(s) Terminating alert monitoring NetAlertStop NetAlertStart ──────────────────────────────────────────────────────────────────────────── NetAlertStart registers a client so that it will be notified of a particular type of alert. Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1, local only ■ MS-DOS not supported Privilege Level No special privilege level is required to successfully execute NetAlertStart. Syntax #define INCL_NETALERT #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAlertStart (const char far * pszEvent, const char far * pszRecipient, unsigned short cbMaxData ); where pszEvent Points to an ASCIIZ string that specifies the alert type for which the client will be notified. pszRecipient Points to an ASCIIZ string that specifies the mailslot or semaphore client to receive the alerts. This must be a local mailslot or system semaphore. cbMaxData Specifies the maximum number of bytes of information the mailslot client can receive for alerts of this type. Return Codes ╓┌─────────────────────┌───────┌─────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadEventName 2143 The event name is invalid. NERR_AlertExists 2430 A program requested to be notified by the alerter of an event for which it is already receiving notifications. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_TooManyAlerts 2431 The number of alert notifications requested exceeded the number specified by the numalerts entry in the LANMAN.INI file. NERR_BadRecipient 2433 The alert recipient is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks Applications can define their own alerts, specifying the alert name when they call NetAlertStart and NetAlertRaise. Be sure to choose a name that does not duplicate an alert name already used by another application. If pszRecipient is a mailslot, a NetAlertRaise call for the specified alert sends data to the mailslot. The process monitoring the alert must call the DosMakeMailslot function to create the mailslot, then call NetAlertStart to register to receive the alert, and then call DosReadMailslot to read the data raised by the alert. If pszRecipient is a semaphore, a NetAlertRaise call for the specified alert clears the system semaphore. The process monitoring the alert must first create the semaphore by calling DosCreateSem with the fNoExclusive flag set to CSEM_PUBLIC, then call DosSemSet to set the semaphore, then call NetAlertStart to register to receive the alert, and then call DosMuxSemWait to wait for the semaphore to be cleared. NetAlertRaise clears and automatically resets the semaphore. The pszRecipient parameter must be a local mailslot or system semaphore. Any other name results in NERR_BadRecipient. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Discontinuing receiving alerts NetAlertStop of a particular type Mailslots DosMakeMailslot and DosReadMailslot in MSOS/2 programming manual(s) Raising an alert NetAlertRaise Semaphores DosCreateSem, DosMuxSemWait, and DosSemSet in MSOS/2 programming manual(s) NetAlertStop ──────────────────────────────────────────────────────────────────────────── NetAlertStop stops a client from receiving the specified type of alert. Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1, local only ■ MS-DOS not supported Privilege Level No special privilege level is required to successfully execute NetAlertStop. Syntax #define INCL_NETALERT #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAlertStop (const char far * pszEvent, const char far * pszRecipient ); where pszEvent Points to an ASCIIZ string that specifies the type of alert from which to exclude the registered client. pszRecipient Points to an ASCIIZ string that specifies the mailslot or semaphore where the alert was received. Return Codes Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_NoSuchAlert 2432 An invalid or nonexistent alertname was raised. ──────────────────────────────────────────────────────────────────────────── Remarks If either pszEvent or pszRecipient does not exist, NetAlertStop returns NERR_NoSuchAlert. Alert Category Example /* NETALRT.C -- a sample program demonstrating the interaction between the Alerter service and NetAlertRaise. This program requires that the Alerter service be started. It relies on that service to monitor the admin alert events. To receive the alert and display it in a popup, the Messenger and Netpopup services must be running and one of the current message alias names must be listed in the alertnames entry of the LANMAN.INI file on the computer that raises the alert. usage: netalrt [-m message1 [message2 [message3...]]] where message1 = First message to appear in the popup message2 = Second message to appear in the popup message3 = Third message to appear in the popup etc. API Used to... ============= ================================================= NetAlertRaise Raise an admin-class alert that will appear as a popup on machines with the Messenger and Netpopup services running. This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETALERT #define INCL_NETERRORS #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include <time.h> #include "samples.h" // Internal routine header file #define DEFAULT_MESSAGE "Hi there!" #define ALERT_BUFFER 512 #define PROGRAM_NAME "NETALRT" void Usage (char * pszProgram); void main(int argc, char *argv[]) { API_RET_TYPE uReturnCode; // API return code char * pbBuffer; // Pointer to data buffer char * psMergeString; // Pointer to alert strings int iCount; // Index counter unsigned short cbBuffer = ALERT_BUFFER; // Buffer size // Alert data header info struct std_alert *pAlertInfo = (struct std_alert *) pbBuffer; struct admin_other_info * pAdminInfo; // Admin alert data // Allocate a data buffer large enough to store the messages. pbBuffer = SafeMalloc(cbBuffer); // Set up the alert data structure. pAlertInfo = (struct std_alert *) pbBuffer; strcpy(pAlertInfo->alrt_eventname, ALERT_ADMIN_EVENT); strcpy(pAlertInfo->alrt_servicename, PROGRAM_NAME); pAdminInfo = (struct admin_other_info *)ALERT_OTHER_INFO(pAlertInfo); pAdminInfo->alrtad_errcode = -1; pAdminInfo->alrtad_numstrings = 0; psMergeString = ALERT_VAR_DATA(pAdminInfo); for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 'm': // -m Message for ( ; iCount < argc-1; ) // Merge all message strings { iCount++; strcpy(psMergeString, argv[iCount]); psMergeString = psMergeString+1+strlen(argv[iCount]); pAdminInfo->alrtad_numstrings++; } break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } // Display at least one string. if (pAdminInfo->alrtad_numstrings == 0) { strcpy(psMergeString, DEFAULT_MESSAGE); (pAdminInfo->alrtad_numstrings)++; } //======================================================================== // NetAlertRaise // // This API sends an admin alert. If alrtad_errcode is -1, the Alerter // service receives the alert and sends the alert message to all // message aliases listed in the alertnames entry of the LANMAN.INI // file. These messages are then displayed in a popup if the receiving // computer is running the Messenger and Netpopup services. //======================================================================== time(&(pAlertInfo->alrt_timestamp)); uReturnCode = NetAlertRaise(ALERT_ADMIN_EVENT, // Admin alert (char far *)pbBuffer, // Alert information cbBuffer, // Buffer size ALERT_MED_WAIT); // Time-out value printf("NetAlertRaise returned %u\n", uReturnCode); free (pbBuffer); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s [-m message1 [message2 [message3...]]]\n", pszProgram); exit(1); } Auditing Category Auditing API functions control the audit log. All Audit API functions require that the NETWKSTA device driver be installed. NetAuditRead requires that the Workstation service be started. NetAuditWrite requires that the Server service be started. The Audit category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, ACCESS.H, and AUDIT.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETAUDIT, and including the master header file, LAN.H. For more information about these definitions, see the "Example" section, later in this category. These are the Auditing API functions: ■ NetAuditClear ■ NetAuditRead ■ NetAuditWrite Description Auditing API functions monitor operations on the specified server. If auditing is enabled, each monitored operation generates an audit entry. For example, when a user establishes a connection to the server, a single audit entry is generated. Audit entries are stored in a binary file called an audit trail or audit log. The default audit trail file is NET.AUD in the LAN Manager LOGS directory. All Auditing API functions perform their operations on this file. LAN Manager defines many types of audit entries. You can find these audit entries listed in the table in the "Fixed-Length Header" section, later in this category. NetAuditRead reads the audit log. NetAuditClear clears the audit log. NetAuditWrite creates additional audit entries and writes them to the audit log. To set a maximum size for the audit log, you can use one of these methods: ■ Use the net config command with the /maxauditlog option. For more information, see your LAN Manager administrator's manual(s). ■ Set the maxauditlog entry in the [server] section of the LANMAN.INI file. For more information, see your LAN Manager administrator's manual(s). ■ Call NetServerSetInfo with sParmNum set to SV_MAXAUDITSZ_PARMNUM. Data Structures All audit entries include a fixed-length header used in conjunction with variable-length data specific to the entry type. Because of the variable lengths and structures of the ae_data element of the audit entry (it is possible for ae_data to be zero bytes), only the fixed header is defined in the audit_entry data structure. The variable-length portion of the audit entry can contain an offset to a variable-length ASCIIZ string. The offset values are unsigned short integers. To determine the value of the pointer to this string, add the offset value to the address of the ae_data data structure. The following example illustrates this procedure. Assume that pAE points to a buffer that contains a complete audit entry and that the ae_type element of the audit_entry data structure contains the value AE_CONNSTOP, which specifies the predefined ae_connstop data structure. To point the variable pszComputerName to the ASCIIZ string that contains the name of the client whose connection was stopped, an application would perform the following algorithm: struct audit_entry * pAE; /* Fixed part of audit entry */ struct ae_connstop * pAEvar; /* Variable-length structure */ char * pszComputerName; /* Pointer to variable-length string */ /* Calculate the offset to the variable-length structure. */ pAEvar = (struct ae_connstop *) ((char *) pAE + pAE->ae_data_offset); /* Calculate the offset to the computername. */ pszComputerName = (char *) pAEvar + pAEvar->ae_cp_compname; Fixed-Length Header The audit_entry data structure has this format: struct audit_entry { unsigned short ae_len; unsigned short ae_reserved; unsigned long ae_time; unsigned short ae_type; unsigned short ae_data_offset; /* Offset from beginning address of audit_entry */ }; /* Variable-length data specific to type of audit entry */ char ae_data[]; /* Terminating length indicator */ unsigned short ae_len2; where ae_len and ae_len2 Specify the length of the audit entry. Both have the same value. The ae_len element is included at the beginning and at the end of the audit entry to enable both backward and forward scanning of the log. To calculate the entry size, add the size of the audit_entry data structure to the size of the variable-length data, ae_data, and the size of an unsigned short integer, as follows: totalsize = sizeof (struct audit_entry) + sizeof (ae_data) + sizeof (unsigned short); ae_reserved Reserved; must be 0. ae_time Specifies when the audit entry was generated. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. ae_type Specifies the type of audit entry. Type values from 0x0000 through 0x07FF are reserved. OEMs and other applications programmers can reserve values from 0x0800 through 0xFFFF. The AUDIT.H header file defines the following types of audit entries: ╓┌────────────────┌──────┌───────────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── AE_SRVSTATUS 0 Status of server changed. AE_SESSLOGON 1 Session was logged on. AE_SESSLOGOFF 2 Session was logged off. AE_SESSPWERR 3 Password error occurred. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── AE_SESSPWERR 3 Password error occurred. AE_CONNSTART 4 Connection was started. AE_CONNSTOP 5 Connection was stopped. AE_CONNREJ 6 Connection was rejected. AE_RESACCESS 7 Access was granted. AE_RESACCESSREJ 8 Access was rejected. AE_CLOSEFILE 9 File, device, or pipe was closed. ─ 10 Undefined. AE_SERVICESTAT 11 Service status code or text changed. AE_ACLMOD 12 Access control list (ACL) was modified. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── AE_ACLMOD 12 Access control list (ACL) was modified. AE_UASMOD 13 User accounts subsystem (UAS) database was modified. AE_NETLOGON 14 User logged on to network. AE_NETLOGOFF 15 User logged off from network. AE_NETLOGDENIED 16 Not supported in LAN Manager 2.0. AE_ACCLIMITEXCD 17 Account limit was exceeded. AE_RESACCESS2 18 Access was granted. AE_ACLMODFAIL 19 ACL modification failed. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ae_data_offset Specifies the byte offset from the beginning of the audit entry to the beginning of the variable-length portion (ae_data) of the audit entry. To calculate the beginning of ae_data, add the value of ae_data_offset to the starting address of the fixed-length portion of the entry. ae_data Specifies the variable-length portion of the audit entry; it differs depending on the type of entry specified by ae_type. The information begins at ae_data_offset bytes from the top of the audit entry. For information about the structure of each entry type defined by LAN Manager, see the following section. Variable-Length Data The following data structures, specific to the audit entry type, are defined in the AUDIT.H header file. The structures follow the audit_entry header, but they are not necessarily contiguous. Server Status Changed - The ae_srvstatus data structure is associated with an audit entry of type AE_SRVSTATUS. The ae_srvstatus data structure has this format: struct ae_srvstatus { unsigned short ae_ss_status; }; where ae_ss_status Specifies a server's status. The AUDIT.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── AE_SRVSTART 0 Server software started. AE_SRVPAUSED 1 Server software paused. AE_SRVCONT 2 Server software restarted. AE_SRVSTOP 3 Server software stopped. ──────────────────────────────────────────────────────────────────────────── Session Begun - The ae_sesslogon data structure is associated with an audit entry of type AE_SESSLOGON. The ae_sesslogon data structure has this format: struct ae_sesslogon { unsigned short ae_so_compname; unsigned short ae_so_username; unsigned short ae_so_privilege; }; where ae_so_compname Specifies the offset (from the beginning of the ae_sesslogon data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_so_username Specifies the offset (from the beginning of the ae_sesslogon data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_so_username is 0, the username and workstation name are assumed to be the same. ae_so_privilege Specifies the privilege level assigned to ae_so_username. The AUDIT.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── AE_GUEST 0 Guest privilege. AE_USER 1 User privilege. AE_ADMIN 2 Admin privilege. ──────────────────────────────────────────────────────────────────────────── Session Ended - The ae_sesslogoff data structure is associated with an audit entry of type AE_SESSLOGOFF. The ae_sesslogoff data structure has this format: struct ae_sesslogoff { unsigned short ae_sf_compname; unsigned short ae_sf_username; unsigned short ae_sf_reason; }; where ae_sf_compname Specifies the offset (from the beginning of the ae_sesslogoff data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_sf_username Specifies the offset (from the beginning of the ae_sesslogoff data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_sf_username is 0, the username and workstation name are assumed to be the same. ae_sf_reason Specifies the reason the session was disconnected. The AUDIT.H header file defines these possible values: ╓┌───────────────┌──────┌────────────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── AE_NORMAL 0 Normal disconnection or username limit. AE_ERROR 1 Error, session disconnect, or bad password. AE_AUTODIS 2 Autodisconnect (time-out), sharename removed, or administrative permissions required. AE_ADMINDIS 3 Administrative disconnection (forced). AE_ACCRESTRICT 4 Forced off by account system due to account restriction such as logon hours. ──────────────────────────────────────────────────────────────────────────── Password Error - The ae_sesspwerr data structure is associated with an audit entry of type AE_SESSPWERR. The ae_sesspwerr data structure has this format: struct ae_sesspwerr { unsigned short ae_sp_compname; unsigned short ae_sp_username; }; where ae_sp_compname Specifies the offset (from the beginning of the ae_sesspwerr data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_sp_username Specifies the offset (from the beginning of the ae_sesspwerr data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_sp_username is 0, the username and workstation name are assumed to be the same. Connection Started - The ae_connstart data structure is associated with an audit entry of type AE_CONNSTART. The ae_connstart data structure has this format: struct ae_connstart { unsigned short ae_ct_compname; unsigned short ae_ct_username; unsigned short ae_ct_netname; unsigned short ae_ct_connid; }; where ae_ct_compname Specifies the offset (from the beginning of the ae_connstart data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_ct_username Specifies the offset (from the beginning of the ae_connstart data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_ct_username is 0, the username and workstation name are assumed to be the same. ae_ct_netname Specifies the offset (from the beginning of the ae_connstart data structure) to an ASCIIZ string that specifies the sharename of the connected resource. ae_ct_connid Specifies the connection identification number. Connection Stopped - The ae_connstop data structure is associated with an audit entry of type AE_CONNSTOP. The ae_connstop data structure has this format: struct ae_connstop { unsigned short ae_cp_compname; unsigned short ae_cp_username; unsigned short ae_cp_netname; unsigned short ae_cp_connid; unsigned short ae_cp_reason; }; where ae_cp_compname Specifies the offset (from the beginning of the ae_connstop data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_cp_username Specifies the offset (from the beginning of the ae_connstop data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_cp_username is 0, the username and workstation name are assumed to be the same. ae_cp_netname Specifies the offset (from the beginning of the ae_connstop data structure) to an ASCIIZ string that specifies the sharename of the connected resource. ae_cp_connid Specifies the connection identification number. ae_cp_reason Specifies the reason the session was disconnected. The AUDIT.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── AE_NORMAL 0 Normal disconnection occurred or the username limit was exceeded. AE_SESSDIS 1 An error, session disconnection, or bad password occurred. AE_UNSHARE 2 Autodisconnection (time-out) occurred, the sharename was removed, or administrative permissions were lacking. ──────────────────────────────────────────────────────────────────────────── Connection Rejected - The ae_connrej data structure is associated with an audit entry of type AE_CONNREJ. The ae_connrej data structure has this format: struct ae_connrej { unsigned short ae_cr_compname; unsigned short ae_cr_username; unsigned short ae_cr_netname; unsigned short ae_cr_reason; }; where ae_cr_compname Specifies the offset (from the beginning of the ae_connrej data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_cr_username Specifies the offset (from the beginning of the ae_connrej data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_cr_username is 0, the username and workstation name are assumed to be the same. ae_cr_netname Specifies the offset (from the beginning of the ae_connrej data structure) to an ASCIIZ string that specifies the sharename of the desired resource. ae_cr_reason Specifies the reason the session was disconnected. The AUDIT.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── AE_USERLIMIT 0 Normal disconnection occurred or the username limit was exceeded. AE_BADPW 1 An error, session disconnection, or bad password occurred. AE_ADMINPRIVREQD 2 Autodisconnection (time-out) occurred, the sharename was removed, or administrative permissions were lacking. AE_NOACCESSPERM 3 No access permissions exist for the shared resource. ──────────────────────────────────────────────────────────────────────────── Access Granted (level 1) - The ae_resaccess data structure is associated with an audit entry of type AE_RESACCESS. The ae_resaccess data structure has this format: struct ae_resaccess { unsigned short ae_ra_compname; unsigned short ae_ra_username; unsigned short ae_ra_resname; unsigned short ae_ra_operation; unsigned short ae_ra_returncode; unsigned short ae_ra_restype; unsigned short ae_ra_fileid; }; where ae_ra_compname Specifies the offset (from the beginning of the ae_resaccess data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_ra_username Specifies the offset (from the beginning of the ae_resaccess data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_ra_username is 0, the username and workstation name are assumed to be the same. ae_ra_resname Specifies the offset (from the beginning of the ae_resaccess data structure) to an ASCIIZ string that specifies the name of the resource accessed. ae_ra_operation Specifies which operation was performed. The ACCESS.H header file defines these possible values: ╓┌──────────────┌─────────┌──────────────────────────────────────────────────╖ Code Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── ACCESS_READ 0x01 Data was read or executed from a resource. ACCESS_WRITE 0x02 Data was written to a resource. ACCESS_CREATE 0x04 An instance of the resource (for example, a file) was created; data may have been written to the resource when creating it. ACCESS_EXEC 0x08 A resource was executed. ACCESS_DELETE 0x10 A resource was deleted. ACCESS_ATRIB 0x20 Resource attributes were modified. ACCESS_PERM 0x40 Resource permissions (read, write, create, Code Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── ACCESS_PERM 0x40 Resource permissions (read, write, create, execute, and delete) for a user were modified, or an application was modified. ──────────────────────────────────────────────────────────────────────────── ae_ra_returncode Specifies the return code from the particular operation. If ae_ra_returncode is 0, the operation was successful. ae_ra_restype Specifies the server message block (SMB) request function code. ae_ra_fileid Specifies the identification number of the file. Access Granted (level 2) - The ae_resaccess2 data structure is associated with an audit entry of type AE_RESACCESS2. The ae_resaccess2 data structure has this format: struct ae_resaccess2 { unsigned short ae_ra2_compname; unsigned short ae_ra2_username; unsigned short ae_ra2_resname; unsigned short ae_ra2_operation; unsigned short ae_ra2_returncode; unsigned short ae_ra2_restype; unsigned long ae_ra2_fileid; }; where ae_ra2_compname through ae_ra2_restype Are the same as the corresponding elements of the ae_resaccess data structure. For more information, see the "Access Granted (level 1)" section. ae_ra2_fileid Specifies the identification number of the file. It is given as an unsigned long value, rather than as an unsigned short value as in the ae_resaccess structure. Access Denied - The ae_resaccessrej data structure is associated with an audit entry of type AE_RESACCESSREJ. The ae_resaccessrej data structure has this format: struct ae_resaccessrej { unsigned short ae_rr_compname; unsigned short ae_rr_username; unsigned short ae_rr_resname; unsigned short ae_rr_operation; }; where ae_rr_compname Specifies the offset (from the beginning of the ae_resaccessrej data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_rr_username Specifies the offset (from the beginning of the ae_resaccessrej data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_rr_username is 0, the username and workstation name are assumed to be the same. ae_rr_resname Specifies the offset (from the beginning of the ae_resaccessrej data structure) to an ASCIIZ string that specifies the name of the resource to which access was denied. ae_rr_operation Specifies the operation requested. The possible values are the same as those for the ae_ra_operation element of the ae_resaccess data structure and the ae_ra2_operation element of the ae_resaccess2 data structure. For more information, see the previous two sections, "Access Granted (level 1)" and "Access Granted (level 2)." File Closed - The ae_closefile data structure is associated with an audit entry of type AE_CLOSEFILE. The ae_closefile data structure has this format: struct ae_closefile { unsigned short ae_cf_compname; unsigned short ae_cf_username; unsigned short ae_cf_resname; unsigned short ae_cf_fileid; unsigned long ae_cf_duration unsigned short ae_cf_reason; }; where ae_cf_compname Specifies the offset (from the beginning of the ae_closefile data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_cf_username Specifies the offset (from the beginning of the ae_closefile data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_cf_username is 0, the username and workstation name are assumed to be the same. ae_cf_resname Specifies the offset (from the beginning of the ae_closefile data structure) to an ASCIIZ string that specifies the name of the resource that owns the accessed files. ae_cf_fileid Specifies the identification number of the file. ae_cf_duration Specifies how many seconds the resource was used. ae_cf_reason Specifies the reason the session was disconnected. The AUDIT.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── AE_NORMAL_CLOSE 0 Normal client disconnection. AE_SES_CLOSE 1 Session disconnection. AE_ADMIN_CLOSE 2 Administrative disconnection. ──────────────────────────────────────────────────────────────────────────── Service Status Code or Text Changed - The ae_servicestat data structure is associated with an audit entry of type AE_SERVICESTAT. The ae_servicestat data structure has this format: struct ae_servicestat { unsigned short ae_ss_compname; unsigned short ae_ss_username; unsigned short ae_ss_svcname; unsigned short ae_ss_status; unsigned long ae_ss_code; unsigned short ae_ss_text; unsigned short ae_ss_returnval; }; where ae_ss_compname Specifies the offset (from the beginning of the ae_servicestat data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_ss_username Specifies the offset (from the beginning of the ae_servicestat data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_ss_username is 0, the username and workstation name are assumed to be the same. ae_ss_svcname Specifies the offset (from the beginning of the ae_servicestat data structure) to an ASCIIZ string that specifies the name of a service. ae_ss_status Specifies the service status to set. ae_ss_code Specifies the service code to set. ae_ss_text Specifies the offset to the text to set. ae_ss_returnval Specifies the return value. Access Control List (ACL) Modification - The ae_aclmod data structure is associated with audit entries of type AE_ACLMOD and AE_ACLMODFAIL. The ae_aclmod data structure has this format: struct ae_aclmod { unsigned short ae_am_compname; unsigned short ae_am_username; unsigned short ae_am_resname; unsigned short ae_am_action; unsigned short ae_am_datalen; }; where ae_am_compname Specifies the offset (from the beginning of the ae_aclmod data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_am_username Specifies the offset (from the beginning of the ae_aclmod data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_am_username is 0, the username and workstation name are assumed to be the same. ae_am_resname Specifies the offset (from the beginning of the ae_aclmod data structure) to an ASCIIZ string that specifies the name of the resource whose ACL was modified. ae_am_action Specifies the action performed on the ACL record. It is one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Modification. 1 Deletion. 2 Addition. ──────────────────────────────────────────────────────────────────────────── ae_am_datalen Specifies the length of data that follows the fixed data structure. This is always 0 in records generated by Microsoft LAN Manager 2.0. User Accounts Subsystem (UAS) Modification - The ae_uasmod data structure is associated with an audit entry of type AE_UASMOD. The ae_uasmod data structure has this format: struct ae_uasmod { unsigned short ae_um_compname; unsigned short ae_um_username; unsigned short ae_um_resname; unsigned short ae_um_rectype; unsigned short ae_um_action; unsigned short ae_um_datalen; }; where ae_um_compname Specifies the offset (from the beginning of the ae_uasmod data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_um_username Specifies the offset (from the beginning of the ae_uasmod data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_um_username is 0, the username and workstation name are assumed to be the same. ae_um_resname Specifies the offset (from the beginning of the ae_uasmod data structure) to an ASCIIZ string that specifies the name of the resource whose entry was modified. ae_um_rectype Specifies the type of UAS record. It is one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 User record. 1 Group record. 2 UAS modals. ──────────────────────────────────────────────────────────────────────────── ae_um_action Specifies the action performed on the UAS record. It is one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Modification. 1 Deletion. 2 Addition. ──────────────────────────────────────────────────────────────────────────── ae_um_datalen Specifies the length of the data that follows the fixed data structure. This is always 0 in records generated by Microsoft LAN Manager 2.0. Network Logon Record - The ae_netlogon data structure is associated with an audit entry of type AE_NETLOGON. The ae_netlogon data structure has this format: struct ae_netlogon { unsigned short ae_no_compname; unsigned short ae_no_username; unsigned short ae_no_privilege; unsigned short ae_no_authflags; }; where ae_no_compname Specifies the offset (from the beginning of the ae_netlogon data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_no_username Specifies the offset (from the beginning of the ae_netlogon data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_no_username is 0, the username and workstation name are assumed to be the same. ae_no_privilege Specifies the privilege level of the user logging on. The AUDIT.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── AE_GUEST 0 Guest privilege. AE_USER 1 User privilege. AE_ADMIN 2 Administrative privilege. ──────────────────────────────────────────────────────────────────────────── ae_no_authflags Reserved; must be 0. Network Logoff Record - The ae_netlogoff data structure is associated with an audit entry of type AE_NETLOGOFF. The ae_netlogoff data structure has this format: struct ae_netlogoff { unsigned short ae_nf_compname; unsigned short ae_nf_username; unsigned short ae_nf_reserved1; unsigned short ae_nf_reserved2; }; where ae_nf_compname Specifies the offset (from the beginning of the ae_netlogoff data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_nf_username Specifies the offset (from the beginning of the ae_netlogoff data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_nf_username is 0, the username and workstation name are assumed to be the same. ae_nf_reserved1 Reserved; must be 0. ae_nf_reserved2 Reserved; must be 0. Account Limit Exceeded - The ae_acclim data structure is associated with an audit entry of type AE_ACCLIMITEXCD. The ae_acclim data structure has this format: struct ae_acclim { unsigned short ae_al_compname; unsigned short ae_al_username; unsigned short ae_al_resname; unsigned short ae_al_limit; }; where ae_al_compname Specifies the offset (from the beginning of the ae_acclim data structure) to an ASCIIZ string that specifies the name of the workstation that established the session. ae_al_username Specifies the offset (from the beginning of the ae_acclim data structure) to an ASCIIZ string that specifies the name of the user who initiated the session. If ae_al_username is 0, the username and workstation name are assumed to be the same. ae_al_resname Specifies the offset to the resource name; must be 0. This field is not used in LAN Manager 2.0. ae_al_limit Specifies the limit that was exceeded. The AUDIT.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── AE_LIM_UNKNOWN 0 Unknown or unavailable. AE_LIM_LOGONHOURS 1 Logon hours. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── LAN Manager network commands LAN Manager administrator's manual(s) LANMAN.INI file LAN Manager administrator's manual(s) Permission levels Access Permissions Category and User Category NetAuditClear ──────────────────────────────────────────────────────────────────────────── NetAuditClear clears the audit log on a server and, optionally, saves the entries in a backup file. When executed locally, NetAuditClear requires that the NETWKSTA device driver be installed, but does not require that the Workstation service be started. When a servername parameter is supplied, NetAuditClear requires that the local Workstation service be started. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege is required to successfully execute NetAuditClear on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETAUDIT #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAuditClear (const char far * pszServer, const char far * pszBackupFile, char far * pszReserved ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetAuditClear. A null pointer or null string specifies the local computer. pszBackupFile Points to an ASCIIZ string that contains a name for the optional backup file. The calling application must have create and write permissions for the path specified by pszBackupFile, and the path must already exist. If the pathname is relative, it is assumed to be relative to the LAN Manager LOGS directory. A null pointer specifies not to back up the audit log. pszReserved Reserved; must be a null pointer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_SHARING_VIOLATION 32 A sharing violation occurred. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_SHARING_VIOLATION 32 A sharing violation occurred. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_NAME 123 The character or file system name is invalid. ERROR_FILENAME_EXCED_RANGE 206 The filename specified is invalid for the file system. This code is returned when checking a FAT disk partition only. It cannot be returned for an HPFS partition. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Getting the status of audit log NetServerGetInfo capacity Reading an entry from the audit NetAuditRead log Writing an entry to the audit NetAuditWrite log NetAuditRead ──────────────────────────────────────────────────────────────────────────── NetAuditRead reads from the audit log on a server. It requires that the Workstation service be started. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or accounts, comm, print, or server operator privilege is required to successfully execute NetAuditRead on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETAUDIT #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAuditRead (const char far * pszServer, const char far * pszReserved1 HLOG far * phAuditLog, unsigned long ulOffset, unsigned short far * pusReserved2, unsigned long ulReserved3, unsigned long flOffset, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbReturned, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetAuditRead. A null pointer or null string specifies the local computer. pszReserved1 Reserved; must be a null pointer. phAuditLog Points to the handle for the audit log. An application calling NetAuditRead for the first time must initialize the audit log handle as follows: Bits Value ──────────────────────────────────────────────────────────────────────────── 127 (MSB) - 64 0 63 - 0 (LSB) 1 ──────────────────────────────────────────────────────────────────────────── The most significant bit (MSB) is the leftmost bit; the least significant bit (LSB) is the rightmost bit. After the first call, each call to NetAuditRead must be given the value for the handle returned by the previous call. ulOffset Specifies the record offset at which to begin reading. This parameter is ignored unless bit 1 in the flOffset parameter is set. If flOffset bit 1 is set, ulOffset is taken as an offset based on the record number (not bytes) at which the returned data should begin. Note that the record offset parameter is zero-based from both directions, depending upon the direction of the read. If reading backward, record 0 is the last record in the log. If reading forward, record 0 is the first record in the log. pusReserved2 Reserved; must be a null pointer. ulReserved3 Reserved; must be 0. flOffset Specifies the open flags, as follows: Bit(s) Meaning ──────────────────────────────────────────────────────────────────────────── 0 If 0, the log is read forward. If 1, the log is read backward and records are returned in the buffer in reverse chronological order (newest records first). 1 If 0, reading proceeds sequentially. If 1, reading proceeds from the nth record from the start of the log, where n is the offset parameter. 2-31 Reserved; must be 0. ──────────────────────────────────────────────────────────────────────────── pbBuffer Points to the buffer for returned data. After a successful read operation, this buffer contains a sequence of audit entries with the accompanying variable-length data structures. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcbReturned Points to an unsigned short integer in which a count of the number of bytes read into the buffer is returned. pcbTotalAvail Points to an unsigned short integer in which a count of the number of bytes available is returned. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_SHARING_VIOLATION 32 A sharing violation occurred. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_InvalidComputer 2351 The specified computername is invalid. NERR_LogFileChanged 2378 The log file has changed since Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_LogFileChanged 2378 The log file has changed since it was last read. NERR_LogFileCorrupt 2379 The log file is corrupt. NERR_InvalidLogSeek 2440 The log file does not contain the requested record number. ──────────────────────────────────────────────────────────────────────────── Remarks To read the contents of an audit log, an application calls NetAuditRead repeatedly until it returns information (via the pcbTotalAvail parameter) that indicates there is no more data to be read. Each call to NetAuditRead returns a handle that must be provided to any subsequent call to NetAuditRead. This handle changes with each subsequent call; it is not a system file handle and should never be treated as such. Note that the audit log can contain much more than 64K of data. If pcbTotalAvail is returned with a value of 0xFFFF, there can be 0xFFFF or more bytes of data available. The application should continue to read the log until 0 is returned in pcbTotalAvail. NetAuditRead passes data back in the buffer in whole records. The application never receives a partial record in the buffer. Use the value pointed to by pcbReturned to determine the end of valid data in the buffer. The audit log is written with the newest records appended to the end of the log. The flOffset parameter determines whether to read the log in forward or in reverse order. If the audit log is read partially, and then the log is cleared or a new record is written, subsequent reading with the handle returned from the first call to NetAuditRead returns an error. An application that finds the audit log changed between calls can reread the changed log by reissuing the call with the audit handle initialized as if it were making the call for the first time. Attempting to read the log while another application is writing an entry to the log results in NetAuditRead returning ERROR_SHARING_VIOLATION. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Clearing an audit log NetAuditClear Writing an entry to the audit NetAuditWrite log NetAuditWrite ──────────────────────────────────────────────────────────────────────────── NetAuditWrite writes an audit entry to the local audit log. For audit entries to be written to the log, the Server service must be started with auditing enabled. Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1 not supported ■ MS-DOS not supported Privilege Level No special privilege level is required to successfully execute NetAuditWrite. Syntax #define INCL_NETAUDIT #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetAuditWrite (unsigned short usType, const char far * pbBuffer, unsigned short cbBuffer, char far * pszReserved1, char far * pszReserved2 ); where usType Specifies the type of entry to write to the audit log. pbBuffer Points to a buffer that contains the data structure associated with the specified audit entry. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pszReserved1 Reserved; must be a null pointer. pszReserved2 Reserved; must be a null pointer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_ACCESS_DENIED 5 The user has insufficient Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_SHARING_VIOLATION 32 A sharing violation occurred. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_NET_WRITE_FAULT 88 A network data fault occurred. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── is not installed. NERR_ServerNotStarted 2114 The Server service is not started. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_LogOverflow 2377 The log file is too big. ──────────────────────────────────────────────────────────────────────────── Remarks NetAuditWrite issues an admin alert by calling NetAlertRaise when the audit log reaches 80% capacity and again when the log reaches 100% capacity. At 100% audit log capacity, NetAuditWrite fails and returns NERR_LogOverflow. Applications should periodically clear the audit log of outdated information to avoid the log reaching 100% capacity. Events of a particular type cannot be written to the audit log unless auditing for that type of event is enabled. If auditing for the event type is not enabled, NetAuditWrite still returns NERR_Success, but no entries are written. You can use one of these methods to enable auditing: ■ Set the auditing entry in the [server] section of the LANMAN.INI file to yes or to a list of event types to be audited. ■ Use the net start server command with the /auditing option. For more information, see the your LAN Manager administrator's manual(s). See Also For information about See ──────────────────────────────────────────────────────────────────────────── Alerts Alert Category Clearing the audit log NetAuditClear Getting the status of audit log NetServerGetInfo capacity Reading the audit log NetAuditRead Setting the maximum size of the NetServerSetInfo audit log Auditing Category Example /* NETAUD.C -- a sample program demonstrating NetAudit API functions. This program requires that you have admin privilege on the specified server. usage: netaud [-s \\server] [-b backup] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). backup = Name of the backup file. API Used to... ============= =========================================== NetAuditRead Read the audit log and display its contents NetAuditClear Copy the audit log and then clear it NetAuditWrite Write entries into the audit log This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETERRORS #define INCL_NETAUDIT #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <malloc.h> #include <time.h> #define DEFAULT_BACKUP "AUDIT.BCK" #define BIG_BUFFER 32768 void Usage (char * pszProgram); void main(int argc, char *argv[]) { char * pszServer = ""; // Servername char * pszBackup = DEFAULT_BACKUP; // Backup audit log int iCount; // Index counter HLOG hLogHandle; // Audit log handle time_t tTime; // Time of entry unsigned short cbBuffer; // Size of buffer, in bytes unsigned short cbRead; // Count of bytes read unsigned short cbAvail; // Count of bytes available API_RET_TYPE uReturnCode; // API return code struct audit_entry far * fpBuffer; // Pointer to the data buffer struct audit_entry far * fpEntry; // Single entry in the audit log struct ae_servicestat far * fpService; // Service status structure for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iCount]; break; case 'b': // -b backup file pszBackup = argv[++iCount]; break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } //======================================================================== // NetAuditRead // // This API reads and displays the audit log for the specified server. // If the entry is for Service Status Code or Text Changed, print // the service and computername. //======================================================================== /* * Allocate a large buffer space to handle large audit logs. * The largest buffer allowed is 64K. If the audit log is * larger than the buffer specified, the API returns as many * full records as it can and the NERR_Success return code. * Subsequent reading starts from the end of the last record * read. To read the whole log, reading must continue until 0 * is returned for the bytes available counter. */ cbBuffer = BIG_BUFFER; // Can be up to 64K /* * Set the log handle for reading from the start of the audit log. * This handle is modified by the API; any subsequent reading * of unread data should use the returned handle. */ hLogHandle.time = 0L; hLogHandle.last_flags = 0L; hLogHandle.offset = 0xFFFFFFFF; hLogHandle.last_flags = 0xFFFFFFFF; fpBuffer = _fmalloc(cbBuffer); // Allocate memory for buffer if (fpBuffer == NULL) { fprintf(stderr, "Malloc failed -- out of memory.\n"); exit(1); } uReturnCode = NetAuditRead( pszServer, // Servername NULL, // Reserved; must be NULL (HLOG far *)&hLogHandle, // Audit log handle 0L, // Start at record 0 NULL, // Reserved; must be NULL 0L, // Reserved; must be 0 0L, // Read the log forward (char far *)fpBuffer, // Data returned here cbBuffer, // Size of buffer, in bytes &cbRead, // Count of bytes read &cbAvail); // Count of available bytes printf("NetAuditRead returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) { for ( fpEntry = fpBuffer; fpEntry < (struct audit_entry far *) ((char far *)fpBuffer + cbRead); ) { tTime = (time_t) fpEntry->ae_time; printf(" Type %d, at %s", fpEntry->ae_type, asctime( gmtime ((const time_t *) &tTime) ) ); /* * If the entry is for Service Status Code or Text Changed, * print the service and computername. This demonstrates how * to extract information using the offsets to the log. */ if (fpEntry->ae_type == AE_SERVICESTAT) { fpService = (struct ae_servicestat far *) ((char far *)fpEntry + fpEntry->ae_data_offset); printf("\tComputer = %Fs\n", (char far *)fpService+fpService->ae_ss_compname); printf("\tService = %Fs\n", (char far *)fpService+fpService->ae_ss_svcname); } fpEntry = (struct audit_entry far *) ((char far *)fpEntry + fpEntry->ae_len); } printf("\nBytes Read = 0x%X\n", cbRead); // To read the whole log, keep reading until cbAvail is 0. if (cbAvail) printf("Data still unread.\n\n"); else printf("All data read.\n\n"); } //======================================================================== // NetAuditClear // // This API clears the audit log for the specified server. A backup // will be kept in the file specified by pszBackup. If a null pointer // is supplied, no backup is kept. //======================================================================== uReturnCode = NetAuditClear( pszServer, // Servername pszBackup, // Name of backup file NULL); // Reserved; must be NULL printf("NetAuditClear returned %u\n", uReturnCode); printf(" backup file = %s \n", pszBackup); //======================================================================== // NetAuditWrite // // This API writes back the entries read by the NetAuditRead call. // Each entry read consisted of a fixed-length header, a variable- // length data section, and a terminating size indicator. Only // the variable-length data area is supplied in the NetAuditWrite // buffer. Note: For any entries to be written to the audit log, the // Server service must be started with auditing enabled. //======================================================================== for ( fpEntry = fpBuffer; fpEntry < (struct audit_entry far *) ((char far *)fpBuffer + cbRead); ) { uReturnCode = NetAuditWrite( fpEntry->ae_type, // Entry type // Buffer address (char far *)fpEntry + fpEntry->ae_data_offset, // Buffer length fpEntry->ae_len - fpEntry->ae_data_offset - sizeof(unsigned short), NULL, // Reserved; must be NULL NULL); // Reserved; must be NULL if (uReturnCode != NERR_Success) { printf("NetAuditWrite returned %u", uReturnCode); break; }; fpEntry = (struct audit_entry far *) ((char far *)fpEntry + fpEntry->ae_len); } _ffree(fpBuffer); exit(0); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s [-s \\\\server] [-b backup]\n", pszProgram); exit(1); } Character Device Category Character Device API functions control shared communication devices and their asso- ciated queues. They require that the Workstation service be started and that the Server service be started on the specified server. The Character Device category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and CHARDEV.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETCHARDEV, and including the master header file, LAN.H. For more information about these definitions, see the "Example" section, later in this category. These are the Character Device API functions: ■ NetCharDevControl ■ NetCharDevEnum ■ NetCharDevGetInfo ■ NetCharDevQEnum ■ NetCharDevQGetInfo ■ NetCharDevQPurge ■ NetCharDevQPurgeSelf ■ NetCharDevQSetInfo Description A modem, FAX machine, or serial printer may require that an application submit commands or change protocols dynamically. Such devices, which require direct and interactive communication, are called communication devices. A LAN Manager server can share one or more communication devices of the same type from a communication-device queue. A communication-device queue stores communication-device requests and sends the requests, one at a time, to a communication device. Multiple applications can use a server's communication devices by establishing connections to the communication-device queue. The server gives each application exclusive access to a device until the application is done using the device. The server allocates available devices based on the priority assigned to the queue. Three things must occur before an application can communicate with a communication device: the server must have a communication device connected to one of its available parallel or serial ports; the server must share a communication-device queue; and the requesting application must establish a connection to the shared communication-device queue. When the application is done using the communication device, it should close the device. Closing the device returns control of the device to the communication-device queue, making it available to another application. NetCharDevGetInfo returns information about a particular communication device. NetCharDevQGetInfo returns the status of a communication-device queue or the position in the waiting list of an application's request. NetCharDevEnum returns the status of all communication devices. All queues can be checked by calling NetCharDevQEnum. Applications can call NetCharDevQPurgeSelf to eliminate all requests submitted to a particular communication-device queue by the specified computer. NetCharDevQPurge removes all pending requests to a particular communication-device queue, but it does not affect a process that has a device open. NetCharDevControl can be used to close the communication device when other methods fail. An application usually closes the communication device by calling the DosClose function. If DosClose fails, a user with admin privilege or comm operator privilege can use NetCharDevControl to close the device. The following scenario illustrates how communication devices and queues work. Three communication devices are connected to a server's serial ports: Port Device ──────────────────────────────────────────────────────────────────────────── COM1: Modem. COM2: Modem. COM3: FAX machine. ──────────────────────────────────────────────────────────────────────────── Note that communication-device queues are not created the same way printer queues are created. A communication-device queue exists from the time the sharename is created by NetShareAdd until it is deleted by NetShareDel. In contrast, a printer queue exists from the time the queue is created by DosPrintQAdd until it is removed by DosPrintQDel, whether or not the printer queue is shared. After communication devices are connected to the ports, the application creates three communication-device queues by calling NetShareAdd three times: Queuename Priority Devicename ──────────────────────────────────────────────────────────────────────────── FAXQ 5 COM3 MODEMQ 5 COM1, COM2 VIPMODEM 1 COM2 ──────────────────────────────────────────────────────────────────────────── Note that the COM2: port is allocated to two different queues, MODEMQ and VIPMODEM. The application assigns a priority to the communication-device queue by calling NetCharDevQSetInfo. The priority can range from 1 (highest) through 9 (lowest). LAN Manager processes requests to queues that have high priority before granting requests to queues that have lower priorities. The VIPMODEM queue is given the highest priority, 1. The application then establishes an implicit or explicit connection to the shared communication-device queue. An implicit connection is established by calling DosOpen, which opens the device. An explicit connection is established by calling NetUseAdd to redirect a local or null devicename to the queue. An explicit connection does not open the device. For more information about redirecting a local devicename to a shared resource, see the Use category API functions. If there is more than one device in a communication-device queue, the queue returns the first available device. If no devices are available, the queue holds the request until a device becomes available. The requesting computer waits for the time specified by the charwait entry in the [workstation] section of its LANMAN.INI file. If the commu- nication device does not become available within that time, the DosOpen function returns the ERROR_BAD_NET_RESP error code. For example, if requests are made to both the MODEMQ and VIPMODEM queues while all communication devices are in use, and if COM2 becomes the next device available, COM2 is made available to the requesting application in the VIPMODEM queue because the VIPMODEM queue has higher priority than the MODEMQ queue. Once an available device is made available to the request, the application begins communicating with that device. When an application successfully opens a remote communication device, the values of the wkiX_chartime and wkiX_charcount elements of the wksta_info_X data structure (where X is the level of detail requested by the function) control how information flows over the network. Because of the following effects, use care when changing these values: ■ The wkiX_chartime and wkiX_charcount elements affect all applications running on the workstation. ■ Network performance can be degraded. Network efficiency, response time, and throughput can be adversely affected. For more information about the wksta_info_X data structure and wkiX_chartime and wkiX_charcount elements, see the Workstation category API functions and your LAN Manager administrator's manual(s). Data Structures The sLevel parameter controls the level of information provided to or returned from the data structures used by NetCharDevEnum, NetCharDevGetInfo, NetCharDevQEnum, NetCharDevQGetInfo, and NetCharDevQSetInfo. Communication Device Information (level 0) NetCharDevEnum and NetCharDevGetInfo use the chardev_info_0 data structure when the sLevel parameter is 0. The chardev_info_0 data structure has this format: struct chardev_info_0 { char ch0_dev[DEVLEN+1]; }; where ch0_dev Contains an ASCIIZ string that specifies the devicename associated with the commu- nication device. The constant DEVLEN is defined in the NETCONS.H header file. Communication Device Information (level 1) NetCharDevEnum and NetCharDevGetInfo use the chardev_info_1 data structure when the sLevel parameter is 1. The chardev_info_1 data structure has this format: struct chardev_info_1 { char ch1_dev[DEVLEN+1]; char ch1_pad1; unsigned short ch1_status; char ch1_username[UNLEN+1]; char ch1_pad2; unsigned long ch1_time; }; where ch1_dev Contains an ASCIIZ string that specifies the devicename associated with the communication device. ch1_pad1 Aligns the next data structure element on a word boundary. ch1_status Specifies the status of the device, as follows: Bit(s) Meaning ──────────────────────────────────────────────────────────────────────────── 0 Reserved; must be 0. 1 If 0, the device is idle; if 1, the device is open. 2 If 0, the device encountered no errors; if 1, the device encountered an error. 3-15 Reserved; must be 0. ──────────────────────────────────────────────────────────────────────────── The following bit masks are used with ch1_status. The CHARDEV.H header file defines these possible values: Code Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── CHARDEV_STAT_OPENED 0x02 The communication device is open. CHARDEV_STAT_ERROR 0x04 The communication device encountered an error. ──────────────────────────────────────────────────────────────────────────── ch1_username Contains an ASCIIZ string that specifies the name of the user currently using the device. The constant UNLEN is defined in the NETCONS.H header file. ch1_pad2 Aligns the next data structure element on a word boundary. ch1_time Specifies how many seconds the current application has been connected to the communication device. Communication Device Queues Information (level 0) NetCharDevQEnum and NetCharDevQGetInfo use the chardevQ_info_0 data structure when the sLevel parameter is 0. The chardevQ_info_0 data structure has this format: struct chardevQ_info_0 { char cq0_dev[NNLEN+1]; }; where cq0_dev Contains an ASCIIZ string that specifies the queuename. The constant NNLEN is defined in the NETCONS.H header file. Communication Device Queues Information (level 1) NetCharDevQEnum, NetCharDevQGetInfo, and NetCharDevQSetInfo use the chardevQ_info_1 data structure when the sLevel parameter is 1. The chardevQ_info_1 data structure has the following format: struct chardevQ_info_1 { char cq1_dev[NNLEN+1]; char cq1_pad; unsigned short cq1_priority; char far * cq1_devs; unsigned short cq1_numusers; unsigned short cq1_numahead; }; where cq1_dev Contains an ASCIIZ string that specifies the queuename. The constant NNLEN is defined in the NETCONS.H header file. cq1_pad Aligns the next data structure element on a word boundary. cq1_priority Specifies the queue priority. The value of cq1_priority can range from 1 (highest priority) through 9 (lowest priority). cq1_devs Points to an ASCIIZ string that contains the devicenames assigned to the queue. The devicenames are separated by a space (for example, COM1 COM3). cq1_numusers Specifies the number of requests in the queue. cq1_numahead Specifies the number of requests ahead of a particular user in the queue. A value of CHARDEVQ_NO_REQUESTS means that the username pointed to by pszUserName in the call to NetCharDevQEnum has no requests in the queue. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Creating a communication-device Share Category queue Data structure architecture Chapter 1, "Overview of the LAN Manager API" Setting LANMAN.INI parameters LAN Manager administrator's manual(s) Using a communication device Use Category NetCharDevControl ──────────────────────────────────────────────────────────────────────────── NetCharDevControl changes the state of a communication device according to the specified operation code (opcode). The supplied opcode, CHARDEV_CLOSE, closes the communication device. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or comm operator privilege is required to successfully execute NetCharDevControl on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETCHARDEV #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetCharDevControl (const char far * pszServer, const char far * pszDevName, short sOpCode ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetCharDevControl. A null pointer or null string specifies the local computer. pszDevName Points to an ASCIIZ string that specifies the device to modify. sOpCode Specifies how to modify pszDevName. This value, defined in the CHARDEV.H header file, can be CHARDEV_CLOSE (0), which indicates to close the communication device and disconnect any current clients. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_SEM_TIMEOUT 121 A time-out occurred from the Semaphore API functions. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_DevInvalidOpCode 2331 The operation is invalid for Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_DevInvalidOpCode 2331 The operation is invalid for this device. NERR_DevNotFound 2332 This device cannot be shared. NERR_DevNotOpen 2333 The device is not open. NERR_NoCommDevs 2337 There are no shared communication devices. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks A communication device is usually closed by a call to the DosClose function. If the process that opened the device cannot close it, NetCharDevControl can be called to force the device closed. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Modifying a communication-device NetCharDevQSetInfo queue Retrieving information about a NetCharDevGetInfo communication device Retrieving information about a NetCharDevQGetInfo communication-device queue NetCharDevEnum ──────────────────────────────────────────────────────────────────────────── NetCharDevEnum provides information about all communication devices in shared communication-device queues on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level No special privilege is required to successfully execute NetCharDevEnum. Syntax #define INCL_NETCHARDEV #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetCharDevEnum (const char far * pszServer, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetCharDevEnum. A null pointer or null string specifies the local computer. sLevel Specifies the level of detail (0 or 1) requested for the returned chardev_info data structure. pbBuffer Points to the buffer in which to store the return data. On a successful return, the buffer contains a sequence of chardev_info_X data structures, where X is 0 or 1, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer that specifies how many entries were returned. This count is valid only if NetCharDevEnum returns NERR_Success or ERROR_MORE_DATA. pcTotalAvail Points to an unsigned short integer that specifies how many entries were available. This count is valid only if NetCharDevEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_NoCommDevs 2337 There are no shared Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NoCommDevs 2337 There are no shared communication devices. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Enum functions Chapter 1, "Overview of the LAN Manager API" Listing communication-device NetCharDevQEnum queues on a server NetCharDevGetInfo ──────────────────────────────────────────────────────────────────────────── NetCharDevGetInfo retrieves information about a particular communication device in a shared communication-device queue on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level No special privilege is required to successfully execute NetCharDevGetInfo. Syntax #define INCL_NETCHARDEV #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetCharDevGetInfo (const char far * pszServer, const char far * pszDevName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetCharDevGetInfo. A null pointer or null string specifies the local computer. pszDevName Points to an ASCIIZ string that contains the name of the specified communication device. sLevel Specifies the level of detail (0 or 1) to be provided in the return buffer. pbBuffer Points to the buffer in which to store the return data. On a successful return, the buffer contains the chardev_info_X data structure, where X is 0 or 1, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcbTotalAvail Points to an unsigned short integer that specifies how many bytes of information were available. This count is valid only if NetCharDevGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_DevNotFound 2332 This device cannot be shared. NERR_NoCommDevs 2337 There are no shared communication devices. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── GetInfo functions Chapter 1, "Overview of the LAN Manager API" Listing all communication NetCharDevEnum devices Modifying the state of a NetCharDevControl communication device NetCharDevQEnum ──────────────────────────────────────────────────────────────────────────── NetCharDevQEnum enumerates all communication-device queues on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level No special privilege is required to successfully execute NetCharDevQEnum. Syntax #define INCL_NETCHARDEV #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetCharDevQEnum (const char far * pszServer, const char far * pszUserName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetCharDevQEnum. A null pointer or null string specifies the local computer. pszUserName Points to an ASCIIZ string that contains the name of a user. When level 1 is specified, the cq1_numahead element of the chardevQ_info_1 data structure represents the number of requests ahead of the request submitted by this user. sLevel Specifies the level of detail (0 or 1) to be returned in the buffer pointed to by pbBuffer. pbBuffer Points to the buffer in which to store the return data. On a successful return, the buffer contains a sequence of chardevQ_info_X data structures, where X is 0 or 1, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the return buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer that specifies how many entries were returned. This count is valid only if NetCharDevQEnum returns NERR_Success or ERROR_MORE_DATA. pcTotalAvail Points to an unsigned short integer that specifies how many entries were available. This count is valid only if NetCharDevQEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_NoCommDevs 2337 There are no shared communication devices. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Enum functions Chapter 1, "Overview of the LAN Manager API" Listing all communication NetCharDevEnum devices associated with communicationdevice queues on a server Retrieving information about a NetCharDevQGetInfo specific communication-device queue NetCharDevQGetInfo ──────────────────────────────────────────────────────────────────────────── NetCharDevQGetInfo retrieves information about a particular communication-device queue on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level No special privilege is required to successfully execute NetCharDevQGetInfo. Syntax #define INCL_NETCHARDEV #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetCharDevQGetInfo (const char far * pszServer, const char far * pszQueueName, const char far * pszUserName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetCharDevQGetInfo. A null pointer or null string specifies the local computer. pszQueueName Points to an ASCIIZ string that contains the name of the communication-device queue about which information is requested. pszUserName Points to an ASCIIZ string that contains the name of a user. The cq1_numahead element in the returned chardevQ_info_1 data structure represents the number of requests in the queue ahead of the request submitted by this user. sLevel Specifies the level of detail (0 or 1) to be provided in the return buffer. pbBuffer Points to the buffer in which to store return data. On a successful return, the buffer contains the chardevQ_info_X data structure, where X is 0 or 1, depending on the level of detail specified. cbBuffer Specifies the size (in bytes) of the return buffer pointed to by pbBuffer. pcbTotalAvail Points to an unsigned short integer that specifies how many bytes of information were available. This count is valid only if NetCharDevQGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_NAME 123 The character or file system name is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_BadUsername 2202 The username or groupname is Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BadUsername 2202 The username or groupname is invalid. NERR_NoCommDevs 2337 There are no shared communication devices. NERR_QueueNotFound 2338 The sharename does not exist. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── GetInfo functions Chapter 1, "Overview of the LAN Manager API" Listing all communication-device NetCharDevQEnum queues on a server Modifying the state of a NetCharDevQSetInfo communication-device queue NetCharDevQPurge ──────────────────────────────────────────────────────────────────────────── NetCharDevQPurge deletes all pending requests in a communication-device queue. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or comm operator privilege is required to successfully execute NetCharDevQPurge on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETCHARDEV #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetCharDevQPurge (const char far * pszServer, const char far * pszQueueName ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetCharDevQPurge. A null pointer or null string specifies the local computer. pszQueueName Points to an ASCIIZ string that contains the name of the queue from which to purge pending requests. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_SEM_TIMEOUT 121 A time-out occurred from the Semaphore API functions. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_ServerNotStarted 2114 The Server service is not started. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_NoCommDevs 2337 There are no shared communication devices. NERR_QueueNotFound 2338 The sharename does not exist. NERR_InvalidComputer 2351 The specified computername is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Remarks NetCharDevQPurge deletes only requests that have not yet been assigned to a device. It does not affect a process that currently has a device open. All pending requests in the queue pointed to by pszQueueName are canceled, and ERROR_BAD_NET_RESP is returned for each call to the DosOpen function. All handles remain valid. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Closing the current session of a NetCharDevControl communication device Deleting the NetCharDevQPurgeSelf communication-device queue requests made by the specified computer Listing the communication-device NetCharDevQEnum queues on a server NetCharDevQPurgeSelf ──────────────────────────────────────────────────────────────────────────── NetCharDevQPurgeSelf deletes all pending requests submitted by a particular computer in a communication-device queue. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or comm operator privilege is required to successfully execute NetCharDevQPurgeSelf on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETCHARDEV #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetCharDevQPurgeSelf (const char far * pszServer, const char far * pszQueueName, const char far * pszComputerName ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetCharDevQPurgeSelf. A null pointer or null string specifies the local computer. pszQueueName Points to an ASCIIZ string that contains the name of the queue from which to purge requests. pszComputerName Points to an ASCIIZ string that contains the name of the computer whose requests are to be deleted from the queue specified by pszQueueName. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_SEM_TIMEOUT 121 A time-out occurred from the Semaphore API functions. ERROR_INVALID_NAME 123 The character or file system name is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_ItemNotFound 2115 The queue is empty. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NoCommDevs 2337 There are no shared communication devices. NERR_QueueNotFound 2338 The sharename does not exist. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks NetCharDevQPurgeSelf is similar to NetCharDevQPurge, except that it deletes only requests made from the computer specified by pszComputerName. A process that has a device open is unaffected. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Deleting the contents of a NetCharDevQPurge communication-device queue Listing communication-device NetCharDevQEnum queues on a server Modifying the state of a NetCharDevQSetInfo communication-device queue NetCharDevQSetInfo ──────────────────────────────────────────────────────────────────────────── NetCharDevQSetInfo modifies the settable fields of a specified communication-device queue on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or comm operator privilege is required to successfully execute NetCharDevQSetInfo on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETCHARDEV #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetCharDevQSetInfo (const char far * pszServer, const char far * pszQueueName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, short sParmNum ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetCharDevQSetInfo. A null pointer or null string specifies the local computer. pszQueueName Points to an ASCIIZ string that contains the name of the communication-device queue to set. sLevel Specifies the level of detail; must be 1. pbBuffer Points to the buffer that contains the data to set. The buffer contains the entire chardevQ_info_1 data structure or an individual record as specified by sParmNum. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. sParmNum Specifies whether to set one or all elements of the chardevQ_info_1 data structure. If sParmNum is PARMNUM_ALL, all elements are to be set, and pbBuffer must point to a chardevQ_info_1 data structure. If sParmNum is any other defined value, only one element is to be set, and pbBuffer must point to that element. Not all elements can be set. Only those elements that have a specific PARMNUM constant value defined can be set. The CHARDEV.H and NETCONS.H header files define these possible values for sParmNum: Code Value Element of chardevQ_info_1 ──────────────────────────────────────────────────────────────────────────── PARMNUM_ALL 0 All elements. CHARDEVQ_PRIORITY_PARMNUM 2 cq1_priority CHARDEVQ_DEVICES_PARMNUM 3 cq1_devs ──────────────────────────────────────────────────────────────────────────── Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_SEM_TIMEOUT 121 A time-out occurred from the Semaphore API functions. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_RedirectedPath 2117 The operation is invalid for a redirected resource. The devicename specified is assigned to a shared resource. NERR_NoRoom 2119 The server could not access enough of a resource, such as memory, to complete the task. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_UseNotFound 2250 This network connection does not exist. NERR_BadQueuePriority 2335 The queue priority is invalid. NERR_NoCommDevs 2337 There are no shared communication devices. NERR_QueueNotFound 2338 The sharename does not exist. NERR_BadDevString 2340 The list of devices is invalid. NERR_BadDev 2341 The devicename is invalid because it does not represent a physical device, or because the Code Value Meaning ──────────────────────────────────────────────────────────────────────────── physical device, or because the device hardware is faulty. NERR_InUseBySpooler 2342 The device is already used with a printer queue. It cannot be used with both printer queues and communication-device queues. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing all communication-device NetCharDevQEnum queues on a server Remote calls Chapter 1, "Overview of the LAN Manager API" Retrieving information about a NetCharDevQGetInfo specific communication-device queue on a server SetInfo functions Chapter 1, "Overview of the LAN Manager API" Character Device Category Example /* NETCHAR1.C -- a sample program demonstrating NetCharDev API functions. This program requires that you have admin privilege or comm operator privilege on the specified server. usage: netchar1 [-s \\server] [-d device] [-q queue] [-u user] [-w wksta] [-p priority] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). device = Actual physical devicename. queue = Shared communication-device queue. user = Name of logged-on user. wksta = Workstation name. priority = Queue priority (1 through 9). This program spawns the child process netchar2.exe. API Used to... ==================== ========================================== NetCharDevQPurge Remove all inactive jobs from a queue NetCharDevControl Close a communication device NetCharDevQPurgeSelf Remove own inactive jobs from a queue NetCharDevQGetInfo Get information about a particular queue NetCharDevQSetInfo Set priority level, comm devices for queue NetCharDevQEnum Get information about all device queues NetCharDevEnum Get information about all devices NetCharDevGetInfo Get information about a particular device This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_BASE #include <os2.h> // MS OS/2 base header files #define INCL_NETCHARDEV #define INCL_NETERRORS #define INCL_NETWKSTA #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <ctype.h> #include <conio.h> #include <string.h> #include <process.h> #include "samples.h" // Internal routine header file /* * List max. size of buffer for each character-device queue. * Note: In this program there is only one device attached. */ #define MAX_CHARDEVQ_INFO_1 (sizeof(struct chardevQ_info_1) + DEVLEN + 1) #define SEMAPHORE "\\sem\\chardev" #define CHILD_PROCESS "netchar2.exe" #define START_JOB '0' #define STATUS_DEVICE '1' #define LIST_DEVICES '2' #define ENUM_QUEUES '3' #define VIEW_PRIORITY '4' #define CHANGE_PRIORITY '5' #define KILL_ACTIVE_JOB '6' #define PURGE_OWN_JOBS '7' #define PURGE_QUEUE '8' #define EXIT '9' #define STACK_SIZE 4096 // Function prototypes BOOL GetDeviceInfo (char *, char *); BOOL EnumerateQueues (char *, char far *); BOOL EnumerateDevices (char *); BOOL ViewPriority (char *, char * , char far *); BOOL ChangePriority (char *, char * , unsigned short); BOOL OpenPort (HSYSSEM, char *, char *); BOOL StopInactiveJobs (char *, char *, char far *); void DisplayPrompt (void); char GetNextAction (void); char far * FarStrcpy (char far *, char far *); void Usage(char *pszString); void main(int argc, char *argv[]) { char *pszDevice = "COM1"; // Default comm device char *pszQueue = "COMQUEUE"; // Default comm-queue name char *pszServer = ""; // Default to local computer char far *pszUser = ""; // far * from NetWkstaGetInfo call char far *pszWksta = ""; // far * from NetWkstaGetInfo call char chAction; // Menu selection char pszShare[RMLEN+1]; // Server, queuename for semaphore HSYSSEM hssmClose; // Handle to system semaphore USHORT cbBuflen; // Size of buffer int iCount; // Index counter USHORT usPriority = 1; // Priority assigned to queue USHORT cbTotalAvail; // Value for NetWkstaGetInfo call USHORT usRet; // MS OS/2 return code unsigned uRet; // LAN Manager return code struct wksta_info_10 *pBuf; // Pointer to return buffer for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iCount]; break; case 'q': // -q queuename pszQueue = argv[++iCount]; break; case 'u': // -u username pszUser = (char far *)argv[++iCount]; break; case 'd': // -d devicename pszDevice = argv[++iCount]; break; case 'w': // -w workstation pszWksta = (char far *)argv[++iCount]; break; case 'p': // -p priority usPriority = atoi(argv[++iCount]); break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } // End for loop if ((pszServer == NULL) || (*pszServer == '\0') || (pszUser == NULL) || (*pszUser == '\0') || (pszWksta == NULL) || (*pszWksta == '\0') ) { uRet = NetWkstaGetInfo(pszServer, // Servername 10, // Level NULL, // Return buffer 0, // Size of buffer &cbTotalAvail); // Count of bytes available if ((uRet != NERR_BufTooSmall) && (uRet != ERROR_MORE_DATA)) { printf("NetWkstaGetInfo returned %u\n", uRet); exit(1); } pBuf = (struct wksta_info_10 *) SafeMalloc(cbBuflen); uRet = NetWkstaGetInfo(pszServer, // Servername 10, // Level (char far *) pBuf, // Return buffer cbBuflen, // Size of buffer &cbTotalAvail); // Count of bytes available if (uRet != NERR_Success) { printf("NetWkstaGetInfo returned %u\n", uRet); exit(1); } } if ((pszServer != NULL) && (*pszServer != '\0')) // Set up for semaphore strcpy (pszShare, pszServer); else { strcpy (pszShare, "\\\\"); //Insert leading backslashes FarStrcat((char far *)pszShare, pBuf->wki10_computername); } strcat (pszShare, "\\" ); strcat (pszShare, pszQueue); if ((pszUser == NULL) || (*pszUser == '\0')) pszUser = pBuf->wki10_username; if ((pszWksta == NULL) || (*pszWksta == '\0')) pszWksta = pBuf->wki10_computername; // Create the semaphore that will be used to stop the active job. if ( (usRet = DosCreateSem (CSEM_PUBLIC, &hssmClose, SEMAPHORE )) != 0) { printf ("DosCreateSem returned %hu\n", usRet); exit(1); } while (TRUE) { DisplayPrompt(); chAction = GetNextAction (); printf("\n"); switch (chAction) { // Open the com port. case START_JOB: OpenPort (hssmClose, pszShare, SEMAPHORE); continue; // Close (has no effect if there is no active job). case PURGE_QUEUE: uRet = NetCharDevQPurge(pszServer, pszQueue); printf("NetCharDevQPurge returned %u\n", uRet); continue; //Kill the active job. case KILL_ACTIVE_JOB: uRet = NetCharDevControl(pszServer, pszDevice, CHARDEV_CLOSE); printf("NetCharDevControl returned %u\n", uRet); usRet = DosSemClear(hssmClose); printf("DosSemClear returned %hu\n", usRet); continue; // NetCharDevQPurgeSelf case PURGE_OWN_JOBS: StopInactiveJobs(pszServer, pszQueue, pszWksta); continue; // NetCharDevQGetInfo case VIEW_PRIORITY: ViewPriority (pszServer, pszQueue, pszUser); continue; // NetCharDevQSetInfo case CHANGE_PRIORITY: ChangePriority (pszServer, pszQueue, usPriority); continue; // NetCharDevQEnum case ENUM_QUEUES: EnumerateQueues (pszServer, pszUser); continue; // NetCharDevEnum case LIST_DEVICES: EnumerateDevices (pszServer); continue; // NetCharDevGetInfo case STATUS_DEVICE: GetDeviceInfo (pszServer, pszDevice); continue; // Close if currently using port or NetCharDevQPurgeSelf. case EXIT: StopInactiveJobs( pszServer, pszQueue, pszWksta); usRet = DosSemClear(hssmClose); printf("DosSemClear returned %hu\n", usRet); break; default: printf("Invalid option: select 1-%c\n", EXIT); continue; } break; } free (pBuf); exit(0); } // OpenPort spawns a child process that: // - Opens the com port (using the UNC name) // - Writes a test message to the port // - Waits on the \sem\chardev semaphore, then closes the port // // If the port is being used by another process, the DosOpen function // in the child process blocks until the port is freed. // // Note: You can always use the same semaphore because the DosOpen function // in the child process blocks if another process currently owns the port // (that is, only one process can wait on the semaphore at any one time). BOOL OpenPort (HSYSSEM hssmClose, char * pszShare, char * pszSem) { char achFailName[PATHLEN]; RESULTCODES rescResults; char pszArgs[PATHLEN]; char *pszNextArg; USHORT usRet; /* * Set the semaphore to cause the child process to wait after printing * the first line. */ usRet = DosSemSet(hssmClose); printf("DosSemSet returned %hu\n", usRet); /* * Make up the argument list for the child process: * usecom<NULL>sharename semaphore<NULL><NULL> * Make sure there are two null terminators in the argument list. */ strnset (pszArgs, '\0', PATHLEN); strcpy (pszArgs, CHILD_PROCESS); pszNextArg = pszArgs + strlen(pszArgs) + 1; strcpy (pszNextArg, pszShare); strcat (pszNextArg, " "); strcat (pszNextArg, pszSem); usRet = DosExecPgm (achFailName, PATHLEN, EXEC_ASYNC, pszArgs, NULL, &rescResults, CHILD_PROCESS); printf ("DosExecPgm returned %hu\n", usRet); if (usRet) return FALSE; return TRUE; } //======================================================================== // NetCharDevGetInfo // // This API finds the status of the ComShare device. //======================================================================== BOOL GetDeviceInfo (char * pszServer, char * pszDev) { unsigned short cbTotalAvail; unsigned uRet; struct chardev_info_1 * pCharDevInfo; /* * The chardev_info_1 structure contains no variable-length data, so * there's no need to find out how much buffer space is required. */ pCharDevInfo = SafeMalloc(sizeof (struct chardev_info_1)); uRet = NetCharDevGetInfo(pszServer, // Servername pszDev, // Devicename 1, // Info level (char far *)pCharDevInfo, // Buffer sizeof(struct chardev_info_1), // Size of buffer &cbTotalAvail); printf("NetCharDevGetInfo returned %u\n", uRet); if (uRet != NERR_Success) return FALSE; else { printf ("Status of device %s ",pCharDevInfo->ch1_dev); printf ("is %d ", pCharDevInfo->ch1_status); if (pCharDevInfo->ch1_status & CHARDEV_STAT_OPENED) printf ("(open"); else printf ("(idle"); if (pCharDevInfo->ch1_status & CHARDEV_STAT_ERROR) printf (" and in error"); printf(")\n\n"); if (pCharDevInfo->ch1_username[0] != '\0') printf ("Username is %s", pCharDevInfo->ch1_username); else printf ("No current users\n"); } free(pCharDevInfo); return TRUE; } //======================================================================== // NetCharDevEnum // // This API displays a list of character devices on the server. // Note: The attached devices are available only at info level 1. //======================================================================== BOOL EnumerateDevices (char * pszServer) { unsigned short cEntriesRead; unsigned short cTotalEntries; unsigned short cbBuflen; unsigned short iCount; unsigned uRet; struct chardev_info_1 *pBuf, *pB; // First, a call to see what size buffer is needed. uRet = NetCharDevEnum(pszServer, // Servername 1, // Info level NULL, // No buffer provided 0, // Size of buffer &cEntriesRead, // Count of entries read &cTotalEntries); // Count of entries available cbBuflen = (cTotalEntries + 1) * sizeof(struct chardev_info_1); pBuf = (struct chardev_info_1 *) SafeMalloc(cbBuflen); pB = pBuf; uRet = NetCharDevEnum(pszServer, // Servername 1, // Info level (char far *)pBuf, // Data returned here cbBuflen, // Size of buffer, in bytes &cEntriesRead, // Count of entries read &cTotalEntries); // Count of entries available printf("NetCharDevEnum returned %u\n", uRet); if (uRet != NERR_Success) { free(pB); return FALSE; } if (cTotalEntries == 0) printf("There are no comm devices on this server\n"); else { for (iCount = 0; iCount < cEntriesRead; iCount++) { printf("Device %s: ", pBuf->ch1_dev); printf("has status %d\n", pBuf->ch1_status); if (pBuf->ch1_status && CHARDEV_STAT_OPENED) { printf("Open %lu seconds ", pBuf->ch1_time); printf("by %s\n", pBuf->ch1_username); } pBuf++; } } free(pB); return TRUE; } //======================================================================== // NetCharDevQEnum // // This API displays a list of character-device queues and the devices // they are attached to. // Note: The attached devices are available only at info level 1. //======================================================================== BOOL EnumerateQueues (char * pszServer, char far * pszUser) { unsigned short cEntriesRead; unsigned short cTotalEntries; unsigned short cbBuflen; unsigned short iCount; unsigned uRet; struct chardevQ_info_1 * pQInfo; struct chardevQ_info_1 * pBuf; // First, a call to see what size buffer is needed. uRet = NetCharDevQEnum(pszServer, // Servername pszUser, // Username 1, // Info level NULL, // No buffer provided 0, // Size of buffer &cEntriesRead, // Count of entries read &cTotalEntries); // Count of entries available cbBuflen = cTotalEntries * MAX_CHARDEVQ_INFO_1; pBuf = SafeMalloc(cbBuflen); // Remember start of memory block pQInfo = pBuf; uRet = NetCharDevQEnum(pszServer, // Servername pszUser, // Username 1, // Info level (char far *)pQInfo, // Data returned here cbBuflen, // Size of buffer, in bytes &cEntriesRead, // Count of entries read &cTotalEntries); // Count of entries available printf("NetCharDevQEnum returned %u\n", uRet); if (uRet != NERR_Success) return FALSE; else { if (cTotalEntries == 0) { printf("There are no comm queues on this server\n"); } else { for (iCount = 0; iCount < cEntriesRead; iCount++) { printf("\nQueue %s: ",pQInfo->cq1_dev ); printf("has devices: %Fs\n", pQInfo->cq1_devs ); printf("%u users, ", pQInfo->cq1_numusers ); /* * If numahead = CHARDEVQ_NO_REQUESTS, user has no jobs * in the queue. */ if (pQInfo->cq1_numahead == CHARDEVQ_NO_REQUESTS) printf("user %s has no jobs\n", pszUser); else printf("%d users ahead of %s\n", pQInfo->cq1_numahead, pszUser); pQInfo++; } } } free(pBuf); return TRUE; } //======================================================================== // NetCharDevQGetInfo // // This API views the queue priority. //======================================================================== BOOL ViewPriority (char *pszServer, char *pszQ, char far *pszUser) { struct chardevQ_info_1 *pBuf; unsigned short cbTotalAvail; unsigned short cbBuflen = sizeof( struct chardevQ_info_1) + 256; unsigned uRet; pBuf = (struct chardevQ_info_1 *) SafeMalloc (cbBuflen); uRet = NetCharDevQGetInfo(pszServer, // Servername pszQ, // Queuename pszUser, // Username 1, // Info level (char far *)pBuf, // Buffer cbBuflen, // Size of buffer &cbTotalAvail); // Count of bytes available printf("NetCharDevQGetInfo returned %u\n", uRet); if (uRet == NERR_Success) { printf ("Queue %s ", pBuf->cq1_dev); printf ("has priority %d\n", pBuf->cq1_priority); printf ("Devices = %s\n", pBuf->cq1_devs); printf ("Number of users in queue = %d\n", pBuf->cq1_numusers); printf ("Number ahead of %s ", pszUser); printf ("= %d\n", pBuf->cq1_numahead); } free(pBuf); return TRUE; } //======================================================================== // NetCharDevQSetInfo // // This API changes the queue priority from the default (5). //======================================================================== BOOL ChangePriority (char * pszSrv, char * pszQ, unsigned short usPrty ) { unsigned uRet; /* * There are two ways to call NetCharDevQSetInfo. * If sParmNum == PARMNUM_ALL, you must pass it a whole structure. * Otherwise, you can set sParmNum to the element of the structure * you want to change. Only the latter method is shown here. */ uRet = NetCharDevQSetInfo(pszSrv, // Servername pszQ, // Queuename 1, // Info level (char far *)&usPrty, // Buffer sizeof (usPrty), // Size of buffer CHARDEVQ_PRIORITY_PARMNUM); // Parameter code number printf("NetCharDevQSetInfo returned %u\n", uRet); if (uRet != NERR_Success) return FALSE; else printf ("Priority for queue changed to %d\n", usPrty); return TRUE; } //======================================================================== // NetCharDevQPurgeSelf // // This API removes its own jobs from the queue. It removes only // jobs that have not started printing. //======================================================================== BOOL StopInactiveJobs (char *pszServer, char *pszQ, char far *pszComputer) { unsigned uRet; uRet = NetCharDevQPurgeSelf (pszServer, // Servername pszQ, // Queuename pszComputer); // Workstation name printf("NetCharDevQPurgeSelf returned %u\n", uRet); switch (uRet) { case NERR_Success: break; case NERR_ItemNotFound: printf ("There are no jobs in the queue\n"); break; default: return FALSE; } return TRUE; } void DisplayPrompt(void) { printf("\n\nCharacter Device Category API Examples\n\n"); printf("%c. Start job: DosExecPgm DosOpen comm device\n", START_JOB); printf("%c. Device status: NetCharDevGetInfo\n", STATUS_DEVICE); printf("%c. List all devices: NetCharDevEnum\n", LIST_DEVICES); printf("%c. List all queues: NetCharDevQEnum\n", ENUM_QUEUES); printf("%c. View queue: NetCharDevQGetInfo\n", VIEW_PRIORITY); printf("%c. Change priority: NetCharDevQSetInfo\n", CHANGE_PRIORITY); printf("%c. Close device, kill job: NetCharDevControl\n", KILL_ACTIVE_JOB); printf("%c. Stop all jobs: NetCharDevQPurgeSelf\n", PURGE_OWN_JOBS); printf("%c. Purge queue: NetCharDevQPurge\n", PURGE_QUEUE); printf("%c. Exit\n", EXIT); printf("Enter selection: "); } // Return the next character typed from the keyboard. char GetNextAction () { return ((char)getche()); } void Usage(char *pszString) { fprintf(stderr, "Usage: %s [-s \\\\server] [-q queue]", pszString); fprintf(stderr, " [-u username]\n"); fprintf(stderr, "\t[-w wksta] [-d device] [-p priority]\n"); exit(1); } /* NETCHAR2.C -- a sample program demonstrating NetCharDev API functions. This program should only be executed from NETCHAR1.C. This program attempts to open the comm device using the UNC name. Note: If the device has already been opened by another process, DosOpen blocks until the device is freed. Once the port is open, a sentence is written out and the process waits on a semaphore to be told to close the port. usage: netchar2 \\server\share semaphore This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define CALLING_PROGRAM "netchar1" #define STRING1 "A test message\r\n" #define STRING1LEN strlen(STRING1) #define STRING2 "Closing statement\r\n" #define STRING2LEN strlen(STRING2) #define INCL_BASE #include <os2.h> // MS OS/2 base header files #define INCL_NETERRORS #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header file #include <stdlib.h> #include <string.h> void Usage(char *pszString); void main(int argc, char *argv[]) { HFILE fh; USHORT usAction; unsigned short usRet; USHORT cbWritten; HSYSSEM hssmClose; if (argc != 3) Usage(CALLING_PROGRAM); // Open the semaphore this thread waits for. if (DosOpenSem(&hssmClose, argv[2]) != 0) exit(1); /* * The first process to open gets a file handle immediately; * all subsequent processes are suspended until the device * is freed (that is, until the current owner closes the device). */ usRet = DosOpen (argv[1], &fh, &usAction, 0L, // No file length, since this is a com port 0, // No action specified since we aren't creating FILE_OPEN, OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYREADWRITE, 0L // Reserved ); if (usRet != NERR_Success) exit(1); DosWrite(fh, STRING1, STRING1LEN, &cbWritten); // Wait to be told to close or for 30 seconds (whichever comes first). usRet = DosSemWait(hssmClose, 30000L); if (usRet != ERROR_SEM_TIMEOUT) { printf("\nQueue was forced closed, DosSemWait returned %hu\n", usRet); exit(1); } DosWrite(fh, STRING2, STRING2LEN, &cbWritten); /* * Close the device using DosClose instead of NetCharDevControl. * The NetCharDevControl function is designed for administrators * when they need to force the device closed. */ DosClose(fh); exit(0); } void Usage(char *pszString) { fprintf(stderr, "This program should not be called directly.\n"); fprintf(stderr, "Usage: %s [-s \\\\server] [-q queue]", pszString); fprintf(stderr, " [-u username]\n"); fprintf(stderr, "\t[-w wksta] [-d device] [-p priority]\n"); exit(1); } Configuration Category Configuration API functions retrieve network configuration information from the LANMAN.INI file. When executed on the local computer, Configuration API functions require that the NETWKSTA device driver be installed. When executed on a remote server, they require that the local Workstation service be started. The Configuration category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and CONFIG.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETCONFIG, and including the master header file, LAN.H. For more information about these definitions, see the "Example" section, later in this category. These are the Configuration API functions: ■ NetConfigGet2 ■ NetConfigGetAll2 Description NetConfigGet2 retrieves a single entry value from the LANMAN.INI file on the local computer or on a remote server. NetConfigGetAll2 retrieves the value of the entries for a given component from the LANMAN.INI file on the local computer or on a remote server. The LANMAN.INI file is an ASCII file that contains configuration information for LAN Manager services, as well as network configuration information for user-defined services and applications. It consists of component lines, entry lines, and comment lines, in the following format: ■ Component lines mark the start of a set of information, in this form: [component name] ■ Entry lines contain a parameter and a value, in this form: entry = value The entry value can consist of any text. Configuration API functions do not process the text, although they do remove leading and trailing spaces. Interpretation of the value is left to the caller. If an entry appears several times in a single component, NetConfigGetAll2 returns each instance; NetConfigGet2 returns only the first instance. Using the same entry name in different components does not affect the data returned by NetConfigGet2. ■ Comment lines are any blank lines or lines that have a semicolon (;) as the first nonblank character. For example, a LANMAN.INI [workstation] component might contain the following information: [workstation] ; define net_tools workstation computername = NET_TOOLS charcount = 16 chartime = 250 charwait = 3600 domain = LAN The LANMAN.INI file contains default values for network parameters. These values are not necessarily the current values for those parameters. For example, in the preceding example, the computername component is set to NET_TOOLS, but the workstation does not necessarily have that name. A different name could be specified from the command line when the Workstation service is started. Use NetWkstaGetInfo to retrieve the current value of parameters in the [workstation] component; use NetServerGetInfo to retrieve the current values for the [server] component. See Also For information about See ──────────────────────────────────────────────────────────────────────────── LANMAN.INI file LAN Manager administrator's manual(s) NetConfigGet2 ──────────────────────────────────────────────────────────────────────────── NetConfigGet2 retrieves the value of a single specified entry for a particular component of the LANMAN.INI file on the local computer or on a remote server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level Admin privilege or accounts, comm, print, or server operator privilege is required to successfully execute NetConfigGet2 on a remote server. Syntax #define INCL_NETCONFIG #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetConfigGet2 (const char far * pszServer, const char far * pszReserved, const char far * pszComponent, const char far * pszParameter, const char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbParmlen ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetConfigGet2. A null pointer or null string specifies the local computer. pszReserved Reserved; must be a null pointer. pszComponent Points to an ASCIIZ string that specifies which LANMAN.INI component to search. pszParameter Points to an ASCIIZ string that specifies the entry whose value is to be returned. pbBuffer Points to the buffer where the value of the entry is to be returned. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcbParmlen Points to an unsigned short integer in which the size of the entry value (in bytes) is returned. This count is valid only if NetConfigGet2 returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_FILE_NOT_FOUND 2 The file was not found. ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── privilege for this operation. ERROR_SHARING_VIOLATION 32 A sharing violation occurred. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_BadTransactConfig 2141 The server is not configured for Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_CfgCompNotFound 2146 The specified component in the LANMAN.INI file is not found. NERR_CfgParamNotFound 2147 The specified parameter in the LANMAN.INI file is not found. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks NetConfigGet2 returns the entry value of the specified LANMAN.INI component as an ASCIIZ string in the buffer pointed to by pbBuffer. This string consists of all text to the right of the equal sign (=) in the LANMAN.INI entry. NetConfigGet2 removes leading and trailing spaces, but performs no other processing on the text. For example, the LANMAN.INI entry " sky = blue,1,long comment string " is returned as the following string: "blue,1,long comment string" The value of cbBuffer must be at least 1 larger than the value returned in pcbParmlen; this is necessary to provide for the NUL at the end of the ASCIIZ string. NetConfigGet2 supersedes NetConfigGet (used in earlier versions of LAN Manager). These functions are the same except that NetConfigGet2 has the pszServer parameter, which enables it to be called remotely. For more information, see Appendix B, "Upgrading LAN Manager 1.0 Applications." See Also For information about See ──────────────────────────────────────────────────────────────────────────── LANMAN.INI file LAN Manager administrator's manual(s) NetConfigGetAll2 ──────────────────────────────────────────────────────────────────────────── NetConfigGetAll2 retrieves all the configuration information for a given component in the LANMAN.INI file on a local or a remote computer. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level Admin privilege or account, comm, print, or server operator privilege is required to successfully execute NetConfigGetAll2 on a remote server. Syntax #define INCL_NETCONFIG #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetConfigGetAll2 (const char far * pszServer, const char far * pszReserved, const char far * pszComponent, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbReturned, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetConfigGetAll2. A null pointer or null string specifies the local computer. pszReserved Reserved; must be a null pointer. pszComponent Points to an ASCIIZ string that specifies which LANMAN.INI component to search. pbBuffer Points to the buffer where the entry values are to be returned. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcbReturned Points to an unsigned short integer in which the number of bytes returned in the buffer pointed to by pbBuffer is returned. pcbTotalAvail Points to an unsigned short integer in which the number of bytes of data available is returned. This count is valid only if NetConfigGetAll2 returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_FILE_NOT_FOUND 2 The file was not found. ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_SHARING_VIOLATION 32 A sharing violation occurred. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_CfgCompNotFound 2146 The specified component in the LANMAN.INI file is not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks NetConfigGetAll2 returns a set of concatenated ASCIIZ strings in the buffer pointed to by pbBuffer, representing configuration information for the specified component. Each string is terminated by a NUL, and the whole buffer is terminated by a null string. NetConfigGetAll2 removes leading and trailing spaces, but performs no other processing on the text. Information is returned in the form ENTRY=value. The entry name (left of the equal sign) is converted to uppercase. For example, the LANMAN.INI entry " sky = blue, 1, long comment string " " ground = brown, 2" is returned as these two consecutive strings: "SKY=blue, 1, long comment string" "GROUND=brown, 2" NetConfigGetAll2 supersedes NetConfigGetAll (used in earlier versions of LAN Manager). These functions are the same except that NetConfigGetAll2 has the pszServer parameter, which enables it to be called remotely. For more information, see Appendix B, "Upgrading LAN Manager 1.0 Applications." See Also For information about See ──────────────────────────────────────────────────────────────────────────── LANMAN.INI file LAN Manager administrator's manual(s) Configuration Category Example /* NETCNFG.C -- a sample program demonstrating NetConfig API functions. This program requires that you have admin privilege or any type of operator privilege on the specified server. usage: netcnfg [-s \\server] [-p parameter] [-c component] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). parameter = Name of the LANMAN.INI parameter to get. component = Name of the component from which the parameter is to be retrieved. API Used to... ================ =========================================== NetConfigGet2 Retrieve a parameter in the LANMAN.INI file on the specified server NetConfigGetAll2 Retrieve complete component info from the specified LANMAN.INI file This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETCONFIG #define INCL_NETERRORS #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include "samples.h" // Internal routine header file #define DEFAULT_COMPONENT "Workstation" #define DEFAULT_PARAMETER "Domain" #define SMALL_BUFF 64 #define BIG_BUFF 4096 void Usage (char * pszProgram); void main(int argc, char *argv[]) { char *pszServer = ""; // Servername char *pszComponent = DEFAULT_COMPONENT; // Component to list char *pszParameter = DEFAULT_PARAMETER; // Parameter within component char *pszBuffer, *p; // String pointers int iCount; // Index counter unsigned short cbBuffer; // Count of bytes in buffer unsigned short cbParmlen; // Length of returned parameter unsigned short cbRead; // Count of bytes read unsigned short cbAvail; // Count of bytes available API_RET_TYPE uReturnCode; // API return code for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iCount]; break; case 'c': // -c component pszComponent = argv[++iCount]; break; case 'p': // -p parameter pszParameter = argv[++iCount]; break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } //======================================================================== // NetConfigGet2 // // This API retrieves a single entry from the LANMAN.INI file on a // specified server. If no servername is given, the local LANMAN.INI // file is used. When executed remotely, the user must have admin // privilege or at least one operator privilege on the remote server. //======================================================================== cbBuffer = SMALL_BUFF; pszBuffer = SafeMalloc(cbBuffer); uReturnCode = NetConfigGet2( pszServer, // Servername NULL, // Reserved; must be NULL pszComponent, // Component in LANMAN.INI pszParameter, // Parameter in component pszBuffer, // Pointer to return buffer cbBuffer, // Size of buffer &cbParmlen); // Length of returned parameter printf("NetConfigGet2 returned %u \n", uReturnCode); if (uReturnCode == NERR_Success) printf(" %s = %s\n\n", pszParameter, pszBuffer); else if (uReturnCode == NERR_BufTooSmall) printf(" %hu bytes were provided, but %hu bytes were needed\n\n", cbBuffer, cbParmlen); free(pszBuffer); //======================================================================== // NetConfigGetAll2 // // This API returns information for an entire LANMAN.INI component // such as [networks] or [workstation]. The returned information is a // sequence of null-terminated strings followed by a null string. //======================================================================== cbBuffer = BIG_BUFF; pszBuffer = SafeMalloc(cbBuffer); uReturnCode = NetConfigGetAll2( pszServer, // Name of remote server NULL, // Reserved; must be NULL pszComponent, // Component of LANMAN.INI pszBuffer, // Pointer to return buffer cbBuffer, // Size of buffer &cbRead, // Count of bytes read &cbAvail); // Count of bytes available printf("NetConfigGetAll2 returned %u \n", uReturnCode); switch(uReturnCode) { case NERR_Success: // It worked p = pszBuffer; while (*p) // While not at null string { printf(" %s\n", p); // Print string p += (strlen(p) + 1); // Step past trailing NUL } break; case ERROR_BAD_NETPATH: printf(" Server %s not found.\n", pszServer); break; case NERR_InvalidAPI: printf(" The remote server %s does not support this API.\n", pszServer); break; default: break; } free(pszBuffer); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s [-s \\\\server] [-c component]" \ " [-p parameter]\n", pszProgram); exit(1); } Connection Category The Connection API function, NetConnectionEnum, lists server connections. When a remote server is specified, NetConnectionEnum requires that the Workstation service be started on the local computer and that the Server service be started on the specified server. The Connection category function, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and SHARES.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETCONNECTION, and including the master header file, LAN.H. For more information about these definitions, see the "Example" section, later in this category. Description A computer accesses a shared resource on a server by means of a connection. A connection is a software link between a computer and a server, made by assigning a local or null devicename to the shared resource on the server. The NetUseAdd function establishes connections. NetConnectionEnum lists information about all connections to a server made by a specified computer, or about all connections made to a specified sharename. Data Structures NetConnectionEnum returns data at a detail level of 0 or 1, using the connection_info_0 and connection_info_1 data structures. Connection Information (level 0) The connection_info_0 data structure has this format: struct connection_info_0 { unsigned short coni0_id; }; where coni0_id Specifies the connection identification number. Connection Information (level 1) The connection_info_1 data structure has this format: struct connection_info_1 { unsigned short coni1_id; unsigned short coni1_type; unsigned short coni1_num_opens; unsigned short coni1_num_users; unsigned long coni1_time; char far * coni1_username; char far * coni1_netname; }; where coni1_id Specifies the connection identification number. coni1_type Specifies the type of connection made from the local computer to the shared resource. The SHARES.H header file defines these possible connections: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── STYPE_DISKTREE 0 Disk connection. STYPE_PRINTQ 1 Printer queue connection. STYPE_DEVICE 2 Communication-device connection. STYPE_IPC 3 Interprocess communication (IPC) connection. ──────────────────────────────────────────────────────────────────────────── coni1_num_opens Specifies the number of resources (files, pipes, or devices) open as a result of the connection. coni1_num_users Specifies the number of connected users. coni1_time Specifies the number of seconds the connection has been established. coni1_username Points to an ASCIIZ string. On a server that has user-level security, the string contains the name of the user who established the connection. On a server that has share-level security, the string contains the name of the computer that established the connection. coni1_netname Points to an ASCIIZ string that contains the sharename or a computername. This value is the inverse of the NetConnectionEnum pszQualifier parameter: when pszQualifier is a sharename, coni1_netname is a computername; when pszQualifier is a computername, coni1_netname is a sharename. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Connecting to a shared resource NetUseAdd on a server NetConnectionEnum ──────────────────────────────────────────────────────────────────────────── NetConnectionEnum lists all connections made to a shared resource on the server or all connections established from a particular computer. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or server, print, or comm operator privilege is required to successfully execute NetConnectionEnum on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETCONNECTION #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetConnectionEnum (const char far * pszServer, const char far * pszQualifier, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalEntries ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetConnectionEnum. A null pointer or null string specifies the local computer. pszQualifier Points to an ASCIIZ string that specifies either a sharename or a computername. If pszQualifier is a sharename, NetConnectionEnum lists all connections made to that sharename. If pszQualifier is a computername, NetConnectionEnum lists all connections made from that computer to the server specified by pszServer. This parameter cannot be a null pointer or null string. When pszQualifier represents a computername, it must start with two backslash characters (\\). sLevel Specifies the level of detail (0 or 1) to be returned in the buffer pointed to by pbBuffer. pbBuffer Points to the buffer for data returned by NetConnectionEnum. On a successful return, the buffer contains connection_info_X data structures, where X is 0 or 1, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the return buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer that specifies the number of entries in the return buffer pointed to by pbBuffer. This count is valid only if NetConnectionEnum returns NERR_Success or ERROR_MORE_DATA. pcTotalEntries Points to an unsigned short integer that specifies the total number of entries available. This count is valid only if NetConnectionEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_WkstaNotStarted 2138 The Workstation service is not started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_NetNameNotFound 2310 The sharename does not exist. NERR_ClientNameNotFound 2312 The specified computer does not have a session with the server. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing all available servers NetServerEnum Listing sessions on a server NetSessionEnum Connection Category Example /* NETCONS.C -- a sample program demonstrating NetConnectionEnum. This program requires that you have admin privilege on the specified server. usage: netcons [-s \\server] [-r sharename | -w \\wkstaname] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). sharename = Name of the shared resource as qualifier. \\wkstaname = Computername used as qualifier. API Used to... ================= ========================================== NetConnectionEnum List connections to a server's shared resources, or list connections established from a particular computer This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETERRORS #define INCL_NETCONNECTION #define INCL_NETSHARE #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include "samples.h" // Internal routine header file void Usage(char *pszString); void main(int argc, char *argv[]) { char *pszServerName = ""; // Can be null; default to local machine char *pszQualifier = "C$"; // Cannot be null; default to shared drive unsigned uRet; // API return code unsigned short cbBuflen; // Buffer length unsigned short cEntriesRead; // Count of entries read unsigned short cTotAvail; // Count of entries available unsigned short fSetQualifier = 0; // Flag; set qualifier only once int iCount; // Index; loop counter struct connection_info_1 *pBuf1, *p1; for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServerName = argv[++iCount]; break; case 'w': // -w workstation if (fSetQualifier == 1) Usage(argv[0]); // Exit program fSetQualifier = 1; pszQualifier = argv[++iCount]; break; case 'r': // -r sharename if (fSetQualifier == 1) Usage(argv[0]); // Exit program fSetQualifier = 1; pszQualifier = argv[++iCount]; break; case 'h': default: Usage(argv[0]); // Exit program } } else Usage(argv[0]); } printf("\nConnection Category API Example\n\n"); // Initial call to determine how large a return buffer is needed. uRet = NetConnectionEnum(pszServerName, // Servername pszQualifier, // Qualifier 1, // Reporting level (0 or 1) NULL, // Return buffer 0, // Size of target buffer &cEntriesRead, // Count of entries read &cTotAvail); // Count of entries available if ((uRet != NERR_Success) && (uRet != ERROR_MORE_DATA)) { printf("NetConnectionEnum returned %u\n", uRet); exit(1); } if (cTotAvail == 0) { printf("No connections with %s\n", pszQualifier); exit(0); } // Each structure contains strings UNLEN+1 and NNLEN+1 long. cbBuflen = cTotAvail * (sizeof (struct connection_info_1) + UNLEN + NNLEN + 2); pBuf1 = (struct connection_info_1 *) SafeMalloc(cbBuflen); p1 = pBuf1; // Save start of memory block for cleanup uRet = NetConnectionEnum(pszServerName, // Servername pszQualifier, // Qualifier 1, // Reporting level (0 or 1) (char far *)pBuf1, // Target buffer for info cbBuflen, // Size of target buffer &cEntriesRead, // Count of entries read &cTotAvail); // Count of entries available printf("NetConnectionEnum returned %u \n", uRet); if (uRet != NERR_Success) exit(1); // Exit if error occurred for (iCount = 0; iCount < (int) cEntriesRead; iCount++) { printf("Connection id number %hu\n", pBuf1->coni1_id); printf(" connection type : %hu ", pBuf1->coni1_type); switch (pBuf1->coni1_type) { case STYPE_DISKTREE: printf("Disk Connection\n"); break; case STYPE_PRINTQ: printf("Printer Queue Connection\n"); break; case STYPE_DEVICE: printf("Character Device Connection\n"); break; case STYPE_IPC: printf("IPC Connection\n"); break; default: printf("Unknown Connection Type\n"); break; } printf(" open files on connection : %hu\n", pBuf1->coni1_num_opens); printf(" users on connection : %hu\n", pBuf1->coni1_num_users); printf(" seconds since established: %lu\n", pBuf1->coni1_time); /* * Print the name of the user or computer that made the connection. * If server has share-level security, the name is a username. * If server has user-level security, the name is a computername. */ printf(" connection user name : %s\n", pBuf1->coni1_username); /* * Print the network name, the inverse of the qualifier. * If qualifier is a sharename, netname is a computername. * If qualifier is a computername, netname is a username. */ printf(" connection network name : %s\n", pBuf1->coni1_netname); pBuf1++; // Increment the record pointer } printf("%hu out of %hu entries read\n", cEntriesRead, cTotAvail); free(p1); exit(0); } void Usage(char *pszString) { fprintf(stderr, "Usage: %s [-s \\\\server]", pszString); fprintf(stderr, " [-r sharename | -w \\\\wkstaname]\n"); exit(1); } Domain Category Domain API functions retrieve information about a domain. They require that the Workstation service be started. NetLogonEnum also requires that the Netlogon service be started on the specified server. The Domain category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and ACCESS.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETDOMAIN, and including the master header file, LAN.H. For more information about these definitions, see the "Example" section, later in this category. These are the Domain API functions: ■ NetGetDCName ■ NetLogonEnum Description NetGetDCName retrieves the name of the domain controller. NetLogonEnum retrieves information about the users who are logged on in a domain. Data Structures NetGetDCName returns the domain name in the form of an ASCIIZ string. NetLogonEnum uses the user_logon_info_X data structure, where X is 0 or 2, depending on the level of detail specified. Logon Information (Level 0) The user_logon_info_0 data structure has this format: struct user_logon_info_0 { char usrlog0_eff_name[UNLEN+1]; char usrlog0_pad_1; }; where usrlog0_eff_name Specifies the name of the user. The constant UNLEN is defined in the NETCONS.H header file. usrlog0_pad_1 Aligns the next data structure element on a word boundary. Logon Information (Level 2) The user_logon_info_2 data structure has this format: struct user_logon_info_2 { char usrlog2_eff_name[UNLEN+1]; char usrlog2_pad_1; char far * usrlog2_computer; char far * usrlog2_full_name; char far * usrlog2_usrcomment; unsigned long usrlog2_logon_time; }; where usrlog2_eff_name Specifies the name of the user. The constant UNLEN is defined in the NETCONS.H header file. usrlog2_pad_1 Aligns the next data structure element on a word boundary. usrlog2_computer Points to an ASCIIZ string that contains the name of the computer where the user logged on. usrlog2_full_name Points to an ASCIIZ string that contains the full name of the user. usrlog2_usrcomment Points to the ASCIIZ string that contains the user's comment. usrlog2_logon_time Specifies the time the user logged on to the network. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. A value of -1 indicates that the logon time is not available. NetGetDCName ──────────────────────────────────────────────────────────────────────────── NetGetDCName returns the name of a domain controller for a specified domain. If no domain name or servername is supplied, NetGetDCName returns the name of the domain controller for the local workstation's primary domain. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level No special privilege level is required to successfully execute NetGetDCName. Syntax #define INCL_NETDOMAIN #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetGetDCName (const char far * pszServer, const char far * pszDomain, char far * pbBuffer, unsigned short cbBuffer ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetGetDCName. A null pointer or null string specifies the local computer. pszDomain Points to an ASCIIZ string that contains the name of the domain. A null pointer or null string indicates that the name of the domain controller for the primary domain is to be returned. pbBuffer Points to the buffer in which to return the name of the domain controller. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. Return Codes ╓┌───────────────────────┌───────┌───────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_InvalidComputer 2351 The specified computername is invalid. NERR_DCNotFound 2453 The domain controller for this domain was not found. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Remarks If the return code is NERR_Success, the buffer contains an ASCIIZ string that contains the name of the domain controller in UNC format, for example: \\SERVER NetGetDCName can require a large amount of network time and can affect the performance of applications that call it often. Because the domain controller of a domain can change, you should not assume that the domain controller remains unchanged for long periods. Applications that require the name of the domain controller should call NetGetDCName when necessary, unless performance tests indicate that these calls cause poor performance. You can assume only that the domain controller remains unchanged for short periods. NetLogonEnum ──────────────────────────────────────────────────────────────────────────── NetLogonEnum supplies information about users who are logged on in a domain. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level No special privilege level is required to successfully execute NetLogonEnum. Syntax #define INCL_NETDOMAIN #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetLogonEnum (const char far * pszServer, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetLogonEnum. A null pointer or null string specifies the local computer. sLevel Specifies the level of detail (0 or 2) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a sequence of user_logon_info_X data structures, where X is 0 or 2, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer in which a count of the number of users listed in the buffer is returned. This count is valid only if NetLogonEnum returns NERR_Success or ERROR_MORE_DATA. pcTotalAvail Points to an unsigned short integer in which a count of the total number of logon data structures available is returned. This count is valid only if NetLogonEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_ACFNotFound 2219 LAN Manager could not find the user accounts database file, NET.ACC. This file should be in the ACCOUNTS subdirectory of the LANMAN directory. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_ACFFileIOFail 2229 A disk I/O failure occurred. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. NERR_NetlogonNotStarted 2455 The Netlogon service is not running. ──────────────────────────────────────────────────────────────────────────── Remarks NetLogonEnumcan return more than one entry for a particular username, if that user is logged on at more than one workstation. Domain Category Example /* NETDOM.C -- a sample program demonstrating the Domain API functions. This program requires that the Netlogon service be started on the specified server. usage: netdom [-s \\server] [-d domain] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). domain = Name of the domain. API Used to... ============ ================================================ NetGetDCName Find the domain controller for a given domain NetLogonEnum Get details about users at the domain controller This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETDOMAIN #define INCL_NETERRORS #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include <time.h> #include "samples.h" // Internal routine header file #define BIG_BUFF 32768 void Usage (char * pszProgram); void main(int argc, char *argv[]) { char * pszServer = ""; // Servername char * pszDomain = ""; // Domain name char pszDCName[UNCLEN+1]; // Name of domain controller int iCount; // Index counter unsigned short cRead; // Count of entries read unsigned short cAvail; // Count of entries available unsigned short cbBuffer; // Size of buffer, in bytes API_RET_TYPE uReturnCode; // API return code struct user_logon_info_2 *pBuffer; // Data buffer for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iCount]; break; case 'd': // -d domain pszDomain = argv[++iCount]; break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } //======================================================================== // NetGetDCName // // This API returns the name of the server that is the domain // controller in the specified domain. If no domain name is given, // the name of the primary domain controller is returned. //======================================================================== cbBuffer = sizeof(pszDCName); uReturnCode = NetGetDCName(pszServer, // Server; NULL means local pszDomain, // Domain; NULL means primary pszDCName, // Return buffer cbBuffer); // Size of buffer printf("NetGetDCName returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) printf(" the domain controller is %s\n", pszDCName); else if (uReturnCode == NERR_DCNotFound) { printf(" domain controller not found\n"); } //======================================================================== // NetLogonEnum // // This API lists the logon names, logon times, and machines the users // logged on from. // // Note: In the printf() statement, the computername is pointed to by // a far pointer and so is formatted with %Fs. NetLogonEnum will NOT list // all the users logged on in a domain. It lists only those users logged // on to the specified server. //======================================================================== cbBuffer = BIG_BUFF; // Can be up to 64K pBuffer = (struct user_logon_info_2 *) SafeMalloc(cbBuffer); uReturnCode = NetLogonEnum(pszDCName, // Servername 2, // Level (0 or 2) (char far *)pBuffer, // Data returned here cbBuffer, // Size of supplied buffer &cRead, // Count of entries read &cAvail); // Count of entries available printf("NetLogonEnum for \"%s\" returned %u\n", pszDCName, uReturnCode); if (uReturnCode == NERR_Success || uReturnCode == ERROR_MORE_DATA) { putenv("TZ=GMT0"); // Allow ctime() to report local time for (iCount = 0; iCount < (int) cRead; iCount++) { printf(" %15s on machine %-15Fs Logon: %s", pBuffer->usrlog2_eff_name, pBuffer->usrlog2_computer, ctime(&pBuffer->usrlog2_logon_time)); pBuffer++; } printf("%hu out of %hu entries returned\n", cRead, cAvail); } free(pBuffer); exit(0); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s [-s \\\\server] [-d domain]\n", pszProgram); exit(1); } Error Logging Category Error Logging API functions control the error log. All Error Logging API functions require that the NETWKSTA device driver be installed. NetErrorLogWrite also requires that the Workstation service be started. The Error Logging category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and ERRLOG.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETERRORLOG, and including the master header file, LAN.H. For more information about these definitions, see the "Example" section, later in this category. These are the Error Logging API functions: ■ NetErrorLogClear ■ NetErrorLogRead ■ NetErrorLogWrite Description The error log is a file that stores error messages (in binary format). It contains information about LAN Manager software internal errors, MS OS/2 and MS-DOS internal errors, and network service errors. The default error log is NET.ERR in the LAN Manager LOGS directory. All Error Logging functions operate on this file. NetErrorLogWrite writes an entry to the error log; NetErrorLogRead reads entries from the error log; and NetErrorLogClear clears the error log and, optionally, saves the entries in a backup file. To set a maximum size for the error log, use one of these methods: ■ Use the net config command with the /maxerrorlog option. For more information, see your LAN Manager user's manual(s). ■ Set the maxerrorlog entry in the [workstation] section of the LANMAN.INI file. For a description of the LANMAN.INI file, see your LAN Manager administrator's manual(s). ■ Call the NetWkstaSetInfo function with the sParmNum parameter set to WKSTA_ERRLOGSZ_PARMNUM. Data Structure NetErrorLogRead and NetErrorLogWrite use the error_log data structure to read entries from and write entries to the error log. An entry consists of a fixed-length data structure. The data structure can be followed by ASCIIZ strings (el_text) that describe the error message, and a block of raw data (el_data) related to the cause of the error. Because of the variable lengths and structures of the el_data and el_text portions of the entry, only the fixed-length data structure is defined in the error_log data structure. The error log entry has the following format: struct error_log { unsigned short el_len; unsigned short el_reserved; unsigned long el_time; unsigned short el_error; char el_name[SNLEN+1]; unsigned short el_data_offset; unsigned short el_nstrings; }; /* * Variable-length data specific to the error. The * data consists of message strings and raw data. * The number of bytes of data is equivalent to: * el_len - el_data_offset - sizeof(unsigned short); */ char el_text[]; /* Error messages */ char el_data[]; /* Raw data */ unsigned short el_len; where el_len Specifies the length of the error log entry (in bytes). The el_len element is included both at the beginning and at the end of the entry to enable both forward and backward scanning of the log. el_reserved Reserved; must be 0. el_time Specifies the time that the service or application specified by el_name submitted the error entry. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. el_error Specifies the error code for the error. You can use el_error to obtain an error message from the NET.MSG file. el_name Contains an ASCIIZ string that specifies the name of the network service or application that returned the error entry. The constant SNLEN is defined in the NETCONS.H header file. el_data_offset Specifies the byte offset from the beginning of the error log entry to the start of its variable-length portion (el_text). el_nstrings Specifies how many ASCIIZ strings the el_text portion of the entry contains. el_text Points to ASCIIZ strings that describe the error. el_data Points to the raw data associated with the error. Error Log Codes The ERRLOG.H header file defines a number of standard error codes that can be written to the error log. Applications can use these values or they can define their own. The defined codes allow string data and raw data to be inserted along with the error code. The string data is represented in the table by a number preceded by a percent sign (%). For example, %1 is the first string. The string entries go in the el_text element of the data buffer. The raw data goes in the el_data element of the data buffer. For more information, see the "Example" section, later in this category. The ERRLOG.H header file defines the code, values, and meanings for these LAN Manager error codes: ╓┌─────────────────────────────────┌──────┌──────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_Internal_Error 3100 The operation failed because a network software error occurred. NELOG_Resource_Shortage 3101 The system ran out of a resource controlled by the %1 option. NELOG_Unable_To_Lock_Segment 3102 The service failed to obtain a long-term lock on the segment for NCBs. The error code is the data. NELOG_Unable_To_Unlock_Segment 3103 The service failed to release the long-term lock on the segment for NCBs. The error code is the data. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NCBs. The error code is the data. NELOG_Uninstall_Service 3104 An error stopped service %1. The error code from NetServiceControl is the data. NELOG_Init_Exec_Fail 3105 Initialization failed because of an MS OS/2 exec failure on path %1. The MS OS/2 error code is the data. NELOG_Ncb_Error 3106 An unexpected NCB was received. The NCB is the data. NELOG_Net_Not_Started 3107 The network is not started. NELOG_Ioctl_Error 3108 A DosDevIOCtl or DosFSCtl call to NETWKSTA.SYS failed. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NETWKSTA.SYS failed. The data shown is in this format: dword Approximate CS:IP of call to IOCtl or FSCtl word Error code word IOCtl or FSCtl number NELOG_System_Semaphore 3109 Unable to create or open system semaphore %1. The error code is the data. NELOG_Init_OpenCreate_Err 3110 Initialization failed because of an open/create error on the file %1. The MS OS/2 error code is the data. NELOG_NetBios 3111 An unexpected NetBIOS error occurred. The error code is the data. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── data. NELOG_SMB_Illegal 3112 An illegal SMB was received. The SMB is the data. NELOG_Service_Fail 3113 Initialization failed because the requested service %1 could not be started. NELOG_Entries_Lost 3114 Some entries in the error log were lost because of a buffer overflow. NELOG_Init_Seg_Overflow 3120 Initialization parameters that control resource use other than network buffers are sized so that too much memory is needed. NELOG_Srv_No_Mem_Grow 3121 The server cannot increase the Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_Srv_No_Mem_Grow 3121 The server cannot increase the size of a memory segment. NELOG_Access_File_Bad 3122 Initialization failed because account file: %1 is either incorrect or not present. NELOG_Srvnet_Not_Started 3123 Initialization failed because network: %1 was not started. NELOG_Init_Chardev_Err 3124 The server failed to start. Either all three character device parameters must be 0 or all three must be nonzero. NELOG_Remote_API 3125 A remote API request was halted due to the following invalid description string: %1. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_Ncb_TooManyErr 3126 The network %1 ran out of NCBs. You may need to increase NCBs for this network. The following information includes the number of NCBs submitted by the server when this error occurred: NELOG_Mailslot_err 3127 The server cannot create the %1 mailslot needed to send the ReleaseMemory alert message. The error received is: NELOG_ReleaseMem_Alert 3128 The server failed to register for the RELEASEMEMORY alert, with recipient %1. The error code from NetAlertStart is the data. NELOG_AT_cannot_write 3129 The server cannot update the AT Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_AT_cannot_write 3129 The server cannot update the AT schedule file. The file is corrupt. NELOG_Cant_Make_Msg_File 3130 The server encountered an error. The error code is the data. NELOG_Exec_Netservr_NoMem 3131 Initialization failed because of an MS OS/2 exec failure on path %1. There is not enough memory to start the process. The MS OS/2 error code is the data. NELOG_Server_Lock_Failure 3132 Long-term lock of server buffers failed. Check swap disk free space and reboot system to start server. NELOG_Msg_Shutdown 3140 The service has stopped due Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_Msg_Shutdown 3140 The service has stopped due to repeated consecutive occurrences of an NCB error. The last bad NCB follows in raw data. NELOG_Msg_Sem_Shutdown 3141 Shutdown has occurred due to a lock on the shared data segment. NELOG_Msg_Log_Err 3150 A file system error occurred while opening or writing to the system message log file, %1. Message logging has been switched off due to the error. The error code is the data. NELOG_VIO_POPUP_ERR 3151 Unable to display message popup due to an MS OS/2 VIO call error. The error code is the data. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_Msg_Unexpected_SMB_Type 3152 An illegal SMB was received. The SMB is the data. NELOG_Wksta_Infoseg 3160 The workstation information segment is bigger than 64K bytes. The size follows, in dword format: NELOG_Wksta_Compname 3161 The workstation was unable to get the name/number of the computername. NELOG_Wksta_BiosThreadFailure 3162 The workstation could not initialize the async NetBIOS thread. The error code is the data. NELOG_Wksta_IniSeg 3163 The workstation could not open Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_Wksta_IniSeg 3163 The workstation could not open the initial shared segment. The error code is the data. NELOG_Wksta_HostTab_Full 3164 The workstation host table is full. NELOG_Wksta_Bad_Mailslot_SMB 3165 A bad mailslot SMB was received. The SMB is the data. NELOG_Wksta_UASInit 3166 The workstation encountered an error while trying to start the UAS. The error code is the data. NELOG_Wksta_SSIRelogon 3167 The workstation encountered an error while responding to an SSI revalidation request. The function code and the error codes are the data. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── are the data. NELOG_Build_Name 3170 The Alerter service had a problem creating the list of alert recipients. The error code is %1. NELOG_Name_Expansion 3171 There was an error expanding %1 as a groupname. Try splitting the group into two or more smaller groups. NELOG_Message_Send 3172 There was an error sending %2 the alert message - (%3). The error code is %1. NELOG_Mail_Slt_Err 3173 There was an error in creating or reading the alerter mailslot. The error code is %1. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_AT_cannot_read 3174 The server could not read the AT schedule file. NELOG_AT_sched_err 3175 The server found an invalid AT schedule record. NELOG_AT_schedule_file_created 3176 The server could not find an AT schedule file so it created one. NELOG_Srvnet_NB_Open 3177 The server could not access the %1 network with NetBiosOpen. NELOG_AT_Exec_Err 3178 The AT command processor couldn't run %1. NELOG_Lazy_Write_Err 3180 WARNING: Because of a lazy-write error, drive %1 now contains some corrupt data. The cache is Code Value Meaning ──────────────────────────────────────────────────────────────────────────── corrupt data. The cache is stopped. NELOG_HotFix 3181 A defective sector on drive %1 has been replaced (hotfixed). No data was lost. You should run CHKDSK soon to restore full performance and replenish the volume's spare sector pool. The hotfix occurred while processing a remote request. NELOG_HardErr_From_Server 3182 A disk error occurred on the HPFS volume in drive %1. The error occurred while processing a remote request. NELOG_LocalSecFail1 3183 The UAS database (NET.ACC) is corrupt. The local security Code Value Meaning ──────────────────────────────────────────────────────────────────────────── corrupt. The local security system is replacing the corrupted NET.ACC with the backup made at %1. Any updates to the UAS made after this time are lost. NELOG_LocalSecFail2 3184 The UAS database (NET.ACC) is missing. The local security system is restoring the backup database made at %1. Any updates to the UAS made after this time are lost. NELOG_LocalSecFail3 3185 Local security could not be started because the UAS database (NET.ACC) was missing or corrupt, and no usable backup database was present. THE SYSTEM IS NOT SECURE. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_LocalSecGeneralFail 3186 Local security could not be started because an error occurred during initialization. The error code returned is %1. THE SYSTEM IS NOT SECURE. NELOG_NetWkSta_Internal_Error 3190 A NetWksta internal error has occurred: %1. NELOG_NetWkSta_No_Resource 3191 The redirector is out of a resource: %1. NELOG_NetWkSta_SMB_Err 3192 An SMB error occurred on connection to %1. The SMB header is the data. NELOG_NetWkSta_VC_Err 3193 A virtual circuit error occurred on the session to %1. The NCB Code Value Meaning ──────────────────────────────────────────────────────────────────────────── on the session to %1. The NCB command and return code is the data. NELOG_NetWkSta_Stuck_VC_Err 3194 Hanging up a stuck session to %1. NELOG_NetWkSta_NCB_Err 3195 An NCB error occurred (%1). The NCB is the data. NELOG_NetWkSta_Write_Behind_Err 3196 A write operation to %1 failed. Data may have been lost. NELOG_NetWkSta_Reset_Err 3197 Reset of driver %1 failed to complete the NCB. The NCB is the data. NELOG_NetWkSta_Too_Many 3198 The amount of resource %1 requested was more than the Code Value Meaning ──────────────────────────────────────────────────────────────────────────── requested was more than the maximum. The maximum amount was allocated. NELOG_Srv_Thread_Failure 3204 The server could not create a thread. The threads parameter in CONFIG.SYS should be increased. NELOG_Srv_Close_Failure 3205 The server could not close %1. The file is probably corrupt. NELOG_ReplUserCurDir 3206 The replicator cannot update directory %1. It has tree integrity and is the current directory for some process. NELOG_ReplCannotMasterDir 3207 The server cannot export directory %1 to client %2. It is exported from another server. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── exported from another server. NELOG_ReplUpdateError 3208 The replication server could not update directory %2 from the source on %3 due to error %1. NELOG_ReplLostMaster 3209 Master %1 did not send an update notice for directory %2 at the expected time. NELOG_NetlogonAuthDCFail 3210 Failed to authenticate with %2, the domain controller for domain %1. NELOG_ReplLogonFailed 3211 The replicator attempted to log on at %3 as %2 and failed. NELOG_ReplNetErr 3212 Network error %1 occurred. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_ReplMaxFiles 3213 Replicator limit for files in a directory has been exceeded. NELOG_ReplMaxTreeDepth 3214 Replicator limit for tree depth has been exceeded. NELOG_ReplBadMsg 3215 Unrecognized message received in mailslot. NELOG_ReplSysErr 3216 System error %1 occurred. NELOG_ReplUserLoged 3217 Cannot log on. User is currently logged on and argument TRYUSER is set to NO. NELOG_ReplBadImport 3218 IMPORT path %1 cannot be found. NELOG_ReplBadExport 3219 EXPORT path %1 cannot be found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_ReplBadExport 3219 EXPORT path %1 cannot be found. NELOG_ReplSignalFileErr 3220 Replicator failed to update signal file in directory %2 due to %1 system error. NELOG_DiskFT 3221 Disk fault tolerance error %1. NELOG_ReplAccessDenied 3222 Replicator could not access %2 on %3 due to %1 system error. NELOG_NetlogonFailedPrimary 3223 The primary domain controller for domain %1 has apparently failed. NELOG_NetlogonPasswdSetFailed 3224 Error in changing this computer's password. NELOG_NetlogonTrackingError 3225 Error in updating the logon or logoff information for %1. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── logoff information for %1. NELOG_NetlogonSyncError 3226 Error in synchronizing with primary domain controller %1. NELOG_UPS_PowerOut 3230 A power failure was detected. NELOG_UPS_Shutdown 3231 The UPS service performed server shutdown. NELOG_UPS_CmdFileError 3232 The UPS service did not complete execution of the user-specified shutdown command file. NELOG_UPS_CannotOpenDriver 3233 The UPS driver could not be opened. The error code is the data. NELOG_Missing_Parameter 3250 Initialization failed because of Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_Missing_Parameter 3250 Initialization failed because of an invalid or missing parameter in LANMAN.INI: %1. NELOG_Invalid_Config_Line 3251 Initialization failed because of an invalid line in the configuration file %1. The invalid line is the data. NELOG_Invalid_Config_File 3252 Initialization failed because of an error in the configuration file %1. NELOG_File_Changed 3253 The file %1 has been changed after initialization. The boot block loading was temporarily terminated. NELOG_Files_Dont_Fit 3254 The files do not fit the boot Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NELOG_Files_Dont_Fit 3254 The files do not fit the boot block configuration file %1. Change BASE and ORG definitions or the order of the files. NELOG_Wrong_DLL_Version 3255 Initialization failed because the dynamic-link library %1 returned a wrong version number. NELOG_Error_in_DLL 3256 There was an unrecoverable error in the dynamic-link library of the service. NELOG_System_Error 3257 The system returned an unexpected error code. The error code is the data. NELOG_FT_ErrLog_Too_Large 3258 The fault-tolerance error log, LANROOT\LOGS\FT.LOG, is more than Code Value Meaning ──────────────────────────────────────────────────────────────────────────── LANROOT\LOGS\FT.LOG, is more than 64K. NELOG_FT_Update_In_Progress 3259 The fault-tolerance error log, LANROOT\LOGS\FT.LOG, had the update-in-progress bit set upon opening, which means that the system crashed while working on the error log. NELOG_OEM_Code 3299 Generic error log entry for OEMs to use to log errors from OEM value-added services. The text for the entry is: %1 %2 %3 %4 %5 %6 %7 %8 %9. (For more detail, see ERRLOG.H.) ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NetErrorLogClear ──────────────────────────────────────────────────────────────────────────── NetErrorLogClear clears the error log and optionally saves the entries in a backup file. When executed locally, NetErrorLogClear requires that the NETWKSTA device driver be installed. When a servername parameter is supplied, NetErrorLogClear requires that the local Workstation service be started. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, remote only Privilege Level Admin privilege is required to successfully execute NetErrorLogClear on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETERRORLOG #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetErrorLogClear (const char far * pszServer, const char far * pszBackupFile, char far * pszReserved ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetErrorLogClear. A null pointer or null string specifies the local computer. pszBackupFile Points to an ASCIIZ string that assigns a name for an optional backup file. The calling application must have write permission for the path specified by pszBackupFile. The DosMove function must also be able to access the pathname. If the pathname is relative, it is assumed to be relative to the LAN Manager LOGS directory. A null pointer indicates not to back up the error log. pszReserved Reserved; must be a null pointer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_SHARING_VIOLATION 32 A sharing violation occurred. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── invalid. ERROR_INVALID_NAME 123 The character or file system name is invalid. ERROR_FILENAME_EXCED_RANGE 206 The filename specified is invalid for the file system. This code is returned when checking a FAT disk partition only. It cannot be returned for an HPFS partition. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_WkstaNotStarted 2138 The Workstation service is not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks NetErrorLogClear returns ERROR_SHARING_VIOLATION if the error log is currently opened by another process. NetErrorLogRead ──────────────────────────────────────────────────────────────────────────── NetErrorLogRead reads from the specified error log. When executed locally, NetErrorLogRead requires that the NETWKSTA device driver be installed. When a servername parameter is supplied, NetErrorLogRead requires that the local Workstation service be started. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, remote only Privilege Level No special privilege level is required to successfully execute NetErrorLogRead. Syntax #define INCL_NETERRORLOG #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetErrorLogRead (const char far * pszServer, const char far * pszReserved1 HLOG far * phErrorLog, unsigned long ulOffset, unsigned short far * pusReserved2, unsigned long ulReserved3, unsigned long flOffset, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbReturned, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetErrorLogRead. A null pointer or null string specifies the local computer. pszReserved1 Reserved; must be a null pointer. phErrorLog Points to the error log handle. An application calling NetErrorLogRead for the first time must initialize the 128-bit error log handle as follows: Bits Value ──────────────────────────────────────────────────────────────────────────── 127 (MSB) - 64 0 63 - 0 (LSB) 1 ──────────────────────────────────────────────────────────────────────────── The most significant bit (MSB) is the leftmost bit. The least significant bit (LSB) is the rightmost bit. Thereafter, each call to NetErrorLogRead must be given the value for the handle returned by the previous call. ulOffset Specifies the record offset at which to begin reading. This parameter is ignored unless bit 1 of flOffset is set. If used, ulOffset is taken as an offset of the record number (not bytes) at which to begin reading. Note that the record offset parameter is zero-based from both directions, depending upon the direction it is read. If reading backward, record 0 is the last record in the log. If reading forward, record 0 is the first record in the log. pusReserved2 Reserved; must be a null pointer. ulReserved3 Reserved; must be 0. flOffset Specifies the open flags, bitmapped as follows: Bit(s) Value ──────────────────────────────────────────────────────────────────────────── 0 If 0, the log is read forward. If 1, the log is read backward and records are returned in reverse chronological order. 1 If 0, the read proceeds normally (sequentially). If 1, the read proceeds from the nth record from the start of the log, where n is the offset parameter. 2-31 Reserved; must be 0. ──────────────────────────────────────────────────────────────────────────── pbBuffer Points to the buffer for returned data. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcbReturned Points to an unsigned short integer that specifies how many bytes were read into the buffer. This count is valid only if NetErrorLogRead returns NERR_Success or NERR_BufTooSmall. pcbTotalAvail Points to an unsigned short integer that specifies how many bytes were available to be read from the log. This count is valid only if NetErrorLogRead returns NERR_Success or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_SHARING_VIOLATION 32 A sharing violation occurred. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_InvalidComputer 2351 The specified computername is invalid. NERR_LogFileChanged 2378 The log file has changed since Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_LogFileChanged 2378 The log file has changed since it was last read. NERR_LogFileCorrupt 2379 The log file is corrupt. NERR_InvalidLogSeek 2440 The log file does not contain the requested record number. ──────────────────────────────────────────────────────────────────────────── Remarks To read the contents of an error log, an application calls NetErrorLogRead repeatedly until the function returns information (via the pcbTotalAvail parameter) that indicates there is no more data to be read. Each call to NetErrorLogRead returns a handle that must be provided to any subsequent call to NetErrorLogRead. This handle changes with each subsequent call. The handle is not a system file handle and should never be treated as such. Note that the error log can contain much more than 64K of data. If pcbTotalAvail is returned with a value of 0xFFFF, there may be 0xFFFF or more bytes of data available. The application should continue to read the log until the value returned in pcbTotalAvail is 0. NetErrorLogRead passes data back in the buffer only in whole records. The application never gets a partial record in the buffer. Use the value pointed to by pcbReturned to determine the end of valid data in the buffer. The error log is written with the newest records appended at the end. The flOffset parameter determines whether to read the log in forward or in reverse order. If the error log is partially read, and then the log is cleared or a new record written, a subsequent read with the handle returned from the first call to NetErrorLogRead will return an error. An application that finds that the error log has changed between calls can reread the changed log by reissuing the call with the error log handle initialized as if it were making the call for the first time. NetErrorLogWrite ──────────────────────────────────────────────────────────────────────────── NetErrorLogWrite writes an entry to the error log on the local computer. It requires that the Workstation service be started. Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1, local only ■ MS-DOS not supported Privilege Level No special privilege level is required to successfully execute NetErrorLogWrite. Syntax #define INCL_NETERRORLOG #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetErrorLogWrite (char far * pszReserved1, unsigned short usCode, const char far * pszComponent, const char far * pbBuffer, unsigned short cbBuffer, const char far * pszStrBuf unsigned short cStrBuf, char far * pszReserved2 ); where pszReserved1 Reserved; must be a null pointer. usCode Specifies the code of the error that occurred. pszComponent Points to an ASCIIZ string that specifies which component encountered the error. pbBuffer Points to the raw data associated with the error condition. cbBuffer Specifies the size (in bytes) of the buffer pointed to by pbBuffer. pszStrBuf Points to ASCIIZ strings that contain the error message. cStrBuf Specifies how many concatenated ASCIIZ strings are stored by pszStrBuf. pszReserved2 Reserved; must be a null pointer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_SHARING_VIOLATION 32 A sharing violation occurred. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_NET_WRITE_FAULT 88 A network data fault occurred. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_WkstaNotStarted 2138 The Workstation service is not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_LogOverflow 2377 The log file is too big. ──────────────────────────────────────────────────────────────────────────── Remarks NetErrorLogWrite internally calls the appropriate functions to open and close the error log. NetErrorLogWrite issues an error log alert (via NetAlertRaise) each time an entry is written to the error log. It also issues an admin alert by calling NetAlertRaise when the error log reaches 80% capacity and again when the log reaches 100% capacity. At 100% error log capacity, NetErrorLogWrite fails and returns NERR_LogOverflow. Applications should periodically clear the log of outdated information so that the log does not reach 100% capacity. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Alerts Alert Category Error Logging Category Example /* NETERR.C -- a sample program demonstrating NetErrorLog API functions. This program requires that you have admin privilege if a servername parameter is supplied. usage: neterr [-s \\server] [-b backup] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). backup = Name of the backup file. API Used to... ================ =========================================== NetErrorLogClear Back up the error log and then clear it NetErrorLogWrite Write several entries into the error log NetErrorLogRead Read the error log and display its contents This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETERRORS #define INCL_NETERRORLOG #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include <time.h> #include "samples.h" // Internal routine header file #define DEFAULT_BACKUP "ERROR.BCK" void Usage (char * pszProgram); void main(int argc, char *argv[]) { char * pszServer = ""; // Servername char * pszBackup = DEFAULT_BACKUP; // Backup log file struct error_log *pBuffer; // Pointer to data buffer struct error_log *pEntry; // Single entry in log int iCount; // Index counter unsigned short cbBuffer; // Count of bytes in buffer unsigned short cbRead; // Count of bytes read unsigned short cbAvail; // Count of bytes available unsigned short usDataByte; // Raw data API_RET_TYPE uReturnCode; // API return code HLOG hLogHandle; // Error log handle time_t tTime; for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iCount]; break; case 'b': // -b backup file pszBackup = argv[++iCount]; break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } //======================================================================== // NetErrorLogClear // // This API clears the error log for the specified server. A backup is // kept in the file specified by pszBackup. If a null pointer is supplied, // no backup is kept. //======================================================================== uReturnCode = NetErrorLogClear( pszServer, // Servername pszBackup, // Backup file NULL); // Reserved; must be NULL printf("NetErrorLogClear returned %u\n", uReturnCode); printf(" backup file = %s \n\n", pszBackup); //======================================================================== // NetErrorLogWrite // // This API writes a few entries to the error log. These entries are // some typical types of errors that may be encountered. The error // codes are defined in the ERRLOG.H header file. // Note: Because NetErrorLogWrite has no servername parameter, the entry // written into the local error log. //======================================================================== /* * Write an entry of type NELOG_Resource_Shortage that has * a single text error message and no raw data. */ uReturnCode = NetErrorLogWrite( NULL, // Reserved; must be NULL NELOG_Resource_Shortage, // Error code argv[0], // Component in error NULL, // Pointer to raw data 0, // Length of raw data buffer "THREADS=", // String data 1, // Number of error strings NULL); // Reserved; must be NULL printf("NetErrorLogWrite for NELOG_Resource_Shortage returned %u\n", uReturnCode); /* * Write an entry of type NELOG_Init_OpenCreate_Err that has * a single text error message and raw data associated with it. */ usDataByte = 3; // Path not found error uReturnCode = NetErrorLogWrite( NULL, // Reserved; must be NULL NELOG_Init_OpenCreate_Err, // Error code argv[0], // Component in error (char far *)&usDataByte, // Pointer to raw data sizeof(unsigned short), // Length of raw data buffer "C:\\INIT\\STARTER.CMD", // String data 1, // Number of error strings NULL); // Reserved; must be NULL printf("NetErrorLogWrite for NELOG_Init_OpenCreate_Err returned %u\n", uReturnCode); /* * Write an entry of type NELOG_Srv_No_Mem_Grow that has * no text error message and no raw data associated with it. */ uReturnCode = NetErrorLogWrite( NULL, // Reserved; must be NULL NELOG_Srv_No_Mem_Grow, // Error code argv[0], // Component in error NULL, // Pointer to raw data 0, // Length of raw data buffer NULL, // String data 0, // Number of error strings NULL); // Reserved; must be NULL printf("NetErrorLogWrite for NELOG_Srv_No_Mem_Grow returned %u\n\n", uReturnCode); //======================================================================== // NetErrorLogRead // // This API reads and displays the error log for the specified server. //======================================================================== /* * Allocate a small buffer space to demonstrate reading the error log * when the log is larger than the buffer allocated to store it. The * maximum allowable buffer is 64K. If the error log is larger than * the buffer specified, the API returns as many full records as it * can and the NERR_Success return code. Subsequent reads start from * the end of the last record read. To read the whole log, the reads * must continue until the bytes available counter is 0. */ cbBuffer = 100; pBuffer = SafeMalloc(cbBuffer); // Allocate memory for buffer /* * Set the log handle for reading from the start of the error log. * This handle gets modified by the API. Any subsequent reads * for unread data should use the returned handle. */ hLogHandle.time = 0L; hLogHandle.last_flags = 0L; hLogHandle.offset = 0xFFFFFFFF; hLogHandle.last_flags = 0xFFFFFFFF; do { uReturnCode = NetErrorLogRead( pszServer, // Servername NULL, // Reserved; must be NULL &hLogHandle, // Error log handle 0L, // Start at record 0 NULL, // Reserved; must be NULL 0L, // Reserved; must be 0 0L, // Read the log forward (char far *)pBuffer, // Data returned here cbBuffer, // Size of buffer, in bytes &cbRead, // Count of bytes read &cbAvail); // Count of bytes available printf("NetErrorLogRead returned %u \n", uReturnCode); if (uReturnCode == NERR_Success) { for ( pEntry = pBuffer; pEntry < (struct error_log *)((char *)pBuffer + cbRead); ) { tTime = (time_t) pEntry->el_time; printf(" Error %hu, from %s at %s", pEntry->el_error, pEntry->el_name, asctime( gmtime ((const time_t *) &tTime) ) ); pEntry = (struct error_log *)((char *)pEntry + pEntry->el_len); } printf("Bytes Read = 0x%X\n", cbRead); // To read to whole log, keep reading until cbAvail is 0. if (cbAvail) printf("Data still unread.\n\n"); else printf("All data read.\n\n"); } } while ((uReturnCode == NERR_Success) && (cbAvail != 0)); free(pBuffer); exit(0); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s [-s \\\\server] [-b backup]\n", pszProgram); exit(1); } File Category File API functions provide a way to monitor and close the file, device, and pipe resources open on a server. They require that the Workstation service be started and that the Server service be started on the specified server. The File category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and SHARES.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETFILE, and including the master header file, LAN.H. For more information about these definitions, see the "Example" section, later in this category. These are the File API functions: ■ NetFileClose2 ■ NetFileEnum2 ■ NetFileGetInfo2 Description NetFileClose2 forces a server resource closed. This function can be used when a system error prevents normal closure (for example, when the DosClose function fails). NetFileEnum2 returns information about resources open on a server. A file can be opened one or more times by one or more applications. Each file opening is uniquely identified. NetFileEnum2 returns an entry for each file opening. NetFileGetInfo2 returns information about one particular opening of a resource. NetFileEnum2 and NetFileGetInfo2 can return the file identifier only, or they can return the file identifier and additional detailed data. Four levels and data structures are available. Levels 0 and 1 return short file identifiers. Levels 2 and 3 return long file identifiers. Long file identifiers support the increased number of open files allowed on computers using the high-performance file system (HPFS). Levels 0 and 2 return only the iden- tification number that was assigned to the resource when it was opened. Levels 1 and 3 return the identification number, permissions, file locks, and the name of the user who opened the resource. You should use levels 2 and 3 to ensure that data is returned for all open resources. Levels 0 and 1 are provided only for compatibility with previous LAN Manager releases. NetFileEnum2 and NetFileGetInfo2 can return level 0 and level 1 data for only those resources that have file identifier values less than 65,536. Do not make assumptions about file identifiers; an open resource can have an identifier greater than 65,536 even if it is the only open resource. Levels 0 and 1 do not guarantee the return of all valid data. When level 0 or level 1 is used, the value of the pcEntriesRemaining parameter returned by NetFileEnum2 reflects only the number of open files that have file identifier values less than 65,536. Data Structures The sLevel parameter of NetFileEnum2 and NetFileGetInfo2 specifies the level of information to be returned. Both functions return the file_info_X data structure, where X is 0, 1, 2, or 3, depending on the level of detail specified. Opened Resources (level 0) The file_info_0 data structure has this format: struct file_info_0 { unsigned short fi0_id; }; where fi0_id Specifies the identification number assigned to the resource when it is opened. Opened Resources (level 1) The file_info_1 data structure has this format: struct file_info_1 { unsigned short fi1_id; unsigned short fi1_permissions; unsigned short fi1_num_locks; char far * fi1_pathname; char far * fi1_username; }; where fi1_id Specifies the identification number assigned to the resource when it is opened. fi1_permissions Specifies the access permissions of the opening application. The bit mask of fi1_permissions is defined in the SHARES.H header file. The SHARES.H header file defines the following permissions: Code Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── PERM_FILE_READ 0x1 Permission to read a resource and, by default, execute the resource. PERM_FILE_WRITE 0x2 Permission to write to a resource. PERM_FILE_CREATE 0x4 Permission to create a resource; data can be written when creating the resource. ──────────────────────────────────────────────────────────────────────────── fi1_num_locks Specifies how many file locks are on the file, device, or pipe. fi1_pathname Points to an ASCIIZ string that gives the pathname of the opened resource. fi1_username Points to an ASCIIZ string that specifies which user (on servers with user-level security) or which computername (on servers with share-level security) opened the resource. Opened Resources (level 2) The file_info_2 data structure has this format: struct file_info_2 { unsigned long fi2_id; }; where fi2_id Specifies the identification number assigned to the resource when it is opened. Opened Resources (level 3) The file_info_3 data structure has this format: struct file_info_3 { unsigned long fi3_id; unsigned short fi3_permissions; unsigned short fi3_num_locks; char far * fi3_pathname; char far * fi3_username; }; where fi3_id Specifies the identification number assigned to the resource when it is opened. fi3_permissions Specifies the access permissions of the opening application. The bit mask of fi3_permissions is defined in the SHARES.H header file. It has the same definition as the fi1_permissions element of the file_info_1 data structure. For more information, see the description of the file_info_1 data structure, earlier in this section. fi3_num_locks Specifies how many file locks are on the file, device, or pipe. fi3_pathname Points to an ASCIIZ string that gives the pathname of the opened resource. fi3_username Points to an ASCIIZ string that specifies which user (on servers that have user-level security) or which computer (on servers that have share-level security) opened the resource. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Access permissions Access Permissions Category NetFileClose2 ──────────────────────────────────────────────────────────────────────────── NetFileClose2 forces a resource to close. This function can be used when an error prevents closure by other means. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or server operator privilege is required to successfully execute NetFileClose2 on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETFILE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetFileClose2 (const char far * pszServer, unsigned long ulFileId ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetFileClose2. A null pointer or null string specifies the local computer. ulFileId Specifies the identification number assigned to the resource when it is opened. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_FileIdNotFound 2314 There is no open file with this ID number. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks Ordinarily, a call to the DosClose function closes a resource opened by a call to the DosOpen function. Use NetFileClose2 to force a resource to close. NetFileClose2 supersedes NetFileClose (used in earlier versions of LAN Manager). NetFileClose2 is the same as NetFileClose except that NetFileClose2 has an unsigned long ulFileId parameter instead of an unsigned short usFileId parameter. For more information, see Appendix B, "Upgrading LAN Manager 1.0 Applications." See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing open files, devices, or NetFileEnum2 pipes on a server Obtaining information about a NetFileGetInfo2 specified open resource NetFileEnum2 ──────────────────────────────────────────────────────────────────────────── NetFileEnum2 supplies information about some or all open files on a server, allowing the user to supply a key and get required information through repeated calls to the function. NetFileEnum2 is slightly different from other Enum functions. NetFileEnum2 uses a file resume key data structure that allows the application to resume enumeration from where it left off. NetFileEnum2 does not require all data to fit in a single buffer returned from a single call. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or server operator privilege is required to successfully execute NetFileEnum2 on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETFILE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetFileEnum2 (const char far * pszServer, const char far * pszBasePath, const char far * pszUserName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcEntriesRemaining, void far * pResumeKey ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetFileEnum2. A null pointer or null string specifies the local computer. pszBasePath Points to the base pathname for enumeration. If not NULL, pszBasePath serves as a qualifier to the enumeration. The entries returned are limited to those that have names beginning with the qualifier string pointed to by pszBasePath. For example, the value C:\TMP enumerates only open files that have pathnames beginning with C:\TMP (such as C:\TMPFILE and C:\TMP\DOCUMENT). If pszBasePath is NULL, no base path qualifier is used. pszUserName Points to an ASCIIZ string that specifies the name of the user. If not NULL, pszUserName serves as a qualifier to the enumeration. The files returned are limited to those that have usernames matching the qualifier. If pszUserName is NULL, no username qualifier is used. sLevel Specifies the level of detail (0, 1, 2, or 3) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a sequence of file_info_X data structures, where X is 0, 1, 2, or 3, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer in which a count of the number of entries in the buffer is returned. This count is valid only if NetFileEnum2 returns NERR_Success or ERROR_MORE_DATA. pcEntriesRemaining Points to an unsigned short integer in which a count of the total number of entries is returned. This count is valid only if NetFileEnum2 returns NERR_Success or ERROR_MORE_DATA. pResumeKey Points to the file resume key structure, FRK. Using pResumeKey allows repeated calls to NetFileEnum2 to continue enumerating files when the return data from a preceding call did not fit within the return buffer supplied. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── started. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks NetFileEnum2 is different from other Enum functions. Other Enum functions supply only the fixed-length data if the buffer cannot hold the complete record; unlike other Enum functions, NetFileEnum2 supplies as many complete records as the buffer can hold. The application can use a resume key and make repeated calls to obtain the data. Rather than make repeated pairs of calls as with other Enum functions (the first to determine a buffer size, the second to obtain the data), an application can determine a representative buffer size, and then make repeated calls using this size. (If the application makes an initial call to NetFileEnum2 to determine the representative buffer size, the file resume key should be reinitialized for the first call that obtains actual data.) NetFileEnum2 allows the user to overcome the problem that arises when the information returned exceeds the size of the return buffer. To initialize pResumeKey, use the FRK_INIT macro supplied in the SHARES.H header file; the macro accepts an FRK structure as an argument. The following example shows an application code fragment: FRK f; FRK_INIT (f); NetFileEnum2 (..., &f, ...); If NetFileEnum2 is called with an initial pResumeKey value, and the buffer supplied is too small to return all the requested information, NetFileEnum2 returns the ERROR_MORE_DATA error code and a pResumeKey value suitable for retrieving the remaining data. When called with a pResumeKey value from a previous call, NetFileEnum2 resumes the enumeration at the place indicated by that value. The user must not attempt to set this key, other than to initialize it. Other user-supplied values for pResumeKey must have been returned by a preceding call to NetFileEnum2. On heavily loaded servers, the information returned by NetFileEnum2 can exceed the maximum allowed buffer size of 64K and generate ERROR_MORE_DATA return codes. The amount of data returned can be minimized by specifying the base path or username. If both the pszUserName and pszBasePath parameters are specified, only files that match both qualifying conditions are returned. NetFileEnum2 supports level 0, 1, 2, and 3 file_info_X data structures. NetFileEnum2 supersedes NetFileEnum (used in earlier versions of LAN Manager). NetFileEnum2 is the same as NetFileEnum except that NetFileEnum2 includes the pResumeKey parameter. For more information, see Appendix B, "Upgrading LAN Manager 1.0 Applications." See Also For information about See ──────────────────────────────────────────────────────────────────────────── Closing open files, devices, or NetFileClose2 pipes Obtaining information about a NetFileGetInfo2 specified open resource NetFileGetInfo2 ──────────────────────────────────────────────────────────────────────────── NetFileGetInfo2 retrieves information about a particular opening of a server resource. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or server operator privilege is required to successfully execute NetFileGetInfo2 on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETFILE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetFileGetInfo2 (const char far * pszServer, unsigned long ulFileId, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetFileGetInfo2. A null pointer or null string specifies the local computer. ulFileId Specifies the identification number assigned to the resource when it was opened. sLevel Specifies the level of detail (0, 1, 2, or 3) to be returned. pbBuffer Points to the buffer in which to store the return data. On a successful return, the buffer contains a sequence of file_info_X data structures, where X is 0, 1, 2, or 3, depending on the level of detail specified. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcbTotalAvail Points to an unsigned short integer that specifies how many bytes of information were available. This count is valid only if NetFileGetInfo2 returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_BufTooSmall 2123 The supplied buffer is too small. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_FileIdNotFound 2314 There is no open file with this ID number. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── Remarks NetFileGetInfo2 supports level 0, 1, 2, and 3 file_info_X data structures. NetFileGetInfo2 supersedes NetFileGetInfo (used in earlier versions of LAN Manager). NetFileGetInfo2 is the same as NetFileGetInfo except that NetFileGetInfo2 has an unsigned long ulFileId parameter instead of an unsigned short usFileId parameter. For more information, see Appendix B, "Upgrading LAN Manager 1.0 Applications." See Also For information about See ──────────────────────────────────────────────────────────────────────────── Closing a file, device, or pipe NetFileClose2 Listing files, devices, or pipes NetFileEnum2 open on a server File Category Example /* NETFILE.C -- a sample program demonstrating NetFile API functions. This program requires that you have admin privilege on the specified server. usage: netfile [-s \\server] [-b basepath] [-u username] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). basepath = Enumerate only open files along this path. username = Enumerate only files opened by this user. API Used to... =============== ================================================ NetFileEnum2 List files in the base path opened by user NetFileGetInfo2 Get information available about each listed file NetFileClose2 Close specified files on the specified server This sample code is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETFILE #define INCL_NETERRORS #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include "samples.h" // Internal routine header file void Usage(char *pszString); void main(int argc, char *argv[]) { char *pszServerName = ""; // Required parameters for calls char far *pszBasePath = (char far *) NULL; char far *pszUserName = (char far *) NULL; API_RET_TYPE uReturnCode; // API return codes int iCount; // Index counter unsigned short cbBuflen; // Count of bytes unsigned short cEntriesRead; // Entries read unsigned short cEntriesRemaining; // Entries remaining to be read unsigned short cGetEntries = 0; // Count of all enumerated IDs unsigned short cbTotalAvail; // Count of bytes available unsigned short fTableAllocated = 0; // Flag to build table of IDs struct file_info_3 *pBuf3, *p3; // File IDs; use only level 2,3 FRK resumekey; // File resume key, used when enum data > buffer size unsigned long *pulIds, *pulStartId; // List of file IDs for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServerName = argv[++iCount]; break; case 'b': // -b base path pszBasePath = (char far *)argv[++iCount]; break; case 'u': // -u username pszUserName = (char far *)argv[++iCount]; break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } // End for loop printf("\nFile Category API Examples\n"); if (pszServerName[0] != '\0') printf("Server = %s\n", pszServerName); if (pszBasePath != NULL) printf("Base path = %s\n", pszBasePath); if (pszUserName != NULL) printf("User name = %s\n", pszUserName); //======================================================================== // NetFileEnum2 // // This API lists all open files on the server below the specified given // base path. If no base path is given, all open files are listed. //======================================================================== cbBuflen = 256; // Small size to demonstrate use of resume key pBuf3 = (struct file_info_3 *) SafeMalloc(cbBuflen); p3 = pBuf3; // Save pointer for free() cleanup at end FRK_INIT(resumekey); // Must init file resume key; use SHARES.H macro do // Use resume key and loop until done { uReturnCode = NetFileEnum2(pszServerName, // NULL means local pszBasePath, // NULL means root pszUserName, // NULL means all users 3, // Level (0 through 3) (char far *)pBuf3, // Return buffer cbBuflen, // Return buffer length &cEntriesRead, // Count of entries read &cEntriesRemaining, // Entries not read &resumekey); // Resume key printf("NetFileEnum2 returned %u\n", uReturnCode); if (uReturnCode == NERR_Success || uReturnCode == ERROR_MORE_DATA) { printf(" Entries read = %hu, Entries remaining = %hu\n", cEntriesRead, cEntriesRemaining); // Save the file IDs. if (cEntriesRead > 0) { // Allocate memory for file ID table first time through only. if (fTableAllocated == 0) { cGetEntries = cEntriesRead + cEntriesRemaining; pulStartId = pulIds = (unsigned long *) SafeMalloc(cGetEntries * sizeof(unsigned long)); fTableAllocated = 1; // Assure allocate only once } // Print the file information. printf(" Id Perms Locks User Path\n"); for (iCount = 0; iCount < (int) cEntriesRead; iCount++) { printf(" %-8lu%-8hu%-8hu%-16Fs%Fs\n", pBuf3->fi3_id, pBuf3->fi3_permissions, pBuf3->fi3_num_locks, pBuf3->fi3_username, pBuf3->fi3_pathname); *pulIds = pBuf3->fi3_id; pulIds++; pBuf3++; } // End for loop pBuf3 = p3; // Pointer was changed; restore to top of buffer } // End if cEntriesRead > 0 } // End if successful call } while (uReturnCode == ERROR_MORE_DATA); // Use FRK until enum all free(p3); //======================================================================== // NetFileGetInfo2 // // This API retrieves all file IDs listed from the NetFileEnum2 call. //======================================================================== if (cGetEntries != 0) { cbBuflen = 1024; pBuf3 = (struct file_info_3 *) SafeMalloc(cbBuflen); p3 = pBuf3; // Save pointer for free() cleanup at end pulIds = pulStartId; // Start at beginning of list printf("NetFileGetInfo2 results:\n"); for (iCount = 0; iCount < (int) cGetEntries; iCount++) { uReturnCode = NetFileGetInfo2( pszServerName, // NULL means local *pulIds, // File ID from enum 3, // Level (0 through 3) (char far *)pBuf3, // Return buffer cbBuflen, // Return buffer length &cbTotalAvail); // Entries not yet read if (uReturnCode) printf("NetFileGetInfo2 for file %lu returned %u\n", *pulIds, uReturnCode); else printf(" File %lu: %-8hu%-8hu%-16Fs%Fs\n", *pulIds, pBuf3->fi3_permissions, pBuf3->fi3_num_locks, pBuf3->fi3_username, pBuf3->fi3_pathname); pulIds++; } } //======================================================================== // NetFileClose2 // // This API closes the specified open files on the specified server. //======================================================================== if (cGetEntries != 0) { pulIds = pulStartId; for (iCount = 0; iCount < (int) cGetEntries; iCount++) { uReturnCode = NetFileClose2(pszServerName, // NULL means local (unsigned long)*pulIds); // File ID from enum printf("NetFileClose2 for file %lu returned %u\n", *pulIds, uReturnCode); pulIds++; } free(pulStartId); } free(p3); exit(0); } void Usage(char *pszString) { fprintf(stderr, "Usage: %s [-s \\\\server] [-b basepath] " "[-u username]\n", pszString); exit(1); } Group Category Group API functions control groups of users. The Group API functions require that the user account subsystem (UAS) be started. On most computers the UAS is started when the Workstation service is started, provided a valid user accounts database file exists. On computers using the high-performance file system 386 (HPFS386) with local security enabled, the UAS is started automatically as part of the boot process. The Group category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and ACCESS.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETGROUP, and including the master header file, LAN.H. For more information about these definitions, see the "Example" section, later in this category. These are the Group API functions: ■ NetGroupAdd ■ NetGroupAddUser ■ NetGroupDel ■ NetGroupDelUser ■ NetGroupEnum ■ NetGroupGetInfo ■ NetGroupGetUsers ■ NetGroupSetInfo ■ NetGroupSetUsers Description A group is a set of users who share common permissions in the user accounts subsystem database. Group API functions create or delete groups, and review or adjust the membership of the groups. The group has a groupname that specifies the usernames of group members. An administrator can assign access permissions for all members of a group by supplying the groupname to NetAccessAdd instead of assigning each user an individual access permission record. For more information, see the Access Permissions category API functions. To create a group, an application calls NetGroupAdd, supplying a groupname. Initially, the group has no members. To assign members to the group, call NetGroupSetUsers. To add a user to an existing group, call NetGroupAddUser. To set general information about the group, call NetGroupSetInfo. NetGroupDelUser deletes a specified username from a group, and NetGroupDel disbands a group. NetGroupDel works whether or not the group has any members. Three Group category API functions retrieve information about the groups on a server: NetGroupEnum produces a list of all groups; NetGroupGetUsers lists all members of a specified group; and NetGroupGetInfo returns general information about the group. All Group API functions executed on a remote server (except NetGroupGetUsers) require that that server have user-level security. Attempting to execute one of these Group API functions on a remote server that has share-level security results in the return code ERROR_NOT_SUPPORTED. LAN Manager supports as many as 252 groups in addition to the special groups admins, guests, users, and local. Each user account automatically belongs to one of the special groups users, admins, or guests, according to the user's privilege level. Membership of these groups is indirectly controlled by the NetUserAdd, NetUserDel, and NetUserSetInfo functions. The local group has no members. For more information, see the User category API functions. Only NetGroupEnum and NetGroupGetUsers can operate on the special groups, but NetGroupEnum does not list the group local. Data Structures NetGroupAdd, NetGroupEnum, and NetGroupGetInfo use the group_info_0 data structure. These three functions and NetGroupSetInfo use the group_info_1 data structure. NetGroupGetUsers and NetGroupSetUsers use the group_users_info_0 data structure. Group Information (level 0) The group_info_0 data structure has this format: struct group_info_0 { char grpi0_name[GNLEN+1]; }; where grpi0_name Contains an ASCIIZ string that specifies a groupname. The constant GNLEN is defined in the NETCONS.H header file. Group Information (level 1) The group_info_1 data structure has this format: struct group_info_1 { char grpi1_name[GNLEN+1]; char grpi1_pad; char far * grpi1_comment; }; where grpi1_name Contains an ASCIIZ string that specifies a groupname. The constant GNLEN is defined in the NETCONS.H header file. grpi1_pad Aligns the next data structure element on a word boundary. grpi1_comment Points to an ASCIIZ string that contains a remark for the group. This element can be a null string. The comment can have as many as MAXCOMMENTSZ+1 characters, as defined in the NETCONS.H header file. Group Membership Information (level 0) The group_users_info_0 data structure has this format: struct group_users_info_0 { char grui0_name[UNLEN+1]; }; where grui0_name Contains an ASCIIZ string that specifies the name of a group member. The constant UNLEN is defined in the NETCONS.H header file. NetGroupAdd ──────────────────────────────────────────────────────────────────────────── NetGroupAdd creates a group account in the user accounts subsystem (UAS) database. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or accounts operator privilege is required to successfully execute NetGroupAdd on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETGROUP #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetGroupAdd (const char far * pszServer, short sLevel, char far * pbBuffer, unsigned short cbBuffer ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetGroupAdd. A null pointer or null string specifies the local computer. sLevel Specifies the level of detail (0 or 1) for the data to be set. pbBuffer Points to the buffer in which the data to be set is located. This buffer should contain a group_info_0 (level 0 call) or group_info_1 (level 1 call) data structure. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_RemoteOnly 2106 This operation can be performed Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_BadUsername 2202 The username or groupname is invalid. NERR_GroupExists 2223 The groupname already exists. NERR_UserExists 2224 The user account already exists. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NotPrimary 2226 The specified server is not the primary domain controller, so its UAS database cannot be updated. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_ACFNoRoom 2228 The user accounts database is full. NERR_ACFFileIOFail 2229 A disk I/O failure occurred. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidComputer 2351 The specified computername is invalid. NERR_CanNotGrowUASFile 2456 The user accounts database cannot be enlarged because the server's hard disk is full. ──────────────────────────────────────────────────────────────────────────── Remarks NetGroupAdd returns NERR_UserExists if the groupname specified is already being used as a username. NetGroupAdd supports level 0 and level 1 data structures. When adding a group account at level 0, the comment element is set to a null string because the group_info_0 data structure does not provide a comment element. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Adding a single user to a group NetGroupAddUser Assigning group permissions NetAccessAdd Deleting a group account from a NetGroupDel server Listing all groups on a server NetGroupEnum Remote calls Chapter 1, "Overview of the LAN Manager API" Setting the list of all users in NetGroupSetUsers a group NetGroupAddUser ──────────────────────────────────────────────────────────────────────────── NetGroupAddUser adds a user to a group in the user accounts subsystem (UAS) database. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or accounts operator privilege is required to successfully execute NetGroupAddUser on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETGROUP #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetGroupAddUser (const char far * pszServer, char far * pszGroupName, char far * pszUserName ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetGroupAddUser. A null pointer or null string specifies the local computer. pszGroupName Points to an ASCIIZ string that specifies which group the user will join. pszUserName Points to an ASCIIZ string that specifies which user to add to the group. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_BadUsername 2202 The username or groupname is Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BadUsername 2202 The username or groupname is invalid. NERR_GroupNotFound 2220 The groupname was not found. NERR_UserNotFound 2221 The username was not found. NERR_NotPrimary 2226 The specified server is not the primary domain controller, so its UAS database cannot be updated. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_ACFFileIOFail 2229 A disk I/O failure occurred. NERR_SpeGroupOp 2234 This operation is not allowed on Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_SpeGroupOp 2234 This operation is not allowed on this special group. NERR_UserInGroup 2236 The user already belongs to this group. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. NERR_CanNotGrowUASFile 2456 The user accounts database cannot be enlarged because the server's hard disk is full. ──────────────────────────────────────────────────────────────────────────── Remarks If an attempt is made to add a user to the users, guests, admins, or local special groups, NetGroupAddUser returns NERR_SpeGroupOp. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Creating a new group NetGroupAdd Defining group access Access Permissions Category permissions Removing a user from a group NetGroupDelUser Retrieving a list of group NetGroupGetUsers members NetGroupDel ──────────────────────────────────────────────────────────────────────────── NetGroupDel removes a group account from the user accounts subsystem (UAS) database. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or accounts operator privilege is required to successfully execute NetGroupDel on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETGROUP #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetGroupDel (const char far * pszServer, char far * pszGroupName ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetGroupDel. A null pointer or null string specifies the local computer. pszGroupName Points to an ASCIIZ string that specifies which group to remove. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_GroupNotFound 2220 The groupname was not found. NERR_NotPrimary 2226 The specified server is not the Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NotPrimary 2226 The specified server is not the primary domain controller, so its UAS database cannot be updated. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_ACFFileIOFail 2229 A disk I/O failure occurred. NERR_SpeGroupOp 2234 This operation is not allowed on this special group. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── invalid. ──────────────────────────────────────────────────────────────────────────── Remarks It is not necessary to remove all members from a group before deleting the group account. Deleting a group deletes it from the access control profiles, but does not delete the individual accounts of its members. If an attempt is made to delete one of the users, guests, admins, or local special groups, NetGroupDel returns NERR_SpeGroupOp. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Adding a group to a server NetGroupAdd Listing all groups on a server NetGroupEnum Removing a user from a group NetGroupDelUser NetGroupDelUser ──────────────────────────────────────────────────────────────────────────── NetGroupDelUser removes a user from a particular group in the user accounts subsystem (UAS) database. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or accounts operator privilege is required to successfully execute NetGroupDelUser on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETGROUP #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetGroupDelUser (const char far * pszServer, char far * pszGroupName, char far * pszUserName ); where pszServer Points to an ASCIIZ string that contains the name of the remote server on which to execute NetGroupDelUser. A null pointer or null string specifies the local computer. pszGroupName Points to an ASCIIZ string that specifies the group from which to remove the user. pszUserName Points to an ASCIIZ string that specifies which user to remove from the group. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_WkstaNotStarted 2138 The Workstation service is not started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_GroupNotFound 2220 The groupname was not found. NERR_UserNotFound 2221 The username was not found. NERR_NotPrimary 2226 The specified server is not the primary domain controller, so its UAS database cannot be updated. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_ACFFileIOFail 2229 A disk I/O failure occurred. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_ACFFileIOFail 2229 A disk I/O failure occurred. NERR_SpeGroupOp 2234 This operation is not allowed on this special group. NERR_UserNotInGroup 2237 The user is not a member of this group. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks Removing a user from a group does not delete the user's account from the system. If an attempt is made to delete a user from the users, guests, admins, or local special groups, NetGroupDelUser returns NERR_SpeGroupOp. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Adding a user to a group NetGroupAddUser Deleting a group NetGroupDel NetGroupEnum ──────────────────────────────────────────────────────────────────────────── NetGroupEnum lists all group accounts in the user accounts subsystem (UAS) database. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or accounts operator privilege is required to successfully execute NetGroupEnum at level 1 on a remote server or on a computer that has local security enabled. No special privilege is required for level 0 calls. Syntax #define INCL_NETGROUP #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetGroupEnum (const char far * pszServer, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetGroupEnum. A null pointer or null string specifies the local computer. sLevel Specifies the level of detail (0 or 1) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a sequence of group_info_X data structures, where X is 0 or 1, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer in which the number of groups enumerated in the buffer pointed to by pbBuffer is returned. This count is valid only if NetGroupEnum returns NERR_Success or ERROR_MORE_DATA. pcTotalAvail Points to an unsigned short integer in which the total number of groups is returned. This count is valid only if NetGroupEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_ACFFileIOFail 2229 A disk I/O failure occurred. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks NetGroupEnum does not list the special group local. NetGroupGetInfo ──────────────────────────────────────────────────────────────────────────── NetGroupGetInfo gets group-related information. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or accounts operator privilege is required to successfully execute NetGroupGetInfo at level 1 on a remote server or on a computer that has local security enabled. No special privilege is required for level 0 calls. Syntax #define INCL_NETGROUP #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetGroupGetInfo (const char far * pszServer, char far * pszGroupName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetGroupGetInfo. A null pointer or null string specifies the local computer. pszGroupName Points to an ASCIIZ string that contains the name of the group about which to get information. sLevel Specifies the level of detail (0 or 1) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a group_info_X data structure, where X is 0 or 1, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcbTotalAvail Points to an unsigned short integer in which the total number of bytes of information available is returned. This count is valid only if NetGroupGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── shared. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_GroupNotFound 2220 The groupname was not found. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_ACFFileIOFail 2229 A disk I/O failure occurred. NERR_SpeGroupOp 2234 This operation is not allowed on this special group. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks If an attempt is made to get information about the users, guests, admins, or local special groups, NetGroupGetInfo returns NERR_SpeGroupOp. NetGroupGetUsers ──────────────────────────────────────────────────────────────────────────── NetGroupGetUsers returns a list of the members of a particular group in the user accounts subsystem (UAS) database. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or accounts operator privilege is required to successfully execute NetGroupGetUsers on a remote server or on a computer that has local security enabled, except when users request details about a group to which they belong. In this case, no special privilege is required. Syntax #define INCL_NETGROUP #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetGroupGetUsers (const char far * pszServer, const char far * pszGroupName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetGroupGetUsers. A null pointer or null string specifies the local computer. pszGroupName Points to an ASCIIZ string that contains the name of the group whose members are to be listed. sLevel Specifies the level of detail requested; must be 0. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer pointed to by pbBuffer contains a sequence of group_users_info_0 data structures. cbBuffer Specifies the size (in bytes) of the buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer in which the number of group_users_info_0 data structures in the buffer pointed to by pbBuffer is returned. This count is valid only if NetGroupGetUsers returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. pcTotalAvail Points to an unsigned short integer in which the total number of users in the group is returned. This count is valid only if NetGroupGetUsers returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── this transaction: IPC$ is not shared. NERR_ACFNotFound 2219 LAN Manager could not find the user accounts database file, NET.ACC. This file should be in the ACCOUNTS subdirectory of the LANMAN directory. NERR_GroupNotFound 2220 The groupname was not found. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_ACFFileIOFail 2229 A disk I/O failure occurred. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks NetGroupGetUsers is the only function in the Group category that can operate on a remote server that has share-level security. All other Group category functions require the remote server to have user-level security. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing all groups that contain NetUserGetGroups a specific username Listing the names of groups on a NetGroupEnum server NetGroupSetInfo ──────────────────────────────────────────────────────────────────────────── NetGroupSetInfo sets information for a given group in the user accounts subsystem (UAS) database. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or accounts operator privilege is required to successfully execute NetGroupSetInfo on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETGROUP #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetGroupSetInfo (const char far * pszServer, char far * pszGroupName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, short sParmNum ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetGroupSetInfo. A null pointer or null string specifies the local computer. pszGroupName Points to an ASCIIZ string that contains the name of the group for which the information is to be set. sLevel Specifies the level of detail provided; must be 1. pbBuffer Points to the data to be set. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. sParmNum Specifies whether to reset all the group information or to change only a part of it. If sParmNum is PARMNUM_ALL, pbBuffer must point to a group_info_1 data structure, and the old group information is replaced by this new information. If sParmNum is any other defined value, only one element of the group information is changed, and pbBuffer must point to a valid value for that element. Not all elements can be set. Only those elements that have a specific PARMNUM constant value defined can be set. The ACCESS.H header file defines these possible values for sParmNum: Code Value Element of group_info_1 ──────────────────────────────────────────────────────────────────────────── PARMNUM_ALL 0 All elements. GRP1_PARMNUM_COMMENT 2 grpi1_comment ──────────────────────────────────────────────────────────────────────────── Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidAPI 2142 The requested API is not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_GroupNotFound 2220 The groupname was not found. NERR_NotPrimary 2226 The specified server is not the primary domain controller, so its UAS database cannot be updated. NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_ACFFileIOFail 2229 A disk I/O failure occurred. NERR_SpeGroupOp 2234 This operation is not allowed on this special group. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. NERR_CanNotGrowUASFile 2456 The user accounts database cannot be enlarged because the server's hard disk is full. ──────────────────────────────────────────────────────────────────────────── Remarks If an attempt is made to set information for the users, guests, admins, or local special groups, NetGroupSetInfo returns NERR_SpeGroupOp. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Remote calls Chapter 1, "Overview of the LAN Manager API" NetGroupSetUsers ──────────────────────────────────────────────────────────────────────────── NetGroupSetUsers sets information about users who belong to a particular group. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or accounts operator privilege is required to successfully execute NetGroupSetUsers on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETGROUP #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetGroupSetUsers (const char far * pszServer, const char far * pszGroupName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short cEntries ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetGroupSetUsers. A null pointer or null string specifies the local computer. pszGroupName Points to an ASCIIZ string that contains the name of the group to which the specified users belong. sLevel Specifies the level of detail supplied; must be 0. pbBuffer Points to the buffer in which the data to be set is stored. This data consists of a sequence of group_users_info_0 data structures. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. cEntries Specifies the number of group_users_info_0 data structures supplied in the buffer pointed to by pbBuffer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_GroupNotFound 2220 The groupname was not found. NERR_UserNotFound 2221 The username was not found. NERR_NotPrimary 2226 The specified server is not the primary domain controller, so its UAS database cannot be updated. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_ACFNotLoaded 2227 The user accounts database is not active. This database must be active for the command to run. NERR_ACFNoRoom 2228 The user accounts database is full. NERR_ACFFileIOFail 2229 A disk I/O failure occurred. NERR_SpeGroupOp 2234 This operation is not allowed on this special group. NERR_InvalidDatabase 2247 The user accounts database file, NET.ACC, is corrupted. NERR_InvalidComputer 2351 The specified computername is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_CanNotGrowUASFile 2456 The user accounts database cannot be enlarged because the server's hard disk is full. ──────────────────────────────────────────────────────────────────────────── Remarks If an attempt is made to set a list of usernames for the users, guests, admins, or local special groups, NetGroupSetUsers returns NERR_SpeGroupOp. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Remote calls Chapter 1, "Overview of the LAN Manager API" Setting a user's group NetUserSetGroups membership Group Category Example /* NETGROUP.C -- a sample program demonstrating NetGroup API functions. This program requires that you have admin privilege or accounts operator privilege on the specified server. usage: netgroup [-s \\server] [-g groupname] [-c comment] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). groupname = Name of the group to be added. comment = Comment for the group to be added. API Used to... ================ ========================================= NetGroupAdd Add a new group NetGroupEnum Display list of groups and group comments NetGroupSetInfo Change a group's comment NetGroupGetInfo Display a particular group's comment NetGroupSetUsers Set the members of a group NetGroupAddUser Add a new member to the group NetGroupDelUser Delete a member from the group NetGroupGetUsers List the members of a group NetGroupDel Delete a group This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETGROUP #define INCL_NETERRORS #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include "samples.h" // Internal routine header file #define DEFAULT_GROUP "TESTERS" #define DEFAULT_COMMENT "Default comment for new group" #define NEW_COMMENT "New group comment" #define TRIAL_USER1 "BRUCE" #define TRIAL_USER2 "LIZ" #define TRIAL_USER3 "JOHN" #define BIG_BUFF 32768 void Usage (char * pszProgram); void main(int argc, char *argv[]) { char * pszServer = ""; char * pszNewGroup = DEFAULT_GROUP; char * pszComment = DEFAULT_COMMENT; char * pszNewUser1 = TRIAL_USER1; char * pszNewUser2 = TRIAL_USER2; char * pszNewUser3 = TRIAL_USER3; char * pbBuffer; // Pointer to data buffer int iArgv; // Index for arguments unsigned short iEntries; // Index for entries read unsigned short cRead; // Count read unsigned short cAvail; // Count available unsigned short cbBuffer; // Size of buffer, in bytes API_RET_TYPE uReturnCode; // API return code struct group_info_1 * pGroupInfo1; // Pointer to group info struct group_users_info_0 * pGroupUsersInfo0; for (iArgv = 1; iArgv < argc; iArgv++) { if ((*argv[iArgv] == '-') || (*argv[iArgv] == '/')) { switch (tolower(*(argv[iArgv]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iArgv]; break; case 'g': // -g groupname pszNewGroup = argv[++iArgv]; break; case 'c': // -c comment pszComment = argv[++iArgv]; break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } //======================================================================== // NetGroupAdd // // This API adds a new group with info level 1. //======================================================================== cbBuffer = sizeof(struct group_info_1); pGroupInfo1 = (struct group_info_1 *) SafeMalloc(cbBuffer); strcpy(pGroupInfo1->grpi1_name, pszNewGroup); pGroupInfo1->grpi1_comment = pszComment; uReturnCode = NetGroupAdd( pszServer, // Servername 1, // Info level (char far *)pGroupInfo1,// Input buffer cbBuffer); // Size of buffer free(pGroupInfo1); printf("NetGroupAdd of group \"%s\" returned %u\n", pszNewGroup, uReturnCode); //======================================================================== // NetGroupEnum // // This API displays the list of current groupnames and group comments. //======================================================================== cbBuffer = BIG_BUFF; // Can be up to 64K pbBuffer = SafeMalloc(cbBuffer); // Data buffer uReturnCode = NetGroupEnum( pszServer, // Servername 1, // Info level pbBuffer, // Data returned here cbBuffer, // Size of buffer, in bytes &cRead, // Count of entries read &cAvail); // Count of entries available printf("NetGroupEnum returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) { pGroupInfo1 = (struct group_info_1 *) pbBuffer; for (iEntries = 0; iEntries < cRead; iEntries++) { printf(" %-24s - %Fs\n", pGroupInfo1->grpi1_name, pGroupInfo1->grpi1_comment); pGroupInfo1++; } printf("%hu out of %hu entries returned\n", cRead, cAvail); } free(pbBuffer); //======================================================================== // NetGroupSetInfo // // This API sets information for a group. // // There are two ways to call NetGroupSetInfo. If sParmNum is set to // PARMNUM_ALL, you must pass it a whole structure. Otherwise, you // can set sParmNum to the structure element you want to change. The // whole structure is used in this example to change the group comment. //======================================================================== cbBuffer = sizeof(struct group_info_1) + MAXCOMMENTSZ + 1; pbBuffer = SafeMalloc(cbBuffer); // Info buffer pGroupInfo1 = (struct group_info_1 *) pbBuffer; strcpy(pGroupInfo1->grpi1_name, pszNewGroup); /* * Data referenced by a pointer from within the fixed-length * portion of the data structure must be located outside the buffer * passed to the API or it will be ignored in remote NetGroupSetInfo * calls. */ pGroupInfo1->grpi1_comment = NEW_COMMENT; uReturnCode = NetGroupSetInfo( pszServer, // Servername pszNewGroup, // Groupname 1, // Info level pbBuffer, // Data buffer cbBuffer, // Size of buffer, in bytes PARMNUM_ALL); // Parameter number code printf("NetGroupSetInfo returned %u\n", uReturnCode); printf(" Changing comment for group \"%s\" %s\n", pszNewGroup, uReturnCode ? "failed" : "succeeded"); //======================================================================== // NetGroupGetInfo // // This API gets the information available about the new group. //======================================================================== uReturnCode = NetGroupGetInfo( pszServer, // Servername pszNewGroup, // Groupname 1, // Info level pbBuffer, // Data buffer cbBuffer, // Size of buffer, in bytes &cAvail); // Count of bytes available printf("NetGroupGetInfo returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) { printf(" %-24s - %Fs\n", pGroupInfo1->grpi1_name, pGroupInfo1->grpi1_comment); } free(pbBuffer); //======================================================================== // NetGroupSetUsers // // This API sets the list of users who belong to the new group. //======================================================================== cbBuffer = sizeof(struct group_users_info_0) * 2; pbBuffer = SafeMalloc(cbBuffer); // Info buffer pGroupUsersInfo0 = (struct group_users_info_0 *) pbBuffer; strcpy(pGroupUsersInfo0->grui0_name, pszNewUser1); pGroupUsersInfo0++; strcpy(pGroupUsersInfo0->grui0_name, pszNewUser2); uReturnCode = NetGroupSetUsers( pszServer, // Servername pszNewGroup, // Groupname 0, // Info level; must be 0 pbBuffer, // Data buffer cbBuffer, // Size of buffer, in bytes 2); // Entries printf("NetGroupSetUsers returned %u\n", uReturnCode); //======================================================================== // NetGroupAddUser // // This API adds a user to the new group. //======================================================================== uReturnCode = NetGroupAddUser( pszServer, // Servername pszNewGroup, // Groupname pszNewUser3); // Username to add printf("NetGroupAddUser for user \"%s\" returned %u\n", pszNewUser3, uReturnCode); //======================================================================== // NetGroupDelUser // // This API deletes a user from the new group. //======================================================================== uReturnCode = NetGroupDelUser( pszServer, // Servername pszNewGroup, // Groupname pszNewUser2); // Username to delete printf("NetGroupDelUser for user \"%s\" returned %u\n", pszNewUser2, uReturnCode); //======================================================================== // NetGroupGetUsers // // This API lists the users who belong to the new group. //======================================================================== uReturnCode = NetGroupGetUsers( pszServer, // Servername pszNewGroup, // Groupname 0, // Info level; must be 0 pbBuffer, // Buffer cbBuffer, // Size of buffer &cRead, // Count of entries read &cAvail); // Count of entries available printf("NetGroupGetUsers returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) { pGroupUsersInfo0 = (struct group_users_info_0 *) pbBuffer; for (iEntries = 0; iEntries < cRead; iEntries++) { printf(" %s\n", pGroupUsersInfo0->grui0_name); pGroupUsersInfo0++; } } free(pbBuffer); //======================================================================== // NetGroupDel // // This API deletes the new group. //======================================================================== uReturnCode = NetGroupDel(pszServer, // Servername pszNewGroup); // Groupname to delete free(pGroupInfo1); printf("NetGroupDel of group \"%s\" returned %u\n", pszNewGroup, uReturnCode); exit(0); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s [-s \\\\server]"\ " [-g groupname] [-c comment]\n", pszProgram); exit(1); } Handle Category Handle API functions get and set information related to the specified character-device or named-pipe handle. They require that the Workstation service be started. The Handle category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and CHARDEV.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETHANDLE, and including the master header file, LAN.H. For more information about these definitions, see the "Example" section, later in this category. These are the Handle API functions: ■ NetHandleGetInfo ■ NetHandleSetInfo Description NetHandleGetInfo and NetHandleSetInfo allow an application to examine or change the communications parameters for character-device handles and named-pipe handles, provided that the handles refer to devices or pipes opened on a remote server. The adjustable parameters are based on the LANMAN.INI file entries for chartime and charcount, which determine the workstation data structure elements wkiX_chartime and wkiX_charcount, where X is the level of detail requested. These values specify when LAN Manager sends a packet of information over the network. Rather than writing single bytes to the network, LAN Manager saves the data in a buffer until chartime milliseconds have elapsed or until the buffer contains charcount characters. The handle_info_1 data structure elements hdli1_chartime and hdli1_charcount take their initial values from the workstation data structure elements wkiX_chartime and wkiX_charcount. The Handle API functions allow these values to be inspected and modified on a handle-by-handle basis. NetHandleGetInfo can also be used to identify the user of a named pipe, provided that the pipe has been opened from a remote server. Handle API functions can be called only locally (there is no servername parameter). Data Structures The handle_info_1 data structure is used with both NetHandleGetInfo and NetHandleSetInfo. The handle_info_2 data structure is used only with NetHandleGetInfo. Handle Information (level 1) The handle_info_1 data structure has this format: struct handle_info_1 { unsigned long hdli1_chartime; unsigned short hdli1_charcount; }; where hdli1_chartime Specifies the amount of time (in milliseconds) that the workstation collects data to send to a character device or named pipe. hdli1_charcount Specifies the number of characters (in bytes) that the workstation stores before it sends data to a character device or named pipe. Handle Information (level 2) The handle_info_2 data structure has this format: struct handle_info_2 { char far * hdli2_username; }; where hdli2_username Points to the name of the user who has opened a named pipe. This username is available only for a handle on the serving side of a valid named pipe that has been opened by a remote computer. If the named pipe has been opened locally, the call to NetHandleGetInfo returns ERROR_INVALID_PARAMETER. NetHandleGetInfo ──────────────────────────────────────────────────────────────────────────── NetHandleGetInfo retrieves handle-specific information for character-device and named-pipe handles. Operating Systems Supported ■ MS OS/2 version 1.2, local only, levels 1 and 2 ■ MS OS/2 version 1.1, local only, level 1 only ■ MS-DOS, local only, level 1 with remote named pipes only Privilege Level Access privilege is determined by the access restrictions to the named pipe or character device being accessed. Syntax #define INCL_NETHANDLE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetHandleGetInfo (unsigned short hHandle, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbTotalAvail ); where hHandle Identifies a communication-device queue or a named pipe. sLevel Specifies the level of detail (1 or 2) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a handle_info_1 data structure (level 1 call) or a handle_info_2 data structure (level 2 call). cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcbTotalAvail Points to an unsigned short integer in which a count of the total number of bytes of information available is returned. This count is valid only if NetHandleGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── started. ──────────────────────────────────────────────────────────────────────────── Remarks NetHandleGetInfo can be called at level 1 only if the value of hHandle is a valid handle to a named pipe or character device that exists on a remote server. NetHandleGetInfo can be called at level 2 only if the value of hHandle is a handle to the server side of a valid named pipe opened on a remote computer. If the named pipe has been opened locally or if the handle is not for a named pipe, NetHandleGetInfo returns ERROR_INVALID_PARAMETER. NetHandleSetInfo ──────────────────────────────────────────────────────────────────────────── NetHandleSetInfo sets handle-specific information for character-device and named-pipe handles. Operating Systems Supported ■ MS OS/2 version 1.2, local only, level 1 only ■ MS OS/2 version 1.1, local only, level 1 only ■ MS-DOS, local only, level 1 with remote named pipes only Privilege Level Access privilege is determined by the access restrictions to the named pipe or character device being accessed. Syntax #define INCL_NETHANDLE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetHandleSetInfo (unsigned short hHandle, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short sParmNum ); where hHandle Identifies a communication-device queue or a named pipe. sLevel Specifies the level of detail provided; must be 1. pbBuffer Points to the data to be set. cbBuffer Specifies the size (in bytes) of the buffer pointed to by pbBuffer. sParmNum Specifies whether to reset all handle information or to change only a part of it. If sParmNum is PARMNUM_ALL, pbBuffer must point to a handle_info_1 data structure, and the previous handle information is replaced by this new information. If sParmNum is any other defined value, only one element of the handle information is changed, and pbBuffer must point to a valid value for that element. Not all elements can be set. Only those elements that have a specific PARMNUM constant value defined can be set. The CHARDEV.H header file defines these possible values for sParmNum: Code Value Element of handle_info_1 ──────────────────────────────────────────────────────────────────────────── PARMNUM_ALL 0 All elements. HANDLE_SET_CHAR_TIME 1 hdli1_chartime HANDLE_SET_CHAR_COUNT 2 hdli1_charcount ──────────────────────────────────────────────────────────────────────────── Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. ──────────────────────────────────────────────────────────────────────────── Handle Category Example /* NETHAND1.C -- a sample program demonstrating NetHandle API functions for the server side of named pipes. This program must be run on a computer that has the Server service running. It is to be used in conjunction with the program NETHAND2 running on a workstation. usage: nethand1 [-p pipename] [-m message] where pipename = Name of the pipe to create. message = Message to be sent through the pipe. Run NETHAND1 on the server to create a named pipe, then run NETHAND2 on a workstation to connect to that named pipe. API Used to... ================ ========================================== NetHandleGetInfo Get the name of the user of the named pipe This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_BASE #define INCL_DOSNMPIPES #include <os2.h> // MS OS/2 base header files #define INCL_NETERRORS #define INCL_NETHANDLE #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include <chardev.h> #include <io.h> #define PIPENAMELEN 128 #define BUFFLEN 128 #define PIPE_BUFFSIZE 2048 #define DEFAULT_MESSAGE "Message from server" #define DEFAULT_PIPE "handtest" #define OPENMODE NP_ACCESS_DUPLEX #define PIPEMODE NP_READMODE_BYTE | NP_TYPE_BYTE | NP_WAIT | \ NP_UNLIMITED_INSTANCES void Usage (char * pszProgram); void main(int argc, char *argv[]) { char * pszMessage = DEFAULT_MESSAGE; // Message to send down pipe char * pszPipeName = DEFAULT_PIPE; // Supplied pipename char achBuffer[BUFFLEN]; // Data buffer char achFullPipe[PIPENAMELEN]; // Full name of pipe to open int iArgv; // Index for arguments unsigned short hPipe; // Handle to named pipe unsigned short cbAvail; // Bytes available from GetInfo unsigned short usReturnCode; // MS OS/2 return code API_RET_TYPE uReturnCode; // LAN Manager API return code struct handle_info_2 * pHandleInfo2; for (iArgv = 1; iArgv < argc; iArgv++) { if ((*argv[iArgv] == '-') || (*argv[iArgv] == '/')) { switch (tolower(*(argv[iArgv]+1))) // Process switches { case 'p': // -p pipename pszPipeName = argv[++iArgv]; break; case 'm': // -m message pszMessage = argv[++iArgv]; break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } strcpy(achFullPipe, "\\PIPE\\"); // Set up named pipe strcat(achFullPipe, pszPipeName); printf("Creating Named Pipe %s\n", achFullPipe); if (usReturnCode = DosMakeNmPipe( achFullPipe, // Name of pipe to open &hPipe, // Handle to opened pipe OPENMODE, // Full duplex PIPEMODE, // Unlimited opens, blocked mode PIPE_BUFFSIZE, // Outgoing buffer size PIPE_BUFFSIZE, // Incoming buffer size 0L)) // Time-out value { printf( "DosMakeNmPipe failed (error %hu).\n", usReturnCode ); exit(1); } printf("Waiting for Connect to Pipe... \n" ); if (usReturnCode = DosConnectNmPipe(hPipe)) { printf("DosConnectNmPipe failed (error %hu).\n", usReturnCode); exit(1); } printf("Waiting for message from pipe... \n" ); if (read( hPipe, achBuffer, BUFFLEN ) == -1) { printf(" Read message failed (error %d)\n", errno); exit(1); } else { printf(" \"%s\"\n", achBuffer); } /* * Write message to the named pipe. Make sure that the message * length specified includes the terminating NUL. */ printf("Writing message \"%s\" \n", pszMessage ); if (write(hPipe, pszMessage, strlen(pszMessage) + 1) == -1) { printf(" Write message failed (error %d)\n", errno); exit(1); } //======================================================================== // NetHandleGetInfo // // This API gets the name of the user who is connected to the named pipe. // It can be called only at level 2 on the server end of a handle. //======================================================================== uReturnCode = NetHandleGetInfo( hPipe, // Handle to named pipe 2, // Level 2 achBuffer, // Data returned here BUFFLEN, // Size of buffer, in bytes (unsigned short far *) &cbAvail); printf("NetHandleGetInfo returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) { pHandleInfo2 = (struct handle_info_2 *) achBuffer; printf(" User of the named pipe is %Fs\n", pHandleInfo2->hdli2_username ); } do // Wait for disconnect { } while (DosConnectNmPipe(hPipe) == 0 ); if ((usReturnCode = DosDisConnectNmPipe(hPipe)) == 0) printf("Pipe disconnected. \n"); else { printf("DosDisConnectNmPipe failed (error %hu).\n", usReturnCode); exit(1); } exit(0); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s [-p pipename] [-m message] \n", pszProgram); exit(1); } /* NETHAND2.C -- a sample program demonstrating NetHandle API functions for the workstation side of named pipes. This program must be run on a computer that has the Workstation service running. It is to be used in conjunction with the program NETHAND1 running on a server. usage: nethand2 -s \\server [-p pipename] [-m message] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). pipename = Name of the pipe to connect to. message = Message to be sent through the pipe. Run NETHAND1 on the server to create a named pipe, then run NETHAND2 on a workstation to connect to that named pipe. API Used to... ================ ================================================ NetHandleGetInfo Get the values for charcount and chartime NetHandleSetInfo Set the value for charcount to half the original This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETERRORS #define INCL_NETHANDLE #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include <chardev.h> #include <fcntl.h> #include <sys\types.h> #include <sys\stat.h> #include <share.h> #include <io.h> #define PIPENAMELEN 128 #define BUFFLEN 128 #define DEFAULT_MESSAGE "Message from workstation" #define DEFAULT_PIPE "handtest" void Usage (char * pszProgram); void main(int argc, char *argv[]) { char * pszServer = NULL; char * pszMessage = DEFAULT_MESSAGE; // Message to send down pipe char * pszPipeName = DEFAULT_PIPE; // Supplied pipename char achFullPipe[PIPENAMELEN]; // Full name of pipe char achBuffer[BUFFLEN]; // Data buffer int iArgv; // Index for arguments unsigned short hPipe; // Handle to named pipe unsigned short cbAvail; // Bytes available from GetInfo unsigned short cbCharCount; // Pipe charcount API_RET_TYPE uReturnCode; // LAN Manager API return code struct handle_info_1 HandleInfo1; for (iArgv = 1; iArgv < argc; iArgv++) { if ((*argv[iArgv] == '-') || (*argv[iArgv] == '/')) { switch (tolower(*(argv[iArgv]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iArgv]; break; case 'p': // -p pipename pszPipeName = argv[++iArgv]; break; case 'm': // -m message pszMessage = argv[++iArgv]; break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } if (pszServer == NULL) // Must specify a servername { Usage(argv[0]); } // Set up full name of pipe strcpy(achFullPipe, pszServer); strcat(achFullPipe, "\\PIPE\\"); strcat(achFullPipe, pszPipeName); printf("Opening named pipe %s\n", achFullPipe); if ((hPipe = sopen(achFullPipe, O_BINARY | O_RDWR, SH_DENYNO))== -1) { printf( " Open of pipe failed (error %d).\n", errno ); exit(1); } // NetHandleGetInfo // // This API gets the values for chartime and charcount for the named pipe. // These values will be the same as the default values for the workstation // as listed in the LANMAN.INI file (unless explicitly altered). This API // can be called only at level 1 on the workstation end of a serial-device // handle. uReturnCode = NetHandleGetInfo( hPipe, // Handle to named pipe 1, // Level 1 (char far *)&HandleInfo1, // Data returned here sizeof(struct handle_info_1), (unsigned short far *) &cbAvail); printf("NetHandleGetInfo returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) { cbCharCount = HandleInfo1.hdli1_charcount; printf(" Chartime = %ld\n", HandleInfo1.hdli1_chartime); printf(" CharCount = %hu\n", cbCharCount); } //======================================================================== // NetHandleSetInfo // // This API sets the value for charcount to half the default value. // There are two ways to call NetHandleSetInfo: If sParmNum is set to // PARMNUM_ALL, you must pass a whole structure. Otherwise, you can // set sParmNum to the element of the structure you want to change and // pass a pointer to the value. The second method is shown here. //======================================================================== cbCharCount /= 2; printf("Setting the charcount to %hu\n", cbCharCount); uReturnCode = NetHandleSetInfo( hPipe, // Handle to named pipe 1, // Level; must be 1 (char far *)&cbCharCount, // Data to be set sizeof(unsigned short), // Size of buffer HANDLE_SET_CHAR_COUNT); // Set the charcount only printf("NetHandleSetInfo returned %u\n", uReturnCode); // Verify the values set uReturnCode = NetHandleGetInfo( hPipe, // Handle to named pipe 1, // Level 1 (char far *)&HandleInfo1, // Data returned here sizeof(struct handle_info_1), (unsigned short far *) &cbAvail); printf("NetHandleGetInfo returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) { printf(" Chartime = %lu\n", HandleInfo1.hdli1_chartime); printf(" CharCount = %hu\n", HandleInfo1.hdli1_charcount); } /* * Write a message to the named pipe. Make sure that the * message length specified includes the terminating NUL. */ printf("Writing \"%s\" to pipe... \n", pszMessage); if (write(hPipe, pszMessage, strlen(pszMessage) + 1) == -1) { printf(" Write message failed (error %d)\n", errno); exit(1); } printf("Waiting for message from pipe... \n" ); if (read(hPipe, achBuffer, BUFFLEN) == -1) { printf(" Read message failed (error %d)\n", errno); exit(1); } printf(" \"%s\"\n", achBuffer); printf("Closing pipe...\n"); // Close the pipe if (close(hPipe)) { printf(" Close handle failed (error %d)\n", errno); exit(1); } exit(0); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s -s \\\\server [-p pipename] [-m message] \n", pszProgram); exit(1); } Mailslot Category Mailslot API functions provide one-way interprocess communication (IPC). They require that the NETWKSTA device driver be installed and, when trying to access remote resources, that the Workstation service be started. The Mailslot category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and MAILSLOT.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETMAILSLOT, and including the master header file, LAN.H. For more information, see the "Example" section, later in this category. These are the Mailslot API functions: ■ DosDeleteMailslot ■ DosMailslotInfo ■ DosMakeMailslot ■ DosPeekMailslot ■ DosReadMailslot ■ DosWriteMailslot Description An application can use LAN Manager mailslots to send data to local or remote applications on the network. Mailslot API functions manage mailslots and mailslot messages. DosMakeMailslot creates a mailslot and returns its handle. DosPeekMailslot reads the highest-priority, most current message without removing it from the mailslot. DosReadMailslot reads the highest-priority, most current message, and then removes it from the mailslot. DosWriteMailslot writes a message to a mailslot. Applications can write messages to any mailslot on any computer or in any domain on the network. The message can be any form of data─it need not be an ASCIIZ string. DosMailslotInfo retrieves information about a particular mailslot. DosDeleteMailslot removes a mailslot, discarding all unread messages. There are two classes of mailslot message delivery: first-class and second-class. First-class messages are successfully delivered or the sender is notified with the appropriate error return code. If a mailslot is full when a first-class message arrives, DosWriteMailslot waits until a message is read and removed from the mailslot (using DosReadMailslot) or until the delivery time-out expires (controlled by the cTimeout parameter in DosWriteMailslot). First-class messages can be used only with mailslots on the local computer and remote servers. Successful delivery of second-class messages is not guaranteed. There is no way to determine whether a message arrived successfully. The simpler delivery system tends to make second-class messages faster than first-class messages. Second-class messages can be sent to any remote computer, not just to remote servers, and can be sent to multiple computers simultaneously. Each message is assigned a priority from 0 (lowest priority) through 9 (highest priority) using the DosWriteMailslot usPriority parameter. Messages are stored in the mailslot sorted first by priority, then by time of arrival. High-priority messages are placed ahead of previously stored messages that have the same or lower priority. Since MS OS/2 is a multitasking operating system, this scheme cannot be guaranteed at any instant (messages could be received but not yet sorted). DosPeekMailslot and DosReadMailslot read the oldest message of highest priority. Since new messages can be placed ahead of others, a message read by DosReadMailslot might not be the same one read earlier by DosPeekMailslot. DosMailslotInfo retrieves information about a mailslot, such as its maximum size, the maximum size of messages it can accept, the priority and size of the next message, and the total number of messages waiting to be read. To write data to a mailslot on a remote computer, the name of the mailslot must include a computername. This enables multiple remote computers to use the same mailslot name locally but to use different names on the network (the computername must be unique). An application can write the same message to all computers in a domain that have a mailslot with a particular name. In this case, only second-class delivery is supported. Specifying an asterisk (*) as the computername when calling DosWriteMailslot sends the same message to the named mailslot on every computer in the sender's primary domain. Use this mailslot format: \\*\mailslot\mailslotname Specifying a domain name for the computername when calling DosWriteMailslot sends the same message to the named mailslot on every computer in the specified domain. Use this mailslot format: \\domainname\mailslot\mailslotname Workstations can receive only second-class messages, with as many as 400 bytes per message. Servers can receive first-class or second-class messages of any size. Mailslots can be read or deleted only by the process that created them. Mailslots created by a process are deleted when that process ends. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Interprocess communication (IPC) Appendix F, "Network Considerations for Named Pipes" DosDeleteMailslot ──────────────────────────────────────────────────────────────────────────── DosDeleteMailslot deletes a mailslot, discarding all messages whether or not they have been read. Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1, local only ■ MS-DOS, local only Privilege Level No special privilege level is required to successfully execute DosDeleteMailslot. Syntax #define INCL_NETMAILSLOT #define INCL_NETERRORS #include <lan.h> API_FUNCTION DosDeleteMailslot (unsigned hMailslot); where hMailslot Specifies a handle for the mailslot to be deleted. The handle must have been returned by a previous call to DosMakeMailslot. Return Codes Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_INVALID_HANDLE 6 The handle specified is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. ──────────────────────────────────────────────────────────────────────────── Remarks Mailslots are generally deleted as the last step in a program's execution. A mailslot can be deleted only by the application that created it. DosMailslotInfo ──────────────────────────────────────────────────────────────────────────── DosMailslotInfo retrieves information about a particular mailslot. Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1, local only ■ MS-DOS, local only Privilege Level No special privilege level is required to successfully execute DosMailslotInfo. Syntax #define INCL_NETMAILSLOT #define INCL_NETERRORS #include <lan.h> API_FUNCTION DosMailslotInfo (unsigned hMailslot, unsigned short far * pcbMessageSize, unsigned short far * pcbMailslotSize, unsigned short far * pcbNextSize, unsigned short far * pusNextPriority, unsigned short far * pcMessages ); where hMailslot Specifies a handle for the mailslot about which information is requested. The handle must have been returned by a previous call to DosMakeMailslot. pcbMessageSize Points to an unsigned short integer in which the maximum message size (in bytes) that the mailslot can accept is returned. pcbMailslotSize Points to an unsigned short integer in which the size (in bytes) of the mailslot is returned. pcbNextSize Points to an unsigned short integer in which the size (in bytes) of the next message in the mailslot is returned. If this value is 0, no message is available. pusNextPriority Points to an unsigned short integer in which the priority (0 through 9) of the next message in the mailslot is returned. pcMessages Points to an unsigned short integer in which a count of the messages in the mailslot is returned. Return Codes Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_INVALID_HANDLE 6 The handle specified is invalid. ERROR_BROKEN_PIPE 109 The pipe has been closed or the pipe is not being read. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. ──────────────────────────────────────────────────────────────────────────── Remarks DosMailslotInfo can be used before DosReadMailslot or DosPeekMailslot to determine the buffer size needed to read the next message. This may fail, because a higher-priority message can arrive after the DosMailslotInfo call and before the identified message is read. If the mailslot is deleted while being queried by DosMailslotInfo, the error code ERROR_BROKEN_PIPE is returned. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Creating (and obtaining the DosMakeMailslot handle for) a mailslot Retrieving the most current DosReadMailslot message in a mailslot Writing a message to a mailslot DosWriteMailslot DosMakeMailslot ──────────────────────────────────────────────────────────────────────────── DosMakeMailslot creates a mailslot on a local computer and returns a handle to that mailslot. The other Mailslot API functions can then use this handle. The mailslot name supplied to the function should be in the format \mailslot\mailslotname where mailslotname is a unique set of characters that distinguish the mailslot from other mailslots on the computer (for example, \mailslot\test\slot1). Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1, local only ■ MS-DOS, local only Privilege Level No special privilege level is required to successfully execute DosMakeMailslot. Syntax #define INCL_NETMAILSLOT #define INCL_NETERRORS #include <lan.h> API_FUNCTION DosMakeMailslot (const char far * pszName, unsigned short cbMessageSize, unsigned short cbMailslotSize, unsigned far * phMailslot ); where pszName Points to an ASCIIZ string that contains the name of the mailslot. cbMessageSize Specifies the maximum message size (in bytes) that the mailslot can accept. Mailslots can accept messages that have as many as 65,475 bytes. cbMailslotSize Specifies the size (in bytes) of the mailslot. This parameter must be 0, or it must be equal to or exceed cbMessageSize. If this value is 0, DosMakeMailslot sets a value based on cbMessageSize. phMailslot Points to an unsigned integer that is the returned handle for the mailslot. This handle must be used for all subsequent operations on the mailslot. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_ALREADY_EXISTS 183 A loader error occurred. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. ──────────────────────────────────────────────────────────────────────────── Remarks Mailslot names must be unique; no two mailslots on any one computer can have the same name. An attempt to create a mailslot with the name of a mailslot that already exists results in ERROR_ALREADY_EXISTS being returned. You cannot pass mailslot handles to other processes using the DosExecPgm function, but mailslot handles can be shared among threads in a single process. Multiple threads can use the handle to read or write data to the mailslot. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Deleting a mailslot DosDeleteMailslot Retrieving information about a DosMailslotInfo mailslot DosPeekMailslot ──────────────────────────────────────────────────────────────────────────── DosPeekMailslot reads the highest-priority, most current message in a mailslot without removing it. Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1, local only ■ MS-DOS, local only Privilege Level No special privilege level is required to successfully execute DosPeekMailslot. Syntax #define INCL_NETMAILSLOT #define INCL_NETERRORS #include <lan.h> API_FUNCTION DosPeekMailslot (unsigned hMailslot, char far * pbBuffer, unsigned short far * pcbReturned, unsigned short far * pcbNextSize, unsigned short far * pusNextPriority ); where hMailslot Specifies the handle of the mailslot to be read. The handle must have been returned by a previous call to DosMakeMailslot. pbBuffer Points to the buffer in which to store the returned message. The buffer should be as large as the cbMessageSize parameter passed to DosMakeMailslot. pcbReturned Points to an unsigned short integer in which the size (in bytes) of the new message is returned. If no message is available, pcbReturned is 0. pcbNextSize Points to an unsigned short integer in which the size (in bytes) of the next message in the mailslot is returned. If the mailslot does not contain another message, pcbNextSize is 0. pusNextPriority Points to an unsigned short integer in which the priority (0 through 9) of the next message in the mailslot is returned. This value is valid only if pcbNextSize is not 0. Return Codes Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_INVALID_HANDLE 6 The handle specified is invalid. ERROR_BROKEN_PIPE 109 The pipe has been closed or the pipe is not being read. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. ──────────────────────────────────────────────────────────────────────────── Remarks There is no guarantee that a message read by calling DosPeekMailslot will be the same message read by a subsequent call to DosReadMailslot. A higher-priority message can arrive between the two calls. If the mailslot is deleted while being queried by DosPeekMailslot, the error code ERROR_BROKEN_PIPE is returned. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Creating a mailslot DosMakeMailslot Reading and removing a message DosReadMailslot Writing a message to a mailslot DosWriteMailslot DosReadMailslot ──────────────────────────────────────────────────────────────────────────── DosReadMailslot reads and then removes the highest-priority, most current message in a mailslot. Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1, local only ■ MS-DOS, local only Privilege Level No special privilege level is required to successfully execute DosReadMailslot. Syntax #define INCL_NETMAILSLOT #define INCL_NETERRORS #include <lan.h> API_FUNCTION DosReadMailslot (unsigned hMailslot, char far * pbBuffer, unsigned short far * pcbReturned, unsigned short far * pcbNextSize, unsigned short far * pusNextPriority, long cTimeout ); where hMailslot Specifies the handle of the mailslot to be read. The handle must have been returned by a previous call to DosMakeMailslot. pbBuffer Points to the buffer in which to store the returned message. The buffer should be as large as the cbMessageSize parameter passed to DosMakeMailslot. pcbReturned Points to an unsigned short integer in which the size (in bytes) of the new message is returned. If no message is available, pcbReturned is 0. pcbNextSize Points to an unsigned short integer in which the size (in bytes) of the next message in the mailslot is returned. If the mailslot does not contain another message, pcbNextSize is 0. pusNextPriority Points to an unsigned short integer in which the priority (0 through 9) of the next message in the mailslot is returned. This value is valid only if pcbNextSize is not 0. cTimeout Specifies how many milliseconds to wait if a message is not available immediately. If this value is 0, DosReadMailslot does not wait; if it is MAILSLOT_NO_TIMEOUT, DosReadMailslot waits indefinitely. Return Codes ╓┌─────────────────────┌───────┌─────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_INVALID_HANDLE 6 The handle specified is invalid. ERROR_INTERUPT 95 The system call was interrupted. ERROR_BROKEN_PIPE 109 The pipe has been closed or the pipe is not being read. ERROR_SEM_TIMEOUT 121 A time-out occurred from the Semaphore API functions. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Remarks If the mailslot is deleted while being queried by DosReadMailslot, the error code ERROR_BROKEN_PIPE is returned. If no message is waiting to be read, and none arrives within the period specified by cTimeout, DosReadMailslot returns ERROR_SEM_TIMEOUT. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Creating a mailslot DosMakeMailslot Reading a message without DosPeekMailslot removing it Writing a message to a mailslot DosWriteMailslot DosWriteMailslot ──────────────────────────────────────────────────────────────────────────── DosWriteMailslot writes a message to a particular mailslot. Operating Systems Supported ■ MS OS/2 version 1.2, local only ■ MS OS/2 version 1.1, local only ■ MS-DOS, local only Privilege Level No special privilege level is required to successfully execute DosWriteMailslot. Syntax #define INCL_NETMAILSLOT #define INCL_NETERRORS #include <lan.h> API_FUNCTION DosWriteMailslot (const char far * pszName, const char far * pbBuffer, unsigned short cbBuffer, unsigned short usPriority, unsigned short usClass, long cTimeout ); where pszName Points to an ASCIIZ string that contains the name of the mailslot where the message is to be written. pbBuffer Points to the data to write to the mailslot. If the data to be written is an ASCIIZ string, the NUL terminator must be included in the count of bytes to send. cbBuffer Specifies the number of bytes of data to be written to the mailslot. usPriority Assigns a priority (0 through 9) to the message. High-priority messages are generally placed ahead of previously stored messages that have lower priority. usClass Specifies the class of mail service to be provided. A value of 1 specifies first-class service; 2 specifies second-class service. cTimeout Specifies the number of milliseconds to wait for space to become available in the mailslot for this message. If this value is 0, DosWriteMailslot does not wait; if it is MAILSLOT_NO_TIMEOUT, DosWriteMailslot waits indefinitely. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_INVALID_FUNCTION 1 The function is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_BUSY 54 The network is busy. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INTERUPT 95 The system call was interrupted. ERROR_BROKEN_PIPE 109 The pipe has been closed or the pipe is not being read. ERROR_SEM_TIMEOUT 121 A time-out occurred from the Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_SEM_TIMEOUT 121 A time-out occurred from the Semaphore API functions. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. ──────────────────────────────────────────────────────────────────────────── Remarks DosWriteMailslot accepts mailslot names in both a local and a remote format, as follows: Format Type ──────────────────────────────────────────────────────────────────────────── \mailslot\mailslotname Local mailslot. \\computername\mailslot\mailslotname Remote mailslot. \\domainname\mailslot\mailslotname Mailslot on another domain. ──────────────────────────────────────────────────────────────────────────── To send a message to all computers in the primary domain that have a local mailslot with a particular name, an application should pass the pszName parameter (\\*\mailslot\mailslotname) and the usClass parameter 2 to DosWriteMailslot. Second-class messages have as many as 400 bytes when written to remote workstations or entire domains; they can be any size when written to local computers or remote servers. When DosWriteMailslot is called with the workstation not started and the name of a mailslot on a remote computer supplied, DosWriteMailslot returns the error code ERROR_INVALID_FUNCTION. If the mailslot is deleted while being used by DosWriteMailslot, ERROR_BROKEN_PIPE is returned. If a first-class message is being sent, but it is not read within the period specified by cTimeout, DosWriteMailslot returns ERROR_SEM_TIMEOUT. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Creating a mailslot DosMakeMailslot Reading a message DosReadMailslot Mailslot Category Example /* NETMAIL.C -- a sample program demonstrating Mailslot API functions. This program requires no special privilege. usage: netmail [-m mailslot] [-s size] [-t text] [-c class] [-p priority] [-i iterations] where mailslot = Name of mailslot to be used. size = Maximum message size for mailslot. text = Text of message sent to mailslot. class = Class of message sent to mailslot (1 or 2). priority = Priority of message sent to mailslot (0 to 9). iterations = Number of times to send the message. API Used to... ================= ================================================== DosMakeMailslot Make a mailslot on the local computer DosWriteMailslot Write a message to the created mailslot DosMailslotInfo Get information about the mailslot and print it DosPeekMailslot Read the most current message without removing it DosReadMailslot Read and then remove the most current message DosDeleteMailslot Delete the created mailslot This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETERRORS #define INCL_NETMAILSLOT #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include "samples.h" // Internal routine header file #define DEFAULT_MAILSLOT "\\mailslot\\testname" #define DEFAULT_MESSAGE "message sent to mailslot" #define DEFAULT_MSGSIZE 1024 // Max. message size #define DEFAULT_CLASS 1 // First class #define DEFAULT_PRIORITY 0 // Lowest priority #define DEFAULT_ITERATIONS 1 // Send message once void Usage (char * pszProgram); void main(int argc, char *argv[]) { char * pszMailslot = DEFAULT_MAILSLOT; // Mailslot to use char * pszMessage = DEFAULT_MESSAGE; // Message to be sent char * pbBuffer; // Pointer to data buffer int iCount; // Index counter int cIterations = DEFAULT_ITERATIONS; // Iteration counter unsigned hMailslot; // Handle to mailslot unsigned short cbBuffer; // Size of data buffer unsigned short cbMessageSize = DEFAULT_MSGSIZE; unsigned short cbMailslotSize, cMessages; unsigned short cbReturned, cbNextSize, usNextPriority; unsigned short usPriority = DEFAULT_PRIORITY; unsigned short usClass = DEFAULT_CLASS; API_RET_TYPE uReturnCode; // API return code for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 'm': // -m mailslot name pszMailslot = argv[++iCount]; break; case 's': // -s max. message size cbMessageSize = atoi(argv[++iCount]); break; case 't': // -t text pszMessage = argv[++iCount]; break; case 'p': // -p priority usPriority = atoi(argv[++iCount]); break; case 'c': // -c class usClass = atoi(argv[++iCount]); break; case 'i': // -i iterations cIterations = atoi(argv[++iCount]); break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } //======================================================================== // DosMakeMailslot // // This API creates a mailslot on the local computer. The mailslot // size is set to 0, indicating to the API to choose a value based // on the size of the message buffer. //======================================================================== uReturnCode = DosMakeMailslot ( pszMailslot, // Mailslot name cbMessageSize, // Max. message size 0, // Size of mailslot &hMailslot); // Handle to mailslot printf("DosMakeMailslot of \"%s\" returned %u \n", pszMailslot, uReturnCode); if (uReturnCode != NERR_Success) exit(1); //======================================================================== // DosWriteMailslot // // This API writes cIterations messages to the mailslot just created. // If the message being written to the mailslot is an ASCIIZ string, // the specified length must include the NUL terminator. //======================================================================== for (iCount = 1; iCount <= cIterations; iCount++) { uReturnCode = DosWriteMailslot( pszMailslot, // Mailslot name pszMessage, // Message to write to mailslot strlen(pszMessage)+1, // Length; allow for NUL usPriority, // Message priority usClass, // Message class 0L); // Immediate time-out printf("DosWriteMailslot #%d returned %u \n", iCount, uReturnCode); } //======================================================================== // DosMailslotInfo // // This API gets information about the mailslot and then prints it. //======================================================================== uReturnCode = DosMailslotInfo( hMailslot, // Handle to mailslot &cbMessageSize, // Max. message size accepted &cbMailslotSize, // Size of mailslot &cbNextSize, // Size of next message &usNextPriority, // Priority of next message &cMessages); // Count of messages in mailslot printf("DosMailslotInfo returned %u \n", uReturnCode); if (uReturnCode == NERR_Success) { printf(" Message buffer size : %hu \n", cbMessageSize); printf(" Mailslot size : %hu \n", cbMailslotSize); printf(" Size of next message: %hu \n", cbNextSize); if (cbNextSize) printf(" Priority of next msg: %hu\n", usNextPriority); printf(" Number of messages : %hu \n", cMessages); } //======================================================================== // DosPeekMailslot // // This API reads the most current message without removing it. //======================================================================== /* * Allocate a data buffer large enough for the next message. * Use the default buffer size, just in case a message of higher * priority is received between the DosMailslotInfo call and * the DosPeekMailslot call. */ cbBuffer = cbMessageSize; // Default buffer size pbBuffer = SafeMalloc(cbBuffer); uReturnCode = DosPeekMailslot( hMailslot, // Handle to mailslot pbBuffer, // Buffer for returned message &cbReturned, // Size of returned message &cbNextSize, // Size of next message &usNextPriority); // Priority of next message printf("DosPeekMailslot returned %u \n", uReturnCode); if (uReturnCode == NERR_Success) { printf(" Message received : \"%s\" \n", pbBuffer); printf(" Size of message read: %hu bytes\n", cbReturned); printf(" Size of next message: %hu bytes\n", cbNextSize); if (cbNextSize) printf(" Priority of next msg: %hu\n", usNextPriority); } //======================================================================== // DosReadMailslot // // Read and delete the most current message. //======================================================================== uReturnCode = DosReadMailslot( hMailslot, // Handle to mailslot pbBuffer, // Buffer for returned message &cbReturned, // Size of returned message &cbNextSize, // Size of next message &usNextPriority, // Priority of next message 0L); // Time-out value; don't wait printf("DosReadMailslot returned %u \n", uReturnCode); if (uReturnCode == NERR_Success) { printf(" Message received : \"%s\" \n", pbBuffer); printf(" Size of message read: %hu bytes\n", cbReturned); printf(" Size of next message: %hu bytes\n", cbNextSize); if (cbNextSize) printf(" Priority of next msg: %hu\n", usNextPriority); } free (pbBuffer); //======================================================================== // DosDeleteMailslot // // This API deletes the created mailslot. //======================================================================== uReturnCode = DosDeleteMailslot(hMailslot); printf("DosDeleteMailslot of \"%s\" returned %u \n", pszMailslot, uReturnCode); exit(0); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s [-m mailslot] [-s size] [-t text] " "[-c class]\n\t\t[-p priority] [-i iterations]\n", pszProgram); exit(1); } Message Category Message API functions send and receive messages, and manipulate message aliases. All Message API functions require that the local computer be running the Workstation service. All Message functions except NetMessageBufferSend and NetMessageFileSend require that the computer where the function is to be executed be running the Messenger service. NetMessageBufferSend and NetMessageFileSend require only the Messenger service to be running on the computer that receives the message. The Message category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and MESSAGE.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETMESSAGE, and including the master header file, LAN.H. For more information, see the "Example" section, later in this category. These are the Message API functions: ■ NetMessageBufferSend ■ NetMessageFileSend ■ NetMessageLogFileGet ■ NetMessageLogFileSet ■ NetMessageNameAdd ■ NetMessageNameDel ■ NetMessageNameEnum ■ NetMessageNameFwd ■ NetMessageNameGetInfo ■ NetMessageNameUnFwd Description A message is any file or buffer of data sent to a user or application on the network. To receive a message, a user or application must register a message alias in a computer's table of message names. This can be done by using NetMessageNameAdd. A message name table contains a list of registered message aliases (users and applications) permitted to receive messages and a list of aliases to which a message can be forwarded. The aliases registered in the message name table are case sensitive. An alias added using the LAN Manager command-line or full-screen interface is added in uppercase. If an alias is added using NetMessageNameAdd, the case is unaltered. To send a message, the alias specified must match exactly the alias that is registered. NetMessageNameDel deletes a specific message alias from the message name table. NetMessageNameEnum lists all the aliases stored in the message name table. NetMessageNameGetInfo retrieves information about a particular message alias in the message name table. To send a message, an application can call either NetMessageFileSend or NetMessageBufferSend. NetMessageFileSend sends a file; NetMessageBufferSend sends a buffer of information. Applications can also send broadcast messages to all users in a domain or to all computers on a network by using NetMessageFileSend or NetMessageBufferSend. All messages sent to an alias on a particular computer can be forwarded to another alias on a different computer by using NetMessageNameFwd. Forwarded messages can be received only by the forwarded alias. They are not received by the alias that forwards them. NetMessageNameUnFwd ends message forwarding for a specified alias. Users can receive messages in one of two ways (or both at the same time): ■ The message is logged in a message log. ■ The message is displayed in a popup. To receive a popup message, the Netpopup service must be installed. NetMessageLogFileSet enables or disables message logging and specifies the name of the message log file. If message logging is enabled, all messages received are logged. The log file is in ASCII format. NetMessageLogFileGet returns the name of the message log file for a workstation or server and specifies whether or not message logging is enabled. The default message log file is LANMAN\LOGS\MESSAGES.LOG. The LANMAN directory is set during installation; the default is C:\LANMAN. The message log file contains messages in the following format: ■ A header specifying who sent the message, who received the message, and the time and date the message was received ■ A blank line ■ The contents of the message ■ A blank line ■ A line containing four asterisks (****) ■ A blank line The following example shows the contents of a message log file containing two messages: Message from JOHN to BRUCE on October 01, 1990, 14:05:20 Hello, this is a BUFFER test message. **** Message from BRUCE to JOHN on October 01, 1990, 14:11:48 Hello, this is a FILE test message. **** ──────────────────────────────────────────────────────────────────────────── NOTE A process must open the message log in read-only/deny-none mode; otherwise, the Messenger service fails when trying to log incoming messages. ──────────────────────────────────────────────────────────────────────────── MS-DOS Considerations By default, LAN Manager for MS-DOS accepts only two names, the name of the workstation and the name of the user in the message name table. To define more names, change the value of the nummsgnames entry in the [messenger] section of the LANMAN.INI file. MS OS/2 LAN Manager accepts up to 14 aliases in the message name table, although this may be limited to a smaller value by the network hardware being used. Data Structures NetMessageNameEnum and NetMessageNameGetInfo use the msg_info_X data structure, where X is 0 or 1, depending on the level of detail requested. Message Information (level 0) The msg_info_0 data structure has this format: struct msg_info_0 { char msgi0_name[CNLEN+1]; }; where msgi0_name Contains an ASCIIZ string that specifies the alias to which the message is to be sent. The constant CNLEN is defined in the NETCONS.H header file. Message Information (level 1) The msg_info_1 data structure has this format: struct msg_info_1 { char msgi1_name[CNLEN+1]; unsigned char msgi1_forward_flag; unsigned char msgi1_pad1; char msgi1_forward[CNLEN+1]; }; where msgi1_name Contains an ASCIIZ string that specifies the alias to which the message is to be sent. The constant CNLEN is defined in the NETCONS.H header file. msgi1_forward_flag Specifies whether to send messages to a message alias on the local computer or to forward them to a message alias on a remote computer. The MESSAGE.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── MSGNAME_NOT_FORWARDED 0x00 Name is not forwarded. MSGNAME_FORWARDED_TO 0x04 Name is forwarded to a remote computer. MSGNAME_FORWARDED_FROM 0x10 Name is forwarded from a remote computer. ──────────────────────────────────────────────────────────────────────────── msgi1_pad1 Aligns the next data structure element on a word boundary. msgi1_forward Contains an ASCIIZ string that specifies the alias to which the message will be sent if forwarding is enabled. The constant CNLEN is defined in the NETCONS.H header file. See Also For information about See ──────────────────────────────────────────────────────────────────────────── LANMAN.INI file LAN Manager administrator's manual(s) Starting services, the Messenger Appendix C, "Creating LAN Manager service Services" NetMessageBufferSend ──────────────────────────────────────────────────────────────────────────── NetMessageBufferSend sends a buffer of information to a registered message alias. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level Admin privilege or accounts, comm, print, or server operator privilege is required to successfully execute NetMessageBufferSend on a remote server. Syntax #define INCL_NETMESSAGE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetMessageBufferSend (const char far * pszServer, char far * pszRecipient, char far * pbBuffer, unsigned short cbBuffer ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetMessageBufferSend. A null pointer or null string specifies the local computer. pszRecipient Points to an ASCIIZ string that contains the registered message alias to receive the message buffer. To broadcast a message to all workstations on the network, pszRecipient should point to an asterisk (*). To broadcast to all members of a domain, pszRecipient should point to the domain name, which should be terminated with an asterisk. pbBuffer Points to the message buffer to be sent. cbBuffer Specifies the size (in bytes) of the message contained in the buffer pointed to by pbBuffer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_REM_NOT_LIST 51 The remote computer is not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_REM_NOT_LIST 51 The remote computer is not listening. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_NoNetworkResource 2105 The network hardware could not access the resources it needed. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BrowserNotStarted 2139 The mailslots entry of the Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BrowserNotStarted 2139 The mailslots entry of the workstation's LANMAN.INI file is incorrect. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_NoComputerName 2270 A computername has not been configured. NERR_NameNotFound 2273 The message alias cannot be located. NERR_PausedRemote 2281 The message was sent, but the recipient has paused the Messenger service, so the message cannot be received. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BadReceive 2282 The remote workstation was unable to receive the message. The Workstation or Messenger service may not be running on that workstation, it may have been receiving another message when this message arrived, or its message buffer may be too small. NERR_NotLocalName 2285 The message alias is not on the local computer. NERR_TruncatedBroadcast 2289 The broadcast message is too long. Only the first 128 characters of the message were sent. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks Broadcast messages (pszRecipient points to * or domainname*) can have as many as 128 bytes; delivery is not guaranteed. Other messages can have as many as 62K, provided they do not exceed the maximum receivable message size for the computer that receives them. The maximum receivable size is set by the sizmessbuf entry in the [messenger] section of the LANMAN.INI file. The sizmessbuf entry cannot define a value larger than 62K. (The default value is 4K on a computer with MS OS/2, and 256 bytes on an MS-DOS workstation.) The total size of sizmessbuf can be divided among different messages if messages arrive at the same time, reducing the actual size of any one message that can be received. For more information about the LANMAN.INI file, see your LAN Manager administrator's manual(s). NetMessageBufferSend requires that the Messenger service be started on the computer where the message is to be received, but it need not be started on the computer that sends the message. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Adding a message alias NetMessageNameAdd Messenger service Appendix C, "Creating LAN Manager Services" Sending a message file NetMessageFileSend Setting the LANMAN.INI LAN Manager administrator's manual(s) sizmessbuf entry for a server NetMessageFileSend ──────────────────────────────────────────────────────────────────────────── NetMessageFileSend sends a file to a registered message alias. It is recommended that you not use NetMessageFileSend because it is unlikely to be supported in future releases of LAN Manager. NetMessageBufferSend can be used as an alternative. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level Admin privilege or accounts, comm, print, or server operator privilege is required to successfully execute NetMessageFileSend on a remote server. Syntax #define INCL_NETMESSAGE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetMessageFileSend (const char far * pszServer, char far * pszRecipient, char far * pszFileSpec ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetMessageFileSend. A null pointer or null string specifies the local computer. pszRecipient Points to an ASCIIZ string that contains the registered message alias to receive the message file. To broadcast a message to all workstations on the network, pszRecipient should point to an asterisk (*). To broadcast to all members of a domain, this parameter should point to the domain name, which should be terminated with an asterisk. pszFileSpec Points to an ASCIIZ string that contains the pathname of the file to send. This pathname must be specified relative to the computer specified by pszServer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_FILE_NOT_FOUND 2 The file was not found. ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_REM_NOT_LIST 51 The remote computer is not listening. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_OPEN_FAILED 110 An open or write operation Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_OPEN_FAILED 110 An open or write operation failed. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_NoNetworkResource 2105 The network hardware could not access the resources it needed. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BrowserNotStarted 2139 The mailslots entry of the workstation's LANMAN.INI file is incorrect. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── shared. NERR_NoComputerName 2270 A computername has not been configured. NERR_NameNotFound 2273 The message alias cannot be located. NERR_PausedRemote 2281 The message was sent, but the recipient has paused the Messenger service, so the message cannot be received. NERR_BadReceive 2282 The remote workstation was unable to receive the message. The Workstation or Messenger service may not be running on that workstation, it may have been receiving another message Code Value Meaning ──────────────────────────────────────────────────────────────────────────── been receiving another message when this message arrived, or its message buffer may be too small. NERR_NotLocalName 2285 The message alias is not on the local computer. NERR_TruncatedBroadcast 2289 The broadcast message is too long. Only the first 128 characters of the message were sent. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks Broadcast messages (pszRecipient points to * or domainname*) can have as many as 128 bytes; delivery is not guaranteed. Other messages can have as many as 62K, provided they do not exceed the maximum receivable message size for the computer that receives them. The maximum receivable size is set with the sizmessbuf entry in the [messenger] section of the LANMAN.INI file. The sizmessbuf entry cannot define a value larger than 62K. (The default value is 4K on a computer with MS OS/2, and 256 bytes on an MS-DOS workstation.) The total size of sizmessbuf can be divided among different messages if messages arrive at the same time, reducing the actual size of any one message that can be received. For more information about the LANMAN.INI file, see your Microsoft LAN Manager administrator's manual(s). NetMessageFileSend requires that the Messenger service be started on the computer where the message is to be received, but it need not be started on the computer that sends the message. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Adding a message alias NetMessageNameAdd Messenger service Appendix C, "Creating LAN Manager Services" Sending a buffer of information NetMessageBufferSend Setting the LANMAN.INI LAN Manager administrator's manual(s) sizmessbuf entry for a server NetMessageLogFileGet ──────────────────────────────────────────────────────────────────────────── NetMessageLogFileGet retrieves the name of the message log and the current logging status (on or off). NetMessageLogFileGet requires that the Messenger service be started. It is recommended that you not use NetMessageLogFileGet because it is unlikely to be supported in future releases of LAN Manager. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level Admin privilege is required to successfully execute NetMessageLogFileGet on a remote server. Syntax #define INCL_NETMESSAGE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetMessageLogFileGet (const char far * pszServer, char far * pbBuffer, unsigned short cbBuffer, short far * pfsEnabled ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetMessageLogFileGet. A null pointer or null string specifies the local computer. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains the pathname of the message log file. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pfsEnabled Points to a short integer in which the status of message logging is returned. If pfsEnabled is 1, message logging is enabled. If it is 0, message logging is not enabled. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BrowserNotStarted 2139 The mailslots entry of the workstation's LANMAN.INI file is incorrect. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_MsgNotStarted 2284 The Messenger service has not been started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Messenger service Appendix C, "Creating LAN Manager Services" Modifying the name and status of NetMessageLogFileSet the message log NetMessageLogFileSet ──────────────────────────────────────────────────────────────────────────── NetMessageLogFileSet specifies the name of a file in which to log messages received by registered message aliases, and enables or disables logging. NetMessageLogFileSet requires that the Messenger service be started. It is recommended that you not use NetMessageLogFileSet because it is unlikely to be supported in future releases of LAN Manager. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level Admin privilege is required to successfully execute NetMessageLogFileSet on a remote server. Syntax #define INCL_NETMESSAGE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetMessageLogFileSet (const char far * pszServer, char far * pszFileSpec, short pfsEnabled ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetMessageLogFileSet. A null pointer or null string specifies the local computer. pszFileSpec Points to an ASCIIZ string that contains the pathname of the file or device (LPT: or COM:) where the messages are logged. If pszFileSpec is passed as a null pointer, the name of the current message log file does not change. If pszFileSpec points to a null string, no message file is used; in this case, pfsEnabled must be 0. If pszFileSpec points to a relative path, the path must be relative to the LAN Manager LOGS directory. All other pathnames must be fully qualified. If a filename extension is not provided, the file extension .LOG is appended. pfsEnabled Points to a short integer that specifies whether logging is enabled. If pfsEnabled is 0, message logging is disabled. If it is 1, message logging is enabled. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_NAME 123 The character or file system name is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RedirectedPath 2117 The operation is invalid for a redirected resource. The devicename specified is assigned to a shared resource. NERR_WkstaNotStarted 2138 The Workstation service is not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BrowserNotStarted 2139 The mailslots entry of the workstation's LANMAN.INI file is incorrect. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_MsgNotStarted 2284 The Messenger service has not been started. NERR_InvalidDevice 2294 The devicename is invalid. NERR_InvalidComputer 2351 The specified computername is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Messenger service Appendix C, "Creating LAN Manager Services" Retrieving the name and status NetMessageLogFileGet of the message log NetMessageNameAdd ──────────────────────────────────────────────────────────────────────────── NetMessageNameAdd registers a message alias in the message name table. NetMessageNameAdd requires that the Messenger service be started. It is recommended that you not use NetMessageNameAdd because it is unlikely to be supported in future releases of LAN Manager. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level Admin privilege is required to successfully execute NetMessageNameAdd on a remote server. Syntax #define INCL_NETMESSAGE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetMessageNameAdd (const char far * pszServer, const char far * pszMessageName, short fsFwdAction ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetMessageNameAdd. A null pointer or null string specifies the local computer. pszMessageName Points to an ASCIIZ string that contains a message alias to add to the message name table. The message alias can have as many as CNLEN+1 bytes, including the terminating NUL character. The constant CNLEN is defined in the NETCONS.H header file. fsFwdAction Specifies the action to take if the message alias pointed to by pszMessageName is already forwarded. If fsFwdAction is 0, an error is returned. If it is any other value, the name is added to the message name table. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_REM_NOT_LIST 51 The remote computer is not listening. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_NoNetworkResource 2105 The network hardware could not access the resources it needed. NERR_WkstaNotStarted 2138 The Workstation service is not started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── started. NERR_BrowserNotStarted 2139 The mailslots entry of the workstation's LANMAN.INI file is incorrect. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_AlreadyForwarded 2274 Messages for this alias are already being forwarded to another alias. NERR_AddForwarded 2275 Messages for this alias are being forwarded to another computer. NERR_AlreadyExists 2276 The message alias already exists Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_AlreadyExists 2276 The message alias already exists on this computer. NERR_TooManyNames 2277 The maximum number of message aliases has been exceeded. NERR_MsgNotStarted 2284 The Messenger service has not been started. NERR_DuplicateName 2297 The name specified is already in use as a message alias on the network. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Deleting a message alias NetMessageNameDel Forwarding messages NetMessageNameFwd Messenger service Appendix C, "Creating LAN Manager Services" NetMessageNameDel ──────────────────────────────────────────────────────────────────────────── NetMessageNameDel deletes a message alias from the table of message aliases on a computer. NetMessageNameDel requires that the Messenger service be started. It is recommended that you not use NetMessageNameDel because it is unlikely to be supported in future releases of LAN Manager. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level Admin privilege is required to successfully execute NetMessageNameDel on a remote server. Syntax #define INCL_NETMESSAGE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetMessageNameDel (const char far * pszServer, const char far * pszMessageName, short fsFwdAction ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetMessageNameDel. A null pointer or null string specifies the local computer. pszMessageName Points to an ASCIIZ string that contains the message alias to be removed. fsFwdAction Specifies what action to take if the messages for the message alias pointed to by pszMessageName are being forwarded to another message alias. If fsFwdAction is 0, an error is returned. If it is any other value, the message alias is deleted from the message name table. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_REM_NOT_LIST 51 The remote computer is not listening. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BrowserNotStarted 2139 The mailslots entry of the workstation's LANMAN.INI file is incorrect. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_NameNotFound 2273 The message alias cannot be Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NameNotFound 2273 The message alias cannot be located. NERR_DelComputerName 2278 A message alias that is also a computername cannot be deleted. NERR_NameInUse 2283 The message alias is currently in use. Try again later. NERR_MsgNotStarted 2284 The Messenger service has not been started. NERR_NotLocalName 2285 The message alias is not on the local computer. NERR_DeleteLater 2298 The message alias will be deleted later. NERR_IncompleteDel 2299 The message alias was not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_IncompleteDel 2299 The message alias was not successfully deleted from all networks. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Adding a message alias NetMessageNameAdd Listing all message aliases NetMessageNameEnum Messenger service Appendix C, "Creating LAN Manager Services" NetMessageNameEnum ──────────────────────────────────────────────────────────────────────────── NetMessageNameEnum lists the message aliases that will receive messages on a specified computer. NetMessageNameEnum requires that the Messenger service be started. It is recommended that you not use NetMessageNameEnum because it is unlikely to be supported in future releases of LAN Manager. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level Admin privilege is required to successfully execute NetMessageNameEnum on a remote server. Syntax #define INCL_NETMESSAGE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetMessageNameEnum (const char far * pszServer, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetMessageNameEnum. A null pointer or null string specifies the local computer. sLevel Specifies the level of detail (0 or 1) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a sequence of msg_info_X data structures, where X is 0 or 1, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer in which a count of the message aliases enumerated in the buffer is returned. This count is valid only if NetMessageNameEnum returns NERR_Success or ERROR_MORE_DATA. pcTotalAvail Points to an unsigned short integer in which a count of the total number of message aliases is returned. This count is valid only if NetMessageNameEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BrowserNotStarted 2139 The mailslots entry of the Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BrowserNotStarted 2139 The mailslots entry of the workstation's LANMAN.INI file is incorrect. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_MsgNotStarted 2284 The Messenger service has not been started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Adding a message alias NetMessageNameAdd Deleting a message alias NetMessageNameDel Messenger service Appendix C, "Creating LAN Manager Services" Retrieving information about a NetMessageNameGetInfo particular message alias NetMessageNameFwd ──────────────────────────────────────────────────────────────────────────── NetMessageNameFwd modifies the message name table to forward messages addressed to one alias on to another alias. The original recipient of the message does not receive the message. NetMessageNameFwd requires that the Messenger service be started. It is recommended that you not use NetMessageNameFwd because it is unlikely to be supported in future releases of LAN Manager. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, remote only Privilege Level Admin privilege is required to successfully execute NetMessageNameFwd on a remote server. Syntax #define INCL_NETMESSAGE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetMessageNameFwd (const char far * pszServer, const char far * pszMessageName, const char far * pszForwardName, short fsDelFwdName ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetMessageNameFwd. A null pointer or null string specifies the local computer. pszMessageName Points to an ASCIIZ string that contains the alias to which the messages are originally sent. pszForwardName Points to an ASCIIZ string that contains the alias to which messages are forwarded. The message aliases can have as many as CNLEN+1 bytes, including the terminating NUL character. The constant CNLEN is defined in the NETCONS.H header file. fsDelFwdName Specifies the action to take if the alias pointed to by pszMessageName already forwards messages to another alias. If fsDelFwdName is 0, an error is returned. If it is any other value, any previous forwarded alias is deleted. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_REM_NOT_LIST 51 The remote computer is not listening. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_NoNetworkResource 2105 The network hardware could not access the resources it needed. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BrowserNotStarted 2139 The mailslots entry of the workstation's LANMAN.INI file is incorrect. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_NameNotFound 2273 The message alias cannot be located. NERR_AlreadyForwarded 2274 Messages for this alias are Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_AlreadyForwarded 2274 Messages for this alias are already being forwarded to another alias. NERR_AlreadyExists 2276 The message alias already exists on this computer. NERR_TooManyNames 2277 The maximum number of message aliases has been exceeded. NERR_LocalForward 2279 Messages cannot be forwarded back to the same workstation. NERR_NameInUse 2283 The message alias is currently in use. Try again later. NERR_MsgNotStarted 2284 The Messenger service has not been started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NotLocalName 2285 The message alias is not on the local computer. NERR_RemoteFull 2287 The message alias table on the remote workstation is full. NERR_DuplicateName 2297 The name specified is already in use as a message alias on the network. NERR_DeleteLater 2298 The message alias will be deleted later. NERR_MultipleNets 2300 This operation is not supported on a computer that is on multiple networks. NERR_InvalidComputer 2351 The specified computername is Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing all message aliases NetMessageNameEnum Messenger service Appendix C, "Creating LAN Manager Services" Setting the LANMAN.INI LAN Manager administrator's manual(s) sizmessbuf entry for a server Stopping the forwarding of NetMessageNameUnFwd messages NetMessageNameGetInfo ──────────────────────────────────────────────────────────────────────────── NetMessageNameGetInfo retrieves information about a particular message alias in the message name table. NetMessageNameGetInfo requires that the Messenger service be started. It is recommended that you not use NetMessageNameGetInfo because it is unlikely to be supported in future releases of LAN Manager. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level Admin privilege is required to successfully execute NetMessageNameGetInfo on a remote server. Syntax #define INCL_NETMESSAGE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetMessageNameGetInfo (const char far * pszServer, const char far * pszMessageName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetMessageNameGetInfo. A null pointer or null string specifies the local computer. pszMessageName Points to an ASCIIZ string that contains the message alias of interest. sLevel Specifies the level of detail (0 or 1) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a msg_info_X data structure, where X is 0 or 1, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcbTotalAvail Points to an unsigned short integer in which a count of the total number of bytes of information available is returned. This count is valid only if NetMessageNameGetInfo returns NERR_Success or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BrowserNotStarted 2139 The mailslots entry of the workstation's LANMAN.INI file is incorrect. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── incorrect. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_MsgNotStarted 2284 The Messenger service has not been started. NERR_NotLocalName 2285 The message alias is not on the local computer. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing all message aliases NetMessageNameEnum Messenger Service Appendix C, "Creating LAN Manager Services" NetMessageNameUnFwd ──────────────────────────────────────────────────────────────────────────── NetMessageNameUnFwd stops the forwarding of messages from one message alias to another. NetMessageNameUnFwd requires that the Messenger service be started. It is recommended that you not use NetMessageNameUnFwd because it is unlikely to be supported in future releases of LAN Manager. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, remote only Privilege Level Admin privilege is required to successfully execute NetMessageNameUnFwd on a remote server. Syntax #define INCL_NETMESSAGE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetMessageNameUnFwd (const char far * pszServer, const char far * pszMessageName ); where pszServer Points to an ASCIIZ string that contains the name of a server on which to execute NetMessageNameUnFwd. A null pointer or null string specifies the local computer. pszMessageName Points to an ASCIIZ string that contains the alias whose message forwarding is to be canceled. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_REM_NOT_LIST 51 The remote computer is not listening. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BrowserNotStarted 2139 The mailslots entry of the workstation's LANMAN.INI file is incorrect. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_NameNotFound 2273 The message alias cannot be located. NERR_NameInUse 2283 The message alias is currently in use. Try again later. NERR_MsgNotStarted 2284 The Messenger service has not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_MsgNotStarted 2284 The Messenger service has not been started. NERR_NotLocalName 2285 The message alias is not on the local computer. NERR_NameNotForwarded 2288 Messages for this alias are not being forwarded. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Forwarding messages to another NetMessageNameFwd alias Messenger service Appendix C, "Creating LAN Manager Services" Message Category Example /* NETMSG.C -- a sample program demonstrating NetMessageBufferSend. This program requires that the Messenger service be running on the specified server, and that you have admin privileges or accounts, server, print, or comm operator privilege on that server. usage: netmsg [-s \\server] [-r recipient] [-m message] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). recipient = Name of the message recipient. message = Message to be sent. Note: When supplying a username as the name of the recipient, the name is case-sensitive. If the name has been added from the command line or from the full-screen interface, it will be uppercase. If the name has been added using NetMessageNameAdd, the case will be unaltered. API Used to... ==================== ========================================== NetMessageBufferSend Send a buffer (message) of information to a registered message alias This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETERRORS #define INCL_NETMESSAGE #define INCL_NETWKSTA #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include "samples.h" // Internal routine header file #define DEFAULT_MESSAGE "Hi there!" #define TRUE 1 #define FALSE 0 void Usage (char * pszProgram); void main(int argc, char * argv[]) { char * pszServer = NULL; // NULL means local machine char * pszRecipient; // Message recipient char * pszMessage = DEFAULT_MESSAGE; // Message to send char * pbBuffer; // Data buffer char achDomain[DNLEN + 1]; // Domain, allow for * at end int iCount; // Index counter short fRecipient = FALSE; // Flag if recipient specified unsigned short cbAvail; // Count of bytes available struct wksta_info_10 * pWksta10; // Pointer to workstation info API_RET_TYPE uReturnCode; // API return code for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iCount]; break; case 'r': // -r recipient pszRecipient = argv[++iCount]; fRecipient = TRUE; break; case 'm': // -m message pszMessage = argv[++iCount]; break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } // NetMessageBufferSend // // This API sends a message to another user/computer. If no message // recipient is specified, this example calls NetWkstaGetInfo to determine // the primary domain for the workstation, then sends a broadcast message // to all computers in that domain. First, NetWkstaGetInfo is called // with a NULL buffer to determine the amount of data available, then // NetWkstaGetInfo is called again with the returned buffer size. if (fRecipient == FALSE) { uReturnCode = NetWkstaGetInfo( pszServer, // Servername 10, // Level of detail NULL, // Data buffer 0, // Size of buffer &cbAvail); // Count of bytes available if (uReturnCode != NERR_BufTooSmall) { printf("NetWkstaGetInfo for \"%s\" failed with %u\n", pszServer, uReturnCode); exit(1); } // Allocate a data buffer large enough for workstation information. pbBuffer = SafeMalloc(cbAvail); uReturnCode = NetWkstaGetInfo( pszServer, // Servername 10, // Level of detail pbBuffer, // Data buffer cbAvail, // Size of buffer &cbAvail); // Count of bytes available if (uReturnCode != NERR_Success) { printf("NetWkstaGetInfo for \"%s\" failed with %u\n", pszServer, uReturnCode); exit(1); } // Add * to domain name so that the message is broadcast. pWksta10 = (struct wksta_info_10 *) pbBuffer; FarStrcpy((char far *)achDomain, pWksta10->wki10_logon_domain); strcat(achDomain, "*"); pszRecipient = achDomain; } uReturnCode = NetMessageBufferSend( pszServer, // Servername pszRecipient, // Message recipient pszMessage, // Message to send strlen(pszMessage)); // Length of message printf("NetMessageBufferSend returned %u\n", uReturnCode); printf(" Sending message to \"%s\"\n", pszRecipient); exit(0); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s [-s \\\\server] [-r recipient]" " [-m message]\n", pszProgram); exit(1); } Print Destination Category Print Destination API functions control printers that receive spooled print jobs. When executed locally, Print Destination functions do not require that the NETWKSTA device driver be installed. When a servername is supplied, they require that the Workstation service be started. The Print Destination category functions, datatypes, structures, and constants are defined in the PMSPL.H header file. A source program can access error codes by defining the constant INCL_NETERRORS and including the LAN.H header file. For an example, see the "Example" section, later in this category. These are the Print Destination API functions: ■ DosPrintDestAdd ■ DosPrintDestControl ■ DosPrintDestDel ■ DosPrintDestEnum ■ DosPrintDestGetInfo ■ DosPrintDestSetInfo Description A print destination is a print device that can be associated with a printer queue. Print jobs submitted to a printer queue are directed to the print destination for the queue. A print destination can be physically connected to the computer, or it can be a redirected device that is physically connected to another computer. The Print Destination API functions allow operations on these printers and on the job they are currently printing. DosPrintDestAdd establishes a print destination on the specified computer. DosPrintDestDel deletes a print destination from the specified computer. DosPrintDestControl pauses or continues the print destination. If a job is currently printing, this function also affects that job. DosPrintDestEnum lists all print destinations on a computer. DosPrintDestGetInfo provides information about a particular print destination. DosPrintDestSetInfo can change the parameter values for a print destination. The Print Destination data structures and the Print Destination API functions use MS OS/2 conventions for names and type definitions. The OS2DEF.H header file defines these types: ╓┌─────────────────────────────────┌─────────────────────────────────────────╖ MS OS/2 Type Definition C-Language Type ──────────────────────────────────────────────────────────────────────────── CHAR char PBYTE unsigned char far * PSZ unsigned char far * PUSHORT unsigned short * SPLENTRY pascal far SPLERR unsigned USHORT unsigned short ──────────────────────────────────────────────────────────────────────────── Data Structures Level 0 and level 1 data structures are provided for compatibility with existing LAN Manager 1.0 applications. LAN Manager 2.0 applications should use level 2 and level 3 data structures. One of the important enhancements of LAN Manager 2.0 is the ability to treat a print destination as a virtual device, independent of a printer queue or a specific logical address. To illustrate this change, consider the definition of print destination names. The LAN Manager 1.0-compatible names must be names of logical addresses, such as LPT1, LPT2, or COM1. The new level 2 and level 3 data structures allow the use of more general names for print destinations. The API functions also demonstrate this enhancement. DosPrintDestGetInfo and DosPrintDestEnum return level 0 and level 1 data only if print destinations are associated with a printer queue. At level 2 and level 3, these functions return data for all print destinations. Existing LAN Manager 1.0 applications (that use the level 0 and level 1 Print Destination data structures) can be compiled and linked using the 1.0 header file NETSPOOL.H and the 1.0-compatible libraries NETSPOOL.LIB and NETSPOOL.DLL. Applications designed to run with both MS OS/2 1.1 and MS OS/2 1.2 should use the new level 0 and level 1 data structure names, include the PMSPL.H header file, and link with the NETSPOOL libraries. Applications designed to run only with MS OS/2 1.2 should use the PMSPL.LIB and PMSPL.DLL libraries. The PMSPL libraries provide faster performance than the corresponding functions in the NETSPOOL library. Applications that run only with MS OS/2 1.2 can be built from existing applications by changing the data structure and element names. The prdest_info data structure and element names can be changed to the corresponding PRDINFO data structure and element names. There is a one-to-one mapping from the prdest_info elements to the PRDINFO elements, as shown in the following table: ╓┌───────────────────────────────────┌───────────────────────────────────────╖ LAN Manager 1.0 LAN Manager 2.0 prdest_info Element PRDINFO Element ──────────────────────────────────────────────────────────────────────────── prdest_name szName prdest_username szUserName prdest_jobid uJobId prdest_status fsStatus prdest_status_string pszStatus prdest_time time ──────────────────────────────────────────────────────────────────────────── DosPrintDestAdd and DosPrintDestSetInfo accept the level 3 data structure PRDINFO3. DosPrintDestEnum and DosPrintDestGetInfo accept levels 0, 1, 2, and 3. These functions accept or return the logical address at level 0, the PRDINFO data structure at level 1, the printer name at level 2, and the PRDINFO3 data structure at level 3. New applications should use levels 2 and 3 only. DosPrintDestControl and DosPrintDestDel do not use these data structures. The required data is defined within the API function definition. Print Destination Name (level 0) At level 0, data is returned in this format: CHAR szName[PDLEN+1]; where szName Specifies an ASCIIZ string that contains the name of a print destination. The constant PDLEN is defined in the PMSPL.H header file. Print Destination Information (level 1) The PRDINFO data structure has this format: typedef struct _PRDINFO { CHAR szName[PDLEN+1]; CHAR szUserName[UNLEN+1]; USHORT uJobId; USHORT fsStatus; PSZ pszStatus; USHORT time; } PRDINFO; where szName Specifies an ASCIIZ string that contains the name of the print destination. The constant PDLEN is defined in the PMSPL.H header file. szUserName Specifies an ASCIIZ string that contains the name of the user who submitted a print job. This component is valid only during printing. A null string indicates that the job was submitted from the local computer. The constant UNLEN is defined in the PMSPL.H header file. uJobId Contains an unsigned short integer that specifies the identification number of the current print job. If no job is printing, uJobId is 0. fsStatus Contains a short integer that specifies the status of the print destination. The bits of fsStatus are defined in PMSPL.H. Bits 0-1 have the code PRD_STATUS_MASK and the value 0x0003. This bit mask isolates the print destination status, as follows: Bits Code Value Meaning ──────────────────────────────────────────────────────────────────────────── 0-1 PRD_ACTIVE 0 The print job is processing. 0-1 PRD_PAUSED 1 The print job is paused. ──────────────────────────────────────────────────────────────────────────── Bits 2-11 indicate the print job and print destination status. Bits 2-11 can be isolated using the constants PRJ_DEVSTATUS and PRD_DEVSTATUS, which have the value 0x0FFC. Bit 15 signals whether an alert indicated that the print job was deleted. These are the meanings for individual bits: ╓┌────┌────────────────┌───────┌─────────────────────────────────────────────╖ Bit Code Value Meaning ──────────────────────────────────────────────────────────────────────────── 2 PRJ_COMPLETE 0x0004 If 1, the print job is complete. 3 PRJ_INTERV 0x0008 If 1, intervention is required. 4 PRJ_ERROR 0x0010 If 1, an error occurred (pszStatus can contain a comment explaining the error). 5 PRJ_DESTOFFLINE 0x0020 If 1, the print destination is offline. 6 PRJ_DESTPAUSED 0x0040 If 1, the print destination is paused. Bit Code Value Meaning ──────────────────────────────────────────────────────────────────────────── 7 PRJ_NOTIFY 0x0080 If 1, an alert is raised. 8 PRJ_DESTNOPAPER 0x0100 If 1, the print destination is out of paper. 9 PRJ_DESTFORMCHG 0x0200 If 1, the printer is waiting for a form change. 10 PRJ_DESTCRTCHG 0x0400 If 1, the printer is waiting for a cartridge change. 11 PRJ_DESTPENCHG 0x0800 If 1, the printer is waiting for a pen change. 15 PRJ_DELETED 0x8000 If 1, an alert indicates the print job was deleted. ──────────────────────────────────────────────────────────────────────────── Bit Code Value Meaning ──────────────────────────────────────────────────────────────────────────── pszStatus Points to an ASCIIZ string that contains a comment about the print destination error status, posted by the print destination's print processor. This element contains valid data only while the job is printing and an error occurs. time Contains an unsigned short integer that specifies the number of minutes the current job has been printing. This value is valid only while the job is printing. Print Destination Information (level 2) At level 2, the pszPrinterName element of the PRDINFO3 data structure is returned in this format: PSZ pszPrinterName; where pszPrinterName Points to an ASCIIZ string that specifies the name of a print destination. The name can contain blanks. The string can have as many as CCHMAXPATHCOMP bytes, as defined in the MS OS/2 header file BSEDOS.H. Print Destination Information (level 3) The PRDINFO3 data structure has this format: typedef struct _PRDINFO3 { PSZ pszPrinterName; PSZ pszUserName; PSZ pszLogAddr; USHORT uJobId; USHORT fsStatus; PSZ pszStatus; PSZ pszComment; PSZ pszDrivers; USHORT time; USHORT pad1; } PRDINFO3; where pszPrinterName Points to an ASCIIZ string that specifies the name of the printer. The name can contain blanks. The string can have as many as CCHMAXPATHCOMP bytes, as defined in the MS OS/2 header file BSEDOS.H. pszUserName Points to an ASCIIZ string that specifies the name of the user who submitted the currently active print job. This variable is valid only during printing. A null string or null pointer indicates the job was submitted from the local computer. pszLogAddr Points to an ASCIIZ string that specifies the name of the logical address where this printer prints, such as LPT1. If the printer is not connected to a logical address, pszLogAddr is a null pointer. uJobId Contains an unsigned short integer that specifies the identification number of a job currently being printed. If no job is printing, uJobId is 0. fsStatus Contains a short integer that specifies the status of the print destination. The bits of fsStatus are identical to the fsStatus element of the PRDINFO data structure. For a full description, see the preceding section. pszStatus Points to an ASCIIZ string that contains a comment about the print destination error status, posted by the print destination's print processor. This value is valid only while the job is printing and an error occurs. pszComment Points to an ASCIIZ string that contains a printer description. pszDrivers Points to an ASCIIZ string that contains a list of drivers that are supported by this printer (the drivernames are separated by commas). If the devicename contains blanks, the name should be enclosed in quotation marks (" "). Each driver can consist of a drivername and a devicename separated by a period (.) For example: IBM 4201, "PSCRIPT. Apple Laserwriter" indicates that this printer supports two drivers. time Contains an unsigned short integer that specifies the number of minutes the current job has been printing. This value is valid only during printing. pad1 Aligns the next data structure element on a word boundary. DosPrintDestAdd ──────────────────────────────────────────────────────────────────────────── DosPrintDestAdd adds a print destination to the specified computer. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote and levels 0 and 1 only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintDestAdd on a remote server or on a computer that has local security enabled. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintDestAdd (PSZ pszServer, USHORT uLevel, PBYTE pbBuf, USHORT cbBuf ); where pszServer Points to an ASCIIZ string that contains the name of a server on which to execute DosPrintDestAdd. A null pointer or null string specifies the local computer. uLevel Specifies the level of detail requested; must be 3. pbBuf Points to the buffer in which to store the returned data. On a successful return, the buffer contains records of the PRDINFO3 data structure. cbBuf Specifies the size (in bytes) of the buffer pointed to by pbBuf. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_REQ_NOT_ACCEP 71 The network request cannot be accepted at this time. There may be a lack of resources on the specified server or the local workstation. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_DestExists 2153 The print destination already exists. NERR_DestNoRoom 2157 The server does not have enough memory available to add another printer. NERR_SpoolerNotLoaded 2161 The spooler is not started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_DestInvalidState 2162 This operation cannot be performed on the print destination in its current state. NERR_SpoolNoMemory 2165 A spooler memory allocation failure occurred. NERR_DriverNotFound 2166 The device driver specified has not been installed on the computer. NERR_BadDev 2341 The devicename is invalid because it does not represent a physical device, or because the device hardware is faulty. NERR_InvalidComputer 2351 The specified computername is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── invalid. ──────────────────────────────────────────────────────────────────────────── Remarks DosPrintDestAdd creates a new print destination to the specified computer. The printer is set to print at the logical address specified by the pszLogAddr element of the PRDINFO3 data structure. If pszLogAddr is a null pointer or null string, the print destination is created but not connected to any logical address. This means that printing cannot occur on that printer or from any printer queue connected only to that printer. A print destination can be successfully added on an MS OS/2 1.2 workstation even if the workstation is not connected to a printer. All device drivers specified for the printer must be installed before calling DosPrintDestAdd. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Changing the connection between DosPrintDestSetInfo a printer and a port DosPrintDestControl ──────────────────────────────────────────────────────────────────────────── DosPrintDestControl pauses or continues printing on the specified print destination. If a job is currently printing on that destination, its status is changed along with that of the print destination. This function can also cancel or restart a job that is printing on the specified destination. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote and levels 0 and 1 only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintDestControl on a remote server or on a computer that has local security enabled. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintDestControl (PSZ pszServer, PSZ pszDestName, USHORT uControl ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintDestControl. A null pointer or null string specifies the local computer. pszDestName Points to an ASCIIZ string that contains the name of the print destination. uControl Contains an unsigned short integer that specifies the operation to be performed. The PMSPL.H header file defines these possible values: ╓┌────────────┌──────┌───────────────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── PRD_DELETE 0 Delete the current print job. PRD_PAUSE 1 Pause printing. PRD_CONT 2 Continue the paused print job. PRD_RESTART 3 Restart the print job. ─ 4-255 Reserved. ──────────────────────────────────────────────────────────────────────────── Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_DestNotFound 2152 The print destination was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── found. NERR_DestIdle 2158 The print destination is idle and cannot accept control operations. NERR_DestInvalidOp 2159 The print destination request contains an invalid control function. NERR_ProcNoRespond 2160 The print processor is not responding. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Remarks While paused, a print destination cannot accept new print jobs. To maintain compatibility with LAN Manager 1.0 applications, DosPrintDestControl uses logical addresses to refer to the destination printer. If the print destination is idle when the application attempts to restart or delete a print job (that is, the uControl parameter has the value PRD_DELETE or PRD_RESTART), DosPrintDestControl returns the error code NERR_DestIdle. These operations can succeed only if a job is printing. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing the print destinations DosPrintDestEnum on a computer Retrieving the status of the DosPrintJobGetInfo current print job spooled to a printer DosPrintDestDel ──────────────────────────────────────────────────────────────────────────── DosPrintDestDel deletes a print destination from a computer. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote and levels 0 and 1 only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintDestDel on a remote server or on a computer that has local security enabled. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintDestDel (PSZ pszServer, PSZ pszPrinterName ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintDestDel. A null pointer or null string specifies the local computer. pszPrinterName Points to the name of the printer to be deleted. The printer name should be a general name as defined in the level 2 and level 3 data structures, rather than a logical address as defined in the level 0 and level 1 data structures. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── shared. NERR_DestNotFound 2152 The print destination was not found. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_DestInvalidState 2162 This operation cannot be performed on the print destination in its current state. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks If the print destination is currently printing a job, DosPrintDestDel returns the error code NERR_DestInvalidState. DosPrintDestEnum ──────────────────────────────────────────────────────────────────────────── DosPrintDestEnum lists all print destinations on a computer and gives status information about the print destinations. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote and levels 0 and 1 only ■ MS-DOS, remote only Privilege Level No special privilege level is required to successfully execute DosPrintDestEnum. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintDestEnum (PSZ pszServer, USHORT uLevel, PBYTE pbBuf, USHORT cbBuf, PUSHORT pcReturned, PUSHORT pcTotal ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintDestEnum. A null pointer or null string specifies the local computer. uLevel Specifies the level of detail (0, 1, 2, or 3) requested. pbBuf Points to the buffer in which to store the returned data. On a successful return, the buffer contains a PRDINFOX data structure, where X is 0, 1, 2, or 3, depending on the level of detail requested. cbBuf Specifies the size (in bytes) of the buffer pointed to by pbBuf. pcReturned Points to an unsigned short integer that indicates the number of entries returned in the buffer pointed to by pbBuf. This count is valid only if DosPrintDestEnum returns NERR_Success or ERROR_MORE_DATA. pcTotal Points to an unsigned short integer that indicates how many entries were available. This count is valid only if DosPrintDestEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌──────────────────────┌───────┌────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_BAD_NETPATH 53 The network path was not found. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_DestNotFound 2152 The print destination was not found. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── Remarks At levels 0 and 1, DosPrintDestEnum returns print destination names only if they are associated with printer queues. At levels 2 and 3, DosPrintDestEnum returns all print destinations. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Pausing or continuing printing DosPrintDestControl on a particular print destination Retrieving the status of a DosPrintDestGetInfo particular print destination DosPrintDestGetInfo ──────────────────────────────────────────────────────────────────────────── DosPrintDestGetInfo retrieves information about a print destination on a computer. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote and levels 0 and 1 only ■ MS-DOS, remote only Privilege Level No special privilege level is required to successfully execute DosPrintDestGetInfo. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintDestGetInfo (PSZ pszServer, PSZ pszName, USHORT uLevel, PBYTE pbBuf, USHORT cbBuf, PUSHORT pcbNeeded ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintDestGetInfo. A null pointer or null string specifies the local computer. pszName Points to an ASCIIZ string that contains the name of the specific print destination. uLevel Specifies the level of detail (0, 1, 2, or 3) requested. The level parameter works in conjunction with pszName and pbBuf, as follows: uLevel pszName Data returned in pbBuf ──────────────────────────────────────────────────────────────────────────── 0 Logical address pszLogAddr element of PRDINFO3 data structure. 1 Logical address PRDINFO data structure. 2 Printer name Pointer to a printer name. 3 Printer name PRDINFO3 data structure. ──────────────────────────────────────────────────────────────────────────── pbBuf Points to the buffer in which to store the returned data. On a successful return, the buffer contains the data structure that corresponds to the uLevel and pszName parameters, as described in the preceding table. cbBuf Specifies the size (in bytes) of the buffer pointed to by pbBuf. pcbNeeded Points to an unsigned short integer that specifies the number of bytes of information available. This count is valid only if DosPrintDestGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌──────────────────────┌───────┌────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_RemoteOnly 2106 This operation can be performed only on a server. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_DestNotFound 2152 The print destination was not found. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks At levels 0 and 1, DosPrintDestGetInfo returns print destination names only if they are associated with printer queues. At levels 2 and 3, DosPrintDestGetInfo returns all print destinations. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing the print destinations DosPrintDestEnum on a computer Pausing or continuing printing DosPrintDestControl on a particular print destination DosPrintDestSetInfo ──────────────────────────────────────────────────────────────────────────── DosPrintDestSetInfo modifies the configuration of a print destination. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote and levels 0 and 1 only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintDestSetInfo on a remote server or on a computer that has local security enabled. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintDestSetInfo (PSZ pszServer, PSZ pszName, USHORT uLevel, PBYTE pbBuf, USHORT cbBuf, USHORT uParmNum ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintDestSetInfo. A null pointer or null string specifies the local computer. pszName Points to an ASCIIZ string that contains the name of the printer or parallel port. uLevel Specifies the level of detail; must be 3. pbBuf Points to the data to be set. cbBuf Specifies the size (in bytes) of the buffer pointed to by pbBuf. uParmNum Specifies whether to set one or all elements of the entire PRDINFO3 data structure. If uParmNum is PARMNUM_ALL, the entire structure is set, and pbBuf must point to a PRDINFO3 data structure. If uParmNum is any other defined value, only one element of the print destination information is changed, and pbBuf must point to a valid value for that element. Not all elements can be set. Only those that have a specific PARMNUM constant value defined can be set. The PMSPL.H and NETCONS.H header files define these possible values for sParmNum: Code Value Element of PRDINFO3 ──────────────────────────────────────────────────────────────────────────── PARMNUM_ALL 0 All elements. PRD_LOGADDR_PARMNUM 3 pszLogAddr PRD_COMMENT_PARMNUM 7 pszComment PRD_DRIVERS_PARMNUM 8 pszDrivers ──────────────────────────────────────────────────────────────────────────── Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_DestNotFound 2152 The print destination was not found. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_SpoolNoMemory 2165 A spooler memory allocation failure occurred. NERR_DriverNotFound 2166 The device driver specified has not been installed on the computer. NERR_BadDev 2341 The devicename is invalid because it does not represent a physical device, or because the device hardware is faulty. NERR_InvalidComputer 2351 The specified computername is Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks DosPrintDestSetInfocan be used to disconnect a printer from a port by supplying a null string for the pszLogAddrelement of the PRDINFO3data structure. Print Destination Category Example /* NETPRD.C -- a program demonstrating the DosPrintDest API functions. Admin or print operator privilege is required to successfully execute the Print Destination API functions on a remote server. This program calls DosPrintDestAdd to add a printer to the specified server, then manipulates that printer using DosPrintDestControl. DosPrintDestGetInfo displays status information about the printer. DosPrintDestSetInfo is called to disconnect the printer from the computer. DosPrintDestEnum lists all printers on the computer. DosPrintDestDel then deletes the print destination. usage: netprd [-s \\server] [-p printername] [-a address] [-l level] [-o operation] [-d driver] [-f flag] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). printername = Name of the printer. address = Logical address, such as LPT1. level = Level of detail. operation = Integer code for DosPrintDestControl. driver = Name of the print driver. flag = Flag whether to delete the printer (0 or 1). API Used to... =================== =============================================== DosPrintDestAdd Add a new print destination DosPrintDestControl Control the status of the printer DosPrintDestGetInfo Get specific information about a single printer DosPrintDestSetInfo Set specific information for a single printer DosPrintDestEnum List all printers available DosPrintDestDel Delete the print destination This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_BASE #include <os2.h> // MS OS/2 base header files #include <pmspl.h> // Print definitions #define INCL_NETERRORS #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include "samples.h" // Internal routine header file #define NEWPORTNAME "LPT1" #define NEWPRINTERNAME "PrntDestTest" #define NEWDRIVER "IBM4201" #define DEFAULT_BUF_SIZE 512 #define MAX_BUFFER_SIZE 65535 #define MAX_PDEST 10 // Limit for this program only void DisplayInfo(short sLevel, char *pbBuffer, unsigned short cEntries); void Usage(char *pszProgram); void main(int argc, char *argv[]) { char * pbBuffer; // Return data char * pszServer = ""; // Server; default to local computer char * szNull = ""; // Null string char far * pszPrinterName = NEWPRINTERNAME; char far * pszLogAddr = NEWPORTNAME; char far * pszDriver = NEWDRIVER; int iCount; // Index counter PRDINFO3 prd3; // Level 3 data structure short sLevel = 3; // Level of detail unsigned uRet; // Return code unsigned short fDone; // Flag successful call unsigned short fDelete = TRUE; // Delete flag unsigned short cEntriesRead; // Count of entries read unsigned short cTotal; // Count of entries available unsigned short cbBuffer = 0; // Count of bytes in data buffer unsigned short cbBufferNeeded = 0; // Bytes needed for GetInfo call unsigned short uControl = PRD_CONT; // DosPrintDestControl operation for (iCount = 1; iCount < argc; iCount++) // Get cmd-line switches { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iCount]; break; case 'l': // -l level sLevel = atoi(argv[++iCount]); break; case 'p': // -p printername pszPrinterName = argv[++iCount]; break; case 'd': // -d drivername pszDriver = argv[++iCount]; break; case 'f': // -f flag deletion fDelete = atoi(argv[++iCount]); break; case 'a': // -a address pszLogAddr = argv[++iCount]; break; case 'o': // -o operation uControl = atoi(argv[++iCount]); break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } printf("\nPrint Destination Category API Examples\n"); //======================================================================= // DosPrintDestAdd // // This API adds the specified printer to the specified server. //======================================================================= memset(&prd3, 0, sizeof(PRDINFO3)); // Initialize memory prd3.pszPrinterName = pszPrinterName; // Set names prd3.pszLogAddr = pszLogAddr; prd3.pszDrivers = pszDriver; uRet = DosPrintDestAdd(pszServer, // Servername 3, // Level; must be 3 (char far *)&prd3, // New printer struct sizeof(PRDINFO3)); // Size of buffer printf("DosPrintDestAdd returned %u\n", uRet); if (uRet == NERR_Success) { printf(" %Fs added to ", prd3.pszPrinterName); if ((pszServer == NULL) || (*pszServer == '\0')) printf("the local computer\n"); else printf(" %s\n", pszServer); printf(" Printer port set to %Fs\n", prd3.pszLogAddr); } //======================================================================= // DosPrintDestControl // // This API controls a printer destination. It can delete, pause, // continue, or restart the printer. If a job is printing at the // time the API is executed, that print job receives the new printer // status. The print destination name must be a logical address. //======================================================================= uRet = DosPrintDestControl(pszServer, // Computername pszLogAddr, // Print destination name uControl); // Operation printf("DosPrintDestControl returned %u\n", uRet); //======================================================================= // DosPrintDestGetInfo // // This API returns information about the specified print destination. //======================================================================= // Call with zero-length buffer, expect NERR_BufTooSmall. uRet = DosPrintDestGetInfo(pszServer, // Servername pszPrinterName, // Printername sLevel, // Call level NULL, // Data buffer 0, // Size of buffer &cbBufferNeeded); // Returns required size if (uRet == NERR_BufTooSmall) { cbBuffer = cbBufferNeeded; pbBuffer = SafeMalloc(cbBuffer); // SafeMalloc() is in SAMPLES.C uRet = DosPrintDestGetInfo(pszServer, // Servername pszPrinterName, // Printername sLevel, // Call level pbBuffer, // Data buffer cbBuffer, // Size of buffer &cbBufferNeeded); // Size required printf("DosPrintDestGetInfo returned %u\n", uRet); if (uRet == NERR_Success) DisplayInfo(sLevel, pbBuffer, 1); // Display buffer free(pbBuffer); } else printf("DosPrintDestGetInfo returned %u\n", uRet); //======================================================================= // DosPrintDestSetInfo // // This API allows control over print destination settings. // It must be called using level 3 (PRDINFO3). // // In this example, a single element is set to the desired value. // A program can also set all elements by setting the parameter number // code to PARMNUM_ALL. Setting the logical address to a null string // disconnects this printer from the computer. //======================================================================= uRet = DosPrintDestSetInfo(pszServer, // Servername pszPrinterName, // Printername 3, // Level; must be 3 (char far *)szNull, // Data sizeof(szNull), // Size of buffer PRD_LOGADDR_PARMNUM); // Parameter number code printf("DosPrintDestSetInfo returned %u", uRet); if (uRet) printf(": Disconnect failed"); printf("\n"); //======================================================================== // DosPrintDestEnum // // This API lists all printers connected to the specified server. // Allocate a buffer for the returned data. If the buffer is too small, // try again with a bigger buffer, and keep trying until the buffer // is large enough or until it cannot be made any larger. //======================================================================== cbBuffer = DEFAULT_BUF_SIZE; pbBuffer = SafeMalloc(cbBuffer); // SafeMalloc() is in SAMPLES.C do { uRet = DosPrintDestEnum (pszServer, // Servername sLevel, // Call level pbBuffer, // Buffer for info cbBuffer, // Size of buffer &cEntriesRead, // Count of entries read &cTotal); // Count of entries available if (uRet == ERROR_MORE_DATA) { free(pbBuffer); // Buffer too small if (cbBuffer == MAX_BUFFER_SIZE) { printf("Exceeded buffer size\n"); exit(1); } else if (cbBuffer > (MAX_BUFFER_SIZE/2)) cbBuffer = MAX_BUFFER_SIZE; else cbBuffer += cbBuffer; // Allocate larger buffer pbBuffer = SafeMalloc(cbBuffer); fDone = FALSE; } else fDone = TRUE; } while (fDone == FALSE); // Loop until buffer big enough or call fails printf("DosPrintDestEnum returned %u\n", uRet); printf(" Entries read = %hu out of %hu\n", cEntriesRead, cTotal); if (uRet == NERR_Success) DisplayInfo(sLevel, pbBuffer, cEntriesRead); free(pbBuffer); //======================================================================== // DosPrintDestDel // // This API deletes the print destination. //======================================================================== if (fDelete == TRUE) { uRet = DosPrintDestDel(pszServer, // Servername pszPrinterName); // Printername printf("DosPrintDestDel returned %u\n", uRet); } exit(0); } // End of main //======================================================================= // DisplayInfo // // Displays the print destination information obtained by // DosPrintDestGetInfo or DosPrintDestEnum. //======================================================================= void DisplayInfo(short sLevel, char *pbBuffer, unsigned short cEntries) { char * pprd0Info; // Level 0 data PPRDINFO pprd1Info; // Pointer to level 1 structure PSZ * pprd2Info; // Array of pointers PPRDINFO3 pprd3Info; // Pointer to level 3 structure unsigned short iCount; // Index counter pprd0Info = (char *) pbBuffer; pprd1Info = (PPRDINFO) pbBuffer; pprd2Info = (PSZ *) pbBuffer; pprd3Info = (PPRDINFO3) pbBuffer; for (iCount = 0; iCount < cEntries; iCount++) { switch (sLevel) { case 0: printf(" Printer Name: %s\n", pprd0Info); pprd0Info += (strlen(pprd0Info) + 1); break; case 1: printf(" Printer Name: %s\n", pprd1Info->szName); printf(" User Name : %s\n", pprd1Info->szUserName); printf(" Job Id : %hu\n", pprd1Info->uJobId); if (pprd1Info->uJobId) // Data valid only while job prints { printf(" Job Status : 0x%hx\n", pprd1Info->fsStatus); printf(" Status Text : %Fs\n", pprd1Info->pszStatus); printf(" Time : %hu\n", pprd1Info->time); } pprd1Info++; break; case 2: printf(" Printer Name: %Fs\n", *pprd2Info++); break; case 3: printf(" Printer Name: %Fs\n", pprd3Info->pszPrinterName); printf(" Logical Addr: %Fs\n", pprd3Info->pszLogAddr); printf(" Drivers : %Fs\n", pprd3Info->pszDrivers); printf(" Comment : %Fs\n", pprd3Info->pszComment); printf(" Job Id : %hu\n", pprd3Info->uJobId); if (pprd3Info->uJobId) { printf(" User Name : %Fs\n", pprd3Info->pszUserName); printf(" Job Status : 0x%hx\n", pprd3Info->fsStatus); printf(" Status Text : %Fs\n", pprd3Info->pszStatus); printf(" Print time : %hu\n", pprd3Info->time); } pprd3Info++; break; default: break; } // End switch sLevel } // End for loop } // End function //======================================================================= // Usage // // Display possible command-line switches for this sample program. //======================================================================= void Usage(char *pszProgram) { fprintf(stderr, "Usage: %s [-s \\\\server] [-l level]", pszProgram); fprintf(stderr, " [-d driver]\n\t[-p printer] [-f flag delete]"); fprintf(stderr, " [-a address] [-o operation]\n"); exit(1); } Print Job Category Print Job API functions control the print jobs in a printer queue. When executed locally, Print Job functions do not require that the NETWKSTA device driver be installed. When a servername is supplied, they require that the Workstation service be started. The Print Job category functions, datatypes, structures, and constants are defined in the PMSPL.H header file. A source program can access these definitions by including the PMSPL.H header file. A source program can access error codes by defining the constant INCL_NETERRORS and including the LAN.H header file. For more information, see the "Example" section, later in this category. These are the Print Job API functions: ■ DosPrintJobContinue ■ DosPrintJobDel ■ DosPrintJobEnum ■ DosPrintJobGetId ■ DosPrintJobGetInfo ■ DosPrintJobPause ■ DosPrintJobSetInfo Description A print job is a file submitted to a printer queue for printing. The Print Job API functions control individual jobs within printer queues, and can change the position of a print job in the queue, pause a print job, or delete it from the queue. DosPrintJobGetId returns the identification number of the spooling job. The print spooler assigns an identification number when the job is queued. DosPrintJobEnum lists the print jobs in a particular printer queue. DosPrintJobGetInfo retrieves information about a particular print job. DosPrintJobSetInfo sets parameters related to the print job, such as its priority. DosPrintJobPause pauses a print job. DosPrintJobContinue allows a paused print job to continue. DosPrintJobDel removes a print job from a printer queue. The Print Job data structures and the Print Job API functions use MS OS/2 conventions for names and type definitions. The OS2DEF.H header file defines these types: ╓┌─────────────────────────────────┌─────────────────────────────────────────╖ MS OS/2 Type Definition C-Language Type ──────────────────────────────────────────────────────────────────────────── CHAR char HFILE unsigned short PBYTE unsigned char far * PSZ unsigned char far * PUSHORT unsigned short * SPLENTRY pascal far SPLERR unsigned USHORT unsigned short ──────────────────────────────────────────────────────────────────────────── MS OS/2 Type Definition C-Language Type ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Data Structures Level 0 and level 1 data structures are provided for compatibility with existing LAN Manager 1.0 applications. LAN Manager 2.0 applications should use level 0, 2, and 3 data structures. Existing LAN Manager 1.0 applications (that use the level 0 and level 1 Print Job data structures) can be compiled and linked using the 1.0 header file NETSPOOL.H and the 1.0-compatible libraries NETSPOOL.LIB and NETSPOOL.DLL. Applications designed to run with both MS OS/2 1.1 and MS OS/2 1.2 should use the new level 0 and level 1 data structure names, include the PMSPL.H header file, and link with the NETSPOOL libraries. Applications that are designed to run only with MS OS/2 1.2 should use the PMSPL.LIB and PMSPL.DLL libraries. The PMSPL library functions provide better performance than the corresponding functions in the NETSPOOL library. Applications that run only with MS OS/2 1.2 can be built from existing applications. These applications can be upgraded by changing the data structure and element names. References to the prjob_info data structure and element names can be changed to the PRJINFO data structure and element names. There is one-to-one mapping from the prjob_info elements to the PRJINFO elements, as shown in the following table: ╓┌──────────────────────────────────┌────────────────────────────────────────╖ LAN Manager 1.0 LAN Manager 2.0 prjob_info Element PRJINFO Element ──────────────────────────────────────────────────────────────────────────── prjob_id uJobId prjob_username szUserName prjob_pad_1 pad_1 LAN Manager 1.0 LAN Manager 2.0 prjob_info Element PRJINFO Element ──────────────────────────────────────────────────────────────────────────── prjob_pad_1 pad_1 prjob_notifyname szNotifyName prjob_datatype szDataType prjob_parms pszParms prjob_position uPosition prjob_status fsStatus prjob_status_string pszStatus prjob_submitted ulSubmitted prjob_size ulSize LAN Manager 1.0 LAN Manager 2.0 prjob_info Element PRJINFO Element ──────────────────────────────────────────────────────────────────────────── prjob_comment pszComment ──────────────────────────────────────────────────────────────────────────── The new data structures are supported when they are directed to servers that run LAN Manager 1.0 software (down-level servers). New elements are given default values or values that indicate the element is not available, such as NULL. DosPrintJobSetInfo uses the level 1 data structure PRJINFO and the level 3 data structure PRJINFO3. DosPrintJobEnum uses levels 0, 1, and 2. DosPrintJobGetInfo uses levels 0, 1, 2, and 3. DosPrintJobGetId returns the PRIDINFO data structure. Print Job Identification Number (level 0) At level 0, data is returned in this format: USHORT uJobId; where uJobId Contains an unsigned short integer that specifies the identification number assigned to the print job when it was queued. The identification number is unique on a particular computer. A combination of the computername and uJobId is sufficient to uniquely identify a particular print job. Print Job Information (level 1) The PRJINFO data structure has this format: typedef struct _PRJINFO { USHORT uJobId; CHAR szUserName[UNLEN+1]; CHAR pad_1; CHAR szNotifyName[CNLEN+1]; CHAR szDataType[DTLEN+1]; PSZ pszParms; USHORT uPosition; USHORT fsStatus; PSZ pszStatus; ULONG ulSubmitted; ULONG ulSize; PSZ pszComment; } PRJINFO; where uJobId Contains an unsigned short integer that specifies the identification number of the print job. The identification number is assigned by the print spooler. szUserName Contains an ASCIIZ string that specifies which user submitted the print job. The constant UNLEN is defined in the PMSPL.H header file. A null string indicates that the job was submitted from the local computer and the user did not log on. pad_1 Aligns the next data structure element on a word boundary. szNotifyName Contains an ASCIIZ string that specifies the message alias that receives alert messages relating to the print job. The constant CNLEN is defined in the PMSPL.H header file. A null string is used for jobs submitted from the local computer. szDataType Contains an ASCIIZ string that specifies the datatype for the print job. This element corresponds to the pszDataType element of the MS OS/2 DEVOPENSTRUC data structure that was supplied when the job was created. The DEVOPENSTRUC data structure is defined in the OS2DEV.H header file. The constant DTLEN is defined in the PMSPL.H header file. pszParms Points to an ASCIIZ string that contains a parameter string to pass to the spooler. The parameter string has this format: parm1=value1 parm2=value2 ... Note that a single space separates the parameter and value pairs. uPosition Contains an unsigned short integer that specifies the position of the print job in the printer queue. If uPosition is 1, the print job prints next. fsStatus Contains an unsigned short integer used as a status flag. Possible values are defined in the PMSPL.H header file. Bits 0-1 have the code PRJ_QSTATUS and the value 0x0003. This bit mask isolates the print job queued status bits, as follows: Bits Code Value Meaning ──────────────────────────────────────────────────────────────────────────── 0-1 PRJ_QS_QUEUED 0 Print job is queued. 0-1 PRJ_QS_PAUSED 1 Print job is paused. 0-1 PRJ_QS_SPOOLING 2 Print job is spooling. 0-1 PRJ_QS_PRINTING 3 Print job is printing (bits 2-11 are valid). ──────────────────────────────────────────────────────────────────────────── Bits 2-11 indicate the print job status. Bits 2-11 can be isolated using the constant PRJ_DEVSTATUS, which has the value 0x0FFC. Bit 15 signals whether an alert indicated that the print job was deleted. These are the meanings for individual bits: ╓┌────┌────────────────┌───────┌─────────────────────────────────────────────╖ Bit Code Value Meaning ──────────────────────────────────────────────────────────────────────────── 2 PRJ_COMPLETE 0x0004 If 1, the print job is complete. 3 PRJ_INTERV 0x0008 If 1, intervention is required. 4 PRJ_ERROR 0x0010 If 1, an error occurred (pszStatus can contain a comment explaining the error). 5 PRJ_DESTOFFLINE 0x0020 If 1, the print destination is offline. 6 PRJ_DESTPAUSED 0x0040 If 1, the print destination is paused. 7 PRJ_NOTIFY 0x0080 If 1, an alert is raised. 8 PRJ_DESTNOPAPER 0x0100 If 1, the print destination is out of paper. 9 PRJ_DESTFORMCHG 0x0200 If 1, the printer is waiting for a form change. 10 PRJ_DESTCRTCHG 0x0400 If 1, the printer is waiting for a cartridge Bit Code Value Meaning ──────────────────────────────────────────────────────────────────────────── 10 PRJ_DESTCRTCHG 0x0400 If 1, the printer is waiting for a cartridge change. 11 PRJ_DESTPENCHG 0x0800 If 1, the printer is waiting for a pen change. 15 PRJ_DELETED 0x8000 If 1, an alert indicates the job was deleted. ──────────────────────────────────────────────────────────────────────────── pszStatus Points to an ASCIIZ string that contains a comment about the status of the print job posted by the queue's print processor. A null pointer or null string indicates that no information was posted. This element contains valid data only while the job is printing and an error occurs. ulSubmitted Contains an unsigned long integer that specifies the time the user submitted the print job. The time is stored in seconds elapsed since 00:00:00, January 1, 1970. ulSize Contains an unsigned long integer that specifies the size (in bytes) of the print job. pszComment Points to an ASCIIZ string that contains a comment about the print job. This string can have as many as MAXCOMMENTSZ bytes. The constant MAXCOMMENTSZ is defined in the PMSPL.H header file. Print Job Information (level 2) The PRJINFO2 data structure has this format: typedef struct _PRJINFO2 { USHORT uJobId; USHORT uPriority; PSZ pszUserName; USHORT uPosition; USHORT fsStatus; ULONG ulSubmitted; ULONG ulSize; PSZ pszComment; PSZ pszDocument; } PRJINFO2; where uJobId Contains an unsigned short integer that specifies the identification number of the print job. The identification number is assigned by the print spooler. uPriority Contains an unsigned short integer that specifies the priority of the print job. The range is 1 (lowest priority) through 99 (highest priority). If the constant PRJ_NO_PRIORITY is used, a default job priority is computed based on the queue priority. The default job priority is defined as follows: default job priority = 100 - (10 * queue priority) The constant PRJ_NO_PRIORITY is defined in the PMSPL.H header file. The job priority determines the order of jobs in the queue. If multiple queues print to the same printer, the spooler compares the priorities of the jobs at the front of the queues and schedules the job with the highest priority first. If job priorities are equal, the oldest job is scheduled. pszUserName Points to an ASCIIZ string that specifies the name of the user who submitted the print job. uPosition through pszComment Are the same as the corresponding elements of the PRJINFO data structure. For a complete description, see the preceding section. pszDocument Points to an ASCIIZ string that contains the document name of the print job. This string can have as many as CCHMAXPATH bytes. The constant CCHMAXPATH is defined in the MS OS/2 header file BSEDOS.H. Print Job Information (level 3) The PRJINFO3 data structure has this format: typedef struct _PRJINFO3 { USHORT uJobId; USHORT uPriority; PSZ pszUserName; USHORT uPosition; USHORT fsStatus; ULONG ulSubmitted; ULONG ulSize; PSZ pszComment; PSZ pszDocument; PSZ pszNotifyName; PSZ pszDataType; PSZ pszParms; PSZ pszStatus; PSZ pszQueue; PSZ pszQProcName; PSZ pszQProcParms; PSZ pszDriverName; PDRIVDATA pDriverData; PSZ pszPrinterName; } PRJINFO3; where uJobId through pszDocument Are the same as the corresponding elements of the PRJINFO2 data structure. For a complete description, see the preceding section. pszNotifyName Points to an ASCIIZ string that contains the message alias that receives alert messages related to the print job. A null string indicates the job was submitted from the local computer. pszDataType Points to an ASCIIZ string that contains the datatype for the print job. This field corresponds to the pszDataType field of the MS OS/2 DEVOPENSTRUC data structure supplied when the job was created. The DEVOPENSTRUC data structure is defined in the OS2DEV.H header file. pszParms Points to an ASCIIZ string that contains a parameter string to pass to the printer queue processor. The parameter string has this format: parms=value pszStatus Points to an ASCIIZ string that contains a comment about the status of the print job posted by the queue's print processor. A null pointer or null string indicates that no information was posted. This element contains valid data only while the job is printing and an error occurs. pszQueue Points to an ASCIIZ string that contains the name of the printer queue that contains the print job. pszQProcName Points to an ASCIIZ string that contains the name of the queue print processor. pszQProcParms Points to an ASCIIZ string that contains parameters passed to the queue print processor. The parameter string has the following format: parm1=value1 parm2=value2 ... Note that a single space separates the parameter and value pairs. An example parameter, CPY=n, specifies that n copies of the document will be printed. pszDriverName Points to an ASCIIZ string that contains the name of the printer device driver. pDriverData Points to the MS OS/2 DRIVDATA data structure for the default driver. This data is specific to the device driver and is used only if pszDriverName is not null. The MS OS/2 DRIVDATA data structure is defined in the OS2DEF.H header file. pszPrinterName Points to an ASCIIZ string that contains the name of the printer on which the job is printing. If the job is not printing, pszPrinterName contains a null string or a null pointer. Print Job Identification Number DosPrintJobGetId returns the PRIDINFO data structure: typedef struct _PRIDINFO { USHORT uJobId; CHAR szServer[CNLEN+1]; CHAR szQName[QNLEN+1]; CHAR pad_1; } PRIDINFO; where uJobId Contains an unsigned short integer that specifies the identification number assigned to the print job when it was queued. The identification number is unique on a particular computer. A combination of the computername and uJobId is sufficient to uniquely identify a particular print job. szServer Specifies an ASCIIZ string that contains the name of the computer handling the print job. The constant CNLEN is defined in the PMSPL.H header file. If the name has more than CNLEN bytes, a null string is returned. szQName Specifies an ASCIIZ string that contains the name of the printer queue for the job. The constant QNLEN is defined in the PMSPL.H header file. If the name has more than QNLEN bytes, a null string is returned. pad_1 Aligns the next data structure element on a word boundary. DosPrintJobContinue ──────────────────────────────────────────────────────────────────────────── DosPrintJobContinue allows a paused print job to resume printing. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintJobContinue on a remote server or on a computer that has local security enabled, except when users are continuing their own jobs. In this case, no special privilege is required. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintJobContinue (PSZ pszServer, USHORT uJobId ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintJobContinue. A null pointer or null string specifies the local computer. uJobId Contains an unsigned short integer that specifies the identification number of the print job. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_JobNotFound 2151 No print job matches the print job identification number typed. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_JobInvalidState 2164 This operation cannot be performed on the print job in its current state. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── its current state. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks DosPrintJobContinue cannot continue a job that is already printing. Use DosPrintDestControl instead. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Obtaining the identification DosPrintJobGetId number of a print job Pausing a print job DosPrintJobPause Retrieving information about a DosPrintJobGetInfo particular print job DosPrintJobDel ──────────────────────────────────────────────────────────────────────────── DosPrintJobDel deletes a print job from a printer queue. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintJobDel on a remote server or on a computer that has local security enabled, except when users are deleting their own jobs. In this case, no special privilege is required. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintJobDel (PSZ pszServer, USHORT uJobId ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintJobDel. A null pointer or null string specifies the local computer. uJobId Contains an unsigned short integer that specifies the identification number of the print job. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_JobNotFound 2151 No print job matches the print job identification number typed. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── job identification number typed. NERR_ProcNoRespond 2160 The print processor is not responding. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing the print jobs in a DosPrintJobEnum printer queue Obtaining the identification DosPrintJobGetId number of a print job DosPrintJobEnum ──────────────────────────────────────────────────────────────────────────── DosPrintJobEnum lists print jobs in the specified printer queue. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level No special privilege level is required to successfully execute DosPrintJobEnum. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintJobEnum (PSZ pszServer, PSZ pszQueueName, USHORT uLevel, PBYTE pbBuf, USHORT cbBuf, PUSHORT pcReturned, PUSHORT pcTotal ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintJobEnum. A null pointer or null string specifies the local computer. pszQueueName Points to an ASCIIZ string that specifies which printer queue to monitor. uLevel Specifies the level of detail (0, 1, or 2) requested. pbBuf Points to the buffer in which to store the returned data. cbBuf Specifies the size (in bytes) of the buffer pointed to by pbBuf. pcReturned Points to an unsigned short integer that specifies the number of entries returned to pbBuf. This count is valid only if DosPrintJobEnum returns NERR_Success or ERROR_MORE_DATA. pcTotal Points to an unsigned short integer that specifies the number of entries available. This count is valid only if DosPrintJobEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌──────────────────────┌───────┌────────────────────────────────────────────╖ Code Value Meaning Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_QNotFound 2150 The queue name specified is invalid. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks Level 0 and level 1 calls are compatible with existing LAN Manager 1.0 applications. Note that for LAN Manager 2.0 three new print destination status bits (9, 10, and 11) are added to the fsStatus element of the PRJINFO data structure. Existing applications that do not examine these new status bits may not accurately report the status. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Modifying instructions for a DosPrintJobSetInfo submitted print job Retrieving information about a DosPrintJobGetInfo particular print job DosPrintJobGetId ──────────────────────────────────────────────────────────────────────────── DosPrintJobGetId retrieves information about a remote print job. Operating Systems Supported ■ MS OS/2 version 1.2, local only with handle to remote queue name ■ MS OS/2 version 1.1, local only with handle to remote queue name ■ MS-DOS, local only with handle to remote queue name Privilege Level DosPrintJobGetId is a handle-based function. If you have privilege to open the file to get the handle, you do not need special privilege to call DosPrintJobGetId. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintJobGetId (HFILE hFile, PPRIDINFO pInfo, USHORT cbInfo ); where hFile Specifies the handle of a redirected print device. pInfo Points to the buffer in which to store the returned data. On a successful return, the buffer contains the PRIDINFO data structure. cbInfo Specifies the size (in bytes) of the data returned in the buffer pointed to by pInfo. Return Codes ╓┌──────────────────────┌───────┌────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_INVALID_HANDLE 6 The handle specified is invalid. ERROR_NOT_SUPPORTED 50 This network request is not supported. NERR_DevNotRedirected 2107 The devicename is not assigned to a shared resource. NERR_BufTooSmall 2123 The supplied buffer is too small. ──────────────────────────────────────────────────────────────────────────── Remarks DosPrintJobGetId is handle-based. The handle must be a valid handle to a remote spooled queue. The handle cannot be a handle to a local job. If LAN Manager is not installed, DosPrintJobGetId returns ERROR_NOT_SUPPORTED. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing the print jobs in a DosPrintJobEnum printer queue Modifying the instructions for a DosPrintJobSetInfo submitted print job Retrieving information about a DosPrintJobGetInfo particular print job DosPrintJobGetInfo ──────────────────────────────────────────────────────────────────────────── DosPrintJobGetInfo retrieves information about a particular print job. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level No special privilege is required to successfully execute DosPrintJobGetInfo. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintJobGetInfo (PSZ pszServer, USHORT uJobId, USHORT uLevel, PBYTE pbBuf, USHORT cbBuf, PUSHORT pcbNeeded ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintJobGetInfo. A null pointer or null string specifies the local computer. uJobId Contains an unsigned short integer that specifies the identification number of the print job. uLevel Specifies the level of detail (0, 1, 2, or 3) requested. pbBuf Points to the buffer in which data is returned. cbBuf Specifies the size (in bytes) of the buffer pointed to by pbBuf. pcbNeeded Points to an unsigned short integer that specifies the number of bytes of information available. This count is valid only if DosPrintJobGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌──────────────────────┌───────┌────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_JobNotFound 2151 No print job matches the print job Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_JobNotFound 2151 No print job matches the print job identification number typed. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing the print jobs in a DosPrintJobEnum printer queue Modifying the instructions for a DosPrintJobSetInfo submitted print job Obtaining the identification DosPrintJobGetId number of a print job DosPrintJobPause ──────────────────────────────────────────────────────────────────────────── DosPrintJobPause pauses a print job in a printer queue. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintJobPause on a remote server or on a computer that has local security enabled, except when users are pausing their own jobs. In this case, no special privilege is required. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintJobPause (PSZ pszServer, USHORT uJobId ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintJobPause. A null pointer or null string specifies the local computer. uJobId Contains an unsigned short integer that specifies the identification number of the print job. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_JobNotFound 2151 No print job matches the print job identification number typed. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── job identification number typed. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_JobInvalidState 2164 This operation cannot be performed on the print job in its current state. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks DosPrintJobPause cannot pause a job that is already printing. Use DosPrintDestControl instead. If the print job is printing when the application calls DosPrintJobPause, the error code NERR_JobInvalidState is returned. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Continuing a paused print job DosPrintJobContinue Obtaining the identification DosPrintJobGetId number of a print job Retrieving information about a DosPrintJobGetInfo particular print job DosPrintJobSetInfo ──────────────────────────────────────────────────────────────────────────── DosPrintJobSetInfo modifies the instructions for a submitted print job. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintJobSetInfo on a remote server or on a computer that has local security enabled, except when users are setting information for their own job. In this case, the only restriction is that users cannot move their jobs forward in the queue. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintJobSetInfo (PSZ pszServer, USHORT uJobId, USHORT uLevel, PSZ pbBuf, USHORT cbBuf, USHORT uParmNum ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintJobSetInfo. A null pointer or null string specifies the local computer. uJobId Contains an unsigned short integer that specifies the identification number of the print job. uLevel Specifies the level of detail (1 or 3) provided. pbBuf Points to a buffer that contains the data to be set. cbBuf Specifies the size (in bytes) of the buffer pointed to by pbBuf. uParmNum Specifies whether to set one or all elements of the print job data structure. If uParmNum is PARMNUM_ALL, pbBuf must point to the print job data structure that corresponds to the uLevel parameter (level 1 indicates PRJINFO, level 3 indicates PRJINFO3). If uParmNum is any other defined value, only one element of the print job information is changed, and pbBuf must point to a valid value for that element. Not all elements can be set. Only those elements that have a specific PARMNUM constant value defined can be set. The PMSPL.H and NETCONS.H header files define these possible values for uParmNum: ╓┌───────────────────────┌──────┌────────────────────────────────────────────╖ Element of PRJINFO and PRJINFO3 Code Value ──────────────────────────────────────────────────────────────────────────── PARMNUM_ALL 0 All elements. PRJ_NOTIFYNAME_PARMNUM 3 szNotifyName or pszNotifyName PRJ_DATATYPE_PARMNUM 4 szDataType or pszDataType PRJ_PARMS_PARMNUM 5 pszParms Element of PRJINFO and PRJINFO3 Code Value ──────────────────────────────────────────────────────────────────────────── PRJ_PARMS_PARMNUM 5 pszParms PRJ_POSITION_PARMNUM 6 uPosition PRJ_COMMENT_PARMNUM 11 pszComment PRJ_DOCUMENT_PARMNUM 12 pszDocument (level 3 only) PRJ_PRIORITY_PARMNUM 14 uPriority (level 3 only) PRJ_PROCPARMS_PARMNUM 16 pszQProcParms (level 3 only) PRJ_DRIVERDATA_PARMNUM 18 pDriverData (level 3 only) ──────────────────────────────────────────────────────────────────────────── The uPosition element can have the following values: Value Position Change ──────────────────────────────────────────────────────────────────────────── 0 No change. 1 Moves to first place. n > 1 Assumes position n in queue. If n is greater than the number of jobs in the queue, the job moves to the end of the queue. ──────────────────────────────────────────────────────────────────────────── Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_RemoteOnly 2106 This operation can be performed only on a server. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_JobNotFound 2151 No print job matches the print job identification number typed. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_JobInvalidState 2164 This operation cannot be performed on the print job in its current state. NERR_SpoolNoMemory 2165 A spooler memory allocation failure occurred. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_DriverNotFound 2166 The device driver specified has not been installed on the computer. NERR_ProcNotFound 2168 The print processor has not been installed on the server. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks Jobs created locally have no username, and can be operated upon by any user on the local computer. Admin privilege or printer operator privilege is required to operate on the job from a remote computer. The job position or job priority can be changed to allow a particular print job to print before other jobs in the queue. Applications or users without admin or print operator privilege can only move their own job backward in a printer queue and set the priority to a lower value. Without admin or print operator privilege, applications or users can improve the relative position of their job in the queue by changing all their other jobs in the queue to lower position or priority values. They cannot increase the job priority. When a new data structure is directed to a server running an earlier version of LAN Manager (a down-level server), the following parameter number codes are not supported: PRJ_PRIORITY_PARMNUM, PRJ_PROCPARMS_PARMNUM, and PRJ_DRIVERDATA_PARMNUM. The function returns ERROR_NOT_SUPPORTED for these codes. If the entire structure is passed, these unsupported entries are ignored. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing the print jobs in a DosPrintJobEnum printer queue Retrieving information about a DosPrintJobGetInfo particular print job Print Job Category Example /* NETPRJ.C -- a program demonstrating the DosPrintJob API functions. Admin or print operator privilege is required to successfully execute the Print Job API functions on a remote server. DosPrintJobGetId is called to demonstrate that a Print Job ID can be returned for those applications that use Open to access a printer. This print job ID can then be used as an input parameter for the other Print Job API functions. This program calls DosPrintJobEnum to list all jobs in the specified queue. If the user did not select a job ID from the command line, the program selects the first job ID returned by the Enum function as the target job ID used in all other calls. DosPrintJobPause is called to pause the job, DosPrintJobSetInfo changes the job's position in the printer queue, DosPrintJobGetInfo displays the new settings, DosPrintJobContinue releases the paused job, and DosPrintJobDel deletes the job. Usage: netprj [-s \\server] [-q queue] [-l level] [-n nth position] [-f flag] [-j jobid] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). queue = Name of the printer queue. level = Level of detail. nth position = Job's new position in the queue. flag = Flag to delete the job; 0 = no, 1 = yes. jobid = ID of the target job for all function calls. API Used to... =================== =========================================== DosPrintJobGetId Get info about the print job (using handle) DosPrintJobEnum List all print jobs in the specified queue DosPrintJobPause Pause a print job in a printer queue DosPrintJobSetInfo Set one or all print job parameters DosPrintJobGetInfo Get info about the print job (using job ID) DosPrintJobContinue Continue a paused print job DosPrintJobDel Delete a print job from the queue This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_BASE #include <os2.h> // MS OS/2 base header files #include <pmspl.h> // Print definitions #define INCL_NETERRORS #include <lan.h> // LAN Manager header files #include <fcntl.h> // File-related defines #include <io.h> // File-related functions #include <malloc.h> // Memory allocation functions #include <share.h> // File-related defines #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include <time.h> #include "samples.h" // SafeMalloc(), FarStrcpy(), etc. #define DEFAULT_POS 1 #define DEFAULT_BUFFER_SIZE 512 #define MAX_BUFFER_SIZE 32768 #define DEFAULT_QUEUE "PRINTQ" void DisplayInfo(USHORT uLevel, PBYTE pbBuffer, USHORT cEntries); void Usage(PSZ pszString); void main(int argc, char *argv[]) { CHAR szPath[2+CNLEN+1+UNLEN+1]; // Allow for slashes and NUL HFILE hFile; // File handle INT iCount; // Index, loop counter PBYTE pbBuffer; // Pointer to return data PSZ pszServerName = ""; // Default to local computer PSZ pszQueueName = DEFAULT_QUEUE; // Queuename SPLERR uRet; // Return code USHORT uLevel = 2; // Level of detail USHORT fDone; // Flag successful call USHORT fDelete = TRUE; // Flag whether to delete or not USHORT cEntriesRead; // Entries in buffer USHORT cEntriesTotal; // Entries available USHORT cbBuffer = 0; // Count of bytes in buffer USHORT cbBufferNeeded = 0; // Count of bytes available USHORT uNewPosition = DEFAULT_POS; // New position in queue; 1 = top USHORT uJobId = 0; // Print job ID number PPRIDINFO pprid; // DosPrintJobGetId data for (iCount = 1; iCount < argc; iCount++) // Get cmd-line switches { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServerName = argv[++iCount]; break; case 'q': // -q queuename pszQueueName = argv[++iCount]; break; case 'l': // -l level uLevel = atoi(argv[++iCount]); break; case 'n': // -n nth position in queue uNewPosition = atoi(argv[++iCount]); break; case 'f': // -f flag for delete fDelete = atoi(argv[++iCount]); break; case 'j': uJobId = atoi(argv[++iCount]); break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } // End for loop printf("\nPrint Job Category API Examples\n"); //======================================================================== // DosPrintJobGetId // // This API returns a job ID to allow existing applications that // write directly to a remote server printer queue to use Print Job // API functions. The input parameter is a handle to the remote // printer queue. //======================================================================== if ((pszServerName != NULL) && (*pszServerName != '\0')) // Remote only { FarStrcpy((PSZ)szPath, pszServerName); // Servername strcat(szPath, "\\"); // Slash precedes sharename FarStrcat((PSZ)szPath, pszQueueName); // Queuename // Open the file on the remote queue to obtain the handle. hFile = sopen(szPath, // Remote printer queue: \\server\queue O_RDONLY, // Open read-only SH_DENYNO); // Share deny-none if (hFile == -1) printf("sopen failed opening %s\n", szPath); else { printf("sopen succeeded opening %s\n", szPath); /* * If sopen succeeded, prepare to call DosPrintJobGetId: Allocate a buffer for the return data. */ if ((pprid = (PPRIDINFO)_fmalloc(sizeof(PRIDINFO))) == NULL) exit(1); uRet = DosPrintJobGetId(hFile, // Handle to printer queue pprid, // Pointer to return buffer sizeof(PRIDINFO)); // Size of return buffer printf("DosPrintJobGetId returned %u\n", uRet); if (uRet == NERR_Success) { printf("Job ID : %hu\n", pprid->uJobId); printf("Server : %Fs\n", pprid->szServer); printf("Queue : %Fs\n", pprid->szQName); /* * If an application prints using the handle, * DosPrintJobGetId can provide the job ID needed * to use the other Print Job API functions. */ } _ffree((PVOID)pprid); close(hFile); // Close handle } // End successful sopen } // End if remote server //======================================================================= // DosPrintJobEnum // // This API lists all print jobs in the specified printer queue. //======================================================================= cbBuffer = DEFAULT_BUFFER_SIZE; if ((pbBuffer = (PBYTE)_fmalloc(cbBuffer)) == NULL) { printf("Cannot allocate buffer\n"); exit(1); } do // Call API function until buffer big enough or call fails { uRet = DosPrintJobEnum ( pszServerName, // Servername pszQueueName, // Queuename uLevel, // Call level pbBuffer, // Buffer for info cbBuffer, // Size of buffer &cEntriesRead, // Count of entries read &cEntriesTotal); // Count of entries available printf("DosPrintJobEnum returned %u\n", uRet); if ((uRet == NERR_BufTooSmall) || (uRet == ERROR_MORE_DATA)) { // Allocate a buffer twice as large, up to the maximum size. _ffree((PVOID)pbBuffer); // Buffer too small to hold data if (cbBuffer >= MAX_BUFFER_SIZE) exit(1); else if (cbBuffer > (MAX_BUFFER_SIZE/2)) cbBuffer = MAX_BUFFER_SIZE; else cbBuffer += cbBuffer; // Allocate a larger one and try again if ((pbBuffer = (PBYTE)_fmalloc(cbBuffer)) == NULL) exit(1); fDone = FALSE; } else fDone = TRUE; } while (fDone == FALSE); // Loop until buffer big enough or call fails if (uRet == NERR_Success) { printf("DosPrintJobEnum read %hu ", cEntriesRead); printf(" out of %hu entries\n", cEntriesTotal); DisplayInfo(uLevel, pbBuffer, cEntriesRead); if ((uJobId == 0) && (cEntriesRead > 0)) // If data in the buffer { uJobId = *((USHORT FAR *)pbBuffer); // uJobId first, all levels printf(" Job ID for other functions = %hu\n", uJobId); } } _ffree((PVOID)pbBuffer); //======================================================================= // DosPrintJobPause // // This API pauses the specified print job. //======================================================================= uRet = DosPrintJobPause(pszServerName, // Servername uJobId); // Job ID printf("DosPrintJobPause returned %u\n", uRet); //======================================================================= // DosPrintJobSetInfo // // This API allows control over one or all print job settings. // In this example, a single element is set to the desired value // (but a valid detail level [1 or 3] must still be provided). //======================================================================= uRet = DosPrintJobSetInfo(pszServerName, // Servername uJobId, // Job ID 1, // Call level (PBYTE)&uNewPosition, // Data to be set sizeof(USHORT), // Size of buffer PRJ_POSITION_PARMNUM);// Set job position in queue printf("DosPrintJobSetInfo returned %u\n", uRet); //======================================================================= // DosPrintJobGetInfo // // This API returns information about one specific print job. //======================================================================= /* * Call with zero-length buffer, expect NERR_BufTooSmall. * Make a second call with the buffer of the required size. */ uRet = DosPrintJobGetInfo(pszServerName, // Servername uJobId, // Job ID uLevel, // Call level NULL, // Buffer for info 0, // Size of buffer &cbBufferNeeded); // Size required if (uRet == NERR_BufTooSmall) { cbBuffer = cbBufferNeeded; if ((pbBuffer = (PBYTE)_fmalloc(cbBuffer)) == NULL) exit(1); uRet = DosPrintJobGetInfo(pszServerName,// Servername uJobId, // Job ID uLevel, // Call level pbBuffer, // Buffer for info cbBuffer, // Size of buffer &cbBufferNeeded); // Size required } printf("DosPrintJobGetInfo returned %u\n", uRet); if (uRet == NERR_Success) DisplayInfo(uLevel, pbBuffer, 1); // Show results of GetInfo _ffree((PVOID)pbBuffer); //======================================================================= // DosPrintJobContinue // // This API allows a paused print job to continue. //======================================================================= uRet = DosPrintJobContinue(pszServerName, // Servername uJobId); // Job ID printf("DosPrintJobContinue returned %u\n", uRet); //======================================================================= // DosPrintJobDel // // This API deletes the print job. This sample program allows the user // to specify a command-line flag that determines whether to delete // the job or not. //======================================================================= if (fDelete == TRUE) { uRet = DosPrintJobDel(pszServerName, // Servername uJobId); // Job ID printf("DosPrintJobDel returned %u\n", uRet); } exit(0); } // End of main //======================================================================= // DisplayInfo // // Display selected print job information obtained by // DosPrintJobGetInfo or DosPrintJobEnum. DosPrintJobGetInfo allows // levels 0, 1, 2, or 3. DosPrintJobEnum allows levels 0, 1, or 2. //======================================================================= void DisplayInfo(USHORT uLevel, PBYTE pbBuffer, USHORT cEntries) { PUSHORT pprj0Info; // Pointer to level 0 data structure PPRJINFO pprj1Info; // Pointer to level 1 data structure PPRJINFO2 pprj2Info; // Pointer to level 2 data structure PPRJINFO3 pprj3Info; // Pointer to level 3 data structure USHORT iCount; // Index, loop counter time_t time; // Convert job submission time pprj0Info = (PUSHORT) pbBuffer; // Initialize pointers pprj1Info = (PPRJINFO) pbBuffer; pprj2Info = (PPRJINFO2) pbBuffer; pprj3Info = (PPRJINFO3) pbBuffer; for (iCount = 1; iCount <= cEntries; iCount++) { printf("\n"); switch (uLevel) { case 0: printf("Job ID : %hu\n", *pprj0Info++); break; case 1: // Level 1 data in buffer printf("Job ID : %hu\n", pprj1Info->uJobId); printf("User Name : %Fs\n", pprj1Info->szUserName); printf("Position : %hu\n", pprj1Info->uPosition); printf("Job Status : 0x%hx\n", pprj1Info->fsStatus); pprj1Info++; break; case 2: // Level 2 data in buffer printf("Job ID : %hu\n", pprj2Info->uJobId); printf("Priority : %hu\n", pprj2Info->uPriority); printf("User Name : %Fs\n", pprj2Info->pszUserName); putenv("TZ=GMT0"); // Print time given in local time time = (time_t) pprj2Info->ulSubmitted; printf("Submitted : %s", ctime(&time)); printf("Job size : %lu\n", pprj2Info->ulSize); pprj2Info++; break; case 3: // Level 3 data in buffer printf("Job ID : %hu\n", pprj3Info->uJobId); printf("Priority : %hu\n", pprj3Info->uPriority); printf("User Name : %Fs\n", pprj3Info->pszUserName); printf("Queue : %Fs\n", pprj3Info->pszQueue); printf("Printer Name: %Fs\n", pprj3Info->pszPrinterName); pprj3Info++; break; default: // Undefined level break; } // End switch uLevel } // End for loop } // End function //======================================================================= // Usage // // Display possible command-line switches for this sample program. //======================================================================= void Usage(PSZ pszString) { fprintf(stderr, "Usage: %Fs [-s \\\\server] [-l level]", pszString); fprintf(stderr, " [-q queuename]\n\t[-j jobid] [-f flag delete]\n"); exit(1); } Printer Queue Category Printer Queue API functions control the printer queues on a server. When executed locally, they do not require that the NETWKSTA device driver be installed. When a servername is supplied, they require that the Workstation service be started. The Printer Queue category functions, datatypes, structures, and constants are defined in the PMSPL.H header file. A source program can access these definitions by including the PMSPL.H header file. A source program can access error codes by defining the constant INCL_NETERRORS and including the LAN.H header file. For more information, see the "Example" section, later in this category. These are the Printer Queue API functions: ■ DosPrintQAdd ■ DosPrintQContinue ■ DosPrintQDel ■ DosPrintQEnum ■ DosPrintQGetInfo ■ DosPrintQPause ■ DosPrintQPurge ■ DosPrintQSetInfo Description A printer queue is an ordered list of print jobs on a computer. A single computer can have multiple printer queues. When a print job is submitted to a printer queue, the spooler directs the print job to a print processor for processing before printing. The print spooler continuously examines the printer queues. The action taken depends on the following: ■ Printer queue priority (in relation to other printer queues) ■ Time of day during which the printer queue accepts jobs ■ Print destination(s) available to the printer queue ■ Print processor, driver, and driver data defaults for jobs added to the queue DosPrintQAdd creates a printer queue on the specified server. DosPrintQDel deletes a printer queue. DosPrintQPause pauses the operation of a printer queue and suspends scheduling of all print jobs but the current job. A paused queue continues to accept new jobs. DosPrintQContinue resumes processing of print jobs in a paused printer queue. Print jobs can be submitted to a paused queue, but jobs are not spooled to a print destination or print processor until the printer queue resumes processing. DosPrintQPurge removes all pending jobs in a printer queue, leaving only currently printing jobs. The DosPrintQEnum API function lists information about all printer queues on a server. The DosPrintQGetInfo API function retrieves information about a particular printer queue. The DosPrintQSetInfo API function allows you to change parameter settings for a particular printer queue. The Printer Queue data structures and the Printer Queue API functions use MS OS/2 conventions for names and type definitions. The OS2DEF.H header file defines these types: ╓┌─────────────────────────────────┌─────────────────────────────────────────╖ MS OS/2 Type Definition C-Language Type ──────────────────────────────────────────────────────────────────────────── CHAR char PBYTE unsigned char far * PSZ unsigned char far * PUSHORT unsigned short * SPLENTRY pascal far SPLERR unsigned USHORT unsigned short ──────────────────────────────────────────────────────────────────────────── Data Structures Level 0, level 1, and level 2 data structures are provided for compatibility with existing LAN Manager 1.0 applications. LAN Manager 2.0 applications should use level 3, level 4, and level 5 data structures. Existing LAN Manager 1.0 applications (that use the level 0, 1, and 2 data structures) can be compiled and linked using the 1.0 header file NETSPOOL.H and the 1.0-compatible libraries NETSPOOL.LIB and NETSPOOL.DLL. Applications designed to run with both MS OS/2 1.1 and MS OS/2 1.2 should use the new level 3, level 4, and level 5 data structure names, include the PMSPL.H header file, and link with the NETSPOOL libraries. Applications that are designed to run only with MS OS/2 1.2 should use the PMSPL.LIB and PMSPL.DLL libraries. The PMSPL library functions provide better performance than the corresponding functions in the NETSPOOL library. Applications that run only with MS OS/2 1.2 can be built from existing applications. These applications can be upgraded by changing the data structure and element names. References to the prq_info data structure and element names can be changed to the PRQINFO data structure and element names. The prq_processor element of the prq_info data structure must be changed. This element contains a path to a .EXE file; the corresponding pszPrProc element of the PRQINFO data structure contains a queue processor name. There is one-to-one mapping from the size and type of the prq_info elements to the PRQINFO elements, as shown in the following table: ╓┌────────────────────────────────┌──────────────────────────────────────────╖ LAN Manager 1.0 LAN Manager 2.0 prq_info Element PRQINFO Element ──────────────────────────────────────────────────────────────────────────── prq_name szName prq_pad1 pad_1 prq_priority uPriority prq_starttime uStarttime prq_untiltime uUntiltime LAN Manager 1.0 LAN Manager 2.0 prq_info Element PRQINFO Element ──────────────────────────────────────────────────────────────────────────── prq_untiltime uUntiltime prq_separator pszSepFile prq_processor pszPrProc prq_destinations pszDestinations prq_parms pszParms prq_comment pszComment prq_status fsStatus prq_jobcount cJobs ──────────────────────────────────────────────────────────────────────────── LAN Manager 1.0 LAN Manager 2.0 prq_info Element PRQINFO Element ──────────────────────────────────────────────────────────────────────────── The new data structures are supported when they are directed to servers that run LAN Manager 1.0 software (down-level servers). New elements are given default values or values that indicate the element is not available, such as NULL. DosPrintQAdd and DosPrintQSetInfo use the level 1 data structure PRQINFO or the level 3 data structure PRQINFO3. DosPrintQEnum and DosPrintQGetInfo use levels 0, 1, 2, 3, 4, and 5. Printer Queue Name (level 0) At level 0, data is returned in this format: CHAR szName[QNLEN+1]; where szName Contains an ASCIIZ string that specifies the name of a printer queue. The constant QNLEN is defined in the PMSPL.H header file. Printer Queue Information (level 1) The PRQINFO data structure has this format: typedef struct _PRQINFO { CHAR szName[QNLEN+1]; CHAR pad_1; USHORT uPriority; USHORT uStarttime; USHORT uUntiltime; PSZ pszSepFile; PSZ pszPrProc; PSZ pszDestinations; PSZ pszParms; PSZ pszComment; USHORT fsStatus; USHORT cJobs; } PRQINFO; where szName Contains an ASCIIZ string that specifies the name of the printer queue. The constant QNLEN is defined in the PMSPL.H header file. pad_1 Aligns the next data structure element on a word boundary. uPriority Contains an unsigned short integer that specifies the printer queue priority, ranging from 1 (highest) through 9 (lowest). When two or more printer queues submit print jobs to the same destination, jobs in printer queues with higher priorities are processed before those in lower-priority queues. The printer queue priority is used to determine the default print job priority. The default job priority is used when no priority is specified for the job or when the specified job priority is higher than the default job priority. For more information, see the Print Job category API functions. uStarttime Contains an unsigned short integer that specifies the time of day a printer queue becomes active and can start sending print jobs to print destinations. This value represents the number of minutes since 00:00 (midnight). For example, a value of 60 indicates that the printer queue becomes active at 1:00 A.M. uUntiltime Contains an unsigned short integer that specifies the time of day a printer queue becomes inactive and stops sending print jobs to print destinations. This value represents the number of minutes since 00:00 (midnight). For example, a value of 1020 (60 minutes * 17 hours) indicates that the printer queue becomes inactive at 5:00 P.M. pszSepFile Points to an ASCIIZ string that contains the pathname of a separator page file. A relative pathname is relative to the current spool directory. The separator page file contains formatting information for the page(s) that separates print jobs. Separator pages are printed only by some print processors, such as LMPRINT; PMPRINT does not print them. pszPrProc Points to an ASCIIZ string that contains the name of the print processor. A null pointer or null string indicates the default queue processor. pszDestinations Points to an ASCIIZ string that contains a list of print destinations for this queue (the concatenated print destinations are separated by spaces). The specified print destinations process the print jobs in this printer queue. Print jobs submitted to the queue are sent to the first available destination in the list. pszParms Points to an ASCIIZ string that contains parameters required by printer queues. The parameter string has the following format: parm1=value1 parm2=value2 ... Note that a single space separates the parameter and value pairs. pszComment Points to an ASCIIZ string that contains a comment about the printer queue. fsStatus Contains an unsigned short integer that specifies the status of a printer queue. Possible values are defined in the PMSPL.H header file. The PRQ_STATUS_MASK code has a value of 3 and specifies the status of the printer queue, as follows: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── PRQ_ACTIVE 0 Active. PRQ_PAUSE 1 Paused. PRQ_ERROR 2 Error occurred. PRQ_PENDING 3 Deletion pending. ──────────────────────────────────────────────────────────────────────────── cJobs Contains an unsigned short integer that specifies the number of print jobs currently in the queue. Printer Queue and Job Information (level 2) Level 2 indicates that the return data consists of the Printer Queue data structure PRQINFO followed by a Print Job data structure PRJINFO for every job in the queue. For a full description of the Printer Queue data structure PRQINFO, see the preceding section. The Print Job data structure PRJINFO has this format: typedef struct _PRJINFO { USHORT uJobId; CHAR szUserName[UNLEN+1]; CHAR pad_1; CHAR szNotifyName[CNLEN+1]; CHAR szDataType[DTLEN+1]; PSZ pszParms; USHORT uPosition; USHORT fsStatus; PSZ pszStatus; ULONG ulSubmitted; ULONG ulSize; PSZ pszComment; } PRJINFO; where uJobId Contains an unsigned short integer that specifies the identification number of the print job. The identification number is assigned by the print spooler. szUserName Specifies an ASCIIZ string that contains the name of the user who submitted the print job. The constant UNLEN is defined in the PMSPL.H header file. A null string indicates that the job was submitted from the local computer. pad_1 Aligns the next data structure element on a word boundary. szNotifyName Contains an ASCIIZ string that specifies the message alias that receives alert messages relating to the print job. A null string indicates that the job was submitted from the local computer. The constant CNLEN is defined in the PMSPL.H header file. szDataType Contains an ASCIIZ string that specifies the datatype for the print job. This element corresponds to the pszDataType element of the MS OS/2 DEVOPENSTRUC data structure supplied when the job was created. DEVOPENSTRUC is defined in the OS2DEV.H header file. The constant DTLEN is defined in the PMSPL.H header file. pszParms Points to an ASCIIZ string that contains a parameter string to pass to the printer queue processor. The parameter string has this format: parms=value uPosition Contains an unsigned short integer that specifies the position of the print job in the printer queue. If uPosition is 1, the print job prints next. fsStatus Contains an unsigned short integer used as a status flag. Possible values are defined in the PMSPL.H header file. Bits 0-1 have the code PRJ_QSTATUS and the value 0x0003. This bit mask isolates the print job queued status bits, as follows: Bits Code Value Meaning ──────────────────────────────────────────────────────────────────────────── 0-1 PRJ_QS_QUEUED 0 Print job is queued. 0-1 PRJ_QS_PAUSED 1 Print job is paused. 0-1 PRJ_QS_SPOOLING 2 Print job is spooling. 0-1 PRJ_QS_PRINTING 3 Print job is printing (bits 2-11 are valid). ──────────────────────────────────────────────────────────────────────────── Bits 2-11 indicate the print job status. Bits 2-11 can be isolated using the constant PRJ_DEVSTATUS, which has the value 0x0FFC. Bit 15 signals whether an alert indicated the print job was deleted. These are the meanings for individual bits: ╓┌────┌────────────────┌───────┌─────────────────────────────────────────────╖ Bit Code Value Meaning ──────────────────────────────────────────────────────────────────────────── 2 PRJ_COMPLETE 0x0004 If 1, the job is complete. 3 PRJ_INTERV 0x0008 If 1, intervention is required. Bit Code Value Meaning ──────────────────────────────────────────────────────────────────────────── 4 PRJ_ERROR 0x0010 If 1, an error occurred (pszStatus can contain a comment explaining the error). 5 PRJ_DESTOFFLINE 0x0020 If 1, the print destination is offline. 6 PRJ_DESTPAUSED 0x0040 If 1, the print destination is paused. 7 PRJ_NOTIFY 0x0080 If 1, an alert is raised. 8 PRJ_DESTNOPAPER 0x0100 If 1, the print destination is out of paper. 9 PRJ_DESTFORMCHG 0x0200 If 1, the printer is waiting for a form change. 10 PRJ_DESTCRTCHG 0x0400 If 1, the printer is waiting for a cartridge change. 11 PRJ_DESTPENCHG 0x0800 If 1, the printer is waiting for a pen Bit Code Value Meaning ──────────────────────────────────────────────────────────────────────────── 11 PRJ_DESTPENCHG 0x0800 If 1, the printer is waiting for a pen change. 15 PRJ_DELETED 0x8000 If 1, an alert indicates the print job was deleted. ──────────────────────────────────────────────────────────────────────────── pszStatus Points to an ASCIIZ string that contains a comment about the status of the print job posted by the queue's print processor. A null pointer or null string indicates that no information was posted. ulSubmitted Contains an unsigned long integer that specifies the time the user submitted the print job. The time is given as the number of seconds elapsed since 00:00:00, January 1, 1970. ulSize Contains an unsigned long integer that specifies the size (in bytes) of the print job. pszComment Points to an ASCIIZ string that contains a comment about the print job. It can have as many as MAXCOMMENTSZ bytes, as defined in the PMSPL.H header file. Printer Queue Information (level 3) The PRQINFO3 data structure has this format: typedef struct _PRQINFO3 { PSZ pszName; USHORT uPriority; USHORT uStarttime; USHORT uUntiltime; USHORT pad1; PSZ pszSepFile; PSZ pszPrProc; PSZ pszParms; PSZ pszComment; USHORT fsStatus; USHORT cJobs; PSZ pszPrinters; PSZ pszDriverName; PDRIVDATA pDriverData; } PRQINFO3; where pszName Points to an ASCIIZ string that contains the name of the printer queue. The queuename can have as many as CCHMAXPATHCOMP bytes, as defined in the MS OS/2 header file BSEDOS.H. uPriority through cJobs Are the same as the corresponding elements of the PRQINFO data structure. For a complete description, see "Printer Queue Information (level 1)," earlier in this category. pszPrinters Points to an ASCIIZ string that contains a list of printers that can print from the printer queue. These names reference printers that already exist. If a null pointer or null string is supplied, the queue is created but is not connected to any printers. Printernames in the list are separated by commas (,). If the printername contains spaces, the name should be enclosed in double quotation marks (" "). pszDriverName Points to an ASCIIZ string that contains the default device driver for the queue. The device driver must already have been installed. The default device driver is used to create a print job when only a queuename is specified. If a null pointer or null string is supplied, pDriverData is not used. pDriverData Points to the device driver data for the default driver. This data is specific to the device driver, and it is used only if pszDriverName is not a null pointer or null string. Printer Queue Information (level 4) Level 4 indicates that the return data consists of the Printer Queue data structure(s) PRQINFO3 followed by a Print Job data structure PRJINFO2 for each job in the queue. For a full description of the Printer Queue data structure PRQINFO3, see the preceding section. The Print Job data structure PRJINFO2 has this format: typedef struct _PRJINFO2 { USHORT uJobId; USHORT uPriority; PSZ pszUserName; USHORT uPosition; USHORT fsStatus; ULONG ulSubmitted; ULONG ulSize; PSZ pszComment; PSZ pszDocument; } PRJINFO2; where uJobId Contains an unsigned short integer that specifies the identification number of the print job. The identification number is assigned by the print spooler. uPriority Contains an unsigned short integer that specifies the priority of the print job, ranging from 1 (lowest priority) through 99 (highest priority). The constant PRJ_NO_PRIORITY should be used to get the default job priority based on the queue priority. The constant PRJ_NO_PRIORITY is defined in the PMSPL.H header file. The job priority determines the order of jobs in the queue. If multiple queues print to the same printer, the jobs at the front of the queues are examined. The job with the highest priority is scheduled. If the job priorities are equal, the oldest job is scheduled. pszUserName Points to an ASCIIZ string that contains the name of the user who submitted the print job. uPosition through pszComment Are the same as the corresponding elements of the PRJINFO data structure. For a complete description, see "Printer Queue and Job Information (level 2)," earlier in this category. pszDocument Points to an ASCIIZ string that contains the document name of the print job. The document name can have as many as CCHMAXPATH bytes, as defined in the MS OS/2 header file BSEDOS.H. Printer Queue Information (level 5) At level 5, data is returned in this format: PSZ pszName; where pszName Points to an ASCIIZ string that specifies the name of the printer queue. The queuename can have as many as CCHMAXPATHCOMP bytes, as defined in the MS OS/2 header file BSEDOS.H. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Controlling a print destination Print Destination Category Controlling print jobs Print Job Category DosPrintQAdd ──────────────────────────────────────────────────────────────────────────── DosPrintQAdd creates a printer queue on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintQAdd on a remote server or on a computer that has local security enabled. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintQAdd (PSZ pszServer, USHORT uLevel, PBYTE pbBuf, USHORT cbBuf ); where pszServer Points to an ASCIIZ string that contains the name of a server on which to execute DosPrintQAdd. A null pointer or null string specifies the local computer. uLevel Specifies the level of detail (1 or 3) provided in the buffer pointed to by pbBuf. Level 1 is provided for compatibility with existing LAN Manager 1.0 applications and should not be used in new applications. Only level 3 should be used in new applications. pbBuf Points to the buffer that contains data for the printer queue to be added. The buffer should contain a PRQINFO or PRQINFO3 data structure, corresponding to the level specified by uLevel. cbBuf Specifies the size (in bytes) of the data buffer pointed to by pbBuf. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_RedirectedPath 2117 The operation is invalid for a redirected resource. The devicename specified is assigned to a shared resource. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_DestNotFound 2152 The print destination was not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_DestNotFound 2152 The print destination was not found. NERR_QExists 2154 A printer queue with this name already exists. NERR_QNoRoom 2155 The server does not have enough memory available to add another printer queue. NERR_DestNoRoom 2157 The server does not have enough memory available to add another printer. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_DestInvalidState 2162 This operation cannot be performed on the print destination in its current state. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── destination in its current state. NERR_SpoolNoMemory 2165 A spooler memory allocation failure occurred. NERR_DriverNotFound 2166 The device driver specified has not been installed on the computer. NERR_DataTypeInvalid 2167 The datatype is not supported by the queue's print processor. NERR_ProcNotFound 2168 The print processor has not been installed on the server. NERR_BadDev 2341 The devicename is invalid because it does not represent a physical device, or because the device hardware is faulty. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── device hardware is faulty. NERR_CommDevInUse 2343 The device is already used with a communication-device queue. It cannot be used with both communication-device queues and printer queues. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks The PRQINFO data structure is provided only for compatibility with existing LAN Manager 1.0 applications. All new applications should use the PRQINFO3 data structure. If the specified queuename is already in use on the server, DosPrintQAdd fails unless the queue is marked for pending deletion. In this case, the queue is not deleted and the parameters provided in DosPrintQAdd are used to set the values of the queue configuration. (The queuename is specified by the szName element of the PRQINFO data structure or by the pszName element of the PRQINFO3 data structure.) If the queuename exceeds the maximum legal length, ERROR_INVALID_PARAMETER is returned. The maximum legal length depends on the installed file system. A queue can be added successfully even if it is not connected to a printer. A queue can be added successfully on an MS OS/2 1.2 workstation. Applications that use the level 3 data structure PRQINFO3 can specify that the queue should use the default pDriverData value by supplying a null pointer for the pDriverData parameter; a new pszDriverName element will be supplied. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Changing the parameters of a DosPrintQSetInfo printer queue Deleting a printer queue DosPrintQDel Listing a server's printer DosPrintQEnum queues Retrieving information about a DosPrintQGetInfo printer queue DosPrintQContinue ──────────────────────────────────────────────────────────────────────────── DosPrintQContinue allows a paused printer queue to resume printing. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintQContinue on a remote server or on a computer that has local security enabled. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintQContinue (PSZ pszServer, PSZ pszQueueName ); where pszServer Points to an ASCIIZ string that contains the name of a server on which to execute DosPrintQContinue. A null pointer or null string specifies the local computer. pszQueueName Points to an ASCIIZ string that contains the name of the printer queue. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_QNotFound 2150 The queuename specified is invalid. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_QInvalidState 2163 This operation cannot be performed on the printer queue in its current state. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── Remarks DosPrintQContinue reenables a printer queue that has been paused by a call to DosPrintQPause or disabled by an error. DosPrintQContinue does not affect an active printer queue. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing a server's printer DosPrintQEnum queues Pausing a printer queue DosPrintQPause Retrieving information about a DosPrintQGetInfo printer queue DosPrintQDel ──────────────────────────────────────────────────────────────────────────── DosPrintQDel deletes a printer queue from a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintQDel on a remote server or on a computer that has local security enabled. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintQDel (PSZ pszServer, PSZ pszQueueName ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintQDel. A null pointer or null string specifies the local computer. pszQueueName Points to an ASCIIZ string that specifies which printer queue to delete. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_QNotFound 2150 The queuename specified is invalid. NERR_SpoolerNotLoaded 2161 The spooler is not started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_QInvalidState 2163 This operation cannot be performed on the printer queue in its current state. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks If print jobs remain to be processed in a printer queue, DosPrintQDel marks the printer queue as "pending delete" so it cannot accept new jobs, and deletes the queue when all jobs have been printed. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Canceling all print jobs in a DosPrintQPurge printer queue Establishing a printer queue DosPrintQAdd Listing a server's printer DosPrintQEnum queues Retrieving information about a DosPrintQGetInfo printer queue DosPrintQEnum ──────────────────────────────────────────────────────────────────────────── DosPrintQEnum lists all printer queues on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level No special privilege level is required to successfully execute DosPrintQEnum. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintQEnum (PSZ pszServer, USHORT uLevel, PSZ pbBuf, USHORT cbBuf, PUSHORT pcReturned, PUSHORT pcTotal ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintQEnum. A null pointer or null string specifies the local computer. uLevel Specifies the level of detail (0, 1, 2, 3, 4, or 5) requested. pbBuf Points to the buffer in which to store the returned data. On a successful return, the buffer contains a sequence of data structures corresponding to the level of detail requested. cbBuf Specifies the size (in bytes) of the buffer pointed to by pbBuf. pcReturned Points to an unsigned short integer that specifies the number of entries returned in the buffer pointed to by pbBuf. This count is valid only if DosPrintQEnum returns NERR_Success or ERROR_MORE_DATA. pcTotal Points to an unsigned short integer that specifies the total number of entries available. This count is valid only if DosPrintQEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌──────────────────────┌───────┌────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks Levels 0, 1, and 2 are provided only for compatibility with existing LAN Manager 1.0 applications and should not be used in new applications. All new applications should use levels 3, 4, and 5. Levels 0, 1, and 2 return queuenames only if the number of bytes in the queuename is less than or equal to QNLEN. (The constant QNLEN is defined in the PMSPL.H header file.) At levels 0, 1, and 2, the values of pcReturned and pcTotal are set to the count of queues with short names. At levels 3, 4, and 5, all queuenames are returned, and the values pcReturned and pcTotal represent the count of all queues. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Retrieving information about a DosPrintQGetInfo printer queue DosPrintQGetInfo ──────────────────────────────────────────────────────────────────────────── DosPrintQGetInfo retrieves information about a particular printer queue on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level No special privilege level is required to successfully execute DosPrintQGetInfo. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintQGetInfo (PSZ pszServer, PSZ pszQueueName, USHORT uLevel, PSZ pbBuf, USHORT cbBuf, PUSHORT pcbNeeded ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintQGetInfo. A null pointer or null string specifies the local computer. pszQueueName Points to an ASCIIZ string that contains the name of the printer queue. uLevel Specifies the level of detail (0, 1, 2, 3, 4, or 5) requested. pbBuf Points to the buffer in which to store the return data. On a successful return, the buffer contains a sequence of data structures corresponding to the level of detail requested. cbBuf Specifies the size (in bytes) of the buffer pointed to by pbBuf. pcbNeeded Points to an unsigned short integer that specifies the number of bytes of information available. This count is valid only if DosPrintQGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_FILENAME_EXCED_RANGE 206 The filename specified is invalid for the file system. This code is returned when checking a FAT disk partition only. It cannot be returned for an HPFS partition. ERROR_MORE_DATA 234 Additional data is available. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_QNotFound 2150 The queuename specified is invalid. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── Remarks Levels 0, 1, and 2 are provided for compatibility with existing LAN Manager 1.0 applications and should not be used in new applications. All new applications should use levels 3, 4, and 5. Levels 0, 1, and 2 return queuenames only if the number of bytes in the queuename is less than or equal to QNLEN. (The constant QNLEN is defined in the PMSPL.H header file.) At levels 0, 1, and 2, the values of pcReturned and pcTotal are set to the count of queues with short names. At levels 3, 4, and 5, all queuenames are returned, and the values pcReturned and pcTotal represent the count of all queues. When a new data structure is directed to a server that runs an earlier version of LAN Manager (a down-level server), the elements uPriority, pszPrProc, and pszPrinters are given default values. The element pszPrProc points to the string "LM10," pszPrinters points to a list of port names separated by commas, and uPriority has the value PRJ_NO_PRIORITY. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Finding out a print job's DosPrintJobGetInfo position in a queue Listing a server's printer DosPrintQEnum queues Modifying the configuration of a DosPrintQSetInfo printer queue DosPrintQPause ──────────────────────────────────────────────────────────────────────────── DosPrintQPause pauses the operation of a printer queue, suspending processing of all print jobs except the current job. A paused queue accepts new jobs. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintQPause on a remote server or on a computer that has local security enabled. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintQPause (PSZ pszServer, PSZ pszQueueName ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintQPause. A null pointer or null string specifies the local computer. pszQueueName Points to an ASCIIZ string that specifies which printer queue to pause. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_QNotFound 2150 The queuename specified is invalid. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks Pausing a printer queue suspends processing of all print jobs in the queue except the job that is printing. A paused queue can accept submitted print jobs, but it holds them in the queue until a call to DosPrintQContinue allows the queue to resume printing. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Continuing a paused printer DosPrintQContinue queue Finding out the position of a DosPrintJobGetInfo print job in a printer queue Retrieving information about a DosPrintQGetInfo printer queue DosPrintQPurge ──────────────────────────────────────────────────────────────────────────── DosPrintQPurge removes all pending jobs in a printer queue, leaving only currently printing jobs. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintQPurge on a remote server or on a computer that has local security enabled. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintQPurge (PSZ pszServer, PSZ pszQueueName ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintQPurge. A null pointer or null string specifies the local computer. pszQueueName Points to an ASCIIZ string that specifies which printer queue to purge. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_QNotFound 2150 The queuename specified is invalid. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_InvalidComputer 2351 The specified computername is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── invalid. ──────────────────────────────────────────────────────────────────────────── Remarks DosPrintQPurge does not affect a print job already sent to a print destination. If a printer queue is pending deletion when DosPrintQPurge is called, the purge clears the way for the printer queue to be deleted at the end of the current printing. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing a server's printer DosPrintQEnum queues Listing the print jobs in a DosPrintQGetInfo printer queue Retrieving information about a DosPrintQGetInfo printer queue DosPrintQSetInfo ──────────────────────────────────────────────────────────────────────────── DosPrintQSetInfo modifies the configuration of a printer queue. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or print operator privilege is required to successfully execute DosPrintQSetInfo on a remote server or on a computer that has local security enabled. Syntax #define INCL_BASE #include <os2.h> #include <pmspl.h> #define INCL_NETERRORS #include <lan.h> SPLERR SPLENTRY DosPrintQSetInfo (PSZ pszServer, PSZ pszQueueName, USHORT uLevel, PSZ pbBuf, USHORT cbBuf, USHORT uParmNum ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute DosPrintQSetInfo. A null pointer or null string specifies the local computer. pszQueueName Points to an ASCIIZ string that specifies which printer queue is to be modified. uLevel Contains an unsigned short integer that specifies the level of detail (1 or 3) provided. pbBuf Points to the provided data structure or component. cbBuf Specifies the size (in bytes) of the buffer pointed to by pbBuf. uParmNum Specifies whether to set all printer queue information or to set only a part of it. If uParmNum is PARMNUM_ALL, pbBuf must point to a PRQINFO or PRQINFO3 data structure. If uParmNum is any other defined value, only one element of the printer queue information is changed, and pbBuf must point to a valid value for that element. Not all elements can be set. Only those elements that have a specific PARMNUM constant value defined can be set. The PMSPL.H header file defines these possible values for uParmNum: ╓┌─────────────────────────┌──────┌──────────────────────────────────────────╖ Element of PRQINFO and PRQINFO3 Code Value ──────────────────────────────────────────────────────────────────────────── PARMNUM_ALL 0 All elements. PRQ_PRIORITY_PARMNUM 2 uPriority PRQ_STARTTIME_PARMNUM 3 uStarttime PRQ_UNTILTIME_PARMNUM 4 uUntiltime PRQ_SEPARATOR_PARMNUM 5 pszSepFile PRQ_PROCESSOR_PARMNUM 6 pszPrProc PRQ_DESTINATIONS_PARMNUM 7 pszDestinations (level 1 only) PRQ_PARMS_PARMNUM 8 pszParms Element of PRQINFO and PRQINFO3 Code Value ──────────────────────────────────────────────────────────────────────────── PRQ_PARMS_PARMNUM 8 pszParms PRQ_COMMENT_PARMNUM 9 pszComment PRQ_PRINTERS_PARMNUM 12 pszPrinters (level 3 only) PRQ_DRIVERNAME_PARMNUM 13 pszDriverName (level 3 only) PRQ_DRIVERDATA_PARMNUM 14 pDriverData (level 3 only) ──────────────────────────────────────────────────────────────────────────── Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_RemoteOnly 2106 This operation can be performed Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_RedirectedPath 2117 The operation is invalid for a redirected resource. The devicename specified is assigned to a shared resource. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_QNotFound 2150 The queuename specified is invalid. NERR_DestNotFound 2152 The print destination was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── found. NERR_DestNoRoom 2157 The server does not have enough memory available to add another printer. NERR_SpoolerNotLoaded 2161 The spooler is not started. NERR_DestInvalidState 2162 This operation cannot be performed on the print destination in its current state. NERR_SpoolNoMemory 2165 A spooler memory allocation failure occurred. NERR_DriverNotFound 2166 The device driver specified has not been installed on the computer. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_DataTypeInvalid 2167 The datatype is not supported by the queue's print processor. NERR_ProcNotFound 2168 The print processor has not been installed on the server. NERR_BadDev 2341 The devicename is invalid because it does not represent a physical device, or because the device hardware is faulty. NERR_CommDevInUse 2343 The device is already used with a communication-device queue. It cannot be used with both communication-device queues and printer queues. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks The PRQINFO data structure is provided only for compatibility with existing LAN Manager 1.0 applications. All new applications should use the PRQINFO3 data structure. If the uPriority element of the PRQINFO3 data structure is set to PRQ_NO_PRIORITY, the queue priority is not changed. If a null pointer is provided for the pDriverData element of the PRQINFO3 data structure, the spooler provides the default driver data. When a new data structure is directed to a server that is running an earlier version of LAN Manager (a down-level server), the PRQ_DRIVERNAME_PARMNUM and PRQ_DRIVERDATA_PARMNUM parameter number codes are not supported. The function returns ERROR_NOT_SUPPORTED for these codes. If the entire structure is passed, these unsupported entries are ignored. The code PRQ_PRINTERS_PARMNUM is interpreted as PRQ_DESTINATIONS_PARMNUM, and commas that are used as delimiters are replaced by blanks. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Establishing a printer queue DosPrintQAdd Listing the printer queues on a DosPrintQEnum server Retrieving a print job's DosPrintJobGetId identification number Retrieving the configuration of DosPrintQGetInfo a printer queue Printer Queue Category Example /* NETPRQ.C -- a program demonstrating the DosPrintQ API functions. This sample program demonstrates how to add a printer queue using DosPrintQAdd, then pauses the queue using DosPrintQPause and calls DosPrintQGetInfo to display its status. The queue priority is modified using DosPrintQSetInfo, and the new priority is displayed using DosPrintQEnum. DosPrintQPurge is called to purge all jobs from the queue, and then DosPrintQContinue allows the paused printer queue to continue. DosPrintQDel deletes the printer queue. usage: netprj [-s \\server] [-l level] [-p priority] [-q queue] [-f flag] [-c comment] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). level = Level of detail. priority = Priority of the queue. queue = Name of the printer queue. flag = Flag to delete the queue; 0 = no, 1 = yes. comment = Queue's comment (enclose in quotes). API Used to... ================= ============================================ DosPrintQAdd Add a new printer queue DosPrintQContinue Continue a paused printer queue DosPrintQDel Delete the printer queue DosPrintQEnum List all printer queues available DosPrintQGetInfo Get specific info on a single printer queue DosPrintQPause Pause the printer queue DosPrintQPurge Delete all jobs from the printer queue DosPrintQSetInfo Set specific info for a single printer queue This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_BASE #include <os2.h> // MS OS/2 base header files #include <pmspl.h> // Print definitions #define INCL_NETERRORS #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include "samples.h" // Internal routine header file #define DEFAULT_BUFFER_SIZE 1024 #define MAX_BUFFER_SIZE 32768 #define DEFAULT_PRIORITY 9 #define NEW_PRIORITY 1 #define NEWCOMMENT "Print q built by example program" #define NEWQUEUENAME "PRINTQ0" void DisplayInfo(short sLevel, char *pbBuffer, unsigned short cEntries); void Usage(char *pszString); void main(int argc, char *argv[]) { char * pbBuffer; // Buffer for return data char * pszServer = ""; // Default to local computer char far * pszQueueName = NEWQUEUENAME; char far * pszComment = NEWCOMMENT; int iCount; // Index, loop counter PRQINFO3 prq3; // Level 3 data structure short sLevel = 3; // Level of detail unsigned uRet; // Return code unsigned short fDone; // Flag successful call unsigned short fDelete = TRUE; // Delete queue flag unsigned short cEntriesRead; // Count of entries read unsigned short cEntriesTotal; // Count of entries available unsigned short cbBuffer = 0; // Count of bytes read unsigned short cbBufferNeeded = 0; // Count of bytes needed unsigned short uPriority = NEW_PRIORITY;// Used to set queue for (iCount = 1; iCount < argc; iCount++) // Get command-line switches { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iCount]; break; case 'p': // -p priority uPriority = atoi(argv[++iCount]); break; case 'l': // -l level sLevel = atoi(argv[++iCount]); break; case 'q': // -q queuename pszQueueName = argv[++iCount]; break; case 'c': // -c comment pszComment = argv[++iCount]; break; case 'f': // -f flag deletion fDelete = atoi(argv[++iCount]); break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } // End for loop printf("\nPrint Queue Category API Examples\n"); //======================================================================== // DosPrintQAdd // // This API adds a printer queue to the specified server. //======================================================================== memset(&prq3, 0, sizeof(PRQINFO3)); // Initialize memory to zeros prq3.pszName = pszQueueName; // Set names prq3.uPriority = DEFAULT_PRIORITY; prq3.pszComment = pszComment; uRet = DosPrintQAdd(pszServer, // Servername 3, // Level (char far *)&prq3, // New printer structure sizeof(PRQINFO3)); // Size of buffer printf("DosPrintQAdd returned %u\n", uRet); if (uRet == NERR_Success) { printf("%Fs added to ", prq3.pszName); if ((pszServer == NULL) || (*pszServer == '\0')) printf("the local computer\n"); else printf("%s\n", pszServer); printf("Priority set to %hu\n", prq3.uPriority); } //======================================================================== // DosPrintQPause // // This API pauses the specified printer queue. //======================================================================== uRet = DosPrintQPause(pszServer, // Servername pszQueueName); // Queuename printf("DosPrintQPause returned %u\n", uRet); //======================================================================== // DosPrintQGetInfo // // This API returns information about a specific printer queue. //======================================================================== // Call with zero-length buffer, expect NERR_BufTooSmall uRet = DosPrintQGetInfo(pszServer, // Servername pszQueueName, // Queuename sLevel, // Call level NULL, // Buffer for info 0, // Size of buffer &cbBufferNeeded);// Required size if (uRet == NERR_BufTooSmall) { cbBuffer = cbBufferNeeded; pbBuffer = SafeMalloc(cbBuffer); // SafeMalloc() in samples.c uRet = DosPrintQGetInfo(pszServer, // Servername pszQueueName, // Queuename sLevel, // Call level pbBuffer, // Buffer for info cbBuffer, // Size of buffer &cbBufferNeeded); // Required size printf("DosPrintQGetInfo returned %u\n", uRet); if (uRet == NERR_Success) DisplayInfo(sLevel, pbBuffer, 1); // Show return data free(pbBuffer); } else printf("DosPrintQGetInfo returned %u\n", uRet); //======================================================================== // DosPrintQSetInfo // // This API controls print destination settings. DosPrintQSetInfo must // be called using level 1 or level 3. In this example, a single // element is set to the desired value. A program can also set all // elements by setting the parameter number code to PARMNUM_ALL. //======================================================================== prq3.uPriority = uPriority; // Disconnect using SetInfo uRet = DosPrintQSetInfo(pszServer, // Servername pszQueueName, // Queuename 3, // Call level (char far *)&(prq3.uPriority),// Data to set sizeof(USHORT), // Size of buffer PRQ_PRIORITY_PARMNUM); // Parameter number code printf("DosPrintQSetInfo returned %u\n", uRet); //======================================================================== // DosPrintQEnum // // This API lists all printers connected to the specified server. //======================================================================== cbBuffer = DEFAULT_BUFFER_SIZE; pbBuffer = SafeMalloc(cbBuffer); // SafeMalloc() is in samples.c do // Until buffer is big enough to succeed { uRet = DosPrintQEnum (pszServer, // Servername sLevel, // Call level pbBuffer, // Buffer for info cbBuffer, // Size of buffer &cEntriesRead, // Count of entries read &cEntriesTotal);// Count of entries available if (uRet == ERROR_MORE_DATA) { free(pbBuffer); // Buffer too small to hold data if (cbBuffer >= MAX_BUFFER_SIZE) exit(1); else if (cbBuffer > (MAX_BUFFER_SIZE/2)) cbBuffer = MAX_BUFFER_SIZE; else cbBuffer += cbBuffer; // Allocate a larger one and try again pbBuffer = SafeMalloc(cbBuffer); // SafeMalloc() in samples.c fDone = FALSE; } else fDone = TRUE; } while (fDone == FALSE); // Loop until buf big enough or call fails printf("DosPrintQEnum returned %u\n", uRet); if (uRet == NERR_Success) { printf("DosPrintQEnum read %hu ", cEntriesRead); printf(" out of %hu entries\n", cEntriesTotal); DisplayInfo(sLevel, pbBuffer, cEntriesRead); } free(pbBuffer); //===================================================================== // DosPrintQPurge // // This API deletes all jobs from the printer queue. //===================================================================== uRet = DosPrintQPurge(pszServer, // Servername pszQueueName); // Queuename printf("DosPrintQPurge returned %u\n", uRet); //===================================================================== // DosPrintQContinue // // This API allows a paused printer queue to continue. //===================================================================== uRet = DosPrintQContinue(pszServer, // Servername pszQueueName); // Queuename printf("DosPrintQContinue returned %u\n", uRet); //===================================================================== // DosPrintQDel // // This API deletes the printer queue. This sample program allows // a command-line switch that prevents deletion of the queue. //===================================================================== if (fDelete == TRUE) { uRet = DosPrintQDel(pszServer, // Servername pszQueueName); // Queuename printf("DosPrintQDel returned %u\n", uRet); } exit(0); } // End of main //===================================================================== // DisplayInfo // // Displays printer queue information obtained by DosPrintQGetInfo or // DosPrintQEnum. // // Level 0: Queuename // Level 1: PRQINFO data structure // Level 2: PRQINFO followed by PRJINFO for each job // Level 3: PRQINFO3 data structure // Level 4: PRQINFO3 followed by PRJINFO2 for each job // Level 5: Far pointer to queuename //===================================================================== void DisplayInfo(short sLevel, char *pbBuffer, unsigned short cEntries) { char * pprq0; // Level 0 data PPRQINFO pprq1; // Pointer to queue data provided at levels 1, 2 PPRJINFO pprj1; // Pointer to job data provided at level 2 PPRJINFO2 pprj2; // Pointer to job data provided at level 3 PPRQINFO3 pprq3; // Pointer to queue data provided at levels 3, 4 char far * far * pprq5; // Pointer to level 5 data unsigned short iCount, iJobs, cJobs; // Loop counters pprq0 = (char *) pbBuffer; // Initialize pointers pprq1 = (PPRQINFO) pbBuffer; pprq3 = (PPRQINFO3) pbBuffer; pprq5 = (char far * far *) pbBuffer; for (iCount = 1; iCount <= cEntries; iCount++) { printf("\n"); switch (sLevel) { case 0: // Level 0 data printf("Queue Name : %s\n", pprq0); pprq0 += (QNLEN + 1); break; case 1: // Level 1 data printf("Queue Name : %s\n", pprq1->szName); printf("Priority : %hu\n", pprq1->uPriority); printf("Comment : %Fs\n", pprq1->pszComment); printf("Jobs : %hu\n", pprq1->cJobs); printf("Queue Status: 0x%hx\n", pprq1->fsStatus); pprq1++; break; case 2: // Level 2 data printf("Queue Name : %s\n", pprq1->szName); printf("Priority : %hu\n", pprq1->uPriority); printf("Comment : %Fs\n", pprq1->pszComment); cJobs = pprq1->cJobs; printf("Jobs : %hu\n", cJobs); printf("Queue Status: 0x%hx\n", pprq1->fsStatus); pprq1++; pprj1 = (PPRJINFO) pprq1; for (iJobs = 0; iJobs < cJobs; iJobs++) { printf("\n"); printf(" Job Id : %hu\n", pprj1->uJobId); printf(" User Name : %s\n", pprj1->szUserName); printf(" Position : %hu\n", pprj1->uPosition); pprj1++; } pprq1 = (PPRQINFO) pprj1; break; case 3: // Level 3 data printf("Queue Name : %Fs\n", pprq3->pszName); printf("Priority : %hu\n", pprq3->uPriority); printf("Comment : %Fs\n", pprq3->pszComment); printf("Jobs : %hu\n", pprq3->cJobs); printf("Queue Status: 0x%hx\n", pprq3->fsStatus); pprq3++; break; case 4: // Level 4 data printf("Printer Name: %s\n", pprq3->pszName); printf("Priority : %hu\n", pprq3->uPriority); printf("Comment : %Fs\n", pprq3->pszComment); cJobs = pprq3->cJobs; printf("Jobs : %hu\n", cJobs); printf("Queue Status: 0x%hx\n", pprq3->fsStatus); pprq3++; // Skip queue data pprj2 = (PPRJINFO2)pprq3; // Examine job data for (iJobs = 0; iJobs < cJobs; iJobs++) { printf("\n"); printf(" Job Id : %hu\n", pprj2->uJobId); printf(" User Name : %Fs\n", pprj2->pszUserName); printf(" Priority : %hu\n", pprj2->uPriority); printf(" Document : %Fs\n", pprj2->pszDocument); pprj2++; // Bump to look at next print job structure } pprq3 = (PPRQINFO3) pprj2; // If next element, it is queue break; case 5: // Level 5 data printf("Queue Name : %Fs\n", *pprq5); pprq5++; break; default: // Undefined level break; } // End switch sLevel } // End for loop } // End function //===================================================================== // Usage // // Display possible command-line switches for this sample program. //===================================================================== void Usage(char *pszString) { fprintf(stderr, "Usage: %s [-s \\\\server] [-l level]", pszString); fprintf(stderr, " [-p priority]\n\t[-q queuename] [-f flag delete]"); fprintf(stderr, " [-c comment for queue]\n"); exit(1); } Remote Utility Category Remote Utility API functions enable applications to copy and move remote files, execute a program remotely, and access the time-of-day information on a remote server. They require that the Workstation service be running on the local computer. The Remote Utility category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and REMUTIL.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETREMUTIL, and including the master header file, LAN.H. For more information, see the "Example" section, later in this category. These are the Remote Utility API functions: ■ NetRemoteCopy ■ NetRemoteExec ■ NetRemoteMove ■ NetRemoteTOD Description NetRemoteCopy copies files on remote servers without copying the files physically to and from the local workstation. NetRemoteMove moves files or directories from one location to another on a remote server, without physically moving the data if the source and destination are on the same drive. If the source and destination are on different drives, the move takes place directly from source to destination, without moving the data to and from the local workstation. For both NetRemoteCopy and NetRemoteMove, the source and destination must be on the same server. NetRemoteExec executes a program on a remote server. It is similar to the DosExecPgm function, but NetRemoteExec is executed on a remote network server. For information about DosExecPgm, see your MS OS/2 programming manual(s). NetRemoteTOD returns time-of-day information from a remote server. Data Structures NetRemoteCopy returns a copy_info data structure. NetRemoteMove returns a move_info data structure. NetRemoteTOD returns a time_of_day_info data structure. NetRemoteExec does not use a data structure. File Copy Information The copy_info data structure has this format: struct copy_info { unsigned short ci_num_copied; char ci_err_buf[1]; }; where ci_num_copied Specifies the number of files copied. ci_err_buf Contains a variable-length ASCIIZ string that specifies error information about the file copy operation. File Move Information The move_info data structure has this format: struct move_info { unsigned short mi_num_moved; char mi_err_buf[1]; }; where mi_num_moved Specifies the number of files moved. mi_err_buf Contains a variable-length ASCIIZ string that specifies error information about the move operation. Time-of-Day Information The time_of_day_info data structure has this format: struct time_of_day_info { unsigned long tod_elapsedt; unsigned long tod_msecs; unsigned char tod_hours; unsigned char tod_mins; unsigned char tod_secs; unsigned char tod_hunds; unsigned short tod_timezone; unsigned short tod_tinterval; unsigned char tod_day; unsigned char tod_month; unsigned short tod_year; unsigned char tod_weekday; }; where tod_elapsedt Specifies the number of seconds elapsed since 00:00:00, January 1, 1970. tod_msecs Specifies the number of milliseconds from an arbitrary starting point (system reset). Typically, tod_msecs is read twice, once at the start of a process and again at the end, then subtracting one value from the other to determine how long that process took. tod_hours Specifies the current hour (0-23). tod_mins Specifies the current minute (0-59). tod_secs Specifies the current second (0-59). tod_hunds Specifies the current hundredth second (0.01 second) (0-99). tod_timezone Specifies the time zone of the server. This value is calculated (in minutes) from Greenwich Mean Time (GMT). For time zones west of Greenwich, the value is positive; for time zones east of Greenwich, the value is negative. A value of -1 indicates that the time zone is undefined. tod_tinterval Specifies the time interval for each tick of the clock. Each integral integer represents one ten-thousandth second (0.0001 second). tod_day Specifies the day of the month (1-31). tod_month Specifies the month of the year (1-12). tod_year Specifies the year. tod_weekday Specifies the day of the week (0-6, where 0 is Sunday, 1 is Monday, and so on). NetRemoteCopy ──────────────────────────────────────────────────────────────────────────── NetRemoteCopy copies one or more files from one location to another on a remote server. The source and destination for the file copy operation must be on the same server. Operating Systems Supported ■ MS OS/2 version 1.2, local only. The function can operate on remote files by using universal naming convention (UNC) paths or redirected drives. ■ MS OS/2 version 1.1, local only. The function can operate on remote files by using UNC paths or redirected drives. ■ MS-DOS, local only. The function can operate on remote files by using UNC paths or redirected drives. Privilege Level The execution privilege level for NetRemoteCopy depends on the access restrictions of the file(s) being accessed. Syntax #define INCL_NETREMUTIL #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetRemoteCopy (const char far * pszSourcePath, const char far * pszDestPath, const char far * pszSourcePasswd, const char far * pszDestPasswd, unsigned short fsOpen, unsigned short fsCopy, char far * pbBuffer, unsigned short cbBuffer ); where pszSourcePath Points to an ASCIIZ string that contains the pathname of the file(s) to be copied. This value can be expressed in UNC format or with a redirected drive letter. pszDestPath Points to an ASCIIZ string that contains the name of the path where the file specified by pszSourcePath is to be copied. When a wildcard is used for pszSourcePath, pszDestPath must be a directory. This value can be expressed in UNC format or with a redirected drive letter. pszSourcePasswd Points to an ASCIIZ string that contains the password needed to access the path specified by pszSourcePath. A null pointer indicates a password is not required. pszDestPasswd Points to an ASCIIZ string that contains the password needed to access the path specified by pszDestPath. A null pointer indicates a password is not required. fsOpen Specifies how to open pszDestPath. The REMUTIL.H header file defines these possible values: Bit(s) Meaning ──────────────────────────────────────────────────────────────────────────── 0-1 Used if pszDestPath exists. If 0, the open operation fails. If 1, the file is appended. If 2, the file is overwritten. 2-3 Reserved; must be 0. 4 Used if pszDestPath does not exist. If 0, the open operation fails. If 1, the file is created. 5-15 Reserved; must be 0. ──────────────────────────────────────────────────────────────────────────── fsCopy Specifies how the file copy operation is done. The REMUTIL.H header file defines these possible values: ╓┌─────────────┌─────────┌───────────────────────────────────────────────────╖ Code Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── MUST_BE_FILE 0x1 If 1, pszDestPath must be a file. MUST_BE_DIR 0x2 If 1, pszDestPath must be a directory. ASCII_DEST 0x4 If 0, pszDestPath is opened in binary mode. If 1, pszDestPath is opened in text mode. Code Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── pszDestPath is opened in text mode. ASCII_SOURCE 0x8 If 0, pszSourcePath is opened in binary mode. If 1, pszSourcePath is opened in text mode. VERIFY 0x10 If 1, all write operations are verified. ──────────────────────────────────────────────────────────────────────────── Note that the fsCopy parameter must not be set to both MUST_BE_FILE and MUST_BE_DIR at the same time. pbBuffer Points to the buffer in which to store the returned copy_info data structure. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_FILE_NOT_FOUND 2 The file was not found. ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NO_MORE_FILES 18 No more files are available. ERROR_SHARING_VIOLATION 32 A sharing violation occurred. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_FILE_EXISTS 80 The file already exists. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_NO_PROC_SLOTS 89 No process slots are available. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── started. NERR_BadSource 2381 The source path is invalid. NERR_BadDest 2382 The destination pathname does not exist. NERR_DifferentServers 2383 The source and destination paths are on different servers. ──────────────────────────────────────────────────────────────────────────── Remarks With NetRemoteCopy, both of the following cases are valid: ■ The source and destination are both files. The source file is copied to the destination file, subject to fsOpen and fsCopy limitations. ■ The source is a file or wildcard and the destination is a directory. The source file(s) is copied to the destination directory, subject to fsOpen and fsCopy limitations. If the remote server runs out of resources while processing the request, NetRemoteCopy returns ERROR_NO_PROC_SLOTS. Any files already transferred are not removed from the specified destination. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Moving remote files between NetRemoteMove servers Passwords for shared resources Share Category User passwords User Category NetRemoteExec ──────────────────────────────────────────────────────────────────────────── NetRemoteExec enables a remote server to execute a program located on that remote server. It is a network extension of the DosExecPgm function. The executed program runs on the computer connected to the caller's current drive. If the caller's current drive is on a remote server, the child process executes on that server. If the caller's current drive is a local drive, the child process executes locally. Operating Systems Supported ■ MS OS/2 version 1.2, local only. The function can operate on remote files by using redirected drives. ■ MS OS/2 version 1.1, local only. The function can operate on remote files by using redirected drives. ■ MS-DOS not supported. Privilege Level The execution privilege level for NetRemoteExec depends on the access restrictions of the file(s) being accessed. Syntax #define INCL_NETREMUTIL #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetRemoteExec (char far * pszReserved1, char far * pszFailName, unsigned cbFailName, unsigned fAsync, const char far * pszArgs, const char far * pszEnvs, char far * pReturnCodes, const char far * pszPgmName, char far * pszReserved2, unsigned short fsRemoteExec ); where pszReserved1 Reserved pointer; must be -1. pszFailName Points to a buffer into which a name is copied if NetRemoteExec cannot successfully load and start the specified program. The name is that of the object that failed, such as a dynamic-link library. cbFailName Specifies the size (in bytes) of the buffer pointed to by pszFailName. fAsync Specifies the asynchronous and trace flags. The MS OS/2 BSEDOS.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── EXEC_SYNC 0 Synchronous process. EXEC_ASYNC 1 Asynchronous process without result code. EXEC_ASYNCRESULT 2 Asynchronous process with result code. ──────────────────────────────────────────────────────────────────────────── pszArgs Points to a set of ASCIIZ strings that contain the arguments of the program to be executed. For programs to run with MS-DOS or MS OS/2, pszArgs should point to a string containing the program name, a NUL character, the program parameters (separated by spaces), and terminated by two NUL characters. pszEnvs Points to a set of ASCIIZ strings that specify environment variables and their current values. The set must be terminated by two NUL characters. The environment variable strings have this form: variable=value pReturnCodes Points to an MS OS/2 data structure (RESULTCODES) that contains the return codes that result from the file execution. This is the same data structure used with the DosExecPgm function. pszPgmName Points to an ASCIIZ string that contains the name and optional extension of the file to be executed. This name must not contain any path separators or a drive letter. The location of the program is determined by the runpath parameter set in the [netrun] section of the LANMAN.INI file on the remote server. pszReserved2 Reserved pointer; must be 0. fsRemoteExec Specifies the remote executable flags that control program execution. The REMUTIL.H header file defines the possible values, as follows. The REM_PIPE_MODE code has the value 1. This bit mask isolates the mode for standard input, as follows: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── REM_PIPE_MODE_MSG 0 Message mode pipe for standard input. REM_PIPE_MODE_CHAR 1 Character mode pipe for standard input. The REM_WAIT_MODE code has the value 2. This bit mask isolates the wait mode for the process, as follows: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── REM_WAIT_MODE_PROCESS 0 The DosCwait function waits for the child process to finish before returning. REM_WAIT_MODE_TREE 2 The DosCwait function waits for all spawned processes to finish before returning. The REM_SIGL_MODE code has the value 4. This bit mask isolates the mode for remote signals, as follows: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── REM_SIGL_MODE_MAP 0 Map SIGINTR and SIGBREAK to SIGKILL when sending remote standard signals. REM_SIGL_MODE_RAW 4 Send signals as received. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_FILE_NOT_FOUND 2 The file was not found. ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. NERR_RunSrvPaused 2385 The server is paused and cannot run a program or command. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── run a program or command. NERR_ErrCommRunSrv 2389 An error occurred when communicating with a run server. NERR_ErrorExecingGhost 2391 An error occurred when starting a background process. NERR_ShareNotFound 2392 The shared resource was not found. ──────────────────────────────────────────────────────────────────────────── Remarks NetRemoteExec requires that the LAN Manager Netrun service be running on the remote server. If this service is not running, NetRemoteExec returns ERROR_PATH_NOT_FOUND. If the Netrun service is running but the specified executable cannot be found on the run path, NetRemoteExec returns ERROR_FILE_NOT_FOUND. A process executed remotely inherits the following handles from the calling process: Handle Meaning ──────────────────────────────────────────────────────────────────────────── 0 Standard input (stdin). 1 Standard output (stdout). 2 Standard error (stderr). ──────────────────────────────────────────────────────────────────────────── When NetRemoteExec initiates an asynchronous process, the process identification (PID) returned to the first word of pReturnCodes is a valid local PID that represents the remote program. The PID can be used with any MS OS/2 function that accepts a PID as a parameter, such as DosFlagProcess (to send signals to the remote process), DosCWait (to wait for the remote process to exit), and DosKillProcess (to terminate the process). See Also For information about See ──────────────────────────────────────────────────────────────────────────── DosFlagProcess, DosCWait, MSOS/2 programming manual(s) DosKillProcess Executing a program DosExecPgm, in MSOS/2 programming manual(s) Listing the resources on a NetShareEnum server Listing the servers on the NetServerAdminCommand network Netrun service LAN Manager administrator's manual(s) NetRemoteMove ──────────────────────────────────────────────────────────────────────────── NetRemoteMove moves one or more files from one location to another on a remote server. The source and destination pathnames must be on the same server. Operating Systems Supported ■ MS OS/2 version 1.2, local only. The function can operate on remote files by using UNC paths or redirected drives. ■ MS OS/2 version 1.1, local only. The function can operate on remote files by using UNC paths or redirected drives. ■ MS-DOS, local only. The function can operate on remote files by using UNC paths or redirected drives. Privilege Level The execution privilege level for NetRemoteMove depends on the access restrictions of the file being moved. Syntax #define INCL_NETREMUTIL #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetRemoteMove (const char far * pszSourcePath, const char far * pszDestPath, const char far * pszSourcePasswd, const char far * pszDestPasswd, unsigned short fsOpen, unsigned short fsMove, char far * pbBuffer, unsigned short cbBuffer ); where pszSourcePath Points to an ASCIIZ string that contains the pathname of the file to be moved. Wildcards are acceptable. pszDestPath Points to an ASCIIZ string that contains the name of the path where the file specified by pszSourcePath is to be moved. If pszSourcePath is a wildcard, pszDestPath must be a directory. pszSourcePasswd Points to an ASCIIZ string that contains the password for the path specified by pszSourcePath. A null pointer means a password is not required. pszDestPasswd Points to an ASCIIZ string that contains the password for the path specified by pszDestPath. A null pointer means a password is not required. fsOpen Specifies how to open pszDestPath. The REMUTIL.H header file defines these possible values: Bit(s) Meaning ──────────────────────────────────────────────────────────────────────────── 0-1 Use if pszDestPath exists. If 0, the open fails. If 1, the file is appended. If 2, the file is overwritten. 2-3 Reserved; must be 0. 4 Use if pszDestPath does not exist. If 0, the open fails. If 1, the file is created. 5-15 Reserved; must be 0. ──────────────────────────────────────────────────────────────────────────── fsMove Specifies control for the file move. The REMUTIL.H header file defines these possible values: Code Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── MUST_BE_FILE 0x1 If 1, pszDestPath must be a file. MUST_BE_DIR 0x2 If 1, pszDestPath must be a directory. ──────────────────────────────────────────────────────────────────────────── Note that the fsMove parameter must not be set to both MUST_BE_FILE and MUST_BE_DIR at the same time. pbBuffer Points to the buffer in which to store the returned move_info data structure. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_FILE_NOT_FOUND 2 The file was not found. ERROR_PATH_NOT_FOUND 3 The path was not found. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NO_MORE_FILES 18 No more files are available. ERROR_SHARING_VIOLATION 32 A sharing violation occurred. ERROR_FILE_EXISTS 80 The file already exists. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_NO_PROC_SLOTS 89 No process slots are available. ERROR_MORE_DATA 234 Additional data is available. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_BadSource 2381 The source path is invalid. NERR_BadDest 2382 The destination pathname does not exist. NERR_DifferentServers 2383 The source and destination paths are on different servers. ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Remarks If the source and destination files are in the same directory, NetRemoteMove renames the source file. If they are in different directories, NetRemoteMove modifies the directory table accordingly. When the source and destination are on different drives, NetRemoteMove moves pszSourcePath to pszDestPath and then deletes pszSourcePath. With NetRemoteMove, both of the following cases are valid: ■ The source and destination are both files. The source file is copied to the destination file, subject to fsOpen and fsMove limitations. ■ The source is a file or wildcard and the destination is a directory. The source file(s) is copied to the destination directory, subject to fsOpen and fsMove limitations. If the remote server runs out of resources while processing the request, NetRemoteMove returns ERROR_NO_PROC_SLOTS. Any files already transferred are not removed from the specified destination. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Copying a file from one network NetRemoteCopy location to another NetRemoteTOD ──────────────────────────────────────────────────────────────────────────── NetRemoteTOD returns a server's time of day. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level No special privilege level is required to successfully execute NetRemoteTOD. Syntax #define INCL_NETREMUTIL #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetRemoteTOD (const char far * pszServer, char far * pbBuffer, unsigned short cbBuffer ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetRemoteTOD. A null pointer or null string specifies the local computer. pbBuffer Points to the buffer in which to store the returned time_of_day_info data structure. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. Return Codes ╓┌─────────────────────┌───────┌─────────────────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_BAD_NETPATH 53 The network path was not found. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remote Utility Category Example /* NETREM.C -- sample program demonstrating NetRemote API functions. This program executes the NetRemote APIs with the supplied parameters. To execute NetRemoteCopy: supply the parameters starting with -c. To execute NetRemoteMove: supply the parameters starting with -m. To execute NetRemoteExec: supply the parameters starting with -e. To execute NetRemoteTOD: supply a servername with a -ts switch. The source and destination for NetRemoteCopy and NetRemoteMove can be specified using either a UNC path or a redirected drive letter. NetRemoteExec is carried out on the computer connected to the current drive. NetRemoteTOD gets the current time from the specified server. usage: netrem [-cs copy source] [-cd copy dest] [-cf copy flag] [-co copy open] [-ms move source] [-md move dest] [-mf move flag] [-mo move open] [-ep executable] [-ea arguments] [-ts \\server] where copy source = Complete path of the source file or directory for NetRemoteCopy. copy dest = Complete path of the destination file or directory for NetRemoteCopy. copy flag = Copy flag for NetRemoteCopy. copy open = Open flag for NetRemoteCopy. move source = Complete path of the source file or directory for NetRemoteMove. move dest = Complete path of the destination file or directory for NetRemoteMove. move flag = Move flag for NetRemoteMove. move open = Open flag for NetRemoteMove. executable = Name of the program for NetRemoteExec. arguments = Argument string for NetRemoteExec. \\server = Name of the server for NetRemoteTOD. A servername must be preceded by two backslashes (\\). API Used to... ============= ===================================================== NetRemoteCopy Copy a file or directory on a remote server to another file or directory on a remote server NetRemoteMove Move a file or directory on a remote server to a new file or directory on a remote server NetRemoteExec Execute a program NetRemoteTOD Obtain time of day from a remote server This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETERRORS #define INCL_NETREMUTIL #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> // Define mnemonic bit masks for the functions to execute. #define DO_NONE 0 #define DO_COPY 0x01 #define DO_MOVE 0x02 #define DO_EXEC 0x04 #define DO_TOD 0x08 // Define mnemonic bit masks for copy and move flag words. #define REM_OPEN_APPEND 0x01 // If dest exists, append #define REM_OPEN_OVERWRITE 0x02 // If dest exists, overwrite #define REM_OPEN_CREATE 0x10 // If dest does not exist, create #define REM_ASYNCRESULT 0x02 // Equivalent of EXEC_ASYNCRESULT #define ARG_LEN 128 #define OBJ_LEN 64 void Usage(char *pszString); void main(int argc, char *argv[]) { char fToDo = DO_NONE; // NetRemote API to perform char achReturnCodes[OBJ_LEN]; // NetRemoteExec MS OS/2 ret codes char achObjectName[OBJ_LEN]; // NetRemoteExec object name char achArgs[ARG_LEN]; // NetRemoteExec argument string char achEnvs[ARG_LEN]; // NetRemoteExec environment string char * pszCopySrc = NULL; // Can be file or directory char * pszCopyDest = NULL; // Can be file or directory char * pszMoveSrc = NULL; // Can be file or directory char * pszMoveDest = NULL; // Can be file or directory char * pszPgmName = NULL; // Program to be executed char * pszArgs; // Arguments for program char * pszServer = NULL; // Time servername unsigned short fsCopy = 0; // Copy flag unsigned short fsMove = 0; // Move flag unsigned short fsCopyOpen = REM_OPEN_OVERWRITE | REM_OPEN_CREATE; unsigned short fsMoveOpen = REM_OPEN_OVERWRITE | REM_OPEN_CREATE; int iCount; // Index counter struct copy_info CopyBuf; // Return data from NetRemoteCopy struct move_info MoveBuf; // Return data from NetRemoteMove struct time_of_day_info TimeBuf; // Time-of-day struct in REMUTIL.H API_RET_TYPE uRet; // Return code from API calls for (iCount = 1; iCount < argc; iCount++) // Get command-line switches { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 'c': // -c copy fToDo |= DO_COPY; switch (tolower(*(argv[iCount]+2))) { case 's': // -cs copy source pszCopySrc = argv[++iCount]; break; case 'd': // -cd copy destination pszCopyDest = argv[++iCount]; break; case 'f': // -cf copy flag fsCopy = atoi(argv[++iCount]); break; case 'o': // -co copy open flag fsCopyOpen = atoi(argv[++iCount]); break; default: Usage(argv[0]); // Display usage and exit } break; case 'm': // -m move fToDo |= DO_MOVE; switch (tolower(*(argv[iCount]+2))) { case 's': // -ms move source pszMoveSrc = argv[++iCount]; break; case 'd': // -md move destination pszMoveDest = argv[++iCount]; break; case 'f': // -mf move flag fsMove = atoi(argv[++iCount]); break; case 'o': // -mo move open flag fsMoveOpen = atoi(argv[++iCount]); break; default: Usage(argv[0]); // Display usage and exit } break; case 'e': // -e exec fToDo |= DO_EXEC; switch (tolower(*(argv[iCount]+2))) { case 'p': // -ep exec executable program pszPgmName = argv[++iCount]; achArgs[0] = '\0'; // Set double NUL terminator achArgs[1] = '\0'; achEnvs[0] = '\0'; // Set double NUL terminator achEnvs[1] = '\0'; break; case 'a': // -ea exec argument string pszArgs = achArgs; strcpy(pszArgs, pszPgmName); // Program name pszArgs += strlen(pszArgs) + 1; // NUL terminator strcpy(pszArgs, argv[++iCount]); // Argument string pszArgs += strlen(pszArgs) + 1; // NUL terminator *pszArgs = '\0'; // Extra NUL break; default: Usage(argv[0]); // Display usage and exit } break; case 't': // -t time of day fToDo |= DO_TOD; if (tolower(*(argv[iCount]+2)) == 's') pszServer = argv[++iCount];// -ts servername else Usage(argv[0]); // Display usage and exit break; case 'h': default: Usage(argv[0]); // Display usage and exit } } else Usage(argv[0]); // Display usage and exit } if (fToDo == DO_NONE) { printf("No operation specified.\n"); Usage(argv[0]); // Display usage and exit } //======================================================================== // NetRemoteCopy // // This API copies a file or directory on the specified server. // The source is copied to the destination according to the flags. // Information about the operation is returned in the CopyBuf structure. //======================================================================== if (fToDo & DO_COPY) { uRet = NetRemoteCopy(pszCopySrc, // Source path pszCopyDest, // Destination path NULL, // No password for source path NULL, // No password for dest path fsCopyOpen, // Open flags fsCopy, // Copy flags (char far *)&CopyBuf, // Return data sizeof(struct copy_info));// Return data size, in bytes printf("NetRemoteCopy returned %u\n", uRet); if (uRet == NERR_Success) { printf(" Copied %s to %s\n",pszCopySrc, pszCopyDest); printf(" Files copied = %hu\n", CopyBuf.ci_num_copied); } } //======================================================================== // NetRemoteMove // // This API moves a file on the remote server. The source file is renamed // to the name specified by the destination file. After the operation, // only one file exists, and its name is the destination filename. //======================================================================== if (fToDo & DO_MOVE) { uRet = NetRemoteMove(pszMoveSrc, // Source path pszMoveDest, // Destination path NULL, // No password for source path NULL, // No password for dest path fsMoveOpen, // Open flags fsMove, // Move flags (char far *) &MoveBuf, // Return data sizeof(struct move_info)); // Return data size, in bytes printf("NetRemoteMove returned %u\n",uRet); if (uRet == NERR_Success) { printf(" Moved %s to %s\n", pszMoveSrc, pszMoveDest); printf(" Number of files moved = %hu\n",MoveBuf.mi_num_moved); } } //======================================================================== // NetRemoteExec // // This API executes the specified file on the computer connected // to the current drive. If the current drive is connected to a // remote server, the file is executed on that server. If the current // drive is local, the file is executed locally. When NETREM.EXE reads // the arguments for the NetRemoteExec call, it adds the name of the // program to be executed to the front of that program's argument string. //======================================================================== if (fToDo & DO_EXEC) { uRet = NetRemoteExec((char far *)-1L, // Reserved; must be -1 achObjectName, // Contains data if error OBJ_LEN, // Length of error data buffer REM_ASYNCRESULT, // Asynchronous with result code achArgs, // Argument strings achEnvs, // Environment strings achReturnCodes, // DosExecPgm return codes pszPgmName, // Program to execute NULL, // Reserved; must be NULL 0); // Remote exec flags if (uRet == NERR_Success) printf("\nNetRemoteExec executed %s\n", pszPgmName); else { printf("\nNetRemoteExec returned error %u\n", uRet); if (achObjectName[0] != '\0') printf(" Error buffer = %s\n", achObjectName); } } //======================================================================= // NetRemoteTOD // // This API obtains the time of day from the specified server. // The time-of-day structure is defined in the REMUTIL.H header file. //======================================================================= if (fToDo & DO_TOD) { uRet = NetRemoteTOD(pszServer, // Servername (char far *) &TimeBuf, // Data returned here sizeof(struct time_of_day_info)); // Size of buffer printf("NetRemoteTOD returned %u\n", uRet); if (uRet == NERR_Success) // Call completed OK { printf(" Time "); if ((pszServer != NULL) && (*pszServer != '\0')) printf("on server %s = ",pszServer); printf("%02u:%02u:%02u ", TimeBuf.tod_hours, TimeBuf.tod_mins, TimeBuf.tod_secs); printf("%02u/%02u/%u \n", TimeBuf.tod_month, TimeBuf.tod_day, TimeBuf.tod_year); } } exit(0); } void Usage(char * pszString) { printf("Usage: %s [-cs copy source] [-cd copy dest] [-cf copy flag]" " [-co copy open]\n\t [-ms move source] [-md move dest]" " [-mf move flag] [-mo move open]\n\t [-ep executable]" " [-ea arguments]\n\t [-ts \\\\server for TOD]\n", pszString); exit(1); } Server Category Server API functions perform administrative tasks on a local or remote server. They require that the Workstation service be started. NetServerAdminCommand, NetServerGetInfo, and NetServerSetInfo also require that the Server service be started on the specified server. The Server category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and SERVER.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETSERVER, and including the master header file, LAN.H. For more information, see the "Example" section, later in this category. These are the Server API functions: ■ NetServerAdminCommand ■ NetServerDiskEnum ■ NetServerEnum2 ■ NetServerGetInfo ■ NetServerSetInfo Description Any user or application with admin privilege on a local or remote server can perform administrative tasks on that server to control its operation, user access, and resource sharing. You can examine and modify low-level parameters that affect a server's operation by calling NetServerGetInfo and NetServerSetInfo. The parameters, elements of the server_info_X data structures (where X is 0, 1, 2, or 3, depending on the level of detail requested), take their default values from the [server] section of the LANMAN.INI file. Another way to change a server's operation is by using the LAN Manager net command. An application can call the NetServerAdminCommand function to execute a LAN Manager net command on a server. For a list of net commands (such as net use, net share, and net access), see your LAN Manager administrator's manual(s). NetServerEnum2 lists all visible servers of specific types in the specified domains. Visible servers are those servers that have not set the svX_hidden element of the server_info_X data structure, where X is 2 or 3. NetServerDiskEnum lists the local drives on the specified server. With MS-DOS, most Server category API functions can be executed only on a remote server. NetServerDiskEnum and NetServerEnum2 can be executed on either a local workstation or a remote server, but all other Server category API functions executed on a local workstation return the NERR_RemoteOnly error code. Data Structures NetServerGetInfo uses the server_info_X data structure, where X is 0, 1, 2, or 3, to return server configuration information. NetServerSetInfo allows the user to change server parameters in the server_info_X data structure, where X is 1, 2, or 3. NetServerEnum2 lists server information using the server_info_X data structure, where X is 0 or 1. NetServerDiskEnum returns a list of all disk drives on a server. The data is returned in the form of consecutive ASCIIZ strings. Each disk drive name string is terminated by a NUL character. The next disk drive name string starts in the byte immediately following the terminating NUL. Level 0 must be specified. Server Information (level 0) The server_info_0 data structure has this format: struct server_info_0 { char sv0_name[CNLEN + 1]; }; where sv0_name Specifies an ASCIIZ string that contains the name of a server. The constant CNLEN is defined in the NETCONS.H header file. Server Information (level 1) The server_info_1 data structure has this format: struct server_info_1 { char sv1_name[CNLEN + 1]; unsigned char sv1_version_major; unsigned char sv1_version_minor; unsigned long sv1_type; char far * sv1_comment; }; where sv1_name Contains an ASCIIZ string that specifies the name of a server. The constant CNLEN is defined in the NETCONS.H header file. sv1_version_major The least significant nibble (rightmost nibble) specifies the major release version number of LAN Manager. The most significant nibble (leftmost nibble) specifies server type. The bits have the following values: Code Value Bits Meaning ──────────────────────────────────────────────────────────────────────────── MAJOR_VERSION_MASK 0x0F 0-3 Major version number. ─ 0x10 4-7 Unlimited server. ─ 0x10 4-7 Limited server. ─ 0x20 4-7 Peer server. ──────────────────────────────────────────────────────────────────────────── The mask MAJOR_VERSION_MASK, defined in the SERVER.H header file, should be used to ensure correct results. sv1_version_minor Specifies the minor release version number of LAN Manager. sv1_type Specifies the type of software the computer is running. The SERVER.H header file defines these possible values: ╓┌───────────────────────┌───────────┌───────────────────────────────────────╖ Code Bit Mask Type of Software ──────────────────────────────────────────────────────────────────────────── SV_TYPE_WORKSTATION 0x00000001 Workstation. SV_TYPE_SERVER 0x00000002 Server. SV_TYPE_SQLSERVER 0x00000004 SQL server. SV_TYPE_DOMAIN_CTRL 0x00000008 Primary domain controller. SV_TYPE_DOMAIN_BAKCTRL 0x00000010 Backup domain controller. SV_TYPE_TIME_SOURCE 0x00000020 Time server. SV_TYPE_AFP 0x00000040 Apple(R) File Protocol (AFP) service. Code Bit Mask Type of Software ──────────────────────────────────────────────────────────────────────────── SV_TYPE_AFP 0x00000040 Apple(R) File Protocol (AFP) service. SV_TYPE_NOVELL 0x00000080 Novell(R) service. SV_TYPE_ALL 0xFFFFFFFF All types of servers. ──────────────────────────────────────────────────────────────────────────── sv1_comment Points to an ASCIIZ string that contains a comment describing the server. The comment can be a null string or a null pointer. Server Information (level 2) The server_info_2 data structure has this format: struct server_info_2 { char sv2_name[CNLEN+1]; unsigned char sv2_version_major; unsigned char sv2_version_minor; unsigned long sv2_type; char far * sv2_comment; unsigned long sv2_ulist_mtime; unsigned long sv2_glist_mtime; unsigned long sv2_alist_mtime; unsigned short sv2_users; unsigned short sv2_disc; char far * sv2_alerts; unsigned short sv2_security; unsigned short sv2_auditing; unsigned short sv2_numadmin; unsigned short sv2_lanmask; unsigned short sv2_hidden; unsigned short sv2_announce; unsigned short sv2_anndelta; char sv2_guestacct[UNLEN + 1]; unsigned char sv2_pad1; char far * sv2_userpath; unsigned short sv2_chdevs; unsigned short sv2_chdevq; unsigned short sv2_chdevjobs; unsigned short sv2_connections; unsigned short sv2_shares; unsigned short sv2_openfiles; unsigned short sv2_sessopens; unsigned short sv2_sessvcs; unsigned short sv2_sessreqs; unsigned short sv2_opensearch; unsigned short sv2_activelocks; unsigned short sv2_numreqbuf; unsigned short sv2_sizreqbuf; unsigned short sv2_numbigbuf; unsigned short sv2_numfiletasks; unsigned short sv2_alertsched; unsigned short sv2_erroralert; unsigned short sv2_logonalert; unsigned short sv2_accessalert; unsigned short sv2_diskalert; unsigned short sv2_netioalert; unsigned short sv2_maxauditsz; char far * sv2_srvheuristics; }; where sv2_name through sv2_comment Are the same as the corresponding elements in the server_info_1 data structure. For a complete description, see the preceding section. sv2_ulist_mtime Specifies the time when the user list (for a server that has user-level security) was last modified. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. sv2_glist_mtime Specifies the time when the group list (for a server that has user-level security) was last modified. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. sv2_alist_mtime Specifies the time when the access control list (for a server that has user-level security) was last modified. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. sv2_users Specifies how many users are allowed on the server. sv2_disc Specifies the time (in minutes) when the session is automatically disconnected. A session is disconnected if it is idle longer than the time specified by sv2_disc. If sv2_disc is SV_NODISC, the autodisconnect feature is not enabled. sv2_alerts Points to an ASCIIZ string that contains the usernames listed in the server's alert table. The usernames are separated by spaces. sv2_security Specifies the security type of the server. The SERVER.H header file defines these possible values: Code Value Type of Security ──────────────────────────────────────────────────────────────────────────── SV_SHARESECURITY 0 Share-level. SV_USERSECURITY 1 User-level. ──────────────────────────────────────────────────────────────────────────── sv2_auditing Specifies whether auditing is enabled on the server. If sv_auditing is 0, auditing is disabled. If it is any other defined value, the server audits LAN Manager activities. For more information about auditing, see the Auditing category API functions. sv2_numadmin Specifies how many users with admin privilege can administer the server at the same time. sv2_lanmask Indicates the network device drivers active on this server. Each bit corresponds to an entry in the [networks] section of the LANMAN. INI file. If sv2_lanmask is 0, the network device driver is not active. If it is 1, the network device driver is active. sv2_hidden Specifies whether the server is visible to other computers in the same network domain. The SERVER.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── SV_VISIBLE 0 Server is visible. SV_HIDDEN 1 Server is hidden (not visible). ──────────────────────────────────────────────────────────────────────────── sv2_announce Specifies the network announce rate (in seconds). This value and the value of sv2_anndelta determine how often the server is announced to other computers on the network. sv2_anndelta Specifies the delta, or change, of the announce rate (in milliseconds). This value specifies how much the announce rate can vary from the time specified in sv2_announce. The delta value allows randomly varied announce rates. For example, if sv2_announce has the value 10, and sv2_anndelta has the value 1, the announce rate can vary from 9.999 seconds to 10.001 seconds. sv2_guestacct Specifies an ASCIIZ string that contains the name of the reserved guests account on a server. The constant UNLEN is defined in the NETCONS.H header file. sv2_pad1 Aligns the next data structure element on a word boundary. sv2_userpath Points to an ASCIIZ string that contains the pathname to user directories. sv2_chdevs Specifies how many communication devices can be shared on the server at any one time. sv2_chdevq Specifies how many communication-device queues can be defined on the server at any one time. sv2_chdevjobs Specifies how many communication device jobs can be pending on a server. sv2_connections Specifies how many connections to sharenames are allowed on a server. sv2_shares Specifies how many sharenames can be defined on the server at any one time. sv2_openfiles Specifies how many files can be open at any one time on the server. sv2_sessopens Specifies how many files can be open per session. sv2_sessvcs Specifies how many virtual circuits are allowed for each client process. sv2_sessreqs Specifies how many simultaneous requests a client process can make. sv2_opensearch Specifies how many searches can be open at any one time. sv2_activelocks Specifies how many file locks can be active at any one time. sv2_numreqbuf Specifies how many server buffers are provided. sv2_sizreqbuf Specifies the size (in bytes) of each server buffer. sv2_numbigbuf Specifies how many 64K server buffers are provided. sv2_numfiletasks Specifies how many server processes can perform file I/O simultaneously. sv2_alertsched Specifies the alert interval (in minutes) for notifying an administrator of a network event. sv2_erroralert Specifies how many entries can be written to the error log during a sv2_alertsched interval before an administrator is notified. sv2_logonalert Specifies how many invalid logon attempts can be made before an administrator is notified. sv2_accessalert Specifies how many invalid file accesses can be made before an administrator is notified. sv2_diskalert Specifies at what point (the number of kilobytes of free disk space) an administrator should be notified that available space on a disk is low. sv2_netioalert Specifies the network I/O error ratio (in tenths of a percent) to allow before an administrator is notified. sv2_maxauditsz Specifies the maximum audit file size (in kilobytes). sv2_srvheuristics Points to an ASCIIZ string of flags used to control a server's operations and optimize server performance. The server heuristics are 20 digits that configure how a server processes network requests. Digits read from left (0) to right (19). For a complete description of these digits, see Appendix G, "Workstation and Server Heuristics." Server Information (level 3) The server_info_3 data structure has this format: struct server_info_3 { char sv3_name[CNLEN+1]; unsigned char sv3_version_major; unsigned char sv3_version_minor; unsigned long sv3_type; char far * sv3_comment; unsigned long sv3_ulist_mtime; unsigned long sv3_glist_mtime; unsigned long sv3_alist_mtime; unsigned short sv3_users; unsigned short sv3_disc; char far * sv3_alerts; unsigned short sv3_security; unsigned short sv3_auditing; unsigned short sv3_numadmin; unsigned short sv3_lanmask; unsigned short sv3_hidden; unsigned short sv3_announce; unsigned short sv3_anndelta; char sv3_guestacct[UNLEN + 1]; unsigned char sv3_pad1; char far * sv3_userpath; unsigned short sv3_chdevs; unsigned short sv3_chdevq; unsigned short sv3_chdevjobs; unsigned short sv3_connections; unsigned short sv3_shares; unsigned short sv3_openfiles; unsigned short sv3_sessopens; unsigned short sv3_sessvcs; unsigned short sv3_sessreqs; unsigned short sv3_opensearch; unsigned short sv3_activelocks; unsigned short sv3_numreqbuf; unsigned short sv3_sizreqbuf; unsigned short sv3_numbigbuf; unsigned short sv3_numfiletasks; unsigned short sv3_alertsched; unsigned short sv3_erroralert; unsigned short sv3_logonalert; unsigned short sv3_accessalert; unsigned short sv3_diskalert; unsigned short sv3_netioalert; unsigned short sv3_maxauditsz; char far * sv3_srvheuristics; unsigned long sv3_auditedevents; unsigned short sv3_autoprofile; char far * sv3_autopath; }; where sv3_name through sv3_srvheuristics Are the same as the corresponding elements of the server_info_2 data structure. For a complete description, see the preceding section. sv3_auditedevents Specifies the audit event control mask. Bits 18 through 31 are reserved. Bits 0 through 16 have the following meaning: ╓┌──────────────┌─────────┌──────────────────────────────────────────────────╖ Event Name Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── service 0x0001 Disable auditing of service state changes. goodsesslogon 0x0006 Disable auditing of successful session logon requests. badsesslogon 0x0018 Disable auditing of failed session logon requests. Event Name Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── badsesslogon 0x0018 Disable auditing of failed session logon requests. sesslogon 0x001E Disable auditing of all session logon/logoff attempts. goodnetlogon 0x0060 Disable auditing of successful network logon requests. badnetlogon 0x0180 Disable auditing of failed network logon requests. netlogon 0x01E0 Disable auditing of all network logon/logoff attempts. logon 0x01FE Disable auditing of all logon/logoff attempts (network and session). This mask produces the same effect as goodnetlogon/badnetlogon and goodsesslogon/badsesslogon masks. gooduse 0x0600 Disable auditing of successful requests to use a Event Name Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── gooduse 0x0600 Disable auditing of successful requests to use a shared resource. baduse 0x0800 Disable auditing of failed attempts to access a shared resource. use 0x1E00 Disable auditing of all access requests to a shared resource regardless of gooduse or baduse masks. This mask produces the same effect as both the gooduse/baduse masks. userlist 0x2000 Disable auditing of changes to the user/domain account database. permissions 0x4000 Disable auditing of changes to the access control list (ACL) database. resource 0x8000 Disable auditing of resource access as defined by the per-resource auditing options, specified in Event Name Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── the per-resource auditing options, specified in the ACL. logonlimit 0x10000 Disable auditing of logon limit violations. ──────────────────────────────────────────────────────────────────────────── sv3_autoprofile Controls how the server acts on the profile. The SERVER.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── SW_AUTOPROF_LOAD_MASK 0x1 Server loads the profile. SW_AUTOPROF_SAVE_MASK 0x2 Server saves the profile. ──────────────────────────────────────────────────────────────────────────── Both flags can be set simultaneously. sv3_autopath Points to the pathname for the profile. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Domains LAN Manager administrator's manual(s) Remote administration of net LAN Manager administrator's manual(s) commands NetServerAdminCommand ──────────────────────────────────────────────────────────────────────────── NetServerAdminCommand executes a command on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege is required to successfully execute NetServerAdminCommand on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETSERVER #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetServerAdminCommand (const char far * pszServer, const char far * pszCommand, short far * psResult, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbReturned, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetServerAdminCommand. A null pointer or null string specifies the local computer. pszCommand Points to an ASCIIZ string that contains the command string to execute on the specified server. psResult Points to the returned exit code of the command executed on the specified server. pbBuffer Points to a buffer in which a string that contains the output returned by the command executed on the specified server is returned. cbBuffer Specifies the size (in bytes) of the buffer pointed to by pbBuffer. pcbReturned Points to an unsigned short integer that specifies the number of bytes returned in the buffer pointed to by pbBuffer. pcbTotalAvail Points to an unsigned short integer that specifies the number of bytes of return information available. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_NAME 123 The character or file system name is invalid. ERROR_FILENAME_EXCED_RANGE 206 The filename specified is invalid for the file system. This code is returned when Code Value Meaning ──────────────────────────────────────────────────────────────────────────── This code is returned when checking a FAT disk partition only. It cannot be returned for an HPFS partition. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_NoRoom 2119 The server could not access enough of a resource, such as memory, to complete the task. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── memory, to complete the task. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_ExecFailure 2315 A failure occurred when executing a remote administration command, probably because of a problem with the server's operating system configuration. NERR_TmpFile 2316 A failure occurred when opening a remote temporary file. NERR_TooMuchData 2317 The data returned from a remote Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_TooMuchData 2317 The data returned from a remote administration command was truncated to 64K. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks NetServerAdminCommand is a remote form of the C-library system function. The command string pointed to by pszCommand can contain multiple commands linked by the following characters, as recognized by the operating system command shell: & && | || ; If multiple commands are specified, only the output of the last command is returned in the buffer pointed to by pbBuffer. If executed remotely, NetServerAdminCommand sets the server environment as follows: ■ The default drive and directory is LANMAN\NETPROG. ■ The PATH environment variable is set to no path. If executed locally, NetServerAdminCommand uses the following: ■ Current drive and directory of the caller. ■ Server's default PATH variable. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Executing a program on a remote NetRemoteExec server Listing available servers NetServerEnum2 NetServerDiskEnum ──────────────────────────────────────────────────────────────────────────── NetServerDiskEnum retrieves a list of disk drives on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, local and remote Privilege Level Admin privilege or server operator privilege is required to successfully execute NetServerDiskEnum on a remote computer. No special privilege is required for local calls. Syntax #define INCL_NETSERVER #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetServerDiskEnum (const char far * pszServer, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetServerDiskEnum. A null pointer or null string specifies the local computer. sLevel Specifies the level of detail requested; must be 0. pbBuffer Points to consecutive ASCIIZ strings that specify the returned list of disk drive names. Each disk drive name string is terminated by the character NUL. The next disk drive name string, if defined, starts in the byte immediately following the terminating NUL. The list is terminated by a null string. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer in which a count of the number of disk drive name strings enumerated in the buffer is returned. This count is valid only if NetServerDiskEnum returns NERR_Success or ERROR_MORE_DATA. pcTotalAvail Points to an unsigned short integer in which a count of the total number of disk drive names available is returned. This count is valid only if NetServerDiskEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_WkstaNotStarted 2138 The Workstation service is not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks NetServerDiskEnum returns a list of local drive names for the specified server. The drive names in the list are consecutive strings, each containing a drive letter, a colon (:), and the character NUL that terminates the ASCIIZ string. For example, NetServerDiskEnum returns the following consecutive strings for a server with two floppy drives (A and B), one hard drive (C), and one RAM drive (E): A:\0B:\0C:\0E:\0\0 NetServerDiskEnum works locally even if the server has not been started. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing a server's shared NetShareEnum resources Listing available servers NetServerEnum2 NetServerEnum2 ──────────────────────────────────────────────────────────────────────────── NetServerEnum2 lists all servers of the specified type(s) that are visible in the specified domain(s). For example, an application can call NetServerEnum2 to list all domain controllers only or all SQL servers only. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, local and remote Privilege Level No special privilege level is required to successfully execute NetServerEnum2. Syntax #define INCL_NETSERVER #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetServerEnum2 (const char far * pszServer, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalAvail, unsigned long flServerType, char far * pszDomain ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetServerEnum2. A null pointer or string specifies the local computer. sLevel Specifies the level of detail (0 or 1) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a sequence of server_info_X data structures, where X is 0 or 1, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer in which a count of the number of servers enumerated in the buffer is returned. This count is valid only if NetServerEnum2 returns NERR_Success or ERROR_MORE_DATA. pcTotalAvail Points to an unsigned short integer in which a count of the total number of available entries is returned. This count is valid only if NetServerEnum2 returns NERR_Success or ERROR_MORE_DATA. flServerType Specifies the type(s) of servers to enumerate. The flServerType parameter is tested against the svX_type element of each entry. Entries that match at least one of the specified bits are included in the entries returned in the buffer and in the counts returned in pcEntriesRead and pcTotalAvail. The SERVER.H header file defines these flag bits: ╓┌───────────────────────┌───────────┌───────────────────────────────────────╖ Code Bit Mask Type of Software ──────────────────────────────────────────────────────────────────────────── SV_TYPE_WORKSTATION 0x00000001 Workstation. SV_TYPE_SERVER 0x00000002 Server. SV_TYPE_SQLSERVER 0x00000004 SQL server. SV_TYPE_DOMAIN_CTRL 0x00000008 Domain controller. Code Bit Mask Type of Software ──────────────────────────────────────────────────────────────────────────── SV_TYPE_DOMAIN_CTRL 0x00000008 Domain controller. SV_TYPE_DOMAIN_BAKCTRL 0x00000010 Backup domain controller. SV_TYPE_TIME_SOURCE 0x00000020 Time server. SV_TYPE_AFP 0x00000040 Apple File Protocol (AFP) service. SV_TYPE_NOVELL 0x00000080 Novell service. SV_TYPE_ALL 0xFFFFFFFF All types of servers. ──────────────────────────────────────────────────────────────────────────── pszDomain Points to an ASCIIZ string that contains the name of the domain in which to enumerate servers of the specified type(s). The specified domain must be the primary domain, the logon domain, or a domain listed as one of the other domains for the computer specified by pszServer. (The domain name must appear in the wkiX_langroup, wkiX_logon_domain, or wkiX_oth_domains element of the wksta_info_X workstation data structure, where X is the level of detail specified.) If the domain does not meet these conditions, NetServerEnum2 returns NERR_NotLocalDomain. If pszDomain is a null string or a null pointer, servers are enumerated for the primary domain, logon domain, and other domains. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_ServerNotStarted 2114 The Server service is not started. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BrowserNotStarted 2139 The mailslots entry of the workstation's LANMAN.INI file is incorrect. NERR_InvalidAPI 2142 The requested API is not supported on the remote server. NERR_BrowserTableIncomplete 2319 The information in the list of servers may be incorrect. NERR_NotLocalDomain 2320 The computer is not active in this domain. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── this domain. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks If SV_TYPE_NOVELL or SV_TYPE_AFP is specified in the flServerType parameter, all servers running a service called "NOVELL" or "AFP," respectively, will be listed. If the workstation has been started with the mailslots = no entry in the LANMAN.INI file, NetServerEnum2 returns the NERR_BrowserNotStarted error code. NetServerEnum2 supersedes NetServerEnum (used in earlier versions of LAN Manager). These functions are the same except that NetServerEnum2 includes the flServerType and pszDomain parameters, which specify the type of server and the domain in which to enumerate that type of server. For more information, see Appendix B, "Upgrading LAN Manager 1.0 Applications." NetServerGetInfo ──────────────────────────────────────────────────────────────────────────── NetServerGetInfo retrieves information about the specified server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or accounts, comm, print, or server operator privilege is required to successfully execute NetServerGetInfo at levels 2 or 3 on a remote server or on a computer that has local security enabled. No special privilege is required for level 0 or level 1 calls. Syntax #define INCL_NETSERVER #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetServerGetInfo (const char far * pszServer, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetServerGetInfo. A null pointer or null string specifies the local computer. sLevel Specifies the level of detail (0, 1, 2, or 3) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a server_info_X data structure, where X is 0, 1, 2, or 3, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the buffer pointed to by pbBuffer. pcbTotalAvail Points to an unsigned short integer in which a count of the total number of bytes of information available is returned. This count is valid only if NetServerGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_BufTooSmall 2123 The supplied buffer is too small. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Configuring a server NetServerSetInfo NetServerSetInfo ──────────────────────────────────────────────────────────────────────────── NetServerSetInfo sets a server's operating parameters; it can set them individually or collectively. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or server operator privilege is required to successfully execute NetServerSetInfo on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETSERVER #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetServerSetInfo (const char far * pszServer, short sLevel, const char far * pbBuffer, unsigned short cbBuffer, short sParmNum ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetServerSetInfo. A null pointer or null string specifies the local computer. sLevel Specifies the level of detail (1, 2, or 3) provided in the buffer pointed to by pbBuffer. pbBuffer Points to the data to be set. cbBuffer Specifies the size (in bytes) of the buffer pointed to by pbBuffer. sParmNum Specifies whether to set all the server information or to change only a part of it. If sParmNum is PARMNUM_ALL, pbBuffer must point to a server_info_X data structure (where X is 1, 2, or 3, depending on the level of detail being set). If sParmNum is any other defined value, only one element of the server information is changed, and pbBuffer must point to a valid value for that element. Not all elements can be set. Only those elements that have a specific PARMNUM constant value defined can be set. The SERVER.H header file defines these possible values for sParmNum: ╓┌───────────────────────┌──────┌────────────────────────────────────────────╖ Code Value Element of server_info_X ──────────────────────────────────────────────────────────────────────────── PARMNUM_ALL 0 All elements. SV_COMMENT_PARMNUM 5 svX_comment SV_DISC_PARMNUM 10 svX_disc SV_ALERTS_PARMNUM 11 svX_alerts SV_HIDDEN_PARMNUM 16 svX_hidden SV_ANNOUNCE_PARMNUM 17 svX_announce SV_ANNDELTA_PARMNUM 18 svX_anndelta SV_ALERTSCHED_PARMNUM 37 svX_alertsched SV_ERRORALERT_PARMNUM 38 svX_erroralert SV_LOGONALERT_PARMNUM 39 svX_logonalert Code Value Element of server_info_X ──────────────────────────────────────────────────────────────────────────── SV_LOGONALERT_PARMNUM 39 svX_logonalert SV_ACCESSALERT_PARMNUM 40 svX_accessalert SV_DISKALERT_PARMNUM 41 svX_diskalert SV_NETIOALERT_PARMNUM 42 svX_netioalert SV_MAXAUDITSZ_PARMNUM 43 svX_maxauditsz ──────────────────────────────────────────────────────────────────────────── Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_NoRoom 2119 The server could not access Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_NoRoom 2119 The server could not access enough of a resource, such as memory, to complete the task. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Remote calls Chapter 1, "Overview of the LAN Manager API" Retrieving information about the NetServerGetInfo configuration of a server Server Category Example /* NETSERV.C -- a sample program demonstrating NetServer API functions. usage: netserv [-s \\servername] [-c comment] [-l level] [-t type] [-a admin command] [-d domain] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). comment = New comment for the server. level = Level of detail to be provided/supplied. type = Types of servers to enumerate. admin command = Command line for remote admin. domain = List of domains to count. API Used to... ===================== ============================================ NetServerGetInfo Return information about the server configuration NetServerSetInfo Change the configuration of the server NetServerEnum2 List the servers visible on the network NetServerDiskEnum List the disk drives on the server NetServerAdminCommand Execute a sequence of commands on the server This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_BASE #include <os2.h> // MS OS/2 base header files #define INCL_NETERRORS #define INCL_NETSERVER #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include <malloc.h> #include "samples.h" // Internal routine header file #define A_CMD_STRING "c: & cd \\ & dir" #define A_COMMENT "This is a new comment" #define BIG_BUFFER_SIZE 32768 void Usage(char *pszString); void main(int argc, char * argv[]) { char * pszServer = ""; // NULL or null string = local char * pbBuffer; // Pointer to data buffer char * pszDisk; // Return string NetServerDiskEnum char * pszComment = A_COMMENT; // New comment string char * pszCommand = A_CMD_STRING; // Cmd for NetServerAdminCommand char far * pszDomain = NULL; // Input to NetServerEnum2 int iCount; // Index and loop counter short sLevel = 0; // Level of detail requested API_RET_TYPE uReturnCode; // API return code unsigned short usRemoteRetCode; // Return code of remote command unsigned short cbBuffer; // Size of buffer, in bytes unsigned short cEntriesRead; // Count of records returned unsigned short cTotalEntries; // Count of records available unsigned short cbReturned; // Count of bytes returned unsigned short cbTotalAvail; // Count of bytes available unsigned long flServerType = SV_TYPE_SERVER; // List of servers struct server_info_0 *pServer0; // Pointer to level 0 structure struct server_info_1 *pServer1; // Pointer to level 1 structure struct server_info_2 *pServer2; // Pointer to level 2 structure struct server_info_3 *pServer3; // Pointer to level 3 structure for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iCount]; break; case 'a': // -a admin command pszCommand = argv[++iCount]; break; case 'c': // -c comment pszComment = argv[++iCount]; break; case 'l': // -l level sLevel = (short)(atoi(argv[++iCount])); break; case 'd': // -d domain pszDomain = argv[++iCount]; break; case 't': // -t type flServerType = (unsigned long)(atoi(argv[++iCount])); break; default: Usage(argv[0]); } } else Usage(argv[0]); } // End for loop //======================================================================== // NetServerGetInfo // // This API returns information about the server's configuration // components. The returned data reflects the current configuration, // including any modifications made by calls to NetServerSetInfo. // The results returned by this API will not necessarily match the // contents of the LANMAN.INI file; use NetConfigGet2 to get the // default values stored in the LANMAN.INI file. //======================================================================== /* * The structure returned by NetServerGetInfo is a combination * of data elements and pointers to variable-size elements within the * returned data. Because of this, the size of the data buffer passed * to the API must be larger than the size of the structure. The extra * space is needed for variable-length strings such as comment elements. * The first call is used to determine how large a buffer is needed; * the second call is used to obtain the data. */ uReturnCode = NetServerGetInfo(pszServer, // Servername sLevel, // Reporting level (0,1,2,3) NULL, // Target buffer for info 0, // Size of target buffer &cbTotalAvail); // Total info available cbBuffer = cbTotalAvail; pbBuffer = SafeMalloc(cbBuffer); uReturnCode = NetServerGetInfo(pszServer, // Servername sLevel, // Reporting level (0,1,2,3) pbBuffer, // Target buffer for info cbBuffer, // Size of target buffer &cbTotalAvail); // Total amount of info printf("NetServerGetInfo returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) { switch (sLevel) { case 3: pServer3 = (struct server_info_3 *) pbBuffer; printf(" Audited events : 0x%lX\n", pServer3->sv3_auditedevents); case 2: pServer2 = (struct server_info_2 *) pbBuffer; printf(" Heuristics : %Fs\n", pServer2->sv2_srvheuristics); case 1: pServer1 = (struct server_info_1 *) pbBuffer; printf(" Major version #: %hu\n", pServer1->sv1_version_major & MAJOR_VERSION_MASK); printf(" Type : 0x%X\n", pServer1->sv1_type); printf(" Comment : %Fs\n", pServer1->sv1_comment); case 0: pServer0 = (struct server_info_0 *) pbBuffer; printf(" Computer Name : %s\n", pServer0->sv0_name); break; default: printf(" Level %hu is not supported\n", sLevel); break; } } free(pbBuffer); //======================================================================== // NetServerSetInfo // // This API function sets configuration components for the specified // server. Note that the function does not change default configuration // parameters in the LANMAN.INI file. // // All SetInfo API functions can be called in two ways: to set all // parameters, or to set a single parameter. To set all parameters, // call NetServerGetInfo to obtain the current values of all // parameters, modify the components to change, and then call // NetServerSetInfo. To set one parameter, set the buffer pointer // to point to the new value for that parameter, and then call // NetServerSetInfo using the corresponding sParmNum value. In this // example, NetServerSetInfo sets the server's comment field. //======================================================================== uReturnCode = NetServerSetInfo(pszServer, // Servername sLevel, // Level of detail (0,1) pszComment, // Pointer to input data strlen(pszComment)+1,// String length + NUL SV_COMMENT_PARMNUM); // Change comment only printf("NetServerSetInfo returned %u\n", uReturnCode); printf(" Set comment to \"%s\" ", pszComment); printf(" %s\n", uReturnCode ? "failed" : "succeeded"); //======================================================================== // NetServerEnum2 // // This API lists all servers visible on the network in the given domain. // In this example, the domain argument is NULL, indicating to list // servers in the workstation's domain, its logon domain, and its other // domains. //======================================================================== cbBuffer = BIG_BUFFER_SIZE; // Can be up to 64K pbBuffer = SafeMalloc(cbBuffer); // Allocate space for buffer uReturnCode = NetServerEnum2(pszServer, // Servername sLevel, // Reporting level (0,1) pbBuffer, // Buffer containing data cbBuffer, // Size of buffer, in bytes &cEntriesRead, // Entries in buffer &cTotalEntries,// Count of entries available flServerType, // Type(s) to enumerate pszDomain); // Server's domain(s) printf("NetServerEnum2 returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) { pServer0 = (struct server_info_0 *) pbBuffer; pServer1 = (struct server_info_1 *) pbBuffer; pServer2 = (struct server_info_2 *) pbBuffer; pServer3 = (struct server_info_3 *) pbBuffer; for (iCount = 0; iCount < (int) cEntriesRead; iCount++) { switch (sLevel) { case 0: printf(" Computer Name : %s\n", pServer0->sv0_name); pServer0++; break; case 1: printf(" Computer Name : %s\n", pServer1->sv1_name); printf(" Type : 0x%X\n", pServer1->sv1_type); pServer1++; break; case 2: printf(" Computer Name : %s\n", pServer2->sv2_name); printf(" Type : 0x%X\n", pServer2->sv2_type); pServer2++; break; case 3: printf(" Computer Name : %s\n", pServer3->sv3_name); printf(" Type : 0x%X\n", pServer3->sv3_type); pServer3++; break; default: break; } // End switch (sLevel) } // End for loop printf("%hu entries returned out of ", cEntriesRead); printf("%hu available\n", cTotalEntries); } // End if successful return //======================================================================== // NetServerDiskEnum // // This API lists all the local disk drives for the specified server, // including hard disk drives, floppy disk drives, and RAM drives. //======================================================================== uReturnCode = NetServerDiskEnum(pszServer, // Servername 0, // Level; must be 0 pbBuffer, // Results buffer cbBuffer, // Size of buffer, in bytes &cEntriesRead, // Count of entries read &cTotalEntries); // Count of entries available printf("NetServerDiskEnum returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) // Print returned info { pszDisk = pbBuffer; printf(" Disk drives on server %s : \n", pszServer); for (iCount = 0; iCount < (int) cEntriesRead; iCount++) { printf(" %s\n", pszDisk); pszDisk += (strlen(pszDisk) + 1); // Skip NUL, get next string } printf("%hu entries returned out of ", cEntriesRead); printf("%hu available\n", cTotalEntries); } //======================================================================== // NetServerAdminCommand // // This API executes a sequence of commands on the specified server. // The default command string, "c: & cd \\ & dir", changes the current // drive to the C: drive, changes the directory to the root C:\, // and performs a list directory DIR command. The results returned // in the buffer are displayed. //======================================================================== if ((pszServer != NULL) && (pszServer[0] != '\0')) printf("On server %s", pszServer); else printf("On local computer"); printf(" execute command string \"%s\"\n", pszCommand); uReturnCode = NetServerAdminCommand(pszServer, // Servername pszCommand, // Commands to execute &usRemoteRetCode, // Ret code of last cmd pbBuffer, // Results buffer cbBuffer, // Size of buffer &cbReturned, // Count of bytes returned &cbTotalAvail); // Count of bytes avail printf("NetServerAdminCommand returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) // Print returned info { printf("Return code of last command : %hu\n", usRemoteRetCode); printf("%hu out of %hu bytes returned\n", cbReturned, cbTotalAvail); printf("Buffer contents:\n"); for (iCount = 0; iCount < (int) cbReturned; iCount++) printf("%c", *((char *)pbBuffer++) ); } free(pbBuffer); exit(0); } // Usage // // Display possible command-line switches for this example. void Usage(char *pszString) { fprintf(stderr, "Usage: %s [-s \\\\server]", pszString); fprintf(stderr, " [-c comment] [-l level]\n [-t type]"); fprintf(stderr, " [-a admin command] [-d domain(s)]\n"); exit(1); } Session Category Session API functions control network sessions established between workstations and servers. They require that the Server service be started on the specified server. The Session category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and SHARES.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETSESSION, and including the master header file, LAN.H. For more information, see the "Example" section, later in this category. These are the Session API functions: ■ NetSessionDel ■ NetSessionEnum ■ NetSessionGetInfo Description A session is a link between a workstation and a server. It is established the first time a workstation makes a connection with a shared resource on the server. Until the session ends, all further connections between the workstation and the server are part of this same session. To end a session, an application on the server end of a connection calls NetSessionDel. This deletes all current connections between the workstation and the server. NetSessionEnum returns information about all sessions established for a server. NetSessionGetInfo returns information about a particular session. Data Structures NetSessionEnum and NetSessionGetInfo return session_info_X data structures, where X is 0, 1, 2, or 10, depending on the level of data requested. Session Information (level 0) The session_info_0 data structure has this format: struct session_info_0 { char far * sesi0_cname; }; where sesi0_cname Points to an ASCIIZ string that contains the computername of the workstation that established the session. Session Information (level 1) The session_info_1 data structure has this format: struct session_info_1 { char far * sesi1_cname; char far * sesi1_username; unsigned short sesi1_num_conns; unsigned short sesi1_num_opens; unsigned short sesi1_num_users; unsigned long sesi1_time; unsigned long sesi1_idle_time; unsigned long sesi1_user_flags; }; where sesi1_cname Points to an ASCIIZ string that contains the computername of the workstation that established the session. sesi1_username Points to an ASCIIZ string that contains the name of the user who established the session. sesi1_num_conns Specifies how many connections have been made during the session. sesi1_num_opens Specifies how many files, devices, and pipes have been opened during the session. sesi1_num_users Specifies how many users have made connections via the session. sesi1_time Specifies how long (in seconds) a session has been active. sesi1_idle_time Specifies how long (in seconds) a session has been idle. sesi1_user_flags Specifies how the user established the session. The SHARES.H header file defines this bit mask for sesi1_user_flags: Code Bit Meaning ──────────────────────────────────────────────────────────────────────────── SESS_GUEST 1 User specified by sesi1_username established the session using a guest account. SESS_NOENCRYPTION 2 User specified by sesi1_username established the session without using password encryption. ──────────────────────────────────────────────────────────────────────────── Session Information (level 2) The session_info_2 data structure has this format: struct session_info_2 { char far * sesi2_cname; char far * sesi2_username; unsigned short sesi2_num_conns; unsigned short sesi2_num_opens; unsigned short sesi2_num_users; unsigned long sesi2_time; unsigned long sesi2_idle_time; unsigned long sesi2_user_flags; char far * sesi2_cltype_name; }; where sesi2_cname through sesi2_user_flags Are the same as the corresponding elements of the session_info_1 data structure. For a complete description, see the preceding section. sesi2_cltype_name Points to an ASCIIZ string that specifies the type of client that established the session. These are the defined types for LAN Manager servers: ╓┌─────────────────────────────────┌─────────────────────────────────────────╖ Name Type ──────────────────────────────────────────────────────────────────────────── DOWN LEVEL Old clients (for example, Microsoft Networks, PC LAN, XENIX(R)). DOS LM LAN Manager 1.0 for MS-DOS clients Name Type ──────────────────────────────────────────────────────────────────────────── DOS LM LAN Manager 1.0 for MS-DOS clients (Basic and Enhanced) and LAN Manager 2.0 for MS-DOS Basic clients. DOS LM 2.0 LAN Manager 2.0 for MS-DOS Enhanced clients. OS/2 LM 1.0 LAN Manager 1.0 for MS OS/2 clients, or LAN Manager 2.0 for MS OS/2 with MS OS/2 1.1. OS/2 LM 2.0 LAN Manager 2.0 for MS OS/2 clients. ──────────────────────────────────────────────────────────────────────────── Session Information (level 10) The session_info_10 data structure has this format: struct session_info_10 { char far * sesi10_cname; char far * sesi10_username; unsigned long sesi10_time; unsigned long sesi10_idle_time; }; where sesi10_cname through sesi10_idle_time Are the same as the corresponding elements of the session_info_1 data structure. For a complete description, see "Session Information (level 1)," earlier in this category. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Guest accounts User Category NetSessionDel ──────────────────────────────────────────────────────────────────────────── NetSessionDel ends a session between a server and a workstation. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or server operator privilege is required to successfully execute NetSessionDel on a remote server or on a computer that has local security enabled. Syntax #define INCL_NETSESSION #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetSessionDel (const char far * pszServer, const char far * pszClientName, short sReserved ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetSessionDel. A null pointer or null string specifies the local server. pszClientName Points to an ASCIIZ string that contains the remote name of the computer whose session is being discontinued. The name must be preceded by two backslashes (for example, \\client). sReserved Reserved; must be 0. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_ClientNameNotFound 2312 The specified computer does not have a session with the server. NERR_InvalidComputer 2351 The specified computername is invalid. NERR_NoSuchServer 2460 The server ID does not specify a valid server. NERR_NoSuchSession 2461 The session ID does not specify a valid session. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── a valid session. ──────────────────────────────────────────────────────────────────────────── Remarks When NetSessionDel ends a session, it disconnects all connections established via the session and closes any files that were opened via the session. Data can be lost if any process on the workstation is communicating with the server when NetSessionDel is called. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Retrieving the status of a NetSessionGetInfo server session NetSessionEnum ──────────────────────────────────────────────────────────────────────────── NetSessionEnum provides information about all current sessions. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or server operator privilege is required to successfully execute NetSessionEnum at level 1 or level 2 on a remote server or on a computer that has local security enabled. No special privilege is required for level 0 or level 10 calls. Syntax #define INCL_NETSESSION #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetSessionEnum (const char far * pszServer, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalAvail ); where pszServer Points to an ASCIIZ string that specifies the name of the server on which to execute NetSessionEnum. A null pointer or null string specifies the local server. sLevel Specifies the level of detail (0, 1, 2, or 10) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a sequence of session_info_X data structures, where X is 0, 1, 2, or 10, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer in which a count of the number of sessions enumerated in the buffer is returned. This count is valid only if NetSessionEnum returns NERR_Success or ERROR_MORE_DATA. pcTotalAvail Points to an unsigned short integer in which a count of the total number of sessions is returned. This count is valid only if NetSessionEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_WkstaNotStarted 2138 The Workstation service is not started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Deleting a session NetSessionDel Listing information about a NetConnectionEnum session between a particular workstation and server Retrieving information about a NetSessionGetInfo session between a particular server and workstation. NetSessionGetInfo ──────────────────────────────────────────────────────────────────────────── NetSessionGetInfo retrieves information about a session established between a particular server and workstation. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or server operator privilege is required to successfully execute NetSessionGetInfo at level 1 or level 2 on a remote server or on a computer that has local security enabled. No special privilege is required for level 0 or level 10 calls. Syntax #define INCL_NETSESSION #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetSessionGetInfo (const char far * pszServer, const char far * pszClientName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetSessionGetInfo. A null pointer or null string specifies the local server. pszClientName Points to an ASCIIZ string that contains the name of the computer whose session is to be monitored. The name must be preceded by two backslashes (for example, \\client). sLevel Specifies the level of detail (0, 1, 2, or 10) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a session_info_X data structure, where X is 0, 1, 2, or 10, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the data buffer pointed to by pbBuffer. pcbTotalAvail Points to an unsigned short integer in which a count of the total number of bytes of information available is returned. This count is valid only if NetSessionGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_ClientNameNotFound 2312 The specified computer does not have a session with the server. NERR_InvalidComputer 2351 The specified computername is Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Deleting a session NetSessionDel Listing all sessions redirected NetSessionEnum to a resource Listing information about a NetConnectionEnum session between a particular workstation and server Session Category Example /* NETSESS.C -- a sample program demonstrating NetSession API functions. This program requires that you have admin privilege or server operator privilege on the specified server. usage: netsess [-s \\server] [-w \\workstation] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). \\workstation = Name of the client machine to check. API Used to... ================= ================================================ NetSessionEnum Display list of workstations connected to server NetSessionGetInfo Check that a particular workstation is connected NetSessionDel Delete a session for a particular workstation This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_BASE #include <os2.h> // MS OS/2 base header files #define INCL_NETERRORS #define INCL_NETSESSION #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include "samples.h" // Internal routine header file #define STRINGLEN 256 #define NETWKSTAGETINFOSIZE 1048 // Function prototypes void Usage (char * pszProgram); void main(int argc, char *argv[]) { char * pszServer = ""; // Servername char * pszClientName = ""; // Workstation name char * pbBuffer; // Pointer to data buffer int iCount; // Index counter unsigned short cbBuffer; // Size of data buffer unsigned short cEntriesRead; // Count of entries read unsigned short cTotalAvail; // Count of entries available API_RET_TYPE uReturnCode; // API return code struct session_info_2 * pSessInfo2; // Session info; level 2 struct session_info_10 * pSessInfo10; // Session info; level 10 for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iCount]; break; case 'w': // -w workstation name pszClientName = argv[++iCount]; break; case 'h': default: Usage(argv[0]); } } else Usage(argv[0]); } //======================================================================== // NetSessionEnum // // This API lists the workstations connected to the server. // Calculate the buffer size needed by determining the number // of sessions and multiplying this value by the size needed // to store the data for one session. //======================================================================== // Supply a zero-length buffer and get back the number of sessions. uReturnCode = NetSessionEnum(pszServer, // "" or NULL means local 10, // Level (0,1,2,10) NULL, // Return buffer 0, // Size of return buffer &cEntriesRead, // Count of entries read &cTotalAvail); // Count of total available if (uReturnCode != NERR_Success && uReturnCode != ERROR_MORE_DATA) printf("NetSessionEnum returned %u\n", uReturnCode); else { printf("There are %hu session(s)\n", cTotalAvail); if (cTotalAvail != 0 ) { cbBuffer = cTotalAvail * (sizeof (struct session_info_10) + CNLEN+1+ // Space for sesi10_cname CNLEN+1); // Space for sesi10_username pbBuffer = SafeMalloc(cbBuffer); // Buffer is large enough unless new sessions have been created. uReturnCode = NetSessionEnum(pszServer, // "" or NULL means local 10, // Level (0,1,2,10) pbBuffer, // Return buffer cbBuffer, // Size of return buffer &cEntriesRead, // Count of entries read &cTotalAvail); // Count of total available // Display information returned by the Enum call. if (uReturnCode == NERR_Success || uReturnCode == ERROR_MORE_DATA) { pSessInfo10 = (struct session_info_10 *) pbBuffer; for (iCount = 0; iCount++ < (int) cEntriesRead; pSessInfo10++) printf(" \"%Fs\"\n", pSessInfo10->sesi10_cname); // May be NULL if uReturnCode != NERR_Success. } else printf("NetSessionEnum returned %u\n", uReturnCode); free(pbBuffer); } } //======================================================================== // NetSessionGetInfo // // This API displays information about sessions at level 2 (maximum // information). Call NetSessionGetInfo with a zero-length buffer to // determine the size of buffer required, and then call it again with // the correct buffer size. //======================================================================== uReturnCode = NetSessionGetInfo(pszServer, // "" or NULL means local pszClientName, // Client to get info on 2, // Level (0,1,2,10) NULL, // Return buffer 0, // Size of return buffer &cbBuffer); // Count of bytes available if (uReturnCode != NERR_BufTooSmall) printf("NetSessionGetInfo with 0 byte buffer returned %u\n", uReturnCode); else { pbBuffer = SafeMalloc(cbBuffer); uReturnCode = NetSessionGetInfo(pszServer, // "" or NULL means local pszClientName, // Client to get info on 2, // Level (0,1,2,10) pbBuffer, // Return buffer cbBuffer, // Size of return buffer &cTotalAvail); // Count of bytes available printf("\nNetSessionGetInfo with %hu byte buffer returned %u\n\n", cTotalAvail, uReturnCode); if (uReturnCode == NERR_Success ) { pSessInfo2 = (struct session_info_2 *) pbBuffer; printf (" Computer name : %Fs\n", pSessInfo2->sesi2_cname); printf (" User name : %Fs\n", pSessInfo2->sesi2_username); printf (" # Connections : %hu\n", pSessInfo2->sesi2_num_conns); printf (" # Opens : %hu\n", pSessInfo2->sesi2_num_opens); printf (" # Users : %hu\n", pSessInfo2->sesi2_num_users); printf (" Seconds active: %lu\n", pSessInfo2->sesi2_time); printf (" Seconds idle : %lu\n", pSessInfo2->sesi2_idle_time); printf (" User flags : %lu\n", pSessInfo2->sesi2_user_flags); printf (" Client version: %Fs\n", pSessInfo2->sesi2_cltype_name); } free(pbBuffer); } //======================================================================== // NetSessionDel // // This API deletes the session with the specified workstation. //======================================================================== uReturnCode = NetSessionDel(pszServer, // "" or NULL means local pszClientName, // Clientname 0); // Reserved; must be 0 printf("NetSessionDel returned %u\n", uReturnCode ); exit(0); } void Usage (char * pszProgram) { fprintf(stderr, "Usage: %s [-s \\\\server] [-w \\\\workstation]\n", pszProgram); exit(1); } Share Category Share API functions control shared resources. They require that the Workstation service be started, and that the Server service be started on the specified server. The Share category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and SHARES.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETSHARE, and including the master header file, LAN.H. For more information, see the "Example" section, later in this category. These are the Share API functions: ■ NetShareAdd ■ NetShareCheck ■ NetShareDel ■ NetShareEnum ■ NetShareGetInfo ■ NetShareSetInfo Description A shared resource is a local resource on a server (for example, a disk directory, print device, or named pipe) that can be accessed by users and applications on the network. NetShareAdd allows a user or application to share a resource of a specific type using the specified sharename. On a server that has share-level security, NetShareAdd also assigns a password and permissions to the shared resource. A user or application can access the shared resource only by supplying the correct password. On a server that has user-level security, NetShareAdd requires only the sharename and local devicename to share the resource. A user or application must have an account on the server to access the resource. For information about accounts on servers that have user-level security, see the User category API functions. For information about assigning permissions in user-level security, see the Access Permissions category API functions. LAN Manager defines three types of special sharenames for interprocess communication (IPC) and remote administration of the server: ■ IPC$, reserved for interprocess communication ■ ADMIN$, reserved for remote administration ■ A$, B$, C$ (and other local disk names followed by a dollar sign), assigned to local disk devices Data Structures The Share API functions use the share_info_X data structures, where X is 0, 1, or 2, depending on the level of detail specified by the sLevel parameter. NetShareEnum and NetShareGetInfo return data at levels 0, 1, and 2. NetShareSetInfo supports data supplied at levels 1 and 2. NetShareAdd supports data supplied at level 2. Share Information (level 0) The share_info_0 data structure has this format: struct share_info_0 { char shi0_netname[NNLEN+1]; }; where shi0_netname Contains an ASCIIZ string that specifies the sharename of a resource. The constant NNLEN is defined in the NETCONS.H header file. Share Information (level 1) The share_info_1 data structure has this format: struct share_info_1 { char shi1_netname[NNLEN+1]; char shi1_pad1; unsigned short shi1_type; char far * shi1_remark; }; where shi1_netname Contains an ASCIIZ string that specifies the sharename of the resource. The constant NNLEN is defined in the NETCONS.H header file. shi1_pad1 Aligns the next data structure element on a word boundary. shi1_type Contains an integer that specifies the type of shared resource. The SHARES.H header file defines these possible values: Code Value Share Type ──────────────────────────────────────────────────────────────────────────── STYPE_DISKTREE 0 Disk directory tree. STYPE_PRINTQ 1 Printer queue. STYPE_DEVICE 2 Communication device. STYPE_IPC 3 Interprocess communication (IPC). ──────────────────────────────────────────────────────────────────────────── shi1_remark Points to an ASCIIZ string that contains a comment about the shared resource. The remark element must be set to NULL when NetShareAdd is called to add the ADMIN$ or IPC$ sharenames; the remark is supplied by NetShareAdd. Share Information (level 2) The share_info_2 data structure has this format: struct share_info_2 { char shi2_netname[NNLEN+1]; char shi2_pad1; unsigned short shi2_type; char far * shi2_remark; unsigned short shi2_permissions; unsigned short shi2_max_uses; unsigned short shi2_current_uses; char far * shi2_path; char shi2_passwd[SHPWLEN+1]; char shi2_pad2; }; where shi2_netname through shi2_remark Are the same as the corresponding elements of the share_info_1 data structure. For a complete description, see the preceding section. shi2_permissions Specifies the permissions for the shared resource on a server that has share-level security. This element is ignored on servers with user-level security. For servers that have share-level security, the ACCESS.H header file defines the bit mask for shi2_permissions: ╓┌──────────────┌─────────┌──────────────────────────────────────────────────╖ Code Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── Code Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── ACCESS_READ 0x01 Permission to read data from a resource and, by default, to execute the resource. ACCESS_WRITE 0x02 Permission to write data to the resource. ACCESS_CREATE 0x04 Permission to create an instance of the resource (such as a file); data can be written to the resource as the resource is created. ACCESS_EXEC 0x08 Permission to execute the resource. ACCESS_DELETE 0x10 Permission to delete the resource. ACCESS_ATRIB 0x20 Permission to modify the resource's attributes (such as the date and time when a file was last modified). ACCESS_PERM 0x40 Permission to modify the permissions (read, write, create, execute, and delete) assigned to a Code Bit Mask Meaning ──────────────────────────────────────────────────────────────────────────── create, execute, and delete) assigned to a resource for a user or application. ACCESS_ALL 0x7F Permission to read, write, create, execute, and delete data from a resource, and to modify attributes and permissions. ──────────────────────────────────────────────────────────────────────────── shi2_max_uses Specifies the maximum number of concurrent connections that the shared resource can accommodate. If shi2_max_uses is -1, the connections are unlimited. shi2_current_uses Specifies the number of connections to the resource. shi2_path Points to an ASCIIZ string that contains the local pathname of the shared resource. For disks, shi2_path is the path being shared. For printer queues, shi2_path is the name of the printer queue being shared. For communication-device queues, shi2_path is a string of one or more communication-device names. In this case, the devicenames are separated by spaces (for example, COM1 COM2 COM6). For ADMIN$ or IPC$ resources, shi2_path must be a null pointer. shi2_passwd Specifies the sharename's password for a server that has share-level security. For a server that has user-level security, shi2_passwd is NULL and is ignored. The constant SHPWLEN is defined in the NETCONS.H header file. shi2_pad2 Aligns the next data structure element on a word boundary. See Also For information about See ──────────────────────────────────────────────────────────────────────────── ADMIN$ and IPC$ resources Chapter 1, "Overview of the LAN Manager API" User accounts User Category NetShareAdd ──────────────────────────────────────────────────────────────────────────── NetShareAdd shares a server resource. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or comm, print, or server operator privilege is required to successfully execute NetShareAdd on a remote server or on a computer that has local security enabled. The print operator can add only printer queues. The comm operator can add only communication-device queues. Syntax #define INCL_NETSHARE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetShareAdd (const char far * pszServer, short sLevel, const char far * pbBuffer, unsigned short cbBuffer ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetShareAdd. A null pointer or null string specifies the local computer. sLevel Specifies the level of detail provided; must be 2. pbBuffer Points to the buffer that contains the share_info_2 data structure provided. cbBuffer Specifies the size (in bytes) of the buffer pointed to by pbBuffer. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_NOT_SUPPORTED 50 This network request is not supported. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_NAME 123 The character or file system Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_INVALID_NAME 123 The character or file system name is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. ERROR_FILENAME_EXCED_RANGE 206 The filename specified is invalid for the file system. This code is returned when checking a FAT disk partition only. It cannot be returned for an HPFS partition. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_UnknownServer 2103 The server was not found. NERR_ServerNotStarted 2114 The Server service is not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_ServerNotStarted 2114 The Server service is not started. NERR_UnknownDevDir 2116 The device or directory does not exist. NERR_RedirectedPath 2117 The operation is invalid for a redirected resource. The devicename specified is assigned to a shared resource. NERR_DuplicateShare 2118 The sharename is already in use on this server. NERR_NoRoom 2119 The server could not access enough of a resource, such as memory, to complete the task. NERR_BufTooSmall 2123 The supplied buffer is too small. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_QNotFound 2150 The queuename specified is invalid. NERR_DeviceShareConflict 2318 Requests cannot be routed from both a printer queue and a communication-device queue to the same device. NERR_BadDevString 2340 The list of devices is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BadDev 2341 The devicename is invalid because it does not represent a physical device, or because the device hardware is faulty. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks NetShareAdd requires a level 2 data structure (share_info_2). Depending on the type of shared resource specified by the shi2_type element of the share_info_2 data structure, you can specify other elements in the data structure, as follows: Code Value Element Requirements ──────────────────────────────────────────────────────────────────────────── STYPE_DISKTREE 0 The shi2_path element must specify a file system pathname, or it must be NULL for ADMIN$. STYPE_PRINTQ 1 The shi2_netname element must specify the name of an existing printer queue. STYPE_DEVICE 2 The shi2_path element must be passed as a null pointer, or it must point to a list of communication devices (the devicenames must be separated by spaces). STYPE_IPC 3 The shi2_netname element must specify an IPC$ resource, and shi2_path must point to a null string. ──────────────────────────────────────────────────────────────────────────── NetShareAdd ignores the value specified in the shi2_current_uses element of share_info_2. If there is a conflict between the server_info_X element svX_numadmin and the share_info_2 element shi2_max_uses for the sharename ADMIN$, LAN Manager gives priority to the shi2_max_uses value. For more information, see your LAN Manager administrator's manual(s). See Also For information about See ──────────────────────────────────────────────────────────────────────────── Listing the resources that can NetShareEnum be shared on a server Remote calls Chapter 1, "Overview of the LAN Manager API" Removing a list of resources NetShareDel that can be shared NetShareCheck ──────────────────────────────────────────────────────────────────────────── NetShareCheck checks whether or not a server is sharing a device. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level No special privilege level is required to successfully execute NetShareCheck. Syntax #define INCL_NETSHARE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetShareCheck (const char far * pszServer, const char far * pszDeviceName, unsigned short far * pusType ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetShareCheck. A null pointer or null string specifies the local computer. pszDeviceName Points to an ASCIIZ string that contains the name of the character device, print destination, or disk to check. pusType Points to an unsigned short integer that contains the returned data. The returned value specifies the type of the shared device specified by pszDeviceName. The SHARES.H header file defines these possible values: Code Value Meaning ──────────────────────────────────────────────────────────────────────────── STYPE_DISKTREE 0 Disk directory tree. STYPE_PRINTQ 1 Printer queue. STYPE_DEVICE 2 Communication device. ──────────────────────────────────────────────────────────────────────────── Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_NetNameNotFound 2310 The sharename does not exist. NERR_DeviceNotShared 2311 The device is not shared. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks The returned pusType value is valid only if NetShareCheck returns NERR_Success. If the device is not shared, NERR_DeviceNotShared is returned. NetShareCheck returns successfully if a specified device is in the routing list of a printer queue or a communication-device queue. See Also For information about See ──────────────────────────────────────────────────────────────────────────── Reconfiguring a server resource NetShareSetInfo that can be shared Retrieving the status of a NetShareGetInfo shared resource NetShareDel ──────────────────────────────────────────────────────────────────────────── NetShareDel deletes a sharename from a server's list of shared resources, disconnecting all connections to the shared resource. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or comm, print, or server operator privilege is required to successfully execute NetShareDel on a remote server or on a computer that has local security enabled. The print operator can delete only printer queues. The comm operator can delete only communication-device queues. Syntax #define INCL_NETSHARE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetShareDel (const char far * pszServer, const char far * pszNetName, unsigned short usReserved ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetShareDel. A null pointer or null string specifies the local computer. pszNetName Points to an ASCIIZ string that contains the sharename to be deleted. usReserved Reserved; must be 0. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_ServerNotStarted 2114 The Server service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_NetNameNotFound 2310 The sharename does not exist. NERR_InvalidComputer 2351 The specified computername is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Adding a share on a server NetShareAdd Listing all connections to a NetConnectionEnum shared resource Listing the resources on a NetShareEnum server that can be shared NetShareEnum ──────────────────────────────────────────────────────────────────────────── NetShareEnum retrieves information about each shared resource on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or comm, print, or server operator privilege is required to successfully execute NetShareEnum at level 2 on a remote server or on a computer that has local security enabled. No special privilege is required for level 0 or level 1 calls. Syntax #define INCL_NETSHARE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetShareEnum (const char far * pszServer, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcEntriesRead, unsigned short far * pcTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetShareEnum. A null pointer or null string specifies the local server. sLevel Specifies the level of detail (0, 1, or 2) returned. pbBuffer Points to the buffer in which to store the return data. On a successful return, the buffer contains a sequence of share_info_X data structures, where X is 0, 1, or 2, depending on the level of detail specified. cbBuffer Specifies the size (in bytes) of the buffer pointed to by pbBuffer. pcEntriesRead Points to an unsigned short integer in which a count of the number of shared resources enumerated in the buffer is returned. This count is valid only if NetShareEnum returns NERR_Success or ERROR_MORE_DATA. pcTotalAvail Points to an unsigned short integer in which a count of the total number of shared resources is returned. This count is valid only if NetShareEnum returns NERR_Success or ERROR_MORE_DATA. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── retrieval or setting is invalid. ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── shared. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Retrieving information about a NetShareGetInfo particular shared resource NetShareGetInfo ──────────────────────────────────────────────────────────────────────────── NetShareGetInfo retrieves information about a particular shared resource on a server. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or comm, print, or server operator privilege is required to successfully execute NetShareGetInfo at level 2 on a remote server or on a computer that has local security enabled. No special privilege is required for level 0 or level 1 calls. Syntax #define INCL_NETSHARE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetShareGetInfo (const char far * pszServer, const char far * pszNetName, short sLevel, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetShareGetInfo. A null pointer or null string specifies the local computer. pszNetName Points to an ASCIIZ string that contains the name of the shared resource. sLevel Specifies the level of detail (0, 1, or 2) requested. pbBuffer Points to the buffer in which to store the returned data. On a successful return, the buffer contains a share_info_X data structure, where X is 0, 1, or 2, depending on the level of detail requested. cbBuffer Specifies the size (in bytes) of the buffer pointed to by pbBuffer. pcbTotalAvail Points to an unsigned short integer in which a count of the total number of bytes of information available is returned. This count is valid only if NetShareGetInfo returns NERR_Success, ERROR_MORE_DATA, or NERR_BufTooSmall. Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_MORE_DATA 234 Additional data is available. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not Code Value Meaning ──────────────────────────────────────────────────────────────────────────── this transaction: IPC$ is not shared. NERR_NetNameNotFound 2310 The sharename does not exist. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── See Also For information about See ──────────────────────────────────────────────────────────────────────────── Reconfiguring a shareable server NetShareSetInfo resource NetShareSetInfo ──────────────────────────────────────────────────────────────────────────── NetShareSetInfo sets the parameters of a shared resource. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, remote only ■ MS-DOS, remote only Privilege Level Admin privilege or comm, print, or server operator privilege is required to successfully execute NetShareSetInfo on a remote server or on a computer that has local security enabled. The print operator can set information only about printer queues. The comm operator can set information only about communication-device queues. Syntax #define INCL_NETSHARE #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetShareSetInfo (const char far * pszServer, const char far * pszNetName, short sLevel, const char far * pbBuffer, unsigned short cbBuffer, short sParmNum ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetShareSetInfo. A null pointer or null string specifies the local computer. pszNetName Points to an ASCIIZ string that contains the sharename of the resource to be set. sLevel Specifies the level of detail (1 or 2) provided. pbBuffer Points to the data to be set. cbBuffer Specifies the size (in bytes) of the buffer pointed to by pbBuffer. sParmNum Specifies whether to set all share information or to change only a part of it. If sParmNum is PARMNUM_ALL, pbBuffer must point to a share_info_X data structure, where X is 1 or 2, depending on the level of detail provided. If sParmNum is any other defined value, only one element of the share information is changed, and pbBuffer must point to a valid value for that element. Not all fields can be set. Only those fields that have a specific PARMNUM constant value defined can be set. The SHARES.H header files define these possible values for sParmNum and the associated elements that must be supplied in the data buffer: ╓┌────────────────────────┌──────┌───────────────────────────────────────────╖ Code Value Element of share_info_X ──────────────────────────────────────────────────────────────────────────── PARMNUM_ALL 0 All elements. SHI_REMARK_PARMNUM 4 shiX_remark SHI_PERMISSIONS_PARMNUM 5 shi2_permissions SHI_MAX_USES_PARMNUM 6 shi2_max_uses SHI_PASSWD_PARMNUM 9 shi2_passwd ──────────────────────────────────────────────────────────────────────────── Code Value Element of share_info_X ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Return Codes ╓┌─────────────────────────────────┌───────┌─────────────────────────────────╖ Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_Success 0 The function encountered no errors. ERROR_ACCESS_DENIED 5 The user has insufficient privilege for this operation. ERROR_BAD_NETPATH 53 The network path was not found. ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied. ERROR_INVALID_PARAMETER 87 The parameter specified is Code Value Meaning ──────────────────────────────────────────────────────────────────────────── ERROR_INVALID_PARAMETER 87 The parameter specified is invalid. ERROR_INVALID_NAME 123 The character or file system name is invalid. ERROR_INVALID_LEVEL 124 The level for information retrieval or setting is invalid. NERR_NetNotStarted 2102 The LAN Manager NETWKSTA driver is not installed. NERR_RemoteOnly 2106 This operation can be performed only on a server. NERR_ServerNotStarted 2114 The Server service is not started. NERR_BufTooSmall 2123 The supplied buffer is too small. Code Value Meaning ──────────────────────────────────────────────────────────────────────────── NERR_BufTooSmall 2123 The supplied buffer is too small. NERR_WkstaNotStarted 2138 The Workstation service is not started. NERR_BadTransactConfig 2141 The server is not configured for this transaction: IPC$ is not shared. NERR_NetNameNotFound 2310 The sharename does not exist. NERR_InvalidComputer 2351 The specified computername is invalid. ──────────────────────────────────────────────────────────────────────────── Remarks If there is a conflict between the server_info_X element svX_numadmin and the share_info_2 element shi2_max_uses for the sharename ADMIN$, LAN Manager gives priority to the shi2_max_uses value. For more information, see your LAN Manager administrator's manual(s). See Also For information about See ──────────────────────────────────────────────────────────────────────────── Retrieving the status of a NetShareGetInfo server resource that can be shared Share Category Example /* NETSHARE.C -- a sample program demonstrating NetShare API functions. This program requires that you have admin privilege or server operator privilege on the specified server. usage: netshare [-s \\server] [-r sharename] [-p path] [-d devicename] [-l level] [-t type] [-c comment] where \\server = Name of the server. A servername must be preceded by two backslashes (\\). sharename = Name of the shared resource. path = Share path for directory tree shares. devicename = Name of the device, such as LPT1, COM1, or C: level = Level of detail; 0, 1, or 2. type = Type of share; Directory=0, Printer Queue=1, Comm device=2, IPC=3. comment = Remark to be added to the share. API Used to... =============== ================================================= NetShareAdd Add a shared resource NetShareGetInfo Get the details of the shared resource just added NetShareSetInfo Change the maximum users of the share NetShareDel Delete the above share NetShareCheck Check to see if the device has been shared NetShareEnum Display the list of current shares This code sample is provided for demonstration purposes only. Microsoft makes no warranty, either express or implied, as to its usability in any given situation. */ #define INCL_NETERRORS #define INCL_NETSHARE #include <lan.h> // LAN Manager header files #include <stdio.h> // C run-time header files #include <stdlib.h> #include <string.h> #include "samples.h" // Internal routine header file #define BIG_BUFFER_SIZE 32768 #define A_SHAREPATH "A:\\" #define A_SHARENAME "FLOPPY" #define A_SHAREREMARK "shared floppy drive" #define CHECK_RESOURCE "LPT1" #define MAX_USERS 8 void Usage(char *pszString); void main(int argc, char *argv[]) { char * pszServer = NULL; // Default to local server char * pbBuffer; // Return data buffer char * pszResShare = A_SHAREPATH; // Share path char * pszResCheck = CHECK_RESOURCE; // Device for NetShareCheck char * pszNetName = A_SHARENAME; // Name for the shared resource char * pszRemark = A_SHAREREMARK; // Default share comment int iCount; // Index and loop counter unsigned short usMaxUses; // For SetInfo call unsigned short cEntriesRead; // Count of entries read unsigned short cTotalAvail; // Count of entries available unsigned short cbBuffer; // Size of buffer, in bytes unsigned short cbTotalAvail; // Total available data unsigned short sLevel = 1; // Level of detail unsigned short usType = STYPE_DISKTREE; // Share type for NetShareAdd API_RET_TYPE uReturnCode; // API return code struct share_info_0 *pBuf0; // Pointer to returned data struct share_info_1 *pBuf1; // Level 1 data struct share_info_2 *pBuf2; // Level 2 data for (iCount = 1; iCount < argc; iCount++) { if ((*argv[iCount] == '-') || (*argv[iCount] == '/')) { switch (tolower(*(argv[iCount]+1))) // Process switches { case 's': // -s servername pszServer = argv[++iCount]; break; case 'r': // -r sharename pszNetName = argv[++iCount]; break; case 'l': // -l level sLevel = (short)(atoi(argv[++iCount])); break; case 'd': // -d devicename pszResCheck = argv[++iCount]; break; case 't': // -t share type usType = (unsigned short)(atoi(argv[++iCount])); break; case 'c': // -c comment for share pszRemark = argv[++iCount]; break; case 'p': // -p pathname for share pszResShare = argv[++iCount]; break; default: Usage(argv[0]); } } else Usage(argv[0]); } // End for loop //======================================================================== // NetShareAdd // // This API adds a shared resource. The default is to share the // A:\ drive using the sharename FLOPPY. The API must be called at // level 2. The logged-on user must have admin privilege or server // operator privilege, and the Server service must be started for // this call to succeed. //======================================================================== cbBuffer = sizeof(struct share_info_2); pbBuffer = SafeMalloc(cbBuffer); // Allocate buffer pBuf2 = (struct share_info_2 *)pbBuffer; // Start of memory block strcpy(pBuf2->shi2_netname, pszNetName); // Sharename pBuf2->shi2_path = pszResShare; // Local pathname pBuf2->shi2_type = usType; // Share type pBuf2->shi2_passwd[0] = '\0'; // No password pBuf2->shi2_remark = pszRemark; // Share remark pBuf2->shi2_permissions = ACCESS_PERM; // Admin privilege pBuf2->shi2_max_uses = MAX_USERS; // Max. users of share uReturnCode = NetShareAdd(pszServer, // Servername 2, // Info level; must be 2 pbBuffer, // Data structure cbBuffer); // Size of buffer, in bytes printf("NetShareAdd returned %u\n", uReturnCode); switch (uReturnCode) { case NERR_DuplicateShare: printf("Resource %s is already shared\n\n", pszResShare); break; case NERR_ServerNotStarted: printf("The server is not started\n\n"); exit(1); break; default: break; } free(pbBuffer); //======================================================================== // NetShareGetInfo // // This API gets and displays information about the sharename just added. //======================================================================== cbBuffer = BIG_BUFFER_SIZE; // Large enough buffer pbBuffer = SafeMalloc(cbBuffer); // Allocate buffer uReturnCode = NetShareGetInfo(pszServer, // Servername pszNetName, // Device to get info about sLevel, // Info level pbBuffer, // Data returned here cbBuffer, // Size of buffer, in bytes &cbTotalAvail); // Bytes of data available printf("NetShareGetInfo of %s ", pszNetName); printf(" returned %u\n", uReturnCode); if (uReturnCode == NERR_Success) { switch (sLevel) { case 2: // Use level 2 structure pBuf2 = (struct share_info_2 *) pbBuffer; printf(" Permissions : 0x%x\n", pBuf2->shi2_permissions); printf(" Max. users : %hu\n", pBuf2->shi2_max_uses); printf(" Curr. users : %hu\n", pBuf2->shi2_current_uses); printf(" Path : %Fs\n", pBuf2->shi2_path); case 1: // Use level 1 structure pBuf1 = (struct share_info_1 *) pbBuffer; printf(" Type : %hu\n", pBuf1->shi1_type); printf(" Remark : %Fs\n", pBuf1->shi1_remark); case 0: // Use level 0 structure pBuf0 = (struct share_info_0 *) pbBuffer; printf(" Resource : %s\n", pBuf0->shi0_netname); break; default: break; } } // NetShareSetInfo // // This API changes the maximum number of users allowed by the share // to unlimited. There are two ways to call NetShareSetInfo. If // sParmNum == PARMNUM_ALL, you must set the whole structure. Otherwise, // you can set sParmNum to the element of the structure you want to // change. This example sets only the "max uses" parameter by setting // sParmNum to SHI_MAX_USES_PARMNUM. usMaxUses = SHI_USES_UNLIMITED; uReturnCode = NetShareSetInfo(pszServer, // Servername pszNetName, // Device to set info on 2, // Info level (char far *)&usMaxUses, // Data buffer address sizeof(usMaxUses), // Size of buffer, in bytes SHI_MAX_USES_PARMNUM); // Parameter to set printf("NetShareSetInfo of max. users returned %u\n", uReturnCode); //======================================================================== // NetShareDel // // This API deletes the sharename established by the previous // NetShareAdd call. //======================================================================== uReturnCode = NetShareDel(pszServer, // Servername pszNetName, // Sharename to be deleted 0); // Reserved; must be 0 printf("NetShareDel of %s returned %u\n", pszNetName, uReturnCode); //======================================================================== // NetShareCheck // // This API checks to see if the device is being shared. //======================================================================== uReturnCode = NetShareCheck(pszServer, // Servername pszResCheck, // Device to check &usType); // Return share type printf("NetShareCheck of %s returned %u\n", pszResCheck, uReturnCode); switch (uReturnCode) { case NERR_Success: printf(" Resource %s is shared as type %hu\n", pszResCheck, usType); break; case NERR_DeviceNotShared: printf(" Resource %s is not shared\n", pszResCheck); break; default: break; } //======================================================================== // NetShareEnum // // This API displays the current sharenames. //======================================================================== uReturnCode = NetShareEnum(pszServer, // Servername sLevel, // Info level pbBuffer, // Data returned here cbBuffer, // Size of buffer, in bytes &cEntriesRead, // Count of entries read &cTotalAvail); // Count of entries available printf("NetShareEnum returned %u \n", uReturnCode); if (uReturnCode == NERR_Success) { pBuf0 = (struct share_info_0 *) pbBuffer; pBuf1 = (struct share_info_1 *) pbBuffer; pBuf2 = (struct share_info_2 *) pbBuffer; for (iCount = 0; iCount < (int) cEntriesRead; iCount++) { switch (sLevel) { case 0: printf(" %s\n", pBuf0->shi0_netname); pBuf0++; break; case 1: printf(" %s\n", pBuf1->shi1_netname); printf(" remark: %Fs\n", pBuf1->shi1_remark); pBuf1++; break; case 2: printf("%s\n", pBuf2->shi2_netname); printf(" remark: %Fs\n", pBuf1->shi1_remark); printf(" path: %Fs\n\n", pBuf2->shi2_path); pBuf2++; break; } } printf("Entries read: %hu out of %hu \n", cEntriesRead, cTotalAvail); } free(pbBuffer); exit(0); } //======================================================================== // Usage // // Display possible command-line switches for this example. //======================================================================== void Usage(char *pszString) { fprintf(stderr, "Usage: %s [-s \\\\server]", pszString); fprintf(stderr, " [-r sharename] [-l level]\n\t\t[-d devicename]"); fprintf(stderr, " [-t type] [-c comment] [-p path]\n"); exit(1); } Statistics Category The Statistics API function, NetStatisticsGet2, retrieves and clears the operating statistics for workstations and servers. It requires that the Workstation service be started and, if server statistics are required, that the Server service be started. The Statistics category functions, datatypes, structures, and constants are defined in the NETCONS.H, NETERR.H, and NETSTATS.H header files. A source program can access these definitions by defining the constants INCL_NETERRORS and INCL_NETSTATS, and including the master header file, LAN.H. For more information, see the "Example" section, later in this category. Description LAN Manager accumulates a set of operating statistics for workstations and servers from the time that the Workstation or Server service is started. NetStatisticsGet2 is called to get, and optionally clear, those statistics. Data Structures NetStatisticsGet2 returns a stat_workstation_0 data structure when workstation statistics are requested; it returns a stat_server_0 data structure when server statistics are requested. Workstation Statistics The stat_workstation_0 data structure has this format: struct stat_workstation_0 { unsigned long stw0_start; unsigned long stw0_numNCB_r; unsigned long stw0_numNCB_s; unsigned long stw0_numNCB_a; unsigned long stw0_fiNCB_r; unsigned long stw0_fiNCB_s; unsigned long stw0_fiNCB_a; unsigned long stw0_fcNCB_r; unsigned long stw0_fcNCB_s; unsigned long stw0_fcNCB_a; unsigned long stw0_sesstart; unsigned long stw0_sessfailcon; unsigned long stw0_sessbroke; unsigned long stw0_uses; unsigned long stw0_usefail; unsigned long stw0_autorec; unsigned long stw0_bytessent_r_hi; unsigned long stw0_bytessent_r_lo; unsigned long stw0_bytesrcvd_r_hi; unsigned long stw0_bytesrcvd_r_lo; unsigned long stw0_bytessent_s_hi; unsigned long stw0_bytessent_s_lo; unsigned long stw0_bytesrcvd_s_hi; unsigned long stw0_bytesrcvd_s_lo; unsigned long stw0_bytessent_a_hi; unsigned long stw0_bytessent_a_lo; unsigned long stw0_bytesrcvd_a_hi; unsigned long stw0_bytesrcvd_a_lo; unsigned long stw0_reqbufneed; unsigned long stw0_bigbufneed; }; where stw0_start Specifies the time statistics collection started. This element also indicates when the statistics were last cleared. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. To calculate the length of time that statistics have been collected, subtract this value from the present time. stw0_numNCB These three elements indicate the total number of network control blocks (NCBs) issued from each source (the counts include failed NCBs). To calculate the total number of successful NCBs, subtract the number of failed NCBs from stw0_numNCB. These numbers are held in the stw0_fiNCB and stw0_fcNCB elements, and are explained in the stw0_fiNCB and stw0_fcNCB descriptions following this list. stw0_numNCB_r Specifies the total number of NCBs issued by the redirector. stw0_numNCB_s Specifies the total number of NCBs issued by the server. stw0_numNCB_a Specifies the total number of NCBs issued by applications. stw0_fiNCB These three elements indicate the number of NCBs that failed for any reason when they were issued. These NCBs are included in the "total issued" count specified by stw0_numNCB. stw0_fiNCB_r Specifies the number of NCBs that failed when issued by the redirector. stw0_fiNCB_s Specifies the number of NCBs that failed when issued by the server. stw0_fiNCB_a Specifies the number of NCBs that failed when issued by applications. stw0_fcNCB These three elements indicate the number of NCBs that failed after issue, at or before completion. These NCBs are also included in the "total issued" count specified by stw0_numNCB. stw0_fcNCB_r Specifies the number of NCBs that were issued by the redirector and that failed before completion. stw0_fcNCB_s Specifies the number of NCBs that were issued by the server and that failed before completion. stw0_fcNCB_a Specifies the number of NCBs that were issued by applications and that failed before completion. stw0_sesstart Specifies the number of workstation sessions started. stw0_sessfailcon Specifies the number of workstation sessions that failed to connect, not counting those that failed due to "name not found." stw0_sessbroke Specifies the number of workstation sessions that failed after the session was established. stw0_uses Specifies the number of workstation uses. stw0_usefail Specifies the number of workstation use failures. This is a count of the times the tree connections failed, when a server is found but the resources are not found. stw0_autorec Specifies the number of workstation autoconnections. The following 12 elements form six quad-words that contain very large counters. (A quad-word is a data area twice as large as a double word.) The high double word (dword) of each is the value divided by 2 sup 32; the low dword is the value modulo 2 sup 32. The counter value equals (high dword * 2 sup 32) + (low dword). These elements count total bytes in all NCBs sent and received for all categories. Note the following for all the NCB-related and byte-count counters: ■ Elements with the suffix _r are NCBs issued by the redirector as part of the typical process of maintaining remote network connections. ■ Elements with the suffix _s are server-related, sent by the redirector on behalf of the server to maintain shared resource connections. ■ Elements with the suffix _a are application-generated NCBs. Applications can generate these elements by calling NetBiosSubmit, using second-class mailslots, sending and receiving server announcements, and so on. stw0_bytessent_r_hi Specifies the number of workstation bytes sent to the network (high dword). stw0_bytessent_r_lo Specifies the number of workstation bytes sent to the network (low dword). stw0_bytesrcvd_r_hi Specifies the number of workstation bytes received from the network (high dword). stw0_bytesrcvd_r_lo Specifies the number of workstation bytes received from the network (low dword). stw0_bytessent_s_hi Specifies the number of server bytes sent to the network (high dword). stw0_bytessent_s_lo Specifies the number of server bytes sent to the network (low dword). stw0_bytesrcvd_s_hi Specifies the number of workstation bytes received from the network (high dword). stw0_bytesrcvd_s_lo Specifies the number of workstation bytes received from the network (low dword). stw0_bytessent_a_hi Specifies the number of application bytes sent to the network (high dword). stw0_bytessent_a_lo Specifies the number of application bytes sent to the network (low dword). stw0_bytesrcvd_a_hi Specifies the number of application bytes received from the network (high dword). stw0_bytesrcvd_a_lo Specifies the number of application bytes received from the network (low dword). stw0_reqbufneed Specifies the number of times the workstation required a request buffer but failed to allocate one. This element indicates that the workstation parameters may need adjustment. stw0_bigbufneed Specifies the number of times the workstation required a big buffer but failed to allocate one. This element indicates that the workstation parameters may need adjustment. ──────────────────────────────────────────────────────────────────────────── NOTE A value of STATS_NO_VALUE for any element means that information is not available. A value of STATS_OVERFLOW means that the element has overflowed. The NETSTATS.H header file defines these constants.─────────────────────────────────────────────────────────────────── Server Statistics The stat_server_0 data structure has this format: struct stat_server_0 { unsigned long sts0_start; unsigned long sts0_fopens; unsigned long sts0_devopens; unsigned long sts0_jobsqueued; unsigned long sts0_sopens; unsigned long sts0_stimedout; unsigned long sts0_serrorout; unsigned long sts0_pwerrors; unsigned long sts0_permerrors; unsigned long sts0_syserrors; unsigned long sts0_bytessent_low; unsigned long sts0_bytessent_high; unsigned long sts0_bytesrcvd_low; unsigned long sts0_bytesrcvd_high; unsigned long sts0_avresponse; unsigned long sts0_reqbufneed; unsigned long sts0_bigbufneed; }; where sts0_start Specifies the time statistics collection started. This element also indicates when the statistics were last cleared. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970. To calculate the length of time that statistics have been collected, subtract this value from the present time. sts0_fopens Specifies the number of server file opens. This includes opens of named pipes. sts0_devopens Specifies the number of server device opens. sts0_jobsqueued Specifies the number of server print jobs spooled. sts0_sopens Specifies the number of times the server session started. sts0_stimedout Specifies the number of times the server session automatically disconnected. sts0_serrorout Specifies the number of times the server sessions failed with an error. sts0_pwerrors Specifies the number of server password violations. sts0_permerrors Specifies the number of server access permission errors. sts0_syserrors Specifies the number of server system errors. The following four elements form two quad-words, which contain very large counters. (A quad-word is a data area twice as large as a double word.) The high dword of each is the value divided by 2 sup 32; the low dword is the value modulo 2 sup 32. The counter value equals (high dword * 2 sup 32) + (low dword). sts0_bytessent_low Specifies the number of server bytes sent to the network (low dword). sts0_bytessent_high Specifies the number of server bytes sent to the network (high dword). sts0_bytesrcvd_low Specifies the number of server bytes received from the network (low dword). sts0_bytesrcvd_high Specifies the number of server bytes received from the network (high dword). sts0_avresponse Specifies the average server response time (in milliseconds). sts0_reqbufneed Specifies the number of times the server required a request buffer but failed to allocate one. This value indicates that the server parameters may need adjustment. sts0_bigbufneed Specifies the number of times the server required a big buffer but failed to allocate one. This value indicates that the server parameters may need adjustment. ──────────────────────────────────────────────────────────────────────────── NOTE A value of STATS_NO_VALUE for any element means that information is not available. A value of STATS_OVERFLOW means that the element has overflowed. The NETSTATS.H header file defines these constants. ──────────────────────────────────────────────────────────────────────────── NetStatisticsGet2 ──────────────────────────────────────────────────────────────────────────── NetStatisticsGet2 retrieves, and optionally clears, operating statistics for a service. Currently, only the Workstation and Server services are supported. Operating Systems Supported ■ MS OS/2 version 1.2, local and remote ■ MS OS/2 version 1.1, local and remote ■ MS-DOS, remote only Privilege Level Admin privilege or server operator privilege is required to successfully execute NetStatisticsGet2 on a remote server. A non-admin class user cannot use this function to clear statistics on a computer that has local security enabled. Syntax #define INCL_NETSTATS #define INCL_NETERRORS #include <lan.h> API_FUNCTION NetStatisticsGet2 (const char far * pszServer, const char far * pszService, unsigned long ulReserved, short sLevel, unsigned long flOptions, char far * pbBuffer, unsigned short cbBuffer, unsigned short far * pcbTotalAvail ); where pszServer Points to an ASCIIZ string that contains the name of the server on which to execute NetStatisticsGet2. A null pointer or null string specifies the local computer. pszService Points to an ASCIIZ string that contains the name of the service about which to get the statistics. Only the values SERVER and WORKSTATION are currently allowed. If another name is used, NetStatisticsGet2 returns ERROR_NOT_SUPPORTED. ulReserved Reserved; must be 0. sLevel Specifies the level of detail requested; must be 0. flOptions Specifies the options flags. The NETSTATS.H header file defines these possible values: Bit(s) Bit Mask Code Meaning ──────────────────────────────────────────────────────────────────────────── 0 0x1 STATSOPT_CLR Clear statistics. 1-31 Reserved; must be 0. ──────────────────────────────────────────────────────────────────────────── The option to clear the