How do I read the MSDN and apply?

Question

Okay, so I want to stop asking lots of questions on how to do most programming stuff because most of my questions are given answers that say "Read the MSDN" founded here. Thing is, I have no idea how to read it or most programming languages. For example, lets take the FtpCreateDirectory function on MSDN (which you can find here)

Now, pretend I just learned this feature and I want to try it out. How do I read it, how to I take the functions/commands it shows me. How do I type it? This reallt does not help:

BOOL FtpCreateDirectory(
_In_  HINTERNET hConnect,
_In_  LPCTSTR lpszDirectory
);

Thanks!

Just clarifying - are you saying that you don't know how to write a function call in C++? — Andrew Shepherd, Jan 04 '13 at 01:49
It's worth noting that MSDN has `Using blah blah blah` sections, where there are tutorials on different aspects of Windows programming. Those can sometimes help with how to call specific functions. — chris, Jan 04 '13 at 02:10

chris · Answer 1 · 2013-01-04T02:13:28.300

I've not used this myself, but let's step through and give an example:

HINTERNET hinternet = InternetConnect(...); //assume hinternet is valid

if (!FtpCreateDirectory(hinternet, "C:\\example")) {
    std::cerr << "Error creating FTP directory. Code: " << GetLastError();
}

Step by step:

First, we get a HINTERNET handle. How? Well, the docs say this about the parameter:

Handle returned by a previous call to InternetConnect using INTERNET_SERVICE_FTP.

That's why I called InternetConnect in the example.

Next, we look at the second parameter. Looking at the Windows Data Types article, you can see that it takes either a CONST WCHAR * or CONST CHAR *, depending on whether UNICODE is defined. For simplicity, I acted as though it wasn't, though you can use the TEXT macro to make a string literal wide or narrow depending on UNICODE.

Pointer to a null-terminated string that contains the name of the directory to be created. This can be either a fully qualified path or a name relative to the current directory.

As we can see, it's just a path, so I passed in an example path. This is just an example, but keep in mind what the Remarks section says about this parameter.

Now, we check the return value:

Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call GetLastError. (more not shown)

Therefore, we wrap the call in an if statement to catch an error, which we can retrieve the code for using GetLastError. It's important to use the error handling technique described in each function's article. A lot of them say that upon an error, you can use GetLastError, but some don't support GetLastError usage, and some support different types of error retrieving functions, so make sure to follow the guidelines for each function individually.

Other than that, the _In_ means that the parameter goes in and it's no use after. This is opposed to, among others, _Out_, which means that you'd pass in allocated memory and the function would write to it, so you can use it after the function call with the value the function writes.

@MoyleJack, You can accept an answer to your question that you want people to see (it will be moved to the top afterwards) by clicking the check mark next to the answer's score. I recommend reviewing your questions and doing so for each one with at least one answer that helped to solve the problem. — chris, Jan 04 '13 at 04:52

score 0 · Answer 2 · answered Jan 04 '13 at 01:52

in the refernce part of MSDN there is a basic assumption that you understand the context for the API set.

If win32 c(++) programming is what you want then you need to read an intro do windows programming / win32. Its not clear what your area of interest is, are you trying to write desktop apps, servers, drivers,....

For some cases classic books like Charles Petzold programming windows are a good place to start. MSDN has a lot of intro level stuff too (google 'start win32 programming')

How do I read the MSDN and apply?

2 Answers2