1.4 Revision

From ReddNet
Revision as of 13:08, 14 December 2007 by Hunterh (talk | contribs) (New page: = IBP Spec 1.4 = == IBP allocate == IBP_set_of_caps IBP_allocate ( IBP_depot depot, IBP_timer timeout, unsigned long int size, IBP_attributes attributes) IBP_allocate() allocates a remot...)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

IBP Spec 1.4

IBP allocate

IBP_set_of_caps IBP_allocate ( IBP_depot depot, IBP_timer timeout, unsigned long int size, IBP_attributes attributes)

IBP_allocate() allocates a remote storage area on the host depot with specified resource. The allocated area has a maximum possible size of size bytes, and storage attributes, defined by attributes.

Return values

Upon success, IBP_allocate() returns an IBP_set_of_caps object. Otherwise, it returns a NULL pointer and sets IBP_errno to one of the following values defined in ”ibp_protocol.h”

  • IBP_INVALID_PARAMETER : One or more of the parameters to the IBP allocate() call has an invalid value (e.g. NULL target host, invalid entry in attributes, ...)
  • IBP_E_CLIENT_TIMEOUT : A client timeout occurs.
  • IBP_E_CONNECTION : An error has occurred while trying to connect to the IBP server running on target host.
  • IBP_E_INVALID_RID : An invalid resource id.
  • IBP_E_UNKNOWN_RS : Resource id can’t be found on IBP depot.
  • IBP_E_SOCK_WRITE : An error has occurred while trying to write to the socket connection to the IBP server.
  • IBP_E_SOCK_READ : An error has occurred while trying to read response from the IBP server.
  • IBP_E_BAD_FORMAT : Response from the IBP server does not have the expected format, or the IBP server received a badly formatted request.
  • IBP_E_INVALID_CMD : The IBP server has received a command it does not recognize.
  • IBP_E_WOULD_EXCEED_LIMIT : Granting the request would cause the IBP server to exceed the maximum storage limit allocated to the storage category defined in attributes.
  • IBP_E_FILE_ACCESS : The IBP server has encountered an error while trying to access one or more of its internal files that control access to the storage area.
  • IBP_E_INTERNAL : The IBP server has encountered an internal error while processing the client’s request.
  • IBP_E_TYPE_NOT_SUPPORTED : A request to allocate a storage area of type IBP_FIFO was made to an IBP server that does not support this type.

IBP store

unsigned long int IBP_store ( IBP_cap cap, IBP_timer timeout, char data, unsigned long int size )

IBP_store() stores size bytes starting at data in the storage area accessed through the IBP capability cap. For this call to succeed, cap must be a write cap returned by an earlier call to IBP_allocate(), or imported from the client which made the IBP_allocate() call. IBP_store() is a blocking call that only returns when the required size of data is successfully stored at the desired storage area accessed through the IBP capability cap, or an error causes the call to abort prematurely. The call appends data to the end of any previously stored data at the storage area accessed through cap for storage areas of type IBP_BYTEARRAY, IBP_CIRQ and IBP_FIFO. Data written to a storage area of type IBP_BUFFER overwrites any previous data (starting at the beginning of the buffer). If a ServerSync time is set, the call will return either if all the data has been written, or the time has expired.

Return values

