IN/OUT 参数以及如何在 C++ 中使用它们

IN/OUT Parameters and how to work with them in C++

提问by danes

When reading documentation on functions from external libraries of different kinds I have always seen the documentation state that a variable has to be [IN/OUT]. Could someone give me a detailed understanding on how [IN/OUT] relates to parameters of a function being passed by reference or by value.

在从不同类型的外部库中阅读有关函数的文档时，我总是看到文档声明变量必须是 [IN/OUT]。有人可以让我详细了解 [IN/OUT] 如何与按引用或按值传递的函数的参数相关联。

Here is an example of a function I have come across that tells me it needs an [IN/OUT] parameter:

这是我遇到的一个函数示例，它告诉我它需要一个 [IN/OUT] 参数：

Prototype:ULONG GetActivationState( ULONG * pActivationState );

原型：ULONG GetActivationState( ULONG * pActivationState );

Parameters

参数

• Type:ULONG*
• Variable: pActivationState
• Mode: IN/OUT

• 类型：ULONG*
• 变量：pActivationState
• 模式：输入/输出

回答by Diego Sevilla

This parameter is in/out because you provide a value that is used inside the function, andthe function modifies it to inform you about something that happened inside the function. The usage of this function would be something like this:

该参数是/，因为您提供的是函数内部使用的值，并且函数修改它通知你的东西，在函数内部发生的事情。这个函数的用法是这样的：

ULONG activationState = 1; // example value
ULONG result = GetActivationState(&activationState);

note that you have to supply the address of the variable so that the function can get the value and set the value outside the function. For instance, the GetActivationStatefunction can perform something like this:

请注意，您必须提供变量的地址，以便函数可以获取该值并在函数外部设置该值。例如，该GetActivationState函数可以执行如下操作：

ULONG GetActivationState(ULONG* pActivationState)
{
    if (*pActivationState == 1)
    {
    // do something
    // and inform by the modification of the variable, say, resetting it to 0
       *pActivationState = 0;
    }
    // ...
    return *pActivationState; // just an example, returns the same value
}

Note how:

注意方法：

1. The function accepts the parameter as a non-const pointer to an UINT. This means it maymodify it.
2. The function can access the value you gave to the parameter by dereferencing it
3. The function can modify the parameter again by dereferencing it.
4. The calling function sees the activationStatevariable holding the newvalue (0 in this case).

1. 该函数接受参数作为指向 UINT 的非常量指针。这意味着它可以修改它。
2. 该函数可以通过取消引用来访问您提供给参数的值
3. 该函数可以通过取消引用来再次修改参数。
4. 调用函数会看到activationState保存新值的变量（在本例中为 0）。

This is an example of "pass by reference", which is performed by using pointers in C (and also with references in C++.)

这是“通过引用传递”的示例，它是通过使用 C 中的指针（以及 C++ 中的引用）来执行的。

回答by Praetorian

This part applies to all types of paramters - most library interfaces try to be C compatible, so it is more common to pass parameters by pointer, rather than by reference.

这部分适用于所有类型的参数——大多数库接口都试图与 C 兼容，因此通过指针而不是通过引用传递参数更为常见。

IN:When a parameter is listed as IN it is a guarantee being offered by the interface that it won't modify that parameter. In my opinion, this is better conveyed by marking the parameter as const, then the language itself will prevent modifications to the value. If this parameter is being passed by value, it is inconsequential whether it is marked IN in the documentation (or const in the prototype) since the parameter is local to the function anyway. But to avoid copying it may be passed by reference or by pointer, in which case the constkeyword becomes very important.

IN：当一个参数被列为 IN 时，它是接口提供的保证，它不会修改该参数。在我看来，通过将参数标记为 来更好地传达这一点const，然后语言本身将阻止对该值的修改。如果这个参数是按值传递的，它在文档中是否标记为 IN（或在原型中标记为 const）是无关紧要的，因为无论如何该参数对于函数来说都是本地的。但是为了避免复制它可以通过引用或指针传递，在这种情况下const关键字变得非常重要。

