SplCreateDevice

This function establishes a print device on the local workstation or a remote server.

Syntax
SplCreateDevice(pszComputerName, ulLevel, pBuf, cbBuf)

Parameters

 * pszComputerName (PSZ) - input
 * Name of computer where print device is to be added.


 * A NULL string specifies the local workstation.


 * ulLevel (ULONG) - input
 * Level of detail provided.


 * This must be 3.


 * pBuf (PVOID) - input
 * Data structure.


 * It points to a PRDINFO3 data structure.


 * cbBuf (ULONG) - input
 * Size, in bytes, of data structure.

Returns

 * rc (SPLERR) - returns
 * Return code.


 * NO_ERROR (0)
 * No errors occurred.
 * ERROR_ACCESS_DENIED (5)
 * Access is denied.
 * ERROR_NOT_SUPPORTED (50)
 * This request is not supported by the network.
 * ERROR_BAD_NETPATH (53)
 * The network path cannot be located.
 * ERROR_INVALID_PARAMETER (87)
 * An invalid parameter is specified.
 * ERROR_INVALID_NAME (123)
 * The computer name is invalid.
 * ERROR_INVALID_LEVEL (124)
 * The level parameter is invalid.
 * NERR_NetNotStarted (2102)
 * The network program is not started.
 * NERR_BufTooSmall (2123)
 * The API return buffer is too small.
 * NERR_DestExists (2153)
 * The print device already exists.
 * NERR_DestNoRoom (2157)
 * The maximum number of print devices has been reached.
 * NERR_DestInvalidState (2162)
 * This operation cannot be performed on the print device.
 * NERR_SpoolNoMemory (2165)
 * A spooler memory allocation failure occurred.
 * NERR_DriverNotFound (2166)
 * The device driver does not exist.
 * NERR_BadDev (2341)
 * The device is already in use as a communications device.
 * NERR_InvalidComputer (2351)
 * The computer name is invalid.

Sample
This sample code creates a PRDINFO3 structure with dummy parameters. This structure is then used to call SplCreateDevice to establish a print device on a local workstation.
 * 1) define INCL_BASE
 * 2) define INCL_DOSMEMMGR
 * 3) define INCL_SPL
 * 4) define INCL_SPLDOSPRINT


 * 1) include 
 * 2) include    /* for printf function */
 * 3) include   /* for strcpy function */

INT main (argc, argv) INT argc; CHAR *argv[]; {   ULONG  splerr  ; ULONG cbBuf; ULONG ulLevel ; PSZ   pszComputerName ; PSZ   pszPrintDeviceName ; PRDINFO3 prd3 ;

if (argc != 2) {      printf("Syntax:  sdcrt  DeviceName \n"); DosExit( EXIT_PROCESS, 0 ) ; }   /* We are going to create a print device on the local workstation. */   pszComputerName = (PSZ)NULL ;

/* Get the name from the command line. */   pszPrintDeviceName = argv[1];

/* Level 3 is valid. We will use level 3. */   ulLevel = 3;

/* Get size of buffer needed for a PRDINFO3 structure. */   cbBuf = sizeof(PRDINFO3);

/* Set up the structure with dummy parameters. */   prd3.pszPrinterName = pszPrintDeviceName; prd3.pszUserName = NULL; prd3.pszLogAddr = "LPT1"; prd3.uJobId=0; prd3.pszComment= "Test comment"; prd3.pszDrivers = "IBMNULL"; prd3.usTimeOut = 777;

/* Make the call. */   splerr = SplCreateDevice(pszComputerName, ulLevel,                             &prd3, cbBuf);

/* Print out the results. */   if (splerr == NO_ERROR) printf("The device was successfully created."); else printf("SplCreateDevice Error=%ld, cbNeeded=%ld\n",                              splerr, cbBuf) ;

DosExit( EXIT_PROCESS, 0 ) ; return (splerr); }

Call Sequence

 * 1) define INCL_SPL /* Or use INCL_PM, */
 * 2) include 

PSZ      pszComputerName;  /*  Name of computer where print device is to be added. */ ULONG    ulLevel;          /*  Level of detail provided. */ PVOID    pBuf;             /*  Data structure. */ ULONG    cbBuf;            /*  Size, in bytes, of data structure. */ SPLERR   rc;               /*  Return code. */

rc = SplCreateDevice(pszComputerName, ulLevel,      pBuf, cbBuf);

Remarks
The result of this function is the creation of a new print device definition.

The printer is set up to print on the logical address (port) defined by in PRDINFO3. If is NULL, the print device definition is created but is not connected to any logical address. In this case no printing can occur on that print device or from any print queue connected only to that print device. If a logical address is specified, it must already be defined in the PM_SPOOLER_PORTS section of the initialization file.


 * Note: To change the connection between a print device and a port, use SplSetDevice.

All device drivers and queues specified with the print device must already be defined to the spooler.

To add a remote print device requires administrator privilege.

Related Functions

 * SplDeleteDevice
 * SplEnumDevice
 * SplEnumDriver
 * SplEnumPort