How to use the MSDN

Question

This might seem like a stupid question, but the documentation is either bad or I'm missing something i didn't read. Everytime i refer to the MSDN for c++ related questions I'm always confused. Like the SetComputerName function. I looked up the MSDN and didn't know how to use it because i was completely clueless. Can anyone teach me how to read something like this, also if you could explain it in laymens terms im not very good at c++ thanks!

BOOL WINAPI SetComputerName(
_In_ LPCTSTR lpComputerName
);

You call it, passing in the new computer name. It returns a BOOL that indicates whether it succeeded or not. — Ken White, Aug 09 '18 at 12:21
@KenWhite could you explain to me what things like WINAPI are for, or _IN_ or LPCTSTR or even LPComputerName kinda wanna get used to using it on my own don't want an explanation like that — Jacob Sator, Aug 09 '18 at 12:22
That question is far too broad in scope for this site. You're asking for a tutorial in basic C programming, WinAPI data types, and reading of WinAPI documentation. We don't write tutorials when there are entire books dedicated to the topic. You might see if you can locate one of Charles Petzold's early books on Amazon or eBay. You're going to need to be much better versed in the basics before you start trying to use the API directly, especially those that have permanent impact. — Ken White, Aug 09 '18 at 12:24
Once you realize WinAPI is **not** C++ and there **isn't** such thing as C/C++, it's all downhill from there. — Ron, Aug 09 '18 at 12:24
He means that the vast majority of the WinAPI is written in C, not C++, and they're not the same language, any more than a cat and a carrot are the same because they both start with *ca*. — Ken White, Aug 09 '18 at 12:27
@KenWhite wait so its not that simple you can't just explain to me what LPCTSTR and _IN_ means or even how to use the MSDN? — Jacob Sator, Aug 09 '18 at 12:28
You read MSDN by reading the words, and understanding the types and conventions that are used in that documentation. Again, *there are entire books written about this topic*. I even recommended one, and an inexpensive way to find one. Explaining to you how to read this one function isn't going to get you far, because it's one of the most simple, clear API calls you can make; if you don't understand that, you're going to need to learn a very large number of things in order to use MSDN effectively, and (once again), that's far too broad for this site. — Ken White, Aug 09 '18 at 12:30

Pete Kirkham · Answer 1 · 2018-08-09T12:37:20.313

There are a few macros here which are there for mainly historic reasons, and the type and name of the parameter

BOOL WINAPI SetComputerName(
_In_ LPCTSTR lpComputerName
);

BOOL is used for booleans as C didn't have a bool type standardised before 1999 and the Windows API is older than that, see Why does microsoft use so many macros in their C++ code?

WINAPI is used to mark Windows API functions with a calling convention, see What does "WINAPI" in main function mean? . Usually this doesn't matter to you, only to your compiler.

LPTCSTR means 'long pointer to a const TCHAR string'. See LPCSTR, LPCTSTR and LPTSTR . TCHAR is another macro which is either a single byte or wide character depending on compile time options. This one you need to pay attention to, as it is the type of the parameter.

_In_ marks the parameter as an input to the function, rather than pointing to storage for a result. This is sometimes useful documentation, and also a hint to code analysis. See What is _In_ in C++?

lpComputerName the 'lp' is Microsoft Hungarian notation for 'long pointer' containing the new value of the computer name.

'long pointer' is a reference to the old memory model where you had 16 bit pointers and 32 bit 'long pointers', now-a-days all the pointers are either 32 or 64 bit depending on compiler options.

Historically, P stands for "pointer" and LP stands for "long pointer". Long pointers (also called far pointers) are a holdover from 16-bit Windows, when they were needed to address memory ranges outside the current segment. The LP prefix was preserved to make it easier to port 16-bit code to 32-bit Windows. Today there is no distinction — a pointer is a pointer. - Windows Coding Conventions

holy shit we need more people like you in this industry. props my man! also how do you know what to put in the LPCSTR? — Jacob Sator, Aug 09 '18 at 12:36
@JacobSator if you've defined UNICODE in your compiler options, then it's a wide character C string, otherwise it's a single byte character C string, e.g. the literal `"My computer"`. There's even a macro for literals to be the right type depending on options ,but I can't recall it at the moment. — Pete Kirkham, Aug 09 '18 at 12:39
Also note that links were the in the first few result when searching for each of the words on this site/msdn. — Pete Kirkham, Aug 09 '18 at 12:42

How to use the MSDN

1 Answers1