Generated from ./inc/complib/cl_ioctl.h with ROBODoc v4.99.17 on Sun Mar 04 2007 18:17:52

[Modules] Component Library/IOCTL Object

[top][parent][index]

NAME

       IOCTL Object

DESCRIPTION

       The IOCTL object provides functionality for handling IOCTL requests.

       The IOCTL object is only available in kernel mode and provides
       functionality for accessing information about IO requests initiated
       by a user-mode application.  The IOCTL_CODE macro is used in both
       user and kernel mode to initiate and dispatch IOCTL requests, respectively.

       In Linux, in order for the IOCTL object to be used, requests must be
       initiated and handled using the Device Framework abstraction.

SEE ALSO

       Structures:
               cl_ioctl_handle_t

       Callbacks:
               cl_pfn_ioctl_handler_t

       Control Code Generation
               IOCTL_CODE

       Kernel Mode Access
               cl_ioctl_process
               cl_ioctl_complete
               cl_ioctl_type
               cl_ioctl_cmd
               cl_ioctl_ctl_code
               cl_ioctl_in_buf
               cl_ioctl_in_size
               cl_ioctl_out_buf
               cl_ioctl_out_size

       User Mode Access
               cl_ioctl_request
               cl_ioctl_result

[Functions] Component Library: IOCTL Object/cl_ioctl_cmd

[top][index]

NAME

       cl_ioctl_cmd

DESCRIPTION

       Returns the command of an IOCTL

SYNOPSIS

CL_EXPORT uint16_t CL_API
cl_ioctl_cmd(
        IN      cl_ioctl_handle_t       h_ioctl );

PARAMETERS

       h_ioctl
               [in] Handle to an IOCTL

RETURN VALUE

       Returns the command of the specified IOCTL request, as defined using
       the IOCTL_CMD macro.

NOTES

       The cl_ioctl_cmd function is only available in the kernel.

SEE ALSO

       IOCTL Object, cl_ioctl_handle_t, cl_ioctl_type, cl_ioctl_ctl_code

[Functions] Component Library: IOCTL Object/cl_ioctl_complete

[top][index]

NAME

       cl_ioctl_complete

DESCRIPTION

       Fills in completion information for an IOCTL and releases the IOCTL request
       for completion.

SYNOPSIS

CL_EXPORT void CL_API
cl_ioctl_complete(
        IN      cl_ioctl_handle_t       h_ioctl,
        IN      cl_status_t                     io_status,
        IN      size_t                          ret_bytes );

PARAMETERS

       h_ioctl
               Handle to the IOCTL being completed.  This handle was provided to
               the IOCTL handler.

       io_status
               Status of the IOCTL request.

       ret_bytes
               Number of bytes written to the output buffer.

 RETURN VALUES
       This function does not return a value.

SEE ALSO

       IOCTL Object, cl_ioctl_handle_t, cl_ioctl_process

[Functions] Component Library: IOCTL Object/cl_ioctl_ctl_code

[top][index]

NAME

       cl_ioctl_ctl_code

DESCRIPTION

       Returns the 32-bit control code of an IOCTL

SYNOPSIS

CL_EXPORT uint32_t CL_API
cl_ioctl_ctl_code(
        IN      cl_ioctl_handle_t       h_ioctl );

PARAMETERS

       h_ioctl
               [in] Handle to an IOCTL

RETURN VALUE

       Returns the 32-bit control code of the specified IOCTL request,
       as defined using the IOCTL_CMD macro.

NOTES

       The cl_ioctl_ctl_code function is only available in the kernel.

SEE ALSO

       IOCTL Object, cl_ioctl_handle_t, cl_ioctl_type, cl_ioctl_cmd

[Definitions] Component Library: IOCTL Object/cl_ioctl_handle_t

[top][index]

NAME

       cl_ioctl_handle_t

DESCRIPTION

       Opaque handle representing an IO request.

NOTES

       The cl_ioctl_handle_t type is only available in the kernel.
       The cl_ioctl_handle_t type should be treated as opaque, as it
       varies from environment to environment.

