GRUPO DE LLAMADAS DOSxxx (7)
Cauces (pipes)


DosConnectNPipe

DosConnectNPipe prepara un named pipe para aceptar peticiones DosOpen desde un cliente. Si el extremo del cauce ya estaba abierto, DosConnectNPipe retorna inmediatamente. Si no es así, depende del modo en que haya sido definida. Si es blocking, el proceso servidor se congela hasta que un cliente habra el cauce; si es nonblocking, retorna inmediatamente con el error Cauce no abierto. Si el cauce fue abierto y luego cerrado por un cliente, pero no ha sido desconectado con DosDisConnectNPipe por el servidor, retorna un error El cauce está cerrado (Error_Broken_Pipe). Si es un cliente quien ejecuta esta llamada, se devuelve el error Cauce incorrecto.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
APIRET rc; /* Codigo de error */

rc = DosConnectNPipe(hpipeHandle);

Parámetros

hpipeHandleEl handle de un named pipe a ser activado (devuelto al proceso servidor por DosCreateNPipe).

Codigos de error

0Sin error
95Interrupción
109El cauce (pipe) está cerrado
230Cauce incorrecto
233Cauce no abierto


DosCreateNPipe

DosCreateNPipe crea un named pipe.

#define INCL_BASE
#include <os2.h>

PSZ pszFileName;
PHPIPE phpipePipeHandle;
ULONG ulOpenMode;
ULONG ulPipeMode;
ULONG ulOutBufSize;
ULONG ulInBufSize;
ULONG ulTimeOut;
APIRET rc; /* Codigo de error */

rc = DosCreateNPipe(pszFileName, phpipePipeHandle, ulOpenMode, ulPipeMode, ulOutBufSize, ulInBufSize, ulTimeOut);

Parámetros

pszFileNamePuntero a una cadena de caracteres con el nombre del cauce a crear. Es necesario que comience con el prefijo \PIPE\ y cumplir las normas de nombres del sistema de archivos.
phpipePipeHandleUn puntero a una zona de memoria donde OS/2 devolverá un handle al cauce que estamos creando.
ulOpenModeUna variable cuyos bits tienen el siguiente significado:
Bit Descripción
31-16 Reservado
15 Reservado. Tiene que ser 0.
14 Write-through. Tiene sentido en el caso de cauces remotos (en otro sistema conectado en red). Si es 0, los datos a enviar pueden ser almacenados en un buffer con el fin de enviarlos todos juntos. Si es 1, los datos serán enviados inmediatamente.
13-8 Reservado
7 Bit de herencia. Si es 0, el cauce pertenecerá también a los procesos hijos. Si es 1, será un cauce privado, y no será heredado por ningún hijo.
6-3 Reservado. Tiene que valer 0.
2-0 Modo de acceso. Indica el sentido de los datos:
000 = (NP_ACCESS_INBOUND) cauce de entrada (del cliente al servidor).
001 = (NP_ACCESS_OUTBOUND) cauce de salida (del servidor al cliente).
010 = (NP_ACCESS_DUPLEX) cauce bidireccional (de cliente a servidor y viceversa). Cualquier otro valor no será válido.
ulPipeModeSus bits tienen los siguientes significados:
Bit Descripción
31-16 Reservado.
15 Modo de bloqueo.
0 = (NP_WAIT) Modo blocking. DosRead y DosWrite se congelan hasta que haya datos disponibles.
1 = (NP_NOWAIT) Modo nonblocking. DosRead y DosWrite retornan inmediatamente si no hay datos disponibles.
DosRead retorna un error No hay datos; DosWrite retorna 0 como cantidad de datos escritos si no queda sitio en el buffer del cauce. En caso contrario, no devuelve error.
14-12 Reservado.
11-10 Tipo de cauce.
00 = (NP_TYPE_BYTE) El cauce está orientado a byte. Esto es, los datos son escritos como una ráfaga de bytes, y recuperados de igual forma.
01 = (NP_TYPE_MESSAGE) El cauce está orientado a mensajes. Esto es, cada vez que se escribe algo, el sistema recuerda su longitud, y al recuperarlo devuelve exactamente el mismo número de bytes introducidos de cada vez. Esto lo almacena en los dos primeros bytes del mensaje (cabecera del mensaje). Una cabecera de ceros está reservada, y no se admiten mensajes de longitud cero.
9-8 Modo de lectura.
00 = (NP_READMODE_BYTE) Modo orientado a bytes. Lee el cauce como una ráfaga de bytes.
01 = (NP_READMODE_MESSAGE) Modo orientado a mensajes. Lee el cauce como un conjunto de mensajes.
Los cauces de mensaje pueden ser leidos tanto como mensajes como bytes; los cauces de bytes sólo pueden ser leidos como bytes.
7-0 ICount (Instance Count). Cuando la primera instancia de una named pipe es creada, ICount especifica cuantas instancias serán creadas. El número de instancias determina cuantos clientes se pueden atender a la vez. Si se intentan definir más instancias de las posibles, se devuelve un error. Los posibles valores son:
1 : Solo se admite una instancia (la actual).
1 < n < 255 : Se admiten n instancias.
-1 : Se admiten ilimitadas instancias.
0 : reservado.
ulOutBufSizeNúmero de bytes que debe reservar OS/2 para el buffer de salida (servidor a cliente).
ulInBufSizeNúmero de bytes que debe reservar OS/2 para el buffer de entrada (cliente a servidor).
ulTimeOutEl valor por defecto para el TimeOut de DosWaitNPipe. Solo se tiene que especificar en la primera instancia. Si se especifica 0, se toma el valor por defecto de 50 milisegundos.

