ilDeclarePipeInvalid(3X)

NAME

ilDeclarePipeInvalid() − set an Image Library pipe state to IL_PIPE_INVALID

SYNOPSIS

ilBool
ilDeclarePipeInvalid (

ilPipe pipe,

ilError error);

DESCRIPTION

ilDeclarePipeInvalid() sets the pipe state of pipe to IL_PIPE_INVALID and sets context->error to error. This function is needed when an application encounters an error prior to using ilAddPipeElement() unless the error was found by ilGetPipeInfo(). Upon finding an error, ilGetPipeInfo() automatically sets the pipe state to IL_PIPE_INVALID.

Because ilDeclarePipeInvalid() causes the pipe execution to abort, this call must not be used within one of the four calls that are passed to ilAddPipeElement(): Init(), Cleanup(), Destroy(), or Execute().

pipe identifies an ilPipe structure created by ilCreatePipe().

error identifies an error code that applies to the error encountered.

RETURN VALUE

Although ilDeclarePipeInvalid() always succeeds, it always returns FALSE, so that pipe execution can be cancelled with a single call, such as a call with the following format:

if (error-in-forming-the-pipe)
return ilDeclarePipeInvalid (pipe, errorCode);

ERRORS

If this call fails, context->error receives a non-zero error code.

EXAMPLE

The following example declares the pipe invalid, and returns an error, if the current pipe state is not IL_PIPE_FORMING.

ilPipe pipe;

ilRect rect;

ilPipeInfo info;

ilImageDes des;

ilImageFormat format;
.
.
.

if (ilGetPipeInfo (pipe, FALSE, &info, &des, &format)

!= IL_PIPE_FORMING) {

if (!pipe->context->error)

return (ilDeclarePipeInvalid

(pipe, IL_ERROR_PIPE_STATE));

return (pipe->context->error);

}

AUTHOR

ilDeclarePipeInvalid() was developed by HP.

Museum

Related Articles