SEE ALSO

       IOCTL Object, cl_ioctl_type, cl_ioctl_cmd, cl_ioctl_in_buf,
       cl_ioctl_in_size, cl_ioctl_out_buf, cl_ioctl_out_size,
       cl_ioctl_set_status, cl_ioctl_set_ret_bytes

[Functions] Component Library: IOCTL Object/cl_ioctl_in_buf

[top][index]

NAME

       cl_ioctl_in_buf

DESCRIPTION

       Returns a pointer to the input buffer of an IOCTL.

SYNOPSIS

CL_EXPORT void* CL_API
cl_ioctl_in_buf(
        IN      cl_ioctl_handle_t       h_ioctl );

PARAMETERS

       h_ioctl
               [in] Handle to an IOCTL

RETURN VALUE

       Returns the input buffer of the specified IOCTL request.

NOTES

       The cl_ioctl_in_buf function is only available in the kernel.

       In Windows, for IOCTL operations defined as METHOD_IN_DIRECT, the
       returned pointer points to the MDL describing the input buffer.

SEE ALSO

       IOCTL Object, cl_ioctl_handle_t, cl_ioctl_in_size,
       cl_ioctl_out_buf, cl_ioctl_out_size

[Functions] Component Library: IOCTL Object/cl_ioctl_in_size

[top][index]

NAME

       cl_ioctl_in_size

DESCRIPTION

       Returns the size of the input buffer of an IOCTL.

SYNOPSIS

CL_EXPORT ULONG CL_API
cl_ioctl_in_size(
        IN      cl_ioctl_handle_t       h_ioctl );

PARAMETERS

       h_ioctl
               [in] Handle to an IOCTL

RETURN VALUE

       Returns the size, in bytes, of the input buffer of the specified
       IOCTL request.

NOTES

       The cl_ioctl_in_size function is only available in the kernel.

SEE ALSO

       IOCTL Object, cl_ioctl_handle_t, cl_ioctl_in_buf,
       cl_ioctl_out_buf, cl_ioctl_out_size

[Functions] Component Library: IOCTL Object/cl_ioctl_out_buf

[top][index]

NAME

       cl_ioctl_out_buf

DESCRIPTION

       Returns a pointer to the output buffer of an IOCTL.

SYNOPSIS

CL_EXPORT void* CL_API
cl_ioctl_out_buf(
        IN      cl_ioctl_handle_t       h_ioctl );

PARAMETERS

       h_ioctl
               [in] Handle to an IOCTL

RETURN VALUE

       Returns a pointer to the output buffer of the specified IOCTL request.

NOTES

       The cl_ioctl_out_buf function is only available in the kernel.

       In Windows, for IOCTL operations defined as METHOD_IN_DIRECT or
       METHOD_OUT_DIRECT, the returned pointer points to the MDL describing
       the input buffer.

SEE ALSO

       IOCTL Object, cl_ioctl_handle_t, cl_ioctl_out_size,
       cl_ioctl_in_buf, cl_ioctl_in_size

[Functions] Component Library: IOCTL Object/cl_ioctl_out_size

[top][index]

NAME

       cl_ioctl_out_size

DESCRIPTION

       Returns the size of the output buffer of an IOCTL.

SYNOPSIS

CL_EXPORT ULONG CL_API
cl_ioctl_out_size(
        IN      cl_ioctl_handle_t       h_ioctl );

PARAMETERS

       h_ioctl
               [in] Handle to an IOCTL

RETURN VALUE

       Returns the size, in bytes, of the input buffer of the specified
       IOCTL request.

NOTES

       The cl_ioctl_out_size function is only available in the kernel.

SEE ALSO

       IOCTL Object, cl_ioctl_handle_t, cl_ioctl_out_buf,
       cl_ioctl_in_buf, cl_ioctl_in_size

[Functions] Component Library: IOCTL Object/cl_ioctl_process

[top][index]

NAME

       cl_ioctl_process