Codigos de error

0Sin error
3Path no encontrado
8No hay suficiente memoria
84Fuera de las estructuras (error interno)
87Parámetro no válido
231Cauce (pipe) ocupado.


DosCreatePipe

DosCreatePipe crea un cauce sin nombre (unnamed pipe).

#define INCL_BASE
#include <os2.h>

PHFILE pshfReadHandle;
PHFILE pshfWriteHandle;
ULONG ulPipeSize;
APIRET rc; /* Codigo de error */

rc = DosCreatePipe(pshfReadHandle, pshfWriteHandle, ulPipeSize);

Parámetros

pshfReadHandleUn puntero a una doble palabra donde OS/2 devolverá el handle de lectura para el cauce. Este handle deberá ser usado por el proceso que quiera leer del cauce.
pshfWriteHandleUn puntero a una doble palabra donde OS/2 devolverá el handle de escritura para el cauce. Este handle deberá ser usado por el proceso que quiera escribir en el cauce.
ulPipeSizeEl tamaño en bytes del buffer del cauce.

Codigos de error

0Sin error
8No hay suficiente memoria


DosDisConnectNPipe

DosDisConnectNPipe sirve de acuse de recibo para un proceso que ha cerrado un named pipe. Mientras el servidor no ejecute esta llamada (sobre un cauce cerrado por un cliente) recibirá un valor de cero en BytesRead si intenta leer, o un error BROKEN_PIPE (el cauce está cerrado, error 109) si intenta escribir. El cauce no puede ser usado por otro cliente hasta que el servidor ejecute DosConnectNPipe. DosDisConnectNPipe también libera todos los threads bloqueados en un DosRead.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
APIRET rc; /* Codigo de error */

rc = DosDisConnectNPipe(hpipeHandle);

Parámetros

hpipeHandleHandle de un named pipe a desconectar.

Codigos de error

0Sin error
109El cauce (pipe) está cerrado
230Cauce incorrecto


DosDupHandle

DosDupHandle obtiene un nuevo handle para un fichero ya abierto, de modo que se puede usar cualquiera de los dos para referirse a él. El uso de DosClose sobre un handle no afectará al handle duplicado.

#define INCL_BASE
#include <os2.h>

HFILE OldFileHandle;
PHFILE pshfNewFileHandle;
APIRET rc; /* Codigo de error */

rc = DosDupHandle(OldFileHandle, pshfNewFileHandle);

Parámetros

OldFileHandleHandle del fichero o cauce a duplicar.
pshfNewFileHandlePuntero a una doble palabra. Si al hacer la llamada contiene 0xFFFFFFFF, OS/2 devolverá el primer valor libre que haya. Si contiene un valor distinto, asociará el fichero con ese número. Por ejemplo, si como valor introducimos 0, OS/2 asociará la entrada estandar del sistema al fichero/cauce indicado en OldFileHandle; si vale 1, OS/2 asociará la salida estandar del sistema, y si vale 2, OS/2 asociará la salida de error estandar. Si el nuevo handle indicado es igual al de algún fichero abierto, OS/2 lo cerrará primero.

Codigos de error

0Sin error
4Demasiados archivos abiertos
6HANDLE no válido
114El handle de destino no es válido


