analytics/informix/SDK/incl/iad_services.h

/*
 *
 *  Licensed Materials - Property of IBM and/or HCL
 *
 *  IBM Informix Dynamic Server
 *  Copyright IBM Corporation 1996, 2012
 *  (c) Copyright HCL Technologies Ltd. 2017.  All Rights Reserved.
 *
 ***************************************************************************
*/

#ifndef IAD_SERVICES_H
#define IAD_SERVICES_H
#include "API.h"

#ifdef __cplusplus
extern "C" {
#endif

#ifndef MAX_PATH
#define MAX_PATH (255)
#endif
/*
Interface to the system-wide services file
provides functions for adding and removing services, testing for the presence of services

all functions return IAD_E_NOERROR on success and IAD_E_STRUCTURE_NOT_INITIALIZED if a null pointer to install structure is passed.
except for iadServicesLoad, iadServicesFree and iadServicesStatus, all functions will also return IAD_E_STRUCTURE_NOT_INITIALIZED if iadServicesLoad has not been called since zeroing the structure or calling iadServicesFree.
if an internal, memory related error is encountered, IAD_E_MEMORY_ALLOCATION_FAILURE is returned.

//use case: add the 'tf2' service on port 27015 for tcp and udp if the port and name are both free
int main() {
	install_t is;
	memset(&is,0,sizeof(install_t));
	if (iadServicesLoad(&is,"c:\\windows\\system32\\drivers\\etc\\hosts") != IAD_E_NOERROR) { 
		printf("Could not load services file\n");
		return 1; 
	}
	if (iadServicesTestPort(&is,27015,NULL) == PORT_FREE && iadServicesTestName(&is,"tf2",NULL) == NAME_FREE) {
		if (iadServicesAddService(&is,"tf2",27015,"tcp",0,NULL,NULL) == IAD_E_NOERROR && iadServicesAddService(&is,"tf2",27015,"udp",0,NULL,NULL)) {
			iadServicesDeploy(&is);
		}
	}
	iadServicesFree(&is);
	return 0;
}

//use case: add a generated entry for an ids instance
int main() {
	install_t is;
	char *name;
	unsigned short port;
	memset(&is,0,sizeof(install_t));
	if (iadServicesLoad(&is,"/etc/services") != IAD_E_NOERROR) { 
		printf("Could not load services file\n");
		return 1; 
	}
	if (iadServicesGenerateName(&is,&name,"ids1170") == IAD_E_NOERROR && iadServicesGeneratePort(&is,&port,9088) == IAD_E_NOERROR) {
		if (iadServicesAddService(&is,name,port,"tcp",0,NULL,"Added by sample use case") == IAD_E_NOERROR) {
			if (iadServicesDeploy(&is) == IAD_E_NOERROR) {
				printf("You have been assigned the service '%s' on port %d\n",name,(int)port);
			} else {
				printf("An open name and port were found, but could not be written to the services file\n");
			}
		}
		free(name);
	} else {
		printf("An open name and port could not be found, exiting.\n");
	}
	iadServicesFree(&is);
	return 0;
}
*/

/*
read in the services at file and get lists of used ports and names
the install structure or at least the services section of it MUST have been zeroed out before this function is called
file: the path to the services file

returns IAD_E_INVALID_PARAMETER if the zeroed-out-requirement above is not met (double loads, neglecting to memset, etc)
returns IAD_E_NULLPOINTER if file is null
returns IAD_E_FILE_NONEXISTENT_ERROR if file does not exist
*/
EXPORT int STDCALL iadServicesLoad(install_t *is, const char *file);

/*
returns the status of the services list
Load or Deploy set the state to clean
AddService, AddComment or Delete set the state to dirty
Free sets the state to uninitialized

returns SVCST_UNINITIALIZED if the services have been freed or have not been loaded
returns SVCST_CLEAN if the services are synchronized with disk
returns SVCST_DIRTY if any changes have been made
*/
EXPORT int STDCALL iadServicesStatus(install_t *is);

/*
writes changes to the service list out to the file that was loaded with iadServicesLoad

returns IAD_E_FAIL if no file has been loaded with iadServicesLoad
returns IAD_E_INVALID_PARAMETER if file could not be written
*/
EXPORT int STDCALL iadServicesDeploy(install_t *is);

/*
write out a new services file based on the services lists. this currently rewrites the entire file and does not make a backup
file: the path to where the new file will be written

returns IAD_E_NULLPOINTER if file is null
returns IAD_E_INVALID_PARAMETER if file could not be created
*/
EXPORT int STDCALL iadServicesDeployFile(install_t *is, const char *file);

/*
release all memory used to hold the services list
*/
EXPORT void STDCALL iadServicesFree(install_t *is);

/*
add a new service to the services list. does not check to see if the name, port or aliases conflict with any existing entries
name: the name of the service
port: the port the service will use
protocol: the protocol the service will use ("tcp", "udp" are common; others exist, check your platform)
aliascount: the number of aliases passed in the next parameter
aliases: an array of other names that the service could be known as. NULL can be passed if aliascount == 0
comment: the comment that will go with the service; the '#' and end of line '\n' are added automatically, embedded '\n's are converted to spaces. NULL can be passed if no comment is desired.

name and aliases must contain only numbers, letters (any case), dashes '-', and underscores '_'

returns IAD_E_NULLPOINTER if name or protocol is null; also if aliascount is nonzero and aliases, or aliases[k] for 0 <= k <= aliascount is null
returns IAD_E_INVALID_PARAMETER if port is zero, if the name or port is not available, or if an invalid character is found in the name or any alias
*/
EXPORT int STDCALL iadServicesAddService(
	install_t *is,
	const char *name,
	unsigned short port,
	const char *protocol,
	int aliascount,
	const char **aliases,
	const char *comment);

/*
add a comment line to the services file
text: the text of the comment. embedded line breaks may be used to create multiline comments

returns IAD_E_NULLPOINTER if text is null
*/
EXPORT int STDCALL iadServicesAddComment(install_t *is, const char *text);

/*
removes services that match the arguments from the services list.
if name is non-null, all services with that name or that name as an alias are removed
if port is not ANY_PORT, all services which use that port are removed
if both are specified, services which match the port condition AND the alias condition are removed.
if neither is specified, IAD_E_INVALID_PARAMETER is returned

in any case, if protocol is specified, services must also match the protocol to be removed

port: if not ANY_PORT, specifies the port number to delete
name: if non-null, specifies the name or alias to delete
protocol: if non-null, specifies which protocol to delete

returns IAD_E_INVALID_PARAMETER if port and name are unspecified
*/
EXPORT int STDCALL iadServicesRemoveService(
	install_t *is,
	unsigned short port,
	const char *name,
	const char *protocol);

/*
determines if any services have claimed a port/protocol combination for use
also attempts to bind to the port to see if it is being used without a services entry
if protocol is not specified, checks against all protocols

port: the desired port to test
protocol: if non-null, which protocol to test

returns IAD_E_INVALID_PARAMETER if port is 0
returns IAD_E_NOERROR/PORT_FREE (0) if the port is free
returns PORT_USED (1) if the port is being used without a services entry (or you are a non-root user testing ports < 1024)
returns PORT_CLAIMED (2) if the port is used in a services entry
*/
EXPORT int STDCALL iadServicesTestPort(install_t *is, unsigned short port, const char *protocol);

/*
determines if any services have claimed a name/protocol combination for use
if protocol is not specified, checks against all protocols

name: the desired name to test
protocol: if non-null, which protocol to test

returns IAD_E_NOERROR/NAME_FREE (0) if name is free
returns NAME_USED (1) if the name is in use
*/
EXPORT int STDCALL iadServicesTestName(install_t *is, const char *name, const char *protocol);

/* get the port of a given name */
EXPORT unsigned short STDCALL iadServicesGetPortFromName(install_t *is, const char *name, const char *protocol);

/*
requests a service name that is unused for every protocol; tries preferred first, then preferred[1-9]
buffer: recieves a newly allocated string containing the generated name. the caller is responsible for freeing this memory; it is invalid unless this function returned IAD_E_NOERROR
preferred: a suggestion for the service name that the application would like

if buffer is null, IAD_E_NULLPOINTER is returned
if preferred is null or empty, IAD_E_INVALID_PARAMETER is returned
if a free name could not be found, IAD_E_FAIL is returned
*/
EXPORT int STDCALL iadServicesGenerateName(install_t *is, char **buffer, const char *preferred);

/*
requests a port that is unclaimed for every protocol and currently unused (not bound to or claimed by a service). if not 0, tries the preferred port first, then generates a random port if necessary
port: pointer to an unsigned short to recieve a clear port number; is invalid unless function returns IAD_E_NOERROR
preferred: a suggestion for the port that the application would like; may be zero to specify that no particular port is desired

if port is null, IAD_E_NULLPOINTER is returned
if a free port could not be found, IAD_E_FAIL is returned
*/
EXPORT int STDCALL iadServicesGeneratePort(install_t *is, unsigned short *port, unsigned short preferred);

/*
enables a dirty hack to short circuit the bind test and rely on the services file only.
once it's on, it's stuck on.
*/
EXPORT int STDCALL iadServicesCheatSockets(install_t *is);

#ifdef __cplusplus
}
#endif

#endif /* IAD_SERVICES_H */