DEVESC DEFAULTJOBPROPERTIES

GreEscape DEVESC_DEFAULTJOBPROPERTIES resets (or defaults) the specified job property types inside the job properties structure that is passed in.

Simulation support

This function is mandatory for all drivers and must be implemented in order to have a valid OS/2 hardcopy driver.

Syntax

GreEscape(hdc, lEscape, cInCount, pInData, pcOutCount, pOutData, pInstance, lFunction);

Parameters

hdc (HDC) - input

Device context handle.

lEscape (LONG) - input

DEVESC_DEFAULTJOBPROPERTIES escape code.

cInCount (LONG) - input

Number of bytes pointed to by pInData.

pInData (PBYTE) - output

Pointer to a list of DJP_ITEM data structures. The end of the list is indicated by a DJP_ITEM structure that has DJP_NONE as its ulProperty value. Note: The values contained within the DJP_ITEMs are ignored. The corresponding job property information will be reset.

pcOutCount (PLONG) - input

Pointer to the number of bytes pointed to by pOutData.

pOutData (PLONG) - input

Pointer to the printer driver's job properties structure as returned by SplQueryQueue. These may have been modified by GreEscape DEVESC_SETJOBPROPERTIES. Note: On output, the job properties are changed.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreEscape.

Returns

rc (LONG) - returns

Return Code.

The handling routine returns:

DEV_OK

Successful

DEV_PROP_BUF_TOO_SMALL

The job properties buffer was too small to contain the proper job properties data or expanded DJP_ITEMs. The buffer will not be updated.

DEV_INV_INP_JOBPROPERTIES

Invalid job properties were passed in. The driver changed them to default values. This is an error and the item buffer will not be updated.

DEVESC_ERROR

Error

Remarks

GreEscape DEVESC_DEFAULTJOBPROPERTIES is used to default individual DJP_ITEMs rather than defaulting the entire job property structure. This structure is known only to the printer presentation driver, and this escape is the only way for an application to reset values inside the structure.

Since this function is new, applications will call GreEscape DEVESC_QUERYESCSUPPORT to determine if you support this DevEscape.

Note that the DevEscape path has a handle to a device context (HDC) that should already have printer property information associated with the HDC. Job property information may change or may be dependent upon the printer property information in the HDC. In that case, if an application passes job properties for a different device or for a different spooler printer name, then misleading information will be returned.

Remember to test the input job properties to make sure that they are valid. This includes passing tests such as whether they contain your driver's signature string, whether the device name is yours, and whether values are within the proper ranges (only landscape or portrait). If these tests fail, then fail the call.

Source Code Sample

Declaration:

#define INCL_DEV
#define INCL_DEVDJP
#include <os2.h>

HDC      hdc;         /* Device context handle. */
LONG     lEscape;     /* DEVESC_DEFAULTJOBPROPERTIES escape code. */
LONG     cInCount;    /* Number of bytes pointed to by pInData. */
PBYTE    pInData;     /* Pointer to a list of DJP_ITEM data structures. */
PLONG    pcOutCount;  /* Pointer to the number of bytes pointed to by pOutData. */
PLONG    pOutData;    /* Pointer to the printer driver's job properties structure. */
PVOID    pInstance;   /* Pointer to instance data. */
ULONG    lFunction;   /* High-order WORD=flags; low-order WORD=NGreEscape. */
LONG     rc;          /* Return Code. */

rc = GreEscape(hdc, lEscape, cInCount, pInData,
       pcOutCount, pOutData, pInstance, lFunction);

Sample Implementation:

LONG ENGENTRY Escape (HDC       hdc,
                      LONG      lEscape,
                      LONG      cInCount,
                      PBYTE     pInData,
                      PLONG     pcOutCount,
                      PBYTE     pOutData,
                      PDDC      pddc,
                      ULONG     ulFunction)
{
   switch (lEscape)
   {
   case DEVESC_DEFAULTJOBPROPERTIES:
   {
      INT            cbQueries   = cInCount;
      PBYTE          pbQueries   = pInData;
      PDJP_ITEM      pISet       = (PDJP_ITEM)pbQueries;
      BOOL           fError      = FALSE;
      ULONG          ulMaxSize;

      pGoodDrivData = ReturnDriverData (pddc->pdb,
                                        pdi,
                                        pddc->pdb->hmcbHeap,
                                        pDrivData,
                                        pddc->pdb->pszPrinterName,
                                        TRUE,
                                        pDevice,
                                        pDriver);
      assertF (pGoodDrivData);

      /* Is the size of the input driver data is not the same as
      ** the size of our good data?
      */
      if (pDrivData->cb != pGoodDrivData->cb)
         lrc = DEV_PROP_BUF_TOO_SMALL;

      /* Or, if the two don't compare, then fail the call.
      */
      if (0 != memcmp (pDrivData, pGoodDrivData, pGoodDrivData->cb))
         lrc = DEV_INV_INP_JOBPROPERTIES;

      // Update the job properties with the input set list
      do
      {
         DBPRINTF (("Set default '%s'/%d.  Query type '%s'/%d. Simple value = %d\n",
                    pszProperty (pISet->ulProperty),
                    pISet->ulProperty,
                    pszType (pISet->lType),
                    pISet->lType,
                    pISet->ulValue));

         switch (pISet->ulProperty)
         {
         case DJP_SJ_ORIENTATION:
         {
            pJobProp->ulOrientation = pDevice->DeviceDefaults.ulOrientation;
            break;
         }

         case DJP_CJ_RESOLUTION:
         {
            pJobProp->ulDefResID = pDevice->DeviceDefaults.ul Maltese Cross;
            break;
         }

         case DJP_SJ_BITSPERPEL:
         case DJP_SJ_COLOR:
         {
            pJobProp->ulDefPrintModeID = pDevice->DeviceDefaults.ulDefPrintModeID;
            break;
         }

         case DJP_SJ_PAPERSIZE:
         case DJP_CJ_FORM:
         {
            pJobProp->ulDefConnID = pDevice->DeviceDefaults.ulDefConnID;
            break;
         }

         case DJP_SJ_COPIES:
         {
            pJobProp->ulCopies = pDevice->DeviceDefaults.ulCopies;
            break;
         }

         case DJP_SJ_PRINTQUALITY:
         case DJP_SJ_TRAYTYPE:
         case DJP_SJ_MEDIA:
         case DJP_SJ_MEDIA_COLOR:
         case DJP_CJ_MIXEDFORMS:
         case DJP_SJ_FONTDOWNLOADING:
         case DJP_SJ_DUPLEX:
         case DJP_SJ_COLLATE:
         case DJP_SJ_FEED:
         case DJP_SJ_SCALING:
         case DJP_SJ_FORMFEEDCONTROL:
         case DJP_SJ_N_UP:
         default:
            fError = TRUE;
            pISet->lType = DJP_ERROR_NOT_SUPPORTED;
            DBPRINTF (("Unknow set default '%s' = %d!\n",
                        pszProperty (pISet->ulProperty),
                        pISet->ulProperty));
            break;
         }

         // Move to the set item
         pISet = DJP_NEXT_STRUCTP (pISet);

      } while (pISet->ulProperty != DJP_NONE);

      cbDrivData = cbParm2;
      pDrivData  = (PDRIVDATA)pbParm2;

      /* Copy the updated job properties onto the user's job properties
      */
      ulMaxSize = min (pGoodDrivData->cb, cbDrivData);
      memcpy (pDrivData, pGoodDrivData, ulMaxSize);
      pDrivData->cb = ulMaxSize;

      if (fError)
      {
         GplErrSetWarning (PMERR_DATATYPE_ENTRY_INVALID);
         ulrc = DEV_ERROR;
      }
      else
      {
         ulrc = DEV_OK;
      }
      break;
   }
   }

   return lrc;
}