DosPeekNPipe

DosPeekNPipe permite examinar el dato en un named pipe sin eliminarlo. También devuelve información sobre el estado del cauce. Esta función nunca se bloquea; siempre retorna inmediatamente. El valor del estado puede ser usado por el cliente o el servidor para tomar la acción adecuada.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
PVOID pBuffer;
ULONG ulBufferLen;
PULONG pBytesRead;
PAVAILDATA pBytesAvail;
PULONG pPipeState;
APIRET rc; /* Codigo de error */

rc = DosPeekNPipe(hpipeHandle, pBuffer, ulBufferLen, pBytesRead, pBytesAvail, pPipeState);

Parámetros

hpipeHandleHandle del named pipe a examinar. DosCreateNPipe devuelve el handle del servidor; DosOpen devuelve el handle del cliente.
pBufferUn puntero al buffer de salida.
ulBufferLenNúmero de bytes a leer del cauce.
pBytesReadUn puntero a una posición de memoria donde OS/2 devolverá el número de bytes leidos.
pBytesAvailUn puntero a una zona de memoria de 4 bytes donde OS/2 devolverá el número de bytes que están disponibles en el cauce. La estructura del buffer es:
Bit Descripción
32-16 Número de bytes que contiene el buffer del cauce (incluyendo bytes de cabecera y bytes que ya han sido examinados).
15-0 Número de bytes que componen el mensaje actual (0 para un cauce orientado a byte).
pPipeStateUn puntero a una posición de memoria donde OS/2 devolverá el estado del cauce
Valor Significado
1 (NP_STATE_DISCONNECTED) Desconectado
2 (NP_STATE_LISTENING) En escucha
3 (NP_STATE_CONNECTED) Conectado
4 (NP_STATE_CLOSING) Cerrándose

El cauce está desconectado inmediatamente después de una llamada a DosCreateNPipe o a DosDisConnectNPipe.
El cauce está en escucha después de que el servidor ejecute DosConnectNPipe.
El cauce está conectado después de que un cliente haya ejecutado con éxito DosOpen.
El cauce está cerrándose después de que un cliente haya ejecutado DosClose al handle del cauce y a todos sus duplicados.

Codigos de error

0Sin error
230Cauce incorrecto
231Cauce (pipe) ocupado.
233Cauce no abierto


DosQueryNPHState

DosQueryNPHState devuelve información sobre un named pipe.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
PULONG pPipeHandleState;
APIRET rc; /* Codigo de error */

rc = DosQueryNPHState(hpipeHandle, pPipeHandleState);

Parámetros

hpipeHandleEl handle del named pipe a comprobar.
pPipeHandleStateUn puntero a una posición de memoria donde OS/2 devolverá el estado del cauce.
Bit Descripción
31-16 Reservado.
15 Modo de bloqueo.
0 = (NP_WAIT) Modo blocking. DosRead y DosWrite se congelan hasta que haya datos disponibles.
1 = (NP_NOWAIT) Modo nonblocking. DosRead y DosWrite retornan inmediatamente si no hay datos disponibles.
DosRead retorna un error No hay datos; DosWrite retorna 0 como cantidad de datos escritos si no queda sitio en el buffer del cauce. En caso contrario, no devuelve error.
14 Si es 0 (NP_END_CLIENT) el handle es para el cliente del cauce.
Si es 1 (NP_END_SERVER) el handle es para el servidor del cauce.
13-12 Reservado.
11-10 Tipo de cauce.
00 = (NP_TYPE_BYTE) El cauce está orientado a byte. Esto es, los datos son escritos como una ráfaga de bytes, y recuperados de igual forma.
01 = (NP_TYPE_MESSAGE) El cauce está orientado a mensajes. Esto es, cada vez que se escribe algo, el sistema recuerda su longitud, y al recuperarlo devuelve exactamente el mismo número de bytes introducidos de cada vez. Esto lo almacena en los dos primeros bytes del mensaje (cabecera del mensaje). Una cabecera de ceros está reservada, y no se admiten mensajes de longitud cero.
9-8 Modo de lectura.
00 = (NP_READMODE_BYTE) Modo orientado a bytes. Lee el cauce como una ráfaga de bytes.
01 = (NP_READMODE_MESSAGE) Modo orientado a mensajes. Lee el cauce como un conjunto de mensajes.
Los cauces de mensaje pueden ser leidos tanto como mensajes como bytes; los cauces de bytes sólo pueden ser leidos como bytes.
7-0 ICount (Instance Count). Número de instancias. Determina cuantos clientes se pueden atender a la vez. Los posibles valores son:
1 : Solo se admite una instancia (la actual).
1 < n < 255 : Se admiten n instancias.
-1 : Se admiten ilimitadas instancias.
0 : reservado.

