MWCALL

Section: MidWay Programmer's Manual (3C)
Updated: DATE
Index Return to Main Contents

NAME

mwcall mwacall, mwfetch - MidWay service calls

SYNOPSIS

#include <MidWay.h>

int mwcall(char * servicename, char * data, int len , char ** rdata, int * rlen, int * appreturncode, int flags);

int mwacall(char * servicename, char * data, int len, int flags);
int mwfetch(int handle, char ** rdata, int * rlen, int flags);

DESCRIPTION

These calls are used to send a service request to a given service see mwservice(3C)/mwprovide(3C). mwcall() is really a mwacall() mwfetch() pair, and is provided as a convince.

Servicename is a null terminated string of max 32 characters long. In order for this call to succeed some server in the MidWay must have provided a service with name servicename. Data is a pointer to the request buffer passed to the service routine. The number of bytes of data is given by len. Id data is a NULL terminated string len may be 0. Similarly rdata and rlen is used for receiving the return buffer from the service routine. The return buffer is alway allocated with mwalloc() and must be freed by mwfree(). It is not required that the request buffer is allocated by mwalloc(). If it is not mw(a)call will allocate one automatically of the needed size, and free it on the return.

Typically when you pass C structs or C++ objects around you will need to copy the data in the return buffer into the struct or have a pointer to it. Note that if you are using fastpath you may cause a possible shared memory buffer leak. (see mwalloc()).

Appreturncode is provided for the service routine to pass back an application level return/exit code. The use of this is not mandatory. It may be NULL. Handle is used if you have made several mwacall() and want it retrieve a specific reply. If handle is 0 the first reply is returned.

The flags parameter controls some aspects of the calls. There are currently these flags.

MWNOREPLY: Used in mwcall() and mwacall() only. It tells the server that no reply is needed. Note that you don't get any confirmation that the request ever gets processed.
MWNOBLOCK: Used in all calls, specifies that the calls should fail if they encounter a condition where they would block. There are one condition, mwcall() will of course block while reading our own message queue while waiting for the reply from a server. If you want to avoid that condition you must used mwacall() and mwfetch() explicitly.
MWMULTIPLE: This flag is only legal for mwacall, and tells the server if it is OK to send multiple replies. In this case each reply must be fetched seperatly with mwfetch, mwfetch will return 1 if there are more to fetch.

RETURN VALUES

On success mwcall() return 0, and mwfetch returns 0 if there is no more replies from the server or 1 if the server intends to send more replies. mwacall() return the handle that may be used with mwfetch to retrieve the reply. On failure we get a negative errno. If the server signalled a failure by setting returncode to MWFAIL, mwcall() and mwfetch() return -EFAULT.

ERRORS

ENOENT: There are no service with servicename available.
EFAULT: The service routine signalled that it failed.
ENOTCONN: The calling process has not performed a successful mwattach() and is thus not attach to a running system.
EINVAL: flags has a undefined flag set.
EINTR: The subroutine was interrupted by a signal. (Actually one of the underlying msgrcv() or select() system calls were.)
ETIME: The deadline set by mwbegin() was reached, while we were waiting for one or more replys, or before mwcall was called..
ENOBUFS: We are out of MidWays shared memory buffers, see mwd(1).
EAGAIN: The call would block and MWNOBLOCK flags was set.

WARNINGS

EXAMPLES

#include <MidWay.h>

char * data;
int handle, len;

data = mwalloc(100);
strcpy(data, "Hello Service");

handle = mwacall("TESTSERVICE", data, 100, MWMULTIPLE);

if (handle < 0) ; /* ERROR */

while( (rc = mwfetch(handle, &data, &len, 0L)) <= 0) {
        .
        .
        .
        mwfree(data);
        if (rc == 0) break;
};

BUGS

STANDARDS

NONE

This document was created by man2html, using the manual pages.
Time: 11:18:49 GMT, October 24, 2000