Standardizing error codes; documenting then.

Perry Werneck
1 parent 9e14881b
Showing 4 changed files with 70 additions and 43 deletions Show diff stats
src/core/bounds.c
src/core/ctlr.c
src/include/lib3270.h
src/selection/selection.c
@@ -52,7 +52,7 @@ LIB3270_EXPORT int lib3270_get_field_bounds(H3270 *hSession, int baddr, int *sta
 	first = lib3270_field_addr(hSession,baddr);
 	if(first < 0)
-		return errno = (errno == 0 ? EINVAL : errno);
+		return -first;
 	first++;
@@ -451,7 +451,7 @@ LIB3270_EXPORT int lib3270_get_field_start(H3270 *hSession, int baddr)
 		return - errno;
 	if (!hSession->formatted)
-		return - (errno = ENOTCONN);
+		return - (errno = ENOTSUP);
     if(baddr < 0)
 		baddr = hSession->cursor_addr;
@@ -474,18 +474,18 @@ LIB3270_EXPORT int lib3270_get_field_len(H3270 *hSession, int baddr)
 	int addr;
 	int width = 0;
-	CHECK_SESSION_HANDLE(hSession);
+	if(check_online_session(hSession))
+		return - errno;
 	if (!hSession->formatted)
-		return errno = ENOTCONN;
+		return - (errno = ENOTSUP);
 	if(baddr < 0)
 		baddr = hSession->cursor_addr;
 	addr = lib3270_field_addr(hSession,baddr);
-
 	if(addr < 0)
-		return -1;
+		return addr;
 	saddr = addr;
 	INC_BA(addr);
@@ -497,26 +497,24 @@ LIB3270_EXPORT int lib3270_get_field_len(H3270 *hSession, int baddr)
 		width++;
 	} while (addr != saddr);
-	return -1;
+	return -(errno = ENODATA);
 }
-/**
- * @brief Find the buffer address of the field attribute for a given buffer address.
- *
- * @param hSession	Session handle.
- * @param addr		Buffer address of the field.
- *
- * @return field address or -1 if the screen isn't formatted (sets errno).
- *
- */
 LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr)
 {
 	int sbaddr;
-	FAIL_IF_NOT_ONLINE(hSession);
+	if(!lib3270_is_connected(hSession))
+		return -(errno = ENOTCONN);
 	if(!hSession->formatted)
-		return errno = ENOTCONN;
+		return -(errno = ENOTSUP);
+
+	if(baddr < 0)
+		baddr = lib3270_get_cursor_address(hSession);
+
+	if(baddr > lib3270_get_length(hSession))
+		return -(errno = EOVERFLOW);
 	sbaddr = baddr;
 	do
@@ -526,8 +524,7 @@ LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr)
 		DEC_BA(baddr);
 	} while (baddr != sbaddr);
-	errno = EINVAL;
-	return -1;
+	return -(errno = ENODATA);
 }
 LIB3270_EXPORT LIB3270_FIELD_ATTRIBUTE lib3270_get_field_attribute(H3270 *hSession, int baddr)
@@ -565,7 +562,7 @@ LIB3270_EXPORT LIB3270_FIELD_ATTRIBUTE lib3270_get_field_attribute(H3270 *hSessi
  * @param hSession	Session handle.
  * @param addr		Buffer address of the field.
  *
- * @return field length or -1 if invalid or not connected (sets errno).
+ * @return field length or negative if invalid or not connected (sets errno).
  *
  */
 int lib3270_field_length(H3270 *hSession, int baddr)
@@ -575,9 +572,8 @@ int lib3270_field_length(H3270 *hSession, int baddr)
 	int width = 0;
 	addr = lib3270_field_addr(hSession,baddr);
-
 	if(addr < 0)
-		return -1;
+		return addr;
 	saddr = addr;
 	INC_BA(addr);
@@ -589,17 +585,22 @@ int lib3270_field_length(H3270 *hSession, int baddr)
 		width++;
 	} while (addr != saddr);
-	return errno = EINVAL;
+	return -(errno = EINVAL);
 }
-/*
- * Find the field attribute for the given buffer address.  Return its address
- * rather than its value.
+/**
+ * @brief Find the field attribute for the given buffer address.
+ *
+ * @return Field attribute.
+ *
  */
 unsigned char get_field_attribute(H3270 *hSession, int baddr)
 {
-	return hSession->ea_buf[lib3270_field_addr(hSession,baddr)].fa;
+	baddr = lib3270_field_addr(hSession,baddr);
+	if(baddr < 0)
+		return 0;
+	return hSession->ea_buf[baddr].fa;
 }
 /**
@@ -608,7 +609,7 @@ unsigned char get_field_attribute(H3270 *hSession, int baddr)
  * @param hSession	Session handle.
  * @param baddr0	Search start addr (-1 to use current cursor position).
  *
- * @return address following the unprotected attribute byte, or 0 if no nonzero-width unprotected field can be found, -1 if not connected.
+ * @return address following the unprotected attribute byte, or 0 if no nonzero-width unprotected field can be found, negative if failed.
  *
  */
 LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0)
@@ -618,7 +619,7 @@ LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0)
 	FAIL_IF_NOT_ONLINE(hSession);
 	if(!hSession->formatted)
-		return errno = ENOTCONN;
+		return -(errno = ENOTSUP);
 	if(baddr0 < 0)
 		baddr0 = hSession->cursor_addr;
@@ -1094,11 +1094,14 @@
 	 * @brief Get all text inside the terminal.
 	 *
 	 * @param h			Session Handle.