Upon success, IBP_store() returns the number of bytes written. Otherwise it returns 0 and sets IBP_errno to one of the following error codes:

  • IBP_E_WRONG_CAP_FORMAT : The IBP capability cap doesn’t have the proper format.
  • IBP_E_CLIENT_TIMEOUT : A client timeout occurs.
  • IBP_E_CAP_NOT_WRITE : The IBP capability cap is not a write capability.
  • IBP_E_CONNECTION : An error has occurred while trying to connect to the IBP server running on target host.
  • IBP_E_SOCK_WRITE : An error has occurred while trying to write to the socket connection to the IBP server.
  • IBP_E_SOCK_READ : An error has occurred while trying to read response from the IBP server.
  • IBP_E_BAD_FORMAT : Response from the IBP server does not have the expected format, or the IBP server received a badly formatted request.
  • IBP_E_INVALID_CMD : The IBP server has received a command it does not recognize.
  • IBP_E_CAP_NOT_FOUND : The storage area accessed through cap does not exist on the associated IBP server.
  • IBP_E_CAP_ACCESS_DENIED : The storage area accessed through cap cannot be accessed for write operations.
  • IBP_E_SIZE_EXCEEDS_LIMIT : The write operation would cause the aggregate size of the storage area to exceed the maximum size specified in the IBP_store() call. This error is only relevant for storage areas of type IBP_BYTEARRAY.
  • IBP_E_FILE_ACCESS: The IBP server has encountered an error while trying to access one or more of its internal files that control access to the storage area.
  • IBP_E_FILE_WRITE: The IBP server has encountered an error while attempting to store incoming data to the underlying storage area.
  • IBP_E_RSRC_UNAVAIL: A resource used by the IBP server was unavailable to service the request. This error is only relevant when the underlying storage area has type IBP_FIFO.
  • IBP_E_INTERNAL : The IBP server has encountered an internal error while processing the client’s request.

IBP load

unsigned long int IBP_load ( IBP_cap cap, IBP_timer timeout, char *buf, unsigned long int size, unsigned long int offset )

IBP_load() reads up to size bytes, starting at offset, from the storage area accessed through the IBP capability cap, into the memory area pointed by buf. For storage areas of type IBP_FIFO and IBP_CIRQ, offset is ignored. For this call to succeed, cap must be read cap returned by an earlier call to IBP_allocate(), or imported from the client which made the IBP_allocate() call. IBP_load() is a blocking call that returns only when all required data is read, the ServerSync expires, or the read operation is prematurely terminated due to an error.

Return values

Upon success, IBP_load() returns the number of bytes actually read, otherwise it returns 0 and sets IBP_errno to one of the following error codes:

  • IBP_E_INVALID_PARAMETER : One or more of the parameters to the IBP_load() call has an invalid value(e.g. negative size, ...)
  • IBP_E_CLIENT_TIMEOUT : A client timeout occurs.
  • IBP_E_WRONG_CAP_FORMAT : The IBP capability cap doesn’t have the proper format.
  • IBP_E_CAP_NOT_READ : The IBP capability cap is not a read capability.
  • IBP_E_CONNECTION : An error has occurred while trying to connect to the IBP server running on target host.
  • IBP_E_SOCK_WRITE : An error has occurred while trying to write to the socket connection to the IBP server.
  • IBP_E_SOCK_READ : An error has occurred while trying to read response from the IBP server.
  • IBP_E_BAD_FORMAT : Response from the IBP server does not have the expected format, or the IBP server received a badly formatted request.
  • IBP_E_INVALID_CMD : The IBP server has received a command it does not recognize.
  • IBP_E_CAP_NOT_FOUND : The storage area accessed through cap does not exist on the associated IBP server.
  • IBP_E_CAP_ACCESS_DENIED : The storage area accessed through cap cannot be accessed for write operations.
  • IBP_E_FILE_ACCESS: The IBP server has encountered an error while trying to access one or more of its internal files that control access to the storage area.
  • IBP_E_FILE_READ: The IBP server has encountered an error while attempting to read incoming data to the underlying storage area.
  • IBP_E_RSRC_UNAVAIL: A resource used by the IBP server was unavailable to service the request. This error is only relevant when the underlying storage area has type IBP_FIFO.
  • IBP_E_INTERNAL : The IBP server has encountered an internal error while processing the client’s request.

IBP copy

unsigned long int IBP_copy ( IBP_cap source, IBP_cap target, IBP_timer sourceTimeout, IBP_timer targetTimeout, unsigned long int size, unsigned long int offset )