Codigos de error

0Sin error
230Cauce incorrecto
233Cauce no abierto


DosSetNPHState

DosSetNPHState permite cambiar el modo de bloqueo y de lectura de un named pipe.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
ULONG ulPipeHandleState;
APIRET rc; /* Codigo de error */

rc = DosSetNPHState(hpipeHandle, ulPipeHandleState);

Parámetros

hpipeHandleEl handle del cauce a cambiar de estado.
ulPipeHandleUn campo de bits con los siguientes significados:
Bit Descripción
31-16 Reservado.
15 Modo de bloqueo.
0 = (NP_WAIT) Modo blocking. DosRead y DosWrite se congelan hasta que haya datos disponibles.
1 = (NP_NOWAIT) Modo nonblocking. DosRead y DosWrite retornan inmediatamente si no hay datos disponibles.
DosRead retorna un error No hay datos; DosWrite retorna 0 como cantidad de datos escritos si no queda sitio en el buffer del cauce. En caso contrario, no devuelve error.
14-10 Reservado.
9-8 Modo de lectura.
00 = (NP_READMODE_BYTE) Modo orientado a bytes. Lee el cauce como una ráfaga de bytes.
01 = (NP_READMODE_MESSAGE) Modo orientado a mensajes. Lee el cauce como un conjunto de mensajes.
Los cauces de mensaje pueden ser leidos tanto como mensajes como bytes; los cauces de bytes sólo pueden ser leidos como bytes.
7-0 Reservado. Debe ser 0.

Codigos de error

0Sin error
87Parámetro no válido
230Cauce incorrecto
231Cauce (pipe) ocupado.
233Cauce no abierto


DosSetNPipeSem

DosSetNPipeSem asocia a un named pipe un semáforo de evento compartido. Solo funciona con cauces locales. Si se intenta hacer con un cauce remoto (situado en otra máquina de la red) dará un error Función no válida. Si ya había un semáforo asociado al cauce, DosSetNPipeSem lo reemplaza con el nuevo semáforo.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
HSEM hsemSemHandle;
ULONG ulKeyHandle;
APIRET rc; /* Codigo de error */

rc = DosSetNPipeSem(hpipeHandle, hsemSemHandle, ulKeyHandle);

Parámetros

hpipeHandleEl handle del cauce al que se le quiere asociar el semáforo de evento.
hsemSemHandleEl handle de un semafor de evento que es activado (posted) cuando el cauce tiene datos disponibles para leer o bien espacio disponible para escribir.
ulKeyHandleUn valor que permite distinguir eventos provenientes de cauces distintos asociados al mismo semáforo.

Codigos de error

0Sin error
1Función no válida
6HANDLE no válido
87Parámetro no válido
230Cauce incorrecto
233Cauce no abierto


DosWaitNPipe

DosWaitNPipe espera a que haya disponible una instancia de un named pipe. Este caso se da cuando todas las posibles instancias de un cauce están ocupadas por procesos cliente. Solo se puede usar cuando DosOpen ha devuelto el error Cauce ocupado. Si DosWaitNPipe no devuelve error, el cliente debe repetir la llamada DosOpen para abrir el cauce. Si hay varios procesos esperando por una instancia libre de un mismo cauce, OS/2 se lo cederá primero al que tenga mayor prioridad; si dos tienen la misma prioridad, recibirá la instancia el que lleve más tiempo esperando.

#define INCL_BASE
#include <os2.h>

PSZ pszFileName;
ULONG ulTimeOut;
APIRET rc; /* Codigo de error */

rc = DosWaitNPipe(pszFileName, ulTimeOut);

Parámetros

pszFileNamePuntero a una cadena ASCIIZ con el nombre del cauce a abrir.
ulTimeOutEl tiempo máximo, en milisegundos, que se esperará para que se libere una instancia del cauce. Cuando se indica un tiempo de 0, se usa el valor TimeOut definido en DosCreateNPipe. Cuando se indica un valor de -1, se espera un tiempo indefinido.

Codigos de error

0Sin error
2Fichero no encontrado
95Interrupción
231Cauce (pipe) ocupado.

 Indice