DESCRIPTION

       The cl_ioctl_process function unpacks information initiated by a call to
       cl_ioctl_request function and invokes a user-supplied callback.

SYNOPSIS

CL_EXPORT cl_status_t CL_API
cl_ioctl_process(
        IN      void                                    *p_ioctl,
        IN      cl_pfn_ioctl_handler_t  pfn_ioctl_handler,
        IN      void                                    *context_1,
        IN      void                                    *context_2 );

PARAMETERS

       p_ioctl
               [in] Pointer to an OS specific IOCTL information.  In Linux,
               this parameter depends on whether the IOCTL is handled synchronously
               or asynchronously.  See the notes for further detail.
               In Windows, this is a pointer to an IRP.

       pfn_ioctl_handler
               [in] Pointer to the callback function to invoke for handling the IOCTL.
               This callback is independent of the IOCTL command.

       context_1
               [in] First of two context parameters to pass to the handler.

       context_2
               [in] Second of two context parameters to pass to the handler.

 RETURN VALUES
       CL_SUCCESS if the IOCTL was processed successfully.

       Other values to indicate various failures.

NOTES

       Users must call cl_ioctl_complete from within the handler if completing
       the IOCTL request synchronously.  If the IOCTL request's control code is
       invalid, the handler should return CL_INVALID_REQUEST.

       In Linux, the p_ioctl parameter is a copy of the argp parameter on input,
       and on output points to the IOCTL request object passed to the IOCTL
       handler if and only if the IOCTL handler returned CL_PENDING.
       This allows the user to cancel the request by passing the same
       handle to the cancel routine that was passed to the IOCTL handler.
       If all IOCTLs are handled synchronously, it is acceptable to pass the argp
       parameter of the IOCTL entry point instead of a copy.

SEE ALSO

       IOCTL Object, cl_ioctl_handle_t, cl_pfn_ioctl_handler_t, cl_ioctl_complete

[Functions] Component Library: IOCTL Object/cl_ioctl_request

[top][index]

NAME

       cl_ioctl_request

DESCRIPTION

       The cl_ioctl_request is used by user-mode clients to initiate IOCTL
       requests to a device.

SYNOPSIS

CL_EXPORT cl_status_t CL_API
cl_ioctl_request(
        IN              void                    *h_dev,
        IN              uint32_t                ioctl_code,
        IN              void                    *p_in_buf,
        IN              size_t                  in_size,
                OUT     void                    *p_out_buf,
        IN              size_t                  out_size,
                OUT     size_t                  *p_ret_bytes OPTIONAL,
        IN              void                    *p_async_info OPTIONAL );

PARAMETERS

       h_dev
               [in] Handle to the device to which the IOCTL request is targetted.
               In Linux, this is a file descriptor.  In Windows, this is a file
               handle.

       ioctl_code
               [in] Control code for the IOCTL request.

       p_in_buf
               [in] Pointer to the input buffer.

       in_size
               [in] Size, in bytes, of the input buffer.

       p_out_buf
               [out] Pointer to the output buffer.

       out_size
               [in] Size, in bytes, of the output buffer.

       p_ret_bytes
               [out] Number of bytes written to the output buffer.  This parameter is
               mutually exclusive of the p_async_info parameter.

       p_async_info
               [in] For platforms that support asynchronous I/O, supplies a pointer
               to that platform's async I/O structure, if any.  For Windows, this
               is a pointer to an OVERLAPPED structure.  This parameter is mutually
               exclusive of the p_ret_bytes parameter.

SEE ALSO

       IOCTL Object, cl_ioctl_result

[Functions] Component Library: IOCTL Object/cl_ioctl_result

[top][index]

NAME

       cl_ioctl_result

DESCRIPTION

       Checks the status of an asynchronous IOCTL request.

SYNOPSIS

CL_EXPORT cl_status_t CL_API
cl_ioctl_result(
        IN      void            *h_dev,
        IN      void            *p_async_info,
        OUT     size_t          *p_ret_bytes,
        IN      boolean_t       blocking );