OUT:A parameter marked OUT usually means that the value of the parameter when it is being passed to the function is not of any importance. In fact, if it being passed by pointer, it may even be required to be NULL, and the function will allocate memory and pass a value back to you.

OUT：标记为 OUT 的参数通常表示该参数在传递给函数时的值并不重要。事实上，如果它是通过指针传递的，它甚至可能被要求为NULL，并且函数会分配内存并将一个值传回给你。

IN/OUT:An IN/OUT parameter usually indicates something where both the input and output values are meaningful. For instance, if you have a library function that fills a buffer, it may require you to pass a pointer to the buffer, along with another pointer indicating the length of the buffer. When the function returns, the second pointer may contain the actual number of bytes that have been written to the buffer.

IN/OUT：IN/OUT 参数通常表示输入和输出值都有意义的东西。例如，如果你有一个填充缓冲区的库函数，它可能需要你传递一个指向缓冲区的指针，以及另一个指示缓冲区长度的指针。当函数返回时，第二个指针可能包含已写入缓冲区的实际字节数。

回答by Dave S

Generally, things marked as IN/OUT will be passed via a non-const pointer or reference, allowing the function to modify the variable directly, as well as read it. Be sure to check the documentation to see if it expects the value to be set prior to passing it in.

通常，标记为 IN/OUT 的内容将通过非常量指针或引用传递，允许函数直接修改变量以及读取它。请务必检查文档以查看它是否希望在传入之前设置该值。

Parameters marked as IN will be passed by value, or by constant pointer or constant reference, disallowing the function from modifying the variable.

标记为 IN 的参数将通过值、常量指针或常量引用传递，不允许函数修改变量。

C++ doesn't enforce OUT-only parameters, but generally they will be passed using non-const pointer or references, similar to IN/OUT.

C++ 不强制 OUT-only 参数，但通常它们将使用非常量指针或引用传递，类似于 IN/OUT。

回答by quant_dev

If a parameter is OUT, it has to be passed by reference. A purely IN parameter would be usually passed by value or const reference, if the cost of copying is too high (nothing prevents the designed from passing it by reference, but it's not very good design IMHO). An IN/OUT parameter must be passed by reference.

如果参数为 OUT，则必须通过引用传递。如果复制的成本太高，一个纯粹的 IN 参数通常会通过值或常量引用传递（没有什么可以阻止设计通过引用传递它，但恕我直言，这不是很好的设计）。IN/OUT 参数必须通过引用传递。

回答by David Hammen

I'm of a mixed mind regarding the use of in, out, and in/out.

我对 in、out 和 in/out 的使用持不同意见。

Upside: When done properly, it communicates intent to the reader of the documentation.

好处：如果做得好，它会将意图传达给文档的读者。

Downside: Far too often it is not done properly. Those designations obviously are not a part of the language; they are either in comments or are in some document that is maintained separately from the code. I've seen far too many cases where a parameter was marked as "out" but the first thing done in the code with that parameter is to use it as a right-hand side value.

缺点：经常没有正确完成。这些名称显然不是语言的一部分；它们要么在注释中，要么在与代码分开维护的某个文档中。我见过太多参数被标记为“out”的情况，但在代码中使用该参数所做的第一件事是将其用作右侧值。

回答by Chris Snowden

You can use by value (simply types) or by constant reference const &for input only parameters. Use non-const reference &or pointer *as in/out parameter to change the value of the variable. You can also use a pointer reference * &to allow you to change the address the actual pointer points to (in/out). As Dave Smithpointed out there is no out only parameter in C++.

您可以按值（简单类型）或按常量引用const &用于仅输入参数。使用非常量引用&或指针*作为输入/输出参数来更改变量的值。您还可以使用指针引用* &来更改实际指针指向的地址（输入/输出）。正如Dave Smith指出的那样，C++ 中没有 out only 参数。