IBP_copy() copies up to size bytes, starting at offset, from the storage area accessed through the IBP read capability source, and writes them to the storage area accessed through the IBP write capability target. For storage areas of type IBP_FIFO and IBP_CIRQ, offset is ignored. As in other read operation to an IBP_FIFO or IBP_CIRQ storage area, data read from the storage area will no longer be available for future reads. For this call to succeed, source must be a read cap returned by an earlier call to IBP_allocate(), or imported from the client which made the IBP_allocate() call, and target must be a write cap returned by a similar call. IBP_copy() is a blocking call that returns only when all required data is read, the ServerSync expires, or the read operation is prematurely terminated due to an error.

Return values

Upon success, IBP_copy() returns the number of bytes actually read, otherwise it returns 0 and sets IBP_errno to one of the following error codes:

  • IBP_E _INVALID_PARAMETER: One or more of the parameters to the IBP_copy() call has an invalid value (e.g.negative size, ...)
  • IBP_E_CLIENT_TIMEOUT : A client timeout occurs.
  • IBP_E__WRONG_CAP_FORMAT : The IBP capability cap doesn’t have the proper format.
  • IBP_E_CAP_NOT_WRITE : The IBP capability source is not a write capability.
  • IBP_E_CAP_NOT_READ : The IBP capability target is not a read capability.
  • IBP_E_CONNECTION : An error has occurred while trying to connect to the IBP server running on target host.
  • IBP_E_SOCK_WRITE : An error has occurred while trying to write to the socket connection to the IBP server.
  • IBP_E_SOCK_READ : An error has occurred while trying to read response from the IBP server.
  • IBP_E_BAD_FORMAT : Response from the IBP server does not have the expected format, or the IBP server received a badly formatted request.
  • IBP_E_INVALID_CMD : The IBP server has received a command it does not recognize.
  • IBP_E_CAP_NOT_FOUND : One ( or both ) storage area accessed through cap does not exist on the associated IBP server.
  • IBP_E_CAP_ACCESS_DENIED : One ( or both ) storage area accessed through cap can not be accessed for write operations.
  • IBP_E_SIZE_EXCEEDS_LIMIT: The write part of the copy operation would cause the aggregate size of the storage area to exceed the maximum size specified in the IBP_store() call. This error is only relevant for storage areas of type IBP_BYTEARRAY.
  • IBP_E_FILE_ACCESS: The IBP server has encountered an error while trying to access one or more of its internal files that control access to the storage area.
  • IBP_E_FILE_WRITE : The IBP server has encountered an error while attempting to store incoming data to the underlying storage area.
  • IBP_E_FILE_READ :The IBP server has encountered an error while attempting to read incoming data to the underlying storage area.
  • IBP_E_RSRC_UNAVAIL: A resource used by the IBP server was unavailable to service the request. This error is only relevant when the underlying storage area has type IBP_FIFO.
  • IBP_E_INTERNAL : The IBP server has encountered an internal error while processing the client’s

IBP mcopy

Unsigned long int IBP_mcopy ( IBP_cap source, IBP_cap target[], unsigned int nCaps, IBP_timer srcTimeout, IBP_timer targetTimeout, unsigned long int size, unsigned long int offset, int type[], int port[], int service )