PARAMETERS

       h_dev
               [in] Handle to the device to which the IOCTL request is targetted.
               In Linux, this is a file descriptor.  In Windows, this is a file
               handle.

       p_async_info
               [in] For platforms that support asynchronous I/O, supplies a pointer
               to that platform's async I/O structure, if any.  For Windows, this
               is a pointer to an OVERLAPPED structure.  This must be the same
               as that provided in the cl_ioctl_request function.

       p_ret_bytes
               [out] Number of bytes written to the output buffer.

       blocking
               [in] If TRUE, indicates that the call should wait until the
               specified IOCTL request is complete.

 RETURN VALUES
       CL_SUCCESS if the IOCTL request was successful.  p_ret_bytes contains
       the number bytes written to the output buffer.

       CL_PENDING if the IOCTL request is not yet complete.

       Other status values to indicate errors.

SEE ALSO

       IOCTL Object, cl_ioctl_request

[Functions] Component Library: IOCTL Object/cl_ioctl_type

[top][index]

NAME

       cl_ioctl_type

DESCRIPTION

       Returns the type of an IOCTL.

SYNOPSIS

CL_EXPORT uint16_t CL_API
cl_ioctl_type(
        IN      cl_ioctl_handle_t       h_ioctl );

PARAMETERS

       h_ioctl
               [in] Handle to an IOCTL

RETURN VALUE

       Returns the type of the specified IOCTL request, as defined using
       the IOCTL_CMD macro.

NOTES

       The cl_ioctl_type function is only available in the kernel.

SEE ALSO

       IOCTL Object, cl_ioctl_handle_t, cl_ioctl_cmd, cl_ioctl_ctl_code

[Definitions] Component Library: IOCTL Object/cl_pfn_ioctl_handler_t

[top][index]

NAME

       cl_pfn_ioctl_handler_t

DESCRIPTION

       The cl_pfn_ioctl_handler_t function type defines the prototype for
       IOCTL handlers used when handling IOCTL requests initiated by
       cl_ioctl_request.

SYNOPSIS

typedef cl_status_t
(CL_API *cl_pfn_ioctl_handler_t)(
        IN      cl_ioctl_handle_t       h_ioctl,
        IN      void                            *context_1,
        IN      void                            *context_2 );

PARAMETERS

       h_ioctl
               [in] Handle to the IOCTL request.

       context_1
               [in] First context parameters, as provided to cl_ioctl_process.

       context_2
               [in] Second context parameters, as provided to cl_ioctl_process.

 RETURN VALUES
       CL_SUCCESS if the IOCTL was completed successfully.

       CL_PENDING if the IOCTL is being processed asynchronously.

       Other return values in case of errors.

NOTES

       It is acceptable to complete the IOCTL successfully to report an error
       status in the output buffer.

SEE ALSO

       IOCTL Object, cl_ioctl_handle_t, cl_ioctl_process

[Definitions] Component Library: IOCTL Object/IOCTL_CODE

[top][index]

NAME

       IOCTL_CODE

DESCRIPTION

       Macro for defining IO control command codes.

SYNOPSIS

*       uint32_t IOCTL_CODE( uint16_t type, uint16_t cmd )

PARAMETERS

       type
               [in] user-defined type representing the type of command.  For Linux,
               the type is truncated to 8-bits.  For Windows, the type is a 16-bit
               value, as described in "Specifying Device Types" in the DDK docs.

       cmd
               [in] User-defined command.  For Linux, the command field is truncated
               to 8-bits.  For Windows, the command can be 12-bits, with values
               below 0x800 reserved by Microsoft for system defined commands.

RETURN VALUE

       A 32-bit control code.  User-mode clients use the control code to initiate
       requests.  Kernel-mode clients use the control code to distinguish between
       different requests.

NOTE

       In Windows, all IOCTL command codes defined with the IOCTL_CODE command
       result in FILE_ANY_ACCESS and METHOD_BUFFERED being specified.

SEE ALSO

       IOCTL Object, cl_dev_ioctl, cl_ioctl_type, cl_ioctl_cmd