Writing code for human beings: IN, OUT and INOUT

By Ran Arad

Categories: SDKs

May 8th, 2008

Checking the searches that lead people to this blog revealed that they search for “Radvision INOUT”. Thus, on public demand, I will explain the super-secret-non-more-secret parameter guidelines. From RADVISION’s common type definitions:

/* Some "empty" definitions that we can use for readability of the code */
#define IN
#define OUT
#define INOUT

What this simply means is these words are replaced by nothing; they are just indications for the reader, not the compiler. I think mini-comments may be the best description – they are there to help whoever is going over the list of parameters stay alert as to which parameters will be manipulated during the execution of the command. In contrast to comments and documentation, these additions are usually considered as part of the prototype by assistance programs, which means they are displayed as a tip while you write.

To sum up: since writing an SDK or even an internal layer or module, sometimes you want to indicate the usage of the parameters passed. One way to do it is to declare input as “const” and the rest will be considered output, but I will show that the hybrid INOUT has important uses as well.

An example, from the H.323 protocol stack:

RVAPI RvStatus RVCALLCONV cmProtConnNew(
    IN    HAPP                  hApp,
    IN    cmProtocol            protocol,
    IN    RvBool                bMultiServer,
    IN    hostEventHandler      eventHandler,
    IN    void *                context,
    IN    cmTransportAddress *  remoteAddr,
    INOUT cmTransportAddress *  localAddr,
    OUT   HPROTCONN *           hConn);

The first few parameters are parameters are used as input to the API. The last parameter is used to place the output of the function in (the function returns a status code, and if successful, the output parameter will be set). The second to last parameter is both an input to the function and an output, it is set by the API caller to some value, this value is used by the API and modified if the API is successful. In the example above, the user sets the local address, and may set the IP or port to zero if he wants the OS to decide, on exit, the local address will be set to the real address used. Other uses may be:

• Passing a buffer length and getting the used or needed length
• Passing partial information (aka hints) and receiving full information
• Translating the contents to another format
• Replacing the content as needed (e.g. NAT, DNS)
• Status, state or location updates (e.g. when navigating a data structure)
• In order to destruct an object and invalidate the pointer to it in a single step

Another search term which led people to the blog was "I'm naughty I need spanking". However, there is a limit to crowd-pleasing.