IBP_mcopy() copies up to size bytes, starting at offset, from the storage area accessed through the IBP read capability source, and writes them to the storage area(s) accessed through the IBP write capability(ies) target[]. The number of target depots is stored in nCaps. For storage areas of type IBP_FIFO and IBP_CIRQ, offset is ignored. A size value of –1 causes all currently stored data in an IBP_BYTEARRAY type storage area accessed through source to be copied. For source storage areas of type IBP_FIFO and IBP_CIRQ, a size value of -1 causes a copy operation for the maximum size specified in IBP_allocate()to be initiated. As in other read operations to an IBP_FIFO or IBP_CIRQ type storage area, data read from the storage area will no longer be available for future reads. For this call to succeed, source must be a read cap returned by an earlier call to IBP_allocate(), or imported from the client which made the IBP_allocate() call and target must be a write cap returned by a similar call. IBP_mcopy() is a blocking call that returns only when all required data is successfully copied from the source IBP serverto all the target IBP server, the highest ServerSync value expired or the operation is prematurely terminated due to an error. At the moment, there are implemented five types of data movers that can support TCP , UDP and IP Multicast data transfer protocols, the selection of the protocol is passed through the API using the parameters types[] (at the moment same type should be specified for all the targets) and service, the first one specifies the data mover type for the target IBP servers, and the second specifies the type of data mover corresponding in the source IBP server; the dm port[] parameter is used to specify the data mover option, which at this point are just the ports to be used by the TCP and UDP protocols. It must be specified and it can be any port number higher than 1024. These types must be defined as follows:

Targets Source Description

  • TCP DM_UNI DM_SMULTI
  • DM_MULTI
  • DM_PMULTI
  • Sequential mcopy
  • Round-robin fashion mcopy
  • Threaded mcopy
  • UDP DM_BLAST DM_MBLAST Threaded UDP Based mcopy
  • MULTICAST DM_MCAST DM_MULTICAST Multicast mcopy

Return values

Upon success, IBP_mcopy() returns the number of bytes read from the source capability, otherwise it returns 0 and sets IBP_errno to the same error codes as IBP_copy.

IBP manage

int IBP_manage ( IBP_cap cap, IBP_timer timeout, int cmd, int type, IBP_CapStatus info );

IBP_manage() allows an IBP client to perform certain management operations on an IBP storage area. Any client that can present the management capability can issue any of the management commands described below. Cap is an IBP management capability that is returned in the IBP_allocate() call or imported from the client which made that call( except when cmd = IBP_PROBE, where any capability can be used). cmd can take one of the following values (defined in the file ”ibp_protocol.h” ):

  • IBP_INCR increments the reference count to the capability associated with the management capability cap, and whose type is specified in the parameter type. The parameter info is ignored for this command.
  • IBP_DECR decrements the reference count to the capability associated with the management cap abilitycap and whose type is specified in the parameter type. Decrementing the reference count the read capability associated with a storage area to 0 causes the IBP server to delete that storage area from its managed pool. Further requests to that area will fail, while requests currently in progress will be allowed to progress to completion. The parameter info is ignored for this command.
  • IBP_CHNG changes one or more of the attributes of the storage area accessed through the management capability cap. The new values are specified through the parameter info (described below). The current version of IBP allows changes to one (or more) of the following attributes:
    • maxSize changes the maximum storage size of the underlying storage area. Changing the size of a storage area of type IBP_FIFO or IBP_CIRQ is currently not allowed. Decreasing maximum size of a storage area of type IBP_BYTEARRAY does not affect data already stored there, it will only affect future requests to that storage area.
    • duration changes the duration property of the storage area (see description of the IBP_allocate() call for further details on the possible values and implications for this parameter.)
  • IBP_PROBE checks the current state of the storage area accessed through the management capability cap. The current state is returned through the parameter info, which is defined below.
 type determines the type of the capability affected by the two commands IBP_INCR and IBP_DECR. 
 It can have one of two values, IBP_READCAP and IBP_WRITECAP. It is ignored for the two commands 
 IBP_CHNG and IBP_PROBE.

 info is a pointer to a structure of type IBP_CapStatus.

The following table summarizes the use of different parameters with every command.

type readRefCount writeRefCount currentSize maxSize attrib

IBP_INCR In Not used Not Used Not Used Not Used Not Used

IBP_DECR In Not used Not Used Not Used Not Used Not Used

IBP_PROBE Not Used Out Out Out Out Out

IBP_CHNG Not Used Not Used Not Used Not Used In In

Return values

