Is AttachedDevice an incorrect paramenter name in the function prototype of IoAttachDevice?

Hi all,

The function prototype of IoAttachDevice is declared as follows in the
DDK documentation.

/*********************************/
NTSTATUS
IoAttachDevice(
IN PDEVICE_OBJECT SourceDevice,
IN PUNICODE_STRING TargetDevice,
OUT PDEVICE_OBJECT *AttachedDevice
);

Parameters

SourceDevice
Pointer to the caller-created device object.

TargetDevice
Pointer to a buffer containing the name of the device object to which
the specified SourceDevice is to be attached.

AttachedDevice
Pointer to caller-allocated storage for a pointer. On return, contains
a pointer to the target device object if the attachment succeeds.
/*********************************/

According to the statement above, AttachedDevice should point to a
lower device, i.e the target device. However, in English, if an upper
device is attached to a lower device, then the upper device, rather
than the lower device, should be called "attached device". So, the
last paramenter should be named DeviceAttachedTo or something like
this.

I'm not a native English speaker. I eagerly hope those who speak
English can give me some tips.

Maxim
Sun Aug 26 08:04:05 CDT 2007

IoAttachDevice is obsolete. Use IoAttachDeviceToDeviceStack(Safe) instead.

--
Maxim Shatskih, Windows DDK MVP
StorageCraft Corporation
maxim@storagecraft.com
http://www.storagecraft.com

"xmllmx" <xmllmx@gmail.com> wrote in message
news:1188119088.339920.9690@i38g2000prf.googlegroups.com...
> Hi all,
>
> The function prototype of IoAttachDevice is declared as follows in the
> DDK documentation.
>
> /*********************************/
> NTSTATUS
> IoAttachDevice(
> IN PDEVICE_OBJECT SourceDevice,
> IN PUNICODE_STRING TargetDevice,
> OUT PDEVICE_OBJECT *AttachedDevice
> );
>
> Parameters
>
> SourceDevice
> Pointer to the caller-created device object.
>
> TargetDevice
> Pointer to a buffer containing the name of the device object to which
> the specified SourceDevice is to be attached.
>
> AttachedDevice
> Pointer to caller-allocated storage for a pointer. On return, contains
> a pointer to the target device object if the attachment succeeds.
> /*********************************/
>
> According to the statement above, AttachedDevice should point to a
> lower device, i.e the target device. However, in English, if an upper
> device is attached to a lower device, then the upper device, rather
> than the lower device, should be called "attached device". So, the
> last paramenter should be named DeviceAttachedTo or something like
> this.
>
> I'm not a native English speaker. I eagerly hope those who speak
> English can give me some tips.
>

Walter
Sun Aug 26 11:34:14 CDT 2007

"Maxim S. Shatskih" wrote:
> IoAttachDevice is obsolete. Use IoAttachDeviceToDeviceStack(Safe) instead.
> "xmllmx" <xmllmx@gmail.com> wrote in message
> > According to the statement above, AttachedDevice should point to a
> > lower device, i.e the target device. However, in English, if an upper
> > device is attached to a lower device, then the upper device, rather
> > than the lower device, should be called "attached device". So, the
> > last paramenter should be named DeviceAttachedTo or something like
> > this.

But tu answer the OP's question, the names of the parameters would be
indicative of their actual purpose in the best of all possible worlds.
But we don't live in that world, so you have to ignore the name and
trust the description.

--
Walter Oney, Consulting and Training
http://www.oneysoft.com

AntonBassov
Sun Aug 26 14:56:02 CDT 2007

Unfortunately, MSDN has quite a few omissions that are much more serious than
the one you have mentioned - after all, unlike more serious omissions and
inconsistencies, this one is not going to result in buggy code, don't you
think?
Therefore, there is nothing to worry about here - you just make up things
out of nothing....

Anton Bassov


"xmllmx" wrote:

> Hi all,
>
> The function prototype of IoAttachDevice is declared as follows in the
> DDK documentation.
>
> /*********************************/
> NTSTATUS
> IoAttachDevice(
> IN PDEVICE_OBJECT SourceDevice,
> IN PUNICODE_STRING TargetDevice,
> OUT PDEVICE_OBJECT *AttachedDevice
> );
>
> Parameters
>
> SourceDevice
> Pointer to the caller-created device object.
>
> TargetDevice
> Pointer to a buffer containing the name of the device object to which
> the specified SourceDevice is to be attached.
>
> AttachedDevice
> Pointer to caller-allocated storage for a pointer. On return, contains
> a pointer to the target device object if the attachment succeeds.
> /*********************************/
>
> According to the statement above, AttachedDevice should point to a
> lower device, i.e the target device. However, in English, if an upper
> device is attached to a lower device, then the upper device, rather
> than the lower device, should be called "attached device". So, the
> last paramenter should be named DeviceAttachedTo or something like
> this.
>
> I'm not a native English speaker. I eagerly hope those who speak
> English can give me some tips.
>
>