-	 * @param offset	Start position.
+	 * @param offset	Start position (-1 to current cursor position).
 	 * @param len		Text length or -1 to all text.
 	 * @param lf		Line break char (0 to disable line breaks).
 	 *
-	 * @return Contents at position if available, or NULL. Release it with lib3270_free()
+	 * @return Contents at position if available, or NULL if error (sets errno). Release it with lib3270_free()
+	 *
+	 * @exception ENOTCONN	Not connected to host.
+	 * @exception EOVERFLOW	Invalid offset.
 	 *
 	 */
 	LIB3270_EXPORT char * lib3270_get_string_at_address(H3270 *h, int offset, int len, char lf);
@@ -1109,13 +1112,16 @@
 	 * @param h			Session Handle.
 	 * @param row		Desired row.
 	 * @param col		Desired col.
-	 * @param length	Text length
+	 * @param len		Text length or -1 to all text.
 	 * @param lf		Line break char (0 to disable line breaks).
 	 *
-	 * @return Contents at position if available, or NULL. Release it with lib3270_free()
+	 * @return Contents at position if available, or NULL if error (sets errno). Release it with lib3270_free()
+	 *
+	 * @exception ENOTCONN	Not connected to host.
+	 * @exception EOVERFLOW	Invalid position.
 	 *
 	 */
-	LIB3270_EXPORT char * lib3270_get_string_at(H3270 *h, int row, int col, int len, char lf);
+	LIB3270_EXPORT char * lib3270_get_string_at(H3270 *h, unsigned int row, unsigned int col, int len, char lf);
 	/**
 	 * @brief Check for text at requested position
@@ -1129,7 +1135,7 @@
 	 * @return Test result from strcmp
 	 *
 	 */
-	 LIB3270_EXPORT int lib3270_cmp_text_at(H3270 *h, int row, int col, const char *text, char lf);
+	 LIB3270_EXPORT int lib3270_cmp_text_at(H3270 *h, unsigned int row, unsigned int col, const char *text, char lf);
 	/**
@@ -1138,7 +1144,10 @@
 	 * @param h			Session Handle.
 	 * @param baddr		Reference position.
 	 *
-	 * @return NULL if failed, contents of the entire field if suceeds (release it with lib3270_free()).
+	 * @return NULL if failed (sets errno), contents of the entire field if suceeds (release it with lib3270_free()).
+	 *
+	 * @exception ENOTCONN	Not connected to host.
+	 * @exception EOVERFLOW	Invalid position.
 	 *
 	 */
 	LIB3270_EXPORT char * lib3270_get_field_text_at(H3270 *h, int baddr);
@@ -1206,7 +1215,12 @@
 	 * @param hSession	Session handle.
 	 * @param addr		Buffer address of the field.
 	 *
-	 * @return field address or -1 if the screen isn't formatted (sets errno).
+	 * @return field address or negative if the screen isn't formatted (sets errno).
+	 *
+	 * @exception -ENOTCONN		Not connected to host.
+	 * @exception -EOVERFLOW	Invalid position.
+	 * @exception -ENOTSUP		Screen is not formatted.
+	 * @exception -ENODATA		No field at the address.
 	 *
 	 */
 	LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr);
@@ -288,10 +288,13 @@ LIB3270_EXPORT char * lib3270_get_string_at_address(H3270 *h, int offset, int le
 		return NULL;
 	}
+	if(offset < 0)
+		offset = lib3270_get_cursor_address(h);
+
 	maxlen = (h->rows * (h->cols+ (lf ? 1 : 0) )) - offset;
 	if(maxlen <= 0 || offset < 0)
 	{
-		errno = EINVAL;
+		errno = EOVERFLOW;
 		return NULL;
 	}
@@ -331,19 +334,28 @@ LIB3270_EXPORT char * lib3270_get_string_at_address(H3270 *h, int offset, int le
 	return buffer;
 }
-LIB3270_EXPORT char * lib3270_get_string_at(H3270 *h, int row, int col, int len, char lf)
+LIB3270_EXPORT char * lib3270_get_string_at(H3270 *h, unsigned int row, unsigned int col, int len, char lf)
 {
 	CHECK_SESSION_HANDLE(h);
-	return lib3270_get_string_at_address(h, ((row-1) * h->cols) + (col-1), len, lf);
+
+	int baddr = lib3270_translate_to_address(h,row,col);
+	if(baddr < 0)
+		return NULL;
+
+	return lib3270_get_string_at_address(h, baddr, len, lf);
 }
-LIB3270_EXPORT int lib3270_cmp_text_at(H3270 *h, int row, int col, const char *text, char lf)
+LIB3270_EXPORT int lib3270_cmp_text_at(H3270 *h, unsigned int row, unsigned int col, const char *text, char lf)
 {
 	int		  rc;
 	size_t	  sz		= strlen(text);
 	char	* contents;
-	contents = lib3270_get_string_at(h,row,col,sz,lf);
+	int baddr = lib3270_translate_to_address(h,row,col);
+	if(baddr < 0)
+		return -1;
+
+	contents = lib3270_get_string_at_address(h,baddr,sz,lf);
 	if(!contents)
 		return -1;
	@@ -52,7 +52,7 @@ LIB3270_EXPORT int lib3270_get_field_bounds(H3270 hSession, int baddr, int sta		@@ -52,7 +52,7 @@ LIB3270_EXPORT int lib3270_get_field_bounds(H3270 hSession, int baddr, int sta
52	first = lib3270_field_addr(hSession,baddr);	52	first = lib3270_field_addr(hSession,baddr);
53		53
54	if(first < 0)	54	if(first < 0)
55	- return errno = (errno == 0 ? EINVAL : errno);	55	+ return -first;
56		56
57	first++;	57	first++;
58		58