Upon success, IBP_manage() returns 0, otherwise it returns -1 and sets IBP_errno to one of the following error codes:

  • IBP_E_INVALID_PARAMETER : One or more of the parameters to the IBP_manage() call has an invalid value (e.g. negative type, ...)
  • IBP_E_CLIENT_TIMEOUT : A client timeout occurs.
  • IBP_E_WRONG_CAP_FORMAT : The IBP capability doesn’t have the proper format.
  • IBP_E_CAP_NOT_MANAGE : The IBP capability is not a write capability.
  • IBP_E_CONNECTION : An error has occurred while trying to connect to the IBP server.
  • IBP_E_SOCK_WRITE : An error has occurred while trying to write to the socket connection to the IBP server.
  • IBP_E_SOCK_READ : An error has occurred while trying to read response from the IBP server.
  • IBP_E_BAD_FORMAT : Response from the IBP server does not have the expected format, or the IBP server received a badly formatted request.
  • IBP_E_INVALID_CMD : The IBP server has received a command it does not recognize.
  • IBP_E_CAP_NOT_FOUND : The storage area accessed through cap does not exist on the associated IBP server.
  • IBP_E_INVALID_MANAGE_CAP: The management cap does not match the management cap associated with the storage area.
  • IBP_E_WOULD_DAMAGE_DATA : Trying to change the size of a storage area of type IBP_ FIFO.
  • IBP_E_WOULD_EXCEED_LIMIT: Trying to increase the maximum size of an IBP_BYTEARRAY type storage area leads exceeding the maximum storage space allocated for its class of storage.
  • IBP_E_INTERNAL : The IBP server has encountered an internal error while processing the client’s request.

IBP status

IBP_DptInfo IBP_status ( IBP_depot depot, int StatusCmd, IBP_timer timeout, Char *password, unsigned long int StableStor, unsigned long int VolStor long duration );

IBP_status() allows an application to perform a query over a particular IBP depot resource and to modify some general storage properties. depot is the particular IBP depot the application would like to query. StatusCmd can have two values:

  • IBP_ST_INQ queries the IBP depot resource for its stable storage and the used amount, its volatile storage and the used amount, and the duration. When this command is used, the subsequent 4 parameters are not used.
  • IBP_ST_CHANGE changes the stable amount, the volatile amount and duration property of the IBP depot resource. Note the difference between this command and the IBP_manage() one. It is not possible to destroy the data already present in an IBP depot, so the changes only take effect if they are equal or bigger than the currently allocated area. password is the IBP depot password. StableStor is the new total Stable Storage of the IBP depot. It must be equal or bigger than the current Stable Storage used; otherwise, it’s ignored. VolStor is the new total Volatile Storage of the IBP depot. It must be equal or bigger than the current Volatile Storage used; otherwise, it’s ignored. duration is the new maximum duration allowed. It is not retro-active.

Return values

Upon success, IBP_status () returns an IBP_DptInfo object, otherwise it returns a NULL and sets IBP_errno to one of the following error codes:

  • IBP_E_CONNECTION : An error has occurred while trying to connect to the IBP server.
  • IBP_E_CLIENT_TIMEOUT : A client timeout occurs.
  • IBP_E_SOCK_WRITE : An error has occurred while trying to write to the socket connection to the IBP server.
  • IBP_E_SOCK_READ : An error has occurred while trying to read response from the IBP server.
  • IBP_E_INVALID_CMD : The IBP server has received a command it does not recognize.
  • IBP_E_WOULD_DAMAGE_DATA : Trying to change the size of a storage area of type IBP_ FIFO.
  • IBP_E_WOULD_EXCEED_LIMIT: Trying to increase the maximum size of an IBP_BYTEARRAY type storage area leads exceeding the maximum storage space allocated for its class of storage.
  • IBP_E_INTERNAL : The IBP server has encountered an internal error while processing the client’s request.
Retrieved from "http://www.reddnet.org/mwiki/index.php?title=1.4_Revision&oldid=2893"