You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -171,13 +170,27 @@ The function [`_configthreadlocale`](configthreadlocale.md) is used to control w
171
170
172
171
## UTF-8 Support
173
172
174
-
Starting in Windows 10 build 17134 (April 2018 Update), the Universal C Runtime supports using a UTF-8 code page. This means that `char` strings passed to C runtime functions will expect strings in the UTF-8 encoding. To enable UTF-8 mode, use "`UTF-8`" as the code page when using `setlocale`. For example, `setlocale(LC_ALL, ".utf8")` will use the current default Windows ANSI code page (ACP) for the locale and UTF-8 for the code page.
173
+
Starting in Windows 10 build 17134 (April 2018 Update), the Universal C Runtime supports using a UTF-8 code page. This means that `char` strings passed to C runtime functions will expect strings in the UTF-8 encoding. To enable UTF-8 mode, use `".UTF8"` as the code page when using `setlocale`. For example, `setlocale(LC_ALL, ".UTF8")` will use the current default Windows ANSI code page (ACP) for the locale and UTF-8 for the code page.
175
174
176
-
After calling `setlocale(LC_ALL, ".UTF8")`, you may pass "😊" to `mbtowcs` and it will be properly translated to a `wchar_t` string, whereas previously there was not a locale setting available to do this.
175
+
The string to specify UTF-8 mode is:
176
+
- case-insensitive
177
+
- the hyphen (-) is optional
178
+
- It must be in the code page part of the locale name, so must have a leading period '.' For example, `"en_US.UTF8"` or `".utf8"`
177
179
178
-
UTF-8 mode is also enabled for functions that have historically translated `char` strings using the default Windows ANSI code page (ACP). For example, calling [`_mkdir("😊")`](../reference/mkdir-wmkdir.md) while using a UTF-8 code page will correctly produce a directory with that emoji as the folder name, instead of requiring the ACP to be changed to UTF-8 prior to running your program. Likewise, calling [`_getcwd()`](../reference/getcwd-wgetcwd.md) inside of that folder will return a UTF-8 encoded string. For compatibility, the ACP is still used if the C locale code page is not set to UTF-8.
180
+
The following examples show how to specify the UTF-8 string:
179
181
180
-
The following aspects of the C Runtime that are not able to use UTF-8 because they are set during program startup and must use the default Windows ANSI code page (ACP): [`__argv`](../argc-argv-wargv.md), [`_acmdln`](../acmdln-tcmdln-wcmdln.md), and [`_pgmptr`](../pgmptr-wpgmptr.md).
182
+
`".UTF8"`\
183
+
`".UTF-8"`\
184
+
`".utf8"`\
185
+
`".utf-8"`\
186
+
`"en_us.utf8"`\
187
+
`"ja_JP.Utf-8"`
188
+
189
+
After calling `setlocale(LC_ALL, ".UTF8")`, you may pass "😊" to `mbtowcs` and it will be properly translated to a `wchar_t` string, whereas previously there wasn't a locale setting available to do this.
190
+
191
+
UTF-8 mode is also enabled for functions that have historically translated `char` strings using the default Windows ANSI code page (ACP). For example, calling [`_mkdir("😊")`](../reference/mkdir-wmkdir.md) while using a UTF-8 code page will correctly produce a directory with that emoji as the folder name, instead of requiring the ACP to be changed to UTF-8 before running your program. Likewise, calling [`_getcwd()`](../reference/getcwd-wgetcwd.md) in that folder will return a UTF-8 encoded string. For compatibility, the ACP is still used if the C locale code page is not set to UTF-8.
192
+
193
+
The following aspects of the C Runtime can't use UTF-8 because they are set during program startup and must use the default Windows ANSI code page (ACP): [`__argv`](../argc-argv-wargv.md), [`_acmdln`](../acmdln-tcmdln-wcmdln.md), and [`_pgmptr`](../pgmptr-wpgmptr.md).
181
194
182
195
Previous to this support, [`mbrtoc16`, `mbrtoc32`](../reference/mbrtoc16-mbrtoc323.md), [`c16rtomb`, and `c32rtomb`](../reference/c16rtomb-c32rtomb1.md) existed to translate between UTF-8 narrow strings, UTF-16 (same encoding as `wchar_t` on Windows platforms) and UTF-32. For compatibility reasons, these APIs still only translate to and from UTF-8 and not the code page set via `setlocale`.
183
196
@@ -190,7 +203,7 @@ To use this feature on an OS prior to Windows 10, such as Windows 7, you must us
190
203
|`setlocale`|`<locale.h>`|
191
204
|`_wsetlocale`|`<locale.h>` or `<wchar.h>`|
192
205
193
-
For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md).
206
+
For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md).
Copy file name to clipboardExpand all lines: docs/mfc/windows-sockets-using-class-casyncsocket.md
+25-28Lines changed: 25 additions & 28 deletions
Original file line number
Diff line number
Diff line change
@@ -1,29 +1,28 @@
1
1
---
2
2
description: "Learn more about: Windows Sockets: Using Class CAsyncSocket"
3
3
title: "Windows Sockets: Using Class CAsyncSocket"
4
-
ms.date: "11/04/2016"
4
+
ms.date: "6/8/2021"
5
5
helpviewer_keywords: ["CAsyncSocket class [MFC], programming model", "Windows Sockets [MFC], asynchronous", "sockets [MFC], converting between Unicode and MBCS strings", "SOCKET handle", "sockets [MFC], asynchronous operation", "Windows Sockets [MFC], converting Unicode and MBCS strings"]
6
-
ms.assetid: 825dae17-7c1b-4b86-8d6c-da7f1afb5d8d
7
6
---
8
-
# Windows Sockets: Using Class CAsyncSocket
7
+
# Windows Sockets: Using Class `CAsyncSocket`
9
8
10
-
This article explains how to use class [CAsyncSocket](../mfc/reference/casyncsocket-class.md). Be aware that this class encapsulates the Windows Sockets API at a very low level. `CAsyncSocket` is for use by programmers who know network communications in detail but want the convenience of callbacks for notification of network events. Based on this assumption, this article provides only basic instruction. You should probably consider using `CAsyncSocket` if you want Windows Sockets' ease of dealing with multiple network protocols in an MFC application but do not want to sacrifice flexibility. You might also feel that you can get better efficiency by programming the communications more directly yourself than you could using the more general alternative model of class `CSocket`.
9
+
This article explains how to use class [`CAsyncSocket`](../mfc/reference/casyncsocket-class.md). This class encapsulates the Windows Sockets API at a very low level. `CAsyncSocket` is for use by programmers who know network communications in detail but want the convenience of callbacks for notification of network events. Based on this assumption, this article provides only basic instruction. You should probably consider using `CAsyncSocket` if you want Windows Sockets' ease of dealing with multiple network protocols in an MFC application but don't want to sacrifice flexibility. You might also feel that you can get better efficiency by programming the communications more directly yourself than you could using the more general alternative model of class `CSocket`.
11
10
12
-
`CAsyncSocket` is documented in the *MFC Reference*. Visual C++ also supplies the Windows Sockets specification, located in the Windows SDK. The details are left to you. Visual C++ does not supply a sample application for `CAsyncSocket`.
11
+
`CAsyncSocket` is documented in the *MFC Reference*. Visual C++ also supplies the Windows Sockets specification, located in the Windows SDK. The details are left to you. Visual C++ doesn't supply a sample application for `CAsyncSocket`.
13
12
14
-
If you are not highly knowledgeable about network communications and want a simple solution, use class [CSocket](../mfc/reference/csocket-class.md) with a `CArchive` object. See [Windows Sockets: Using Sockets with Archives](../mfc/windows-sockets-using-sockets-with-archives.md) for more information.
13
+
If you aren't highly knowledgeable about network communications and want a simple solution, use class [`CSocket`](../mfc/reference/csocket-class.md) with a `CArchive` object. See [Windows Sockets: Using Sockets with Archives](../mfc/windows-sockets-using-sockets-with-archives.md) for more information.
15
14
16
15
This article covers:
17
16
18
17
- Creating and using a `CAsyncSocket` object.
19
18
20
-
-[Your responsibilities with CAsyncSocket](#_core_your_responsibilities_with_casyncsocket).
19
+
-[Your responsibilities with `CAsyncSocket`](#_core_your_responsibilities_with_casyncsocket).
21
20
22
-
## <aname="_core_creating_and_using_a_casyncsocket_object"></a> Creating and Using a CAsyncSocket Object
21
+
## <aname="_core_creating_and_using_a_casyncsocket_object"></a> Creating and using a `CAsyncSocket`
23
22
24
-
#### To use CAsyncSocket
23
+
#### To use `CAsyncSocket`
25
24
26
-
1. Construct a [CAsyncSocket](../mfc/reference/casyncsocket-class.md) object and use the object to create the underlying **SOCKET** handle.
25
+
1. Construct a [`CAsyncSocket`](../mfc/reference/casyncsocket-class.md) object and use the object to create the underlying **`SOCKET`** handle.
27
26
28
27
Creation of a socket follows the MFC pattern of two-stage construction.
The first constructor above creates a `CAsyncSocket` object on the stack. The second constructor creates a `CAsyncSocket` on the heap. The first [Create](../mfc/reference/casyncsocket-class.md#create) call above uses the default parameters to create a stream socket. The second `Create` call creates a datagram socket with a specified port and address. (You can use either `Create` version with either construction method.)
37
+
The first constructor above creates a `CAsyncSocket` object on the stack. The second constructor creates a `CAsyncSocket` on the heap. The first [`Create`](../mfc/reference/casyncsocket-class.md#create) call above uses the default parameters to create a stream socket. The second `Create` call creates a datagram socket with a specified port and address. (You can use either `Create` version with either construction method.)
39
38
40
39
The parameters to `Create` are:
41
40
42
41
- A "port": a short integer.
43
42
44
43
For a server socket, you must specify a port. For a client socket, you typically accept the default value for this parameter, which lets Windows Sockets select a port.
45
44
46
-
- A socket type: **SOCK_STREAM** (the default) or **SOCK_DGRAM**.
45
+
- A socket type: **`SOCK_STREAM`** (the default) or **`SOCK_DGRAM`**.
47
46
48
-
- A socket "address," such as "ftp.microsoft.com" or "128.56.22.8".
47
+
- A socket "address" such as `"ftp.microsoft.com"` or `"128.56.22.8"`.
49
48
50
-
This is your Internet Protocol (IP) address on the network. You will probably always rely on the default value for this parameter.
49
+
This is your Internet Protocol (IP) address on the network. You'll probably always rely on the default value for this parameter.
51
50
52
51
The terms "port" and "socket address" are explained in [Windows Sockets: Ports and Socket Addresses](../mfc/windows-sockets-ports-and-socket-addresses.md).
53
52
54
-
1. If the socket is a client, connect the socket object to a server socket, using [CAsyncSocket::Connect](../mfc/reference/casyncsocket-class.md#connect).
53
+
1. If the socket is a client, connect the socket object to a server socket, using [`CAsyncSocket::Connect`](../mfc/reference/casyncsocket-class.md#connect).
55
54
56
55
-or-
57
56
58
-
If the socket is a server, set the socket to begin listening (with [CAsyncSocket::Listen](../mfc/reference/casyncsocket-class.md#listen)) for connect attempts from a client. Upon receiving a connection request, accept it with [CAsyncSocket::Accept](../mfc/reference/casyncsocket-class.md#accept).
57
+
If the socket is a server, set the socket to begin listening (with [`CAsyncSocket::Listen`](../mfc/reference/casyncsocket-class.md#listen)) for connect attempts from a client. Upon receiving a connection request, accept it with [`CAsyncSocket::Accept`](../mfc/reference/casyncsocket-class.md#accept).
59
58
60
-
After accepting a connection, you can perform such tasks as validating passwords.
59
+
After accepting a connection, you can do tasks like validating passwords.
61
60
62
61
> [!NOTE]
63
-
> The `Accept` member function takes a reference to a new, empty `CSocket` object as its parameter. You must construct this object before you call `Accept`. If this socket object goes out of scope, the connection closes. Do not call `Create` for this new socket object. For an example, see the article [Windows Sockets: Sequence of Operations](../mfc/windows-sockets-sequence-of-operations.md).
62
+
> The `Accept` member function takes a reference to a new, empty `CSocket` object as its parameter. You must construct this object before you call `Accept`. If this socket object goes out of scope, the connection closes. Don't call `Create` for this new socket object. For an example, see the article [Windows Sockets: Sequence of Operations](../mfc/windows-sockets-sequence-of-operations.md).
64
63
65
64
1. Carry out communications with other sockets by calling the `CAsyncSocket` object's member functions that encapsulate the Windows Sockets API functions.
66
65
67
-
See the Windows Sockets specification and class [CAsyncSocket](../mfc/reference/casyncsocket-class.md) in the *MFC Reference*.
66
+
See the Windows Sockets specification and class [`CAsyncSocket`](../mfc/reference/casyncsocket-class.md) in the *MFC Reference*.
68
67
69
68
1. Destroy the `CAsyncSocket` object.
70
69
71
-
If you created the socket object on the stack, its destructor is called when the containing function goes out of scope. If you created the socket object on the heap, using the **`new`** operator, you are responsible for using the **`delete`** operator to destroy the object.
70
+
If you created the socket object on the stack, its destructor is called when the containing function goes out of scope. If you created the socket object on the heap, using the **`new`** operator, you're responsible for using the **`delete`** operator to destroy the object.
72
71
73
-
The destructor calls the object's [Close](../mfc/reference/casyncsocket-class.md#close) member function before destroying the object.
72
+
The destructor calls the object's [`Close`](../mfc/reference/casyncsocket-class.md#close) member function before destroying the object.
74
73
75
74
For an example of this sequence in code (actually for a `CSocket` object), see [Windows Sockets: Sequence of Operations](../mfc/windows-sockets-sequence-of-operations.md).
76
75
77
-
## <aname="_core_your_responsibilities_with_casyncsocket"></a> Your Responsibilities with CAsyncSocket
76
+
## <aname="_core_your_responsibilities_with_casyncsocket"></a> Your responsibilities with `CAsyncSocket`
78
77
79
-
When you create an object of class [CAsyncSocket](../mfc/reference/casyncsocket-class.md), the object encapsulates a Windows **SOCKET** handle and supplies operations on that handle. When you use `CAsyncSocket`, you must deal with all the issues you might face if using the API directly. For example:
78
+
When you create an object of class [`CAsyncSocket`](../mfc/reference/casyncsocket-class.md), the object encapsulates a Windows **`SOCKET`** handle and supplies operations on that handle. When you use `CAsyncSocket`, you must deal with all the issues you might face if using the API directly. For example:
80
79
81
80
- "Blocking" scenarios.
82
81
@@ -86,14 +85,12 @@ When you create an object of class [CAsyncSocket](../mfc/reference/casyncsocket-
86
85
87
86
For definitions of these terms and additional information, see [Windows Sockets: Blocking](../mfc/windows-sockets-blocking.md), [Windows Sockets: Byte Ordering](../mfc/windows-sockets-byte-ordering.md), [Windows Sockets: Converting Strings](../mfc/windows-sockets-converting-strings.md).
88
87
89
-
Despite these issues, class `CAsycnSocket` may be the right choice for you if your application requires all the flexibility and control you can get. If not, you should consider using class `CSocket` instead. `CSocket` hides a lot of detail from you: it pumps Windows messages during blocking calls and gives you access to `CArchive`, which manages byte order differences and string conversion for you.
88
+
Despite these issues, class `CAsyncSocket` may be the right choice for you if your application requires all the flexibility and control you can get. If not, consider using class `CSocket` instead. `CSocket` hides many details from you: it pumps Windows messages during blocking calls and gives you access to `CArchive`, which manages byte order differences and string conversion for you.
0 commit comments