Understanding a C++ sample - printers, handles, strings

There are few question from the following code which i came across here:

// RawDataToPrinter - sends binary data directly to a printer 
//  
// szPrinterName: NULL-terminated string specifying printer name 
// lpData:        Pointer to raw data bytes 
// dwCount        Length of lpData in bytes 
//  
// Returns: TRUE for success, FALSE for failure. 
//  
BOOL RawDataToPrinter(LPTSTR szPrinterName, LPBYTE lpData, DWORD dwCount)
{
    BOOL     bStatus = FALSE;
    HANDLE     hPrinter = NULL;
    DOC_INFO_1 DocInfo;
    DWORD      dwJob = 0L;
    DWORD      dwBytesWritten = 0L;

    // Open a handle to the printer. 
    bStatus = OpenPrinter( szPrinterName, &hPrinter, NULL );  // question 1
    if (bStatus) {
        // Fill in the structure with info about this "document." 
        DocInfo.pDocName = (LPTSTR)_T("My Document");  // question 2
        DocInfo.pOutputFile = NULL;                 // question 3
        DocInfo.pDatatype = (LPTSTR)_T("RAW");   // question 4

        // Inform the spooler the document is beginning. 
        dwJob = StartDocPrinter( hPrinter, 1, (LPBYTE)&D开发者_运维问答ocInfo );  // question 5
        if (dwJob > 0) {
            // Start a page. 
            bStatus = StartPagePrinter( hPrinter );
            if (bStatus) {
                // Send the data to the printer. 
                bStatus = WritePrinter( hPrinter, lpData, dwCount, &dwBytesWritten);
                EndPagePrinter (hPrinter);
            }
            // Inform the spooler that the document is ending. 
            EndDocPrinter( hPrinter );
        }
        // Close the printer handle. 
        ClosePrinter( hPrinter );
    }
    // Check to see if correct number of bytes were written. 
    if (!bStatus || (dwBytesWritten != dwCount)) {
        bStatus = FALSE;
    } else {
        bStatus = TRUE;
    }
    return bStatus;
}

Please look for the question number in comments

Question 1

• when i have set hPrinter = null then what is meant by &hPrinter ?

Question 2

• what does (LPTSTR)_T denote ? (see T )

Question 3

• What does null here denote ?

Question 4

• What does RAW mean ( what type of data it is ? ) ?

Question 5

• What does 1 denote here ?

---

1. &hPrinter is the address of the hPrinter variable. You need to pass it so the OpenPrinter function can write in it the actual handle to the printer.

2. _T takes your character string and converts it to the proper ANSI (8bits/character) or Unicode (16bits/character) representation based on your compilation settings. Basically it's a macro that either expands to nothing (ANSI) or L (Unicode) plus the actual string.

3. Here where, in the code? NULL is a macro that expands to (basically) 0. It's used to provide a decent default value.

4. Raw data is exactly what it sounds, raw data. It's not structured in any way, it's just a soup of bytes you pass to a (usually) device.

5. From http://msdn.microsoft.com/en-us/library/dd145115(v=vs.85).aspx:

   The version of the structure to which pDocInfo points. This value must be 1.

---

1. &hPrinter is the address of the memory space that the symbol hPrinter occupies. For instance, if the value of hPrinter were stored at the address 0x1000 (unlikely!), then the four (or eight, or more; HANDLE is defined as PVOID, so it'll vary between architectures) bytes starting at 0x1000 will contain the value 0 (NULL). In other words, while the value of hPrinter might be NULL, it still has an address and it still occupies memory space.

   Edit: My answer is probably not what you were after. The second parameter to OpenPrinter (to which you pass the address of hPrinter) is actually an output parameter, not an input parameter. It's a common work-around for the fact that C is limited to one return value, and most Win32 API functions return a status value. It receives a handle to the printer once the OpenPrinter function has finished successfully.

2. The _T() macro determines whether your project is configured to use Unicode or not, and interprets the string literal accordingly; see MSDN's explanation.

3. pOutputFile is described here as:

   Pointer to a null-terminated string that specifies the name of an output file. To print to a printer, set this to NULL.

   In other words: when printing to a printer rather than a file, set this to NULL. NULL typically denotes "no value" in the context of pointer types.

4. Was better answered by others.

5. See this for more info, but basically:

   The version of the structure to which pDocInfo points. This value must be 1.

   ... So I wouldn't worry too much about it if I were you. ;)

---

when i have set hPrinter = null then what is meant by &hPrinter ?

When you pass &hPrinter it means you are passing the address of the handle to the api, so that the api will allocate a handle and put it inside hPrinter .

what does (LPTSTR)_T denote ? (see T )

_T() is a macro which In a Unicode build, they puts the L before the string literal to make it wide, and in non-Unicode, does nothing.

---

hPrinter is a reference parameter, which means a function can change the actual parameter involved in the function call. It is of course (behind the curtains) implemented as a pointer, so

    int j;
    int &i = j
    // realy is:
    int *i = &j;

taking the address by putting & infront of &i evaluates to the value of the 'behind the curtain' pointer.

_T("hello world") is a compiler defined macro that may return "hello world" in wide character format, in case of a unicode build. Or in case of an ANSI build: "hello world" in char's.

To answer the rest of your questions, consult the documentation, or wait for another someone